Version 1.6.0 release

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.

Version 1.5.1 release

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.

Version 1.5.0 release

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.

Version 1.4.2 release

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.

Version 1.4.1 release

Bug fix release to add support for Clingo 5.6

Version 1.4.0 release

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

Version 1.3.8 release

Bug fixes and enhancements:

• Bug fix for query aliases. Internally an alias has a generated uuid. Clashes in the uuid can cause a query to fail. Since a clash only happens occasionally this can lead to frustrating intermittent failures that are hard to track down. Now using the full uuid.uuid4() identity so shouldn't get any more clashes (see https://stackoverflow.com/questions/1785503/when-should-i-use-uuid-uuid1-vs-uuid-uuid4-in-python)

• Added picking of anonymous tuples in a predicate definition. This makes it easier to use facts in a multi-process setting.

• Cleanup implementation of fact instantiation and unification for some performance improvements.

Version 1.3.7 release

Bug fixes and enhancements:

• Better type annotations and field type annotations

• Experimental feature to declare predicates using only field type annotations to infer the correct field type. This will make the predicate declaration look more like standard dataclasses and will be more intuitive for most python user. This feature is currently undocumented but hopefully will become the main way of declaring clorm predicates. For example, the following two declarations will now create the same class definition:

       class Fact(Predicate):
            i : int
            s : str
  
       class Fact(Predicate):
            i = IntegerField
            s = StringField
  

• Some small improvements to the performance for the fact parser and symbol unification

• Some internal simplifications

Version 1.3.6 release

Bug fix and enhancements:

• Bug fix to dealiasing paths
• Enhancement to FactBase.asp_str(commented=True) for complex/nested predicate signatures.

Version 1.3.4 release

Minor enhancements:

• Added a flag FactBase.asp_str(sorted=True) to make the generated ASP string sorted. By default the output is not sorted (but is deterministic based on the insertion order of constructing the factbase). With the sorted flag the output is sorted first on the predicate type (name/arity) and then on the instances of each predicate.
• Internal implementation change to Predicate initialiser that is cleaner and also works better with pylint.