aspalchemy 1.0.0__tar.gz

aspalchemy-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jolyon Bloomfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aspalchemy-1.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: aspalchemy
+Version: 1.0.0
+Summary: A Python ORM interface for building and solving clingo ASP programs
+Author: Jolyon Bloomfield
+Author-email: Jolyon Bloomfield <jolyonb84@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Requires-Dist: clingo>=5.8.0,<6
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# ASPAlchemy
+
+ASPAlchemy is a Python library for building clingo ASP (Answer Set Programming) programs with a clean, object-oriented interface.
+
+## Term Hierarchy
+
+The library is built around a rich hierarchy of term types that represent different ASP constructs:
+
+- `Term` (abstract base class)
+  - `ComparableTerm` (abstract: usable in comparisons; provides `==`, `!=`, `<`, `<=`, `>`, `>=`)
+    - `Value` (abstract, for basic values — also a `BasicTerm`)
+      - `Variable` (e.g., `X`, `Y`)
+      - `ConstantBase` (abstract)
+        - `Number` (numeric constants, e.g., `42`)
+        - `String` (string literals, e.g., `"hello"`)
+        - `DefinedConstant` (#const-defined constants, e.g., `max_size`)
+        - `Supremum` / `Infimum` (`#sup`/`#inf`, the ordering's end markers; `SUP` and `INF` are the singletons)
+    - `Expression` (arithmetic expressions, e.g., `X+Y*2`)
+    - `AggregateBase` (abstract marker so core can recognize aggregates)
+      - `Aggregate` (abstract)
+        - `Count`, `Sum`, `SumPlus`, `Min`, `Max`
+  - `BasicTerm` (abstract, can be direct predicate arguments: `Value`, `Predicate`, `Pool`)
+    - `Predicate` (e.g., `person(john, 42)`)
+    - `Pool` (abstract)
+      - `RangePool` (e.g., `1..5`)
+      - `ExplicitPool` (e.g., `(1;3;5)`)
+  - `Negatable` (abstract mixin: `~` builds `not term` on atoms; on plain comparisons it builds the complement — see `Not`)
+    - `Comparison` (comparisons, e.g., `X < Y`)
+    - `DefaultNegation` (default negation, e.g., `not p(X)`)
+  - `ConditionalLiteral` (e.g., `p(X) : q(X)`)
+  - `Choice` (e.g., `{ p(X) : q(X) }`)
+
+## Core Concepts
+
+### Values
+
+Values represent basic elements in an ASP program. Plain Python literals coerce
+automatically wherever terms are expected — an int becomes an ASP number, a str
+becomes a quoted ASP string. Variables you construct by hand, and bare atoms
+(the `n` in `direction(n)`) are zero-arity predicates:
+
+```python
+from aspalchemy import Predicate, Variable
+
+X = Variable("X")  # an ASP variable
+n = Predicate.define("n", [], show=False)()  # a bare atom: n, distinct from the string "n"
+```
+
+### Predicates
+
+Declare predicates as classes; fields are statically checked, so typos and
+missing arguments are type errors, and instances autocomplete:
+
+```python
+from aspalchemy import Predicate, PredicateField
+
+class Person(Predicate):
+    name: PredicateField
+    age: PredicateField
+
+john = Person(name="john", age=30)
+mary = Person(name="mary", age=25)
+```
+
+The ASP name defaults to the class name, snake-cased (HasSymbol becomes
+has_symbol); class kwargs override it and set namespacing and visibility (`class Pipe(Predicate, name="pipe_seg",
+show=False)`). When the schema is only known at runtime, build the same thing
+dynamically:
+
+```python
+Edge = Predicate.define("edge", ["a", "b"])
+```
+
+For fully typed fields, annotate them as `Field[int]`, `Field[str]`, or
+`Field[SomePredicate]`. Writes accept rule terms (Variables, Expressions) as
+well as ground values, and are validated per field; reads are plain Python
+values, statically typed — so solution atoms come back as real ints and strs:
+
+```python
+from aspalchemy import ASPProgram, Field, Predicate
+
+class Score(Predicate):
+    player: Field[str]
+    points: Field[int]
+
+program = ASPProgram()
+program.fact(Score(player="ada", points=3), Score(player="ben", points=5))
+model = program.solve().first()  # raises UnsatisfiableError if there is no model
+total = sum(score.points for score in model.atoms(Score))  # plain ints
+assert total == 8
+```
+
+### Rules
+
+Build rules with clear syntax:
+
+```python
+from aspalchemy import ANY, ASPProgram, Variable
+
+program = ASPProgram()
+X, Y = Variable("X"), Variable("Y")
+Adult = Predicate.define("adult", ["name"])
+
+# Facts
+program.fact(john)
+program.fact(mary)
+
+# Rules
+program.when(Person(name=X, age=Y), Y >= 18).derive(Adult(name=X))
+
+# Constraints
+program.forbid(Person(name=ANY, age=Y), Y < 0)
+```
+
+### Comparisons
+
+Compare terms:
+
+```python
+X < Y  # Creates a comparison X < Y
+```
+
+### Aggregates
+
+Use aggregates for advanced computations:
+
+```python
+from aspalchemy import ANY, Count, Variable
+
+X = Variable("X")
+count = Count(X, Person(name=X, age=ANY)) > 5
+```
+
+### Solving
+
+Solve your ASP program:
+
+```python
+# Generate ASP code
+asp_code = program.render()
+print(asp_code)
+
+# Solve
+result = program.solve()  # a lazy stream: consume the models you want
+for model in result:
+    print("Solution found:")
+    for adult in model.atoms(Adult):
+        print(f"  {adult}")
+print(f"Satisfiable: {result.satisfiable}")
+```
+
+### Diagnostics point at your code
+
+Every statement remembers the Python line that authored it. A `when()` left
+unclosed reports where it was opened; grounding diagnostics from clingo carry
+a "generated by file:line" note back to your source;
+`program.render(annotate=True)` appends a trailing `% file:line` comment to
+each rule — without changing line numbers, so the annotated text doubles as
+a map from raw-clingo error lines back to your source; and when a grounding
+is slow or huge, `program.ground().analyze_grounding()` reports ground-atom
+counts per signature, largest first, each joined back to the lines that
+derive it. Frameworks built on
+aspalchemy call `register_skip_package()` (whole package, or per-module dotted
+prefixes) so locations point at *their* caller's code; mark a single helper
+with `@attribute_to_caller` to attribute its statements to its call sites.
+Switch capture off with `ASPProgram(source_locations=False)` when
+generating rules in bulk.
+
+## Requirements
+
+- Python 3.14+
+- clingo 5.8+
+
+## License
+
+MIT License

aspalchemy-1.0.0/docs/README.md

@@ -0,0 +1,176 @@
+# ASPAlchemy
+
+ASPAlchemy is a Python library for building clingo ASP (Answer Set Programming) programs with a clean, object-oriented interface.
+
+## Term Hierarchy
+
+The library is built around a rich hierarchy of term types that represent different ASP constructs:
+
+- `Term` (abstract base class)
+  - `ComparableTerm` (abstract: usable in comparisons; provides `==`, `!=`, `<`, `<=`, `>`, `>=`)
+    - `Value` (abstract, for basic values — also a `BasicTerm`)
+      - `Variable` (e.g., `X`, `Y`)
+      - `ConstantBase` (abstract)
+        - `Number` (numeric constants, e.g., `42`)
+        - `String` (string literals, e.g., `"hello"`)
+        - `DefinedConstant` (#const-defined constants, e.g., `max_size`)
+        - `Supremum` / `Infimum` (`#sup`/`#inf`, the ordering's end markers; `SUP` and `INF` are the singletons)
+    - `Expression` (arithmetic expressions, e.g., `X+Y*2`)
+    - `AggregateBase` (abstract marker so core can recognize aggregates)
+      - `Aggregate` (abstract)
+        - `Count`, `Sum`, `SumPlus`, `Min`, `Max`
+  - `BasicTerm` (abstract, can be direct predicate arguments: `Value`, `Predicate`, `Pool`)
+    - `Predicate` (e.g., `person(john, 42)`)
+    - `Pool` (abstract)
+      - `RangePool` (e.g., `1..5`)
+      - `ExplicitPool` (e.g., `(1;3;5)`)
+  - `Negatable` (abstract mixin: `~` builds `not term` on atoms; on plain comparisons it builds the complement — see `Not`)
+    - `Comparison` (comparisons, e.g., `X < Y`)
+    - `DefaultNegation` (default negation, e.g., `not p(X)`)
+  - `ConditionalLiteral` (e.g., `p(X) : q(X)`)
+  - `Choice` (e.g., `{ p(X) : q(X) }`)
+
+## Core Concepts
+
+### Values
+
+Values represent basic elements in an ASP program. Plain Python literals coerce
+automatically wherever terms are expected — an int becomes an ASP number, a str
+becomes a quoted ASP string. Variables you construct by hand, and bare atoms
+(the `n` in `direction(n)`) are zero-arity predicates:
+
+```python
+from aspalchemy import Predicate, Variable
+
+X = Variable("X")  # an ASP variable
+n = Predicate.define("n", [], show=False)()  # a bare atom: n, distinct from the string "n"
+```
+
+### Predicates
+
+Declare predicates as classes; fields are statically checked, so typos and
+missing arguments are type errors, and instances autocomplete:
+
+```python
+from aspalchemy import Predicate, PredicateField
+
+class Person(Predicate):
+    name: PredicateField
+    age: PredicateField
+
+john = Person(name="john", age=30)
+mary = Person(name="mary", age=25)
+```
+
+The ASP name defaults to the class name, snake-cased (HasSymbol becomes
+has_symbol); class kwargs override it and set namespacing and visibility (`class Pipe(Predicate, name="pipe_seg",
+show=False)`). When the schema is only known at runtime, build the same thing
+dynamically:
+
+```python
+Edge = Predicate.define("edge", ["a", "b"])
+```
+
+For fully typed fields, annotate them as `Field[int]`, `Field[str]`, or
+`Field[SomePredicate]`. Writes accept rule terms (Variables, Expressions) as
+well as ground values, and are validated per field; reads are plain Python
+values, statically typed — so solution atoms come back as real ints and strs:
+
+```python
+from aspalchemy import ASPProgram, Field, Predicate
+
+class Score(Predicate):
+    player: Field[str]
+    points: Field[int]
+
+program = ASPProgram()
+program.fact(Score(player="ada", points=3), Score(player="ben", points=5))
+model = program.solve().first()  # raises UnsatisfiableError if there is no model
+total = sum(score.points for score in model.atoms(Score))  # plain ints
+assert total == 8
+```
+
+### Rules
+
+Build rules with clear syntax:
+
+```python
+from aspalchemy import ANY, ASPProgram, Variable
+
+program = ASPProgram()
+X, Y = Variable("X"), Variable("Y")
+Adult = Predicate.define("adult", ["name"])
+
+# Facts
+program.fact(john)
+program.fact(mary)
+
+# Rules
+program.when(Person(name=X, age=Y), Y >= 18).derive(Adult(name=X))
+
+# Constraints
+program.forbid(Person(name=ANY, age=Y), Y < 0)
+```
+
+### Comparisons
+
+Compare terms:
+
+```python
+X < Y  # Creates a comparison X < Y
+```
+
+### Aggregates
+
+Use aggregates for advanced computations:
+
+```python
+from aspalchemy import ANY, Count, Variable
+
+X = Variable("X")
+count = Count(X, Person(name=X, age=ANY)) > 5
+```
+
+### Solving
+
+Solve your ASP program:
+
+```python
+# Generate ASP code
+asp_code = program.render()
+print(asp_code)
+
+# Solve
+result = program.solve()  # a lazy stream: consume the models you want
+for model in result:
+    print("Solution found:")
+    for adult in model.atoms(Adult):
+        print(f"  {adult}")
+print(f"Satisfiable: {result.satisfiable}")
+```
+
+### Diagnostics point at your code
+
+Every statement remembers the Python line that authored it. A `when()` left
+unclosed reports where it was opened; grounding diagnostics from clingo carry
+a "generated by file:line" note back to your source;
+`program.render(annotate=True)` appends a trailing `% file:line` comment to
+each rule — without changing line numbers, so the annotated text doubles as
+a map from raw-clingo error lines back to your source; and when a grounding
+is slow or huge, `program.ground().analyze_grounding()` reports ground-atom
+counts per signature, largest first, each joined back to the lines that
+derive it. Frameworks built on
+aspalchemy call `register_skip_package()` (whole package, or per-module dotted
+prefixes) so locations point at *their* caller's code; mark a single helper
+with `@attribute_to_caller` to attribute its statements to its call sites.
+Switch capture off with `ASPProgram(source_locations=False)` when
+generating rules in bulk.
+
+## Requirements
+
+- Python 3.14+
+- clingo 5.8+
+
+## License
+
+MIT License

aspalchemy-1.0.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "aspalchemy"
+version = "1.0.0"
+description = "A Python ORM interface for building and solving clingo ASP programs"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+readme = "docs/README.md"
+requires-python = ">=3.14"
+authors = [{ name = "Jolyon Bloomfield", email = "jolyonb84@gmail.com" }]
+dependencies = ["clingo>=5.8.0,<6"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1",
+    "pre-commit>=4.6",
+    "pyright>=1.1.411",
+    "ruff>=0.15",
+    "pytest>=9.1",
+    "ty>=0.0.56",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# Internal docs and OS litter must not ship in the wheel
+source-exclude = ["src/aspalchemy/CLAUDE.md", "**/.DS_Store"]
+
+[tool.mypy]
+python_version = "3.14"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+strict_optional = true
+files = ["src", "tests"]
+
+[tool.pyright]
+include = ["src", "tests"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["A", "B", "C4", "E", "F", "I", "Q", "RET", "RUF", "SIM", "UP", "W"]
+# RUF001/RUF002/RUF003: flag legitimate typography ("9×9 grid") as ambiguous unicode
+ignore = [
+    "RUF001", "RUF002", "RUF003",  # legitimate typography (9×9 grids)
+    "SIM300",  # 'yoda' flips change which operand builds the ASP Comparison, churning rendered output
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aspalchemy"]
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src/aspalchemy"]
+addopts = "--doctest-modules"
+markers = [
+    "allow_invalid_render: opt this test out of the suite-wide render parse-check (for tests exercising invalid-program error handling)",
+]
+python_files = "test_*.py"
+python_functions = "test_*"
+
+[tool.coverage.run]
+source = ["aspalchemy"]
+
+[tool.coverage.report]
+# Line coverage of aspalchemy must be total. Genuinely unexecutable lines are
+# excluded here (not with scattered pragmas): abstract-method bodies that
+# subclasses always override, and type-checking-only imports.
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod",
+]

aspalchemy-1.0.0/src/aspalchemy/__init__.py

@@ -0,0 +1,171 @@
+"""
+ASPAlchemy: A Python library for building clingo ASP (Answer Set Programming) programs
+with a clean, object-oriented interface.
+"""
+
+from .aggregates import (
+    Aggregate,
+    Count,
+    Max,
+    Min,
+    Sum,
+    SumPlus,
+)
+from .choice import CardinalityType, Choice
+from .clingo_handler import ClingoMessage, LogLevel
+from .conditional_literal import ConditionalLiteral
+from .conditioned_element import ConditionedElement, ConditionType
+from .core import (
+    ANY,
+    INF,
+    SUP,
+    BasicTerm,
+    ComparableTerm,
+    Comparison,
+    Compl,
+    ConstantBase,
+    DefaultNegation,
+    DefinedConstant,
+    ExplicitPool,
+    Expression,
+    Infimum,
+    Negatable,
+    Not,
+    Number,
+    Pool,
+    PredicateOccurrence,
+    RangePool,
+    RenderingContext,
+    String,
+    Supremum,
+    Term,
+    V,
+    Value,
+    Variable,
+    Vars,
+    pool,
+)
+from .exceptions import ASPAlchemyError, GroundingError, UnsatisfiableError
+from .operators import ComparisonOperator, Operation
+from .optimization import OptStrategy
+from .predicate import Field, FieldAsTermType, NegatedSignature, Predicate, PredicateField, TupleTermType
+from .program_elements import ProgramElement, RenderedLine
+from .segment import Segment, When
+from .solve_result import (
+    AtomCollection,
+    BraveConsequences,
+    CautiousConsequences,
+    Consequences,
+    CostedModel,
+    Model,
+    OptimizeSteps,
+    Optimum,
+    PredicateTypes,
+    RefinementSteps,
+    Search,
+    SolveResult,
+    convert_predicate_to_symbol,
+    convert_symbol_to_predicate,
+)
+from .solver import ASPProgram, GroundedProgram, SignatureGrounding
+from .source_location import (
+    SourceLocation,
+    attribute_to_caller,
+    capture_location,
+    location_override,
+    register_skip_package,
+)
+from .version import __version__
+
+__all__ = [  # noqa: RUF022 (categorized deliberately, not sorted)
+    # The program and its results
+    "ASPProgram",
+    "Segment",
+    "When",
+    "GroundedProgram",
+    "SignatureGrounding",
+    "SolveResult",
+    "Model",
+    "CostedModel",
+    "AtomCollection",
+    "Consequences",
+    "BraveConsequences",
+    "CautiousConsequences",
+    "RefinementSteps",
+    "OptimizeSteps",
+    "Optimum",
+    "OptStrategy",
+    "Search",
+    "LogLevel",
+    "ClingoMessage",
+    "ASPAlchemyError",
+    "GroundingError",
+    "UnsatisfiableError",
+    "RenderedLine",
+    # Source locations (diagnostics point at the authoring Python line)
+    "SourceLocation",
+    "capture_location",
+    "register_skip_package",
+    "attribute_to_caller",
+    "location_override",
+    # Declaring predicates
+    "Predicate",
+    "NegatedSignature",
+    "Field",
+    "PredicateField",
+    # Rule-building objects
+    "Variable",
+    "ANY",
+    "V",
+    "Vars",
+    "Choice",
+    "ConditionalLiteral",
+    "RangePool",
+    "ExplicitPool",
+    "SUP",
+    "INF",
+    # Aggregates
+    "Count",
+    "Sum",
+    "SumPlus",
+    "Min",
+    "Max",
+    # Rule-building utilities
+    "pool",
+    "Not",
+    "Compl",
+    # Hierarchy types: these appear in public signatures and return types —
+    # annotate with them; you rarely construct them directly
+    "ConditionType",
+    "ConditionedElement",
+    "TupleTermType",
+    "CardinalityType",
+    "PredicateTypes",
+    "FieldAsTermType",
+    "PredicateOccurrence",
+    "Term",
+    "BasicTerm",
+    "Value",
+    "ConstantBase",
+    "ComparableTerm",
+    "Negatable",
+    "ProgramElement",
+    "Expression",
+    "Comparison",
+    "ComparisonOperator",
+    "Operation",
+    "RenderingContext",
+    "DefaultNegation",
+    "DefinedConstant",
+    "Aggregate",
+    "Pool",
+    "Number",
+    "String",
+    "Supremum",
+    "Infimum",
+    # Interop with raw clingo symbols
+    "convert_predicate_to_symbol",
+    "convert_symbol_to_predicate",
+    # Metadata
+    "__version__",
+]