Clorm

Changes with this release:

- The behavior of the comparison (`==`, `!=`, `<`, `<=`, `>`, `>=`) and `hash` operators for Clorm `Predicate` instance are changed to call the corresponding underlying `clingo.Symbol` operators. Previously these operators explicitly combined the Python representation of the individual field parameters.
- This change provides a clearer semantics for the comparison operator. `Predicate` instances should be understood as providing a view of `clingo.Symbol` objects.
- An important property is that now all `Predicate` instances will be comparable for all comparison operators. Previously this was not guaranteed as it depended on the types of the underlying Python object. For example, in Python `1 < "foo"` will raise and exception because a comparison of `int` and `str` is undefined.
- **Warning**: the sort ordering for Predicate instances will be different to previous versions of the library.

- The initializer for `BaseField` and its sub-classes has changed to separate the `default` and `default_factory` parameters. This is consistent with the `field()` function as well as existing libraries, such as `dataclasses`.
- **Warning**: while this changes the API it should not be noticeable to users because users should not be explicitly instantiating field instances. Instead the preferred approach is to use the `field()` function to specify default parameters.

**Warning**: this release changes some behavior of Clorm. While we would expect that this would not be noticeable for most users, nevertheless please test carefully before updating your dependencies.

Minor release with bug fixes and small improvements:
- Bug fix when using inner Predicate classes with postponed type annotations
- Add support for '&' to separate query join clauses
- Documentation fixes
- Fixed need for "casting" to get around type checking when using functions in a query select statement.

This release add support for Python postponed type annotations.

* Postponed type annotations are configured by specifying `from __future__ import annotations` at the top of module files.

* It causes all type annotations to be returned as plain strings, rather than processed Python class objects. This feature is being increasingly used with user code, and will eventually become the default behavior for Python.

* Using Python type annotations is now the preferred mechanism to specify Clorm Predicate sub-classes. For example:

from clorm import Predicate, ConstantStr

class MyPredicate(Predicate, name="my_predicate"):
field1: int
field2: str
field3: ConstantStr

p = MyPredicate(field1=10, field2="Hello", `field3="friend")

resulting ASP fact: `my_predicate(10, "Hello", friend).`

* The documentation has been updated to reflect the new preferred syntax.

This version mainly contains bug fixes. It also has a small addition to the query API. The changes are:

- Export the `field()` function at the `clorm` namespace level. Previously you had to import it from `clorm.orm.core` This works in a similar way to the `field()` function in `dataclasses`.
- Fixed the bug in the `func()` function. This function provides a wrapper for using functions/lambdas within clorm queries.
- Added missing `on_core` and `on_unsat` callbacks for `clorm.clingo.Control.solve()`, which were callbacks introduced in Clingo 5.5.
- Fixed non-determinism in `clorm.clingo.Control.solve()` with assumptions. Previously was using a `set` object which is not deterministic between python instances so was creating non-determinism when looking at the results of different clingo runs.
- Fix bug when specifying a function/lambda in the `select` clause of a query over multiple predicates. The order that the facts were presented to the function/lambda wouldn't always match to the function requirements because of the internal order within the generated query plan.
- New feature: while clorm facts are immutable, so cannot be modified within a factbase, the query API now lets you specify how facts can be replaced by a modified version. This can be used to simulate modifying the facts of a factbase.

Bug fix release to add support for Clingo 5.6

This version adds a lot of new type annotation features and performance enhancements. **Note**: in order to provide the performance enhancements the API has changed very slightly. However, the standard usage of clorm has not changed so would only affect more unusual usages of the library; for example, not using the provided clorm functions to unify predicate classes with symbols. The main features are:

- Better support for type annotations. *Modern* Python code makes heavy use of type annotations. You can see this in popular libraries such as Pydantic. Clorm should now behave a lot better when used with modern tools such as `mypy`, `pylint`, and integrated IDEs.
- Type annotations for Clorm's query API. If you use the new type annotated format for specifying Predicate sub-classes, tools like mypy can infer function inputs and outputs for clorm queries. This should make it much easier to use the query API for first-time or casual users.
- A more compact way to declare your Predicate sub-classes. Instead of writing:


class SomePredicate(Predicate):
i = IntegerField

class Meta:
name = "some_predicate"

you can write:


class SomePredicate(Predicate, name="some_predicate"):
i: int


- Performance enchancement. The overhead of using Clorm facts has now been reduced. So creating Clorm fact instances and extracting/unifying facts from clingo models has been made a lot more efficient. Note: this required a small change to the API but it shouldn't affect normal user code. In particular, it is only if a user was explicitly passing a clingo symbol to the initialiser (eg. `Predicate.__init__(raw=clingo.Function("something",[]))` will their code need to change. The API is now cleaner (calling raw=XX was really ugly), and you will need to call the `Predicate.unify()` class function.

- *No Clingo Mode*. Currently, clingo.Symbol objects cannot be freed. This makes it potentially problematic to use clingo within long running processes. Clorm solves this by offering a NOCLINGO mode where you can use an internal clorm noclingo.Symbol objects in a long running parent process, and only use real clingo symbol objects in spawned sub-processes. To enable no clingo mode you must now set the environment variable `CLORM_NOCLINGO`. This must be set before the library is loaded. For example from the bash shell:

export CLORM_NOCLINGO=True