arg2p 0.19.0__py3-none-win_amd64.whl

arg2p/__init__.py

@@ -0,0 +1,63 @@
+"""
+Arg2P from Python: structured argumentation in Prolog (ASPIC+, ABA, abstract frameworks, ...), the library of the JVM
+run through JPype, on the Java runtime the package bundles.
+
+    >>> from arg2p import Arg2p
+    >>> Arg2p.of("r1 : [] => a.\nr2 : [] => -a.\nsup(r1, r2).").answer("a").in_statements
+    ['a']
+"""
+
+from .arg2p import Answer, Arg2p, Arg2pError, Builder, Causality, Solution, Solutions
+from .flags import (
+    ConflictModel,
+    Flags,
+    GraphBuilder,
+    GraphExtension,
+    GraphLanguage,
+    OrderingComparator,
+    OrderingPrinciple,
+    Profile,
+    Semantics,
+    StatementLabelling,
+)
+from .model import Argument, Attack, Graph, LabelledArgument, Support
+from .parallel import EvaluationResponse, LocalCluster, Response, ThreadedCluster
+from .values import Struct, Value, Var
+
+try:
+    from ._version import __version__
+except ImportError:  # a package built without Gradle
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Answer",
+    "Arg2p",
+    "Arg2pError",
+    "Argument",
+    "Attack",
+    "Builder",
+    "Causality",
+    "ConflictModel",
+    "EvaluationResponse",
+    "Flags",
+    "Graph",
+    "GraphBuilder",
+    "GraphExtension",
+    "GraphLanguage",
+    "LabelledArgument",
+    "LocalCluster",
+    "OrderingComparator",
+    "OrderingPrinciple",
+    "Profile",
+    "Response",
+    "Semantics",
+    "Solution",
+    "Solutions",
+    "StatementLabelling",
+    "Struct",
+    "Support",
+    "ThreadedCluster",
+    "Value",
+    "Var",
+    "__version__",
+]

arg2p/__main__.py

@@ -0,0 +1,49 @@
+"""The labels of the statements of a theory, from the command line: python -m arg2p theory.pl [-q query] ..."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional
+
+from .arg2p import Arg2p, Arg2pError
+from .flags import Flags, Profile, Semantics
+from .values import text
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="arg2p", description="Evaluates a theory of arg2p.")
+    parser.add_argument("theory", help="the file of the theory (- for the standard input)")
+    parser.add_argument("-q", "--query", action="append", help="a statement to evaluate (all of them by default)")
+    parser.add_argument("-p", "--profile", choices=[it.value for it in Profile], help="the profile of the theory")
+    parser.add_argument("-s", "--semantics", choices=[it.value for it in Semantics], help="the semantics")
+    arguments = parser.parse_args(argv)
+    theory = sys.stdin.read() if arguments.theory == "-" else open(arguments.theory, encoding="utf-8").read()
+    flags = Flags.defaults()
+    if arguments.profile:
+        flags.graph_build_mode(Profile(arguments.profile))
+    if arguments.semantics:
+        flags.argument_labelling_mode(Semantics(arguments.semantics))
+    try:
+        arg2p = Arg2p.of(theory, flags)
+        if arguments.query:
+            for query in arguments.query:
+                answer = arg2p.answer(query)
+                print(
+                    f"{query}: in {text(answer.in_statements)}, out {text(answer.out_statements)}, "
+                    f"und {text(answer.und_statements)}"
+                )
+        else:
+            for index, graph in enumerate(arg2p.graphs()):
+                if index:
+                    print()
+                for label in ("in", "out", "und"):
+                    print(f"{label}: {', '.join(sorted(graph.conclusions(label)))}")
+    except Arg2pError as error:
+        print(f"arg2p: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

arg2p/_jvm.py

@@ -0,0 +1,145 @@
+"""The JVM running arg2p: started once, at the first use, with the jars of the package, on the Java runtime it
+bundles (that of the system, for a package without one)."""
+
+from __future__ import annotations
+
+import glob
+import os
+import sys
+import threading
+from typing import Any, Callable, TypeVar
+
+import jpype
+
+T = TypeVar("T")
+
+_lock = threading.Lock()
+
+#: The jars of the package, copied there by ``./gradlew :python:pythonJars``
+JARS = os.path.join(os.path.dirname(__file__), "jars")
+
+#: The Java runtime the package bundles, made there by ``./gradlew :python:pythonRuntime``
+RUNTIME = os.path.join(os.path.dirname(__file__), "jre")
+
+#: The stack of the threads of the JVM: resolution goes deep (the tests of arg2p run with the same)
+STACK = os.environ.get("ARG2P_STACK", "512m")
+
+
+def classpath() -> list[str]:
+    """The jars of arg2p: those of ``ARG2P_CLASSPATH`` if set, those of the package otherwise."""
+    stated = os.environ.get("ARG2P_CLASSPATH")
+    if stated:
+        return stated.split(os.pathsep)
+    jars = sorted(glob.glob(os.path.join(JARS, "*.jar")))
+    if not jars:
+        raise RuntimeError(
+            "No jar of arg2p in " + JARS + ": copy them with ./gradlew :python:pythonJars, "
+            "or set ARG2P_CLASSPATH"
+        )
+    return jars
+
+
+def jvm_path() -> str:
+    """
+    The library of the JVM: that of ``ARG2P_JVM`` if set, of the runtime the package bundles if it does, of the system
+    otherwise (JAVA_HOME, or where JPype finds one).
+    """
+    stated = os.environ.get("ARG2P_JVM")
+    if stated:
+        return stated
+    library = {"win32": ("bin", "server", "jvm.dll"), "darwin": ("lib", "server", "libjvm.dylib")}.get(
+        sys.platform, ("lib", "server", "libjvm.so")
+    )
+    bundled = os.path.join(RUNTIME, *library)
+    return bundled if os.path.exists(bundled) else jpype.getDefaultJVMPath()
+
+
+def start() -> None:
+    """Starts the JVM, unless it runs already (started by another library: the jars of arg2p must be on its path)."""
+    with _lock:
+        if not jpype.isJVMStarted():
+            jpype.startJVM(
+                jvm_path(), f"-Xss{STACK}", "-Dslf4j.internal.verbosity=ERROR", classpath=classpath(), convertStrings=True
+            )
+
+
+def jclass(name: str) -> Any:
+    """The Java class [name], the JVM started."""
+    start()
+    return jpype.JClass(name)
+
+
+@jpype.JImplements("java.lang.Runnable", deferred=True)
+class _Task:
+    def __init__(self, function: Callable[[], Any]) -> None:
+        self.function = function
+        self.value: Any = None
+        self.error: BaseException | None = None
+
+    @jpype.JOverride
+    def run(self) -> None:
+        try:
+            self.value = self.function()
+        except BaseException as error:  # noqa: BLE001 - raised again by the caller
+            self.error = error
+
+
+@jpype.JImplements("java.util.concurrent.ThreadFactory", deferred=True)
+class _Threads:
+    @jpype.JOverride
+    def newThread(self, runnable: Any) -> Any:
+        # daemons, not to hold the JVM when Python exits; their stack is the one of -Xss (see STACK)
+        thread = jpype.JClass("java.lang.Thread")(runnable, _THREAD)
+        thread.setDaemon(True)
+        return thread
+
+
+_THREAD = "arg2p"
+_pool: Any = None
+
+
+def _threads() -> Any:
+    """The threads running arg2p, made as calls need them and kept for the next ones (a minute idle)."""
+    global _pool
+    with _lock:
+        if _pool is None:
+            _pool = jpype.JClass("java.util.concurrent.Executors").newCachedThreadPool(_Threads())
+    return _pool
+
+
+def run(function: Callable[[], T]) -> T:
+    """The result of [function], run on a thread of the JVM, whose stack resolution needs (see STACK)."""
+    start()
+    if str(jpype.JClass("java.lang.Thread").currentThread().getName()) == _THREAD:
+        return function()  # already on one
+    task = _Task(function)
+    _threads().submit(task).get()
+    if task.error is not None:
+        raise task.error
+    return task.value
+
+
+@jpype.JImplements("kotlin.jvm.functions.Function1", deferred=True)
+class _Function:
+    def __init__(self, function: Callable[[Any], Any]) -> None:
+        self.function = function
+
+    @jpype.JOverride
+    def invoke(self, value: Any) -> Any:
+        return self.function(value)
+
+
+def function1(function: Callable[[Any], Any]) -> Any:
+    """[function] as a Kotlin function of one argument returning Unit."""
+    unit = jclass("kotlin.Unit").INSTANCE
+
+    def invoke(value: Any) -> Any:
+        function(value)
+        return unit
+
+    return _Function(invoke)
+
+
+def jarray(name: str, values: list[Any]) -> Any:
+    """A Java array of the class [name], of [values]."""
+    return jpype.JArray(jclass(name))(values)

arg2p/_version.py

@@ -0,0 +1,2 @@
+# Generated by the build (./gradlew :python:pythonVersion): the version of arg2p
+__version__ = "0.19.0"

arg2p/arg2p.py

@@ -0,0 +1,271 @@
+"""A solver of arg2p: its answers, graphs and solutions, and the causality tests on its theory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterator, Optional
+
+import jpype
+
+from . import _jvm
+from .flags import Flags
+from .model import Graph, graph_from_jvm
+from .values import Value, from_jvm
+
+_API = "it.unibo.tuprolog.argumentation"
+
+
+class Arg2pError(Exception):
+    """An evaluation halted by an error: a theory its profile refuses, a goal that cannot be parsed, ..."""
+
+
+def call(function: Callable[[], Any]) -> Any:
+    """The result of [function], run on a thread of the JVM, an exception of arg2p raised as an Arg2pError."""
+
+    def guarded() -> Any:
+        try:
+            return function()
+        except jpype.JException as error:
+            if error.getClass().getName() == f"{_API}.Arg2pException":
+                raise Arg2pError(str(error.getMessage())) from None
+            raise
+
+    return _jvm.run(guarded)
+
+
+@dataclass(frozen=True)
+class Answer:
+    """The statements for a query labelled in, out and und (see Arg2p.answer)."""
+
+    in_statements: list[Value] = field(default_factory=list)
+    out_statements: list[Value] = field(default_factory=list)
+    und_statements: list[Value] = field(default_factory=list)
+    # the answer of the library of the JVM, for label
+    _answer: Any = field(default=None, compare=False, repr=False)
+
+    def label(self, statement: str) -> Optional[str]:
+        """The label of [statement], Prolog text: in, out or und, None for a statement the query did not label."""
+        if self._answer is None:
+            raise ValueError("Not the answer of a solver")
+        label = call(lambda: self._answer.label(statement))
+        return None if label is None else str(label)
+
+
+class Solution:
+    """A solution of a goal: yes, no or halt (an error), with the values a yes solution binds to its variables."""
+
+    def __init__(self, solution: Any) -> None:
+        self._solution = solution
+
+    @property
+    def is_yes(self) -> bool:
+        return bool(self._solution.isYes())
+
+    @property
+    def is_no(self) -> bool:
+        return bool(self._solution.isNo())
+
+    @property
+    def is_halt(self) -> bool:
+        return bool(self._solution.isHalt())
+
+    @property
+    def query(self) -> str:
+        """The goal, as a yes solution solves it (its variables bound), otherwise as it was asked, as Prolog text."""
+        return str(self._solution.getQuery())
+
+    @property
+    def error(self) -> Optional[str]:
+        """The error of a halt solution."""
+        error = self._solution.getError()
+        return None if error is None else str(error)
+
+    @property
+    def variables(self) -> list[str]:
+        """The variables of the goal a yes solution binds."""
+        return [str(name) for name in self._solution.getVariables()]
+
+    @property
+    def bindings(self) -> dict[str, Value]:
+        """The values a yes solution binds to the variables of the goal, by their names."""
+        return {str(entry.getKey()): from_jvm(entry.getValue()) for entry in self._solution.getBindings().entrySet()}
+
+    def value(self, name: str) -> Optional[Value]:
+        """The value a yes solution binds to the variable of the goal named [name]."""
+        value = self._solution.value(name)
+        return None if value is None else from_jvm(value)
+
+    def text(self, name: str) -> Optional[str]:
+        """The value a yes solution binds to the variable of the goal named [name], as Prolog text."""
+        written = self._solution.text(name)
+        return None if written is None else str(written)
+
+    def __repr__(self) -> str:
+        return str(self._solution.toString())
+
+
+class Solutions:
+    """The solutions of a goal, computed one at a time as they are asked for: with has_next and next, or iterated."""
+
+    def __init__(self, solutions: Any) -> None:
+        self._solutions = solutions
+
+    def has_next(self) -> bool:
+        return bool(_jvm.run(self._solutions.hasNext))
+
+    def next(self) -> Solution:
+        return Solution(_jvm.run(self._solutions.next))
+
+    def to_list(self, limit: Optional[int] = None) -> list[Solution]:
+        """The solutions left, at most [limit] of them."""
+        return [Solution(it) for it in _jvm.run(lambda: self._solutions.toList(2**31 - 1 if limit is None else limit))]
+
+    def __iter__(self) -> Iterator[Solution]:
+        return self
+
+    def __next__(self) -> Solution:
+        # the next solution, if there is one, in a single call
+        found = _jvm.run(lambda: self._solutions.next() if self._solutions.hasNext() else None)
+        if found is None:
+            raise StopIteration
+        return Solution(found)
+
+
+class Causality:
+    """
+    Whether a statement of the theory of a solver causes another, on the grounded labelling of the theory and of its
+    interventions: the NESS test, as published (Pisano, Prakken, Sartor, Liepina; ICAIL 2025) and revised, and the
+    but-for test. The statements are Prolog text; an intervention is a list of statements.
+    """
+
+    def __init__(self, causality: Any) -> None:
+        self._causality = causality
+
+    def ness(self, cause: str, effect: str) -> Optional[Value]:
+        """Whether [cause] is a NESS cause of [effect] (the revised condition): the intervention, None if it is not."""
+        return _optional(call(lambda: self._causality.ness(cause, effect)))
+
+    def ness_original(self, cause: str, effect: str) -> Optional[Value]:
+        """Whether [cause] is a NESS cause of [effect] as published: the intervention, None if it is not."""
+        return _optional(call(lambda: self._causality.nessOriginal(cause, effect)))
+
+    def ness_intervention(self, intervention: str, effect: str) -> bool:
+        """Whether [intervention], a list of statements, meets the revised NESS condition for [effect]."""
+        return bool(call(lambda: self._causality.nessIntervention(intervention, effect)))
+
+    def ness_original_intervention(self, intervention: str, effect: str) -> bool:
+        """Whether [intervention], a list of statements, meets the NESS condition for [effect] as published."""
+        return bool(call(lambda: self._causality.nessOriginalIntervention(intervention, effect)))
+
+    def but_for(self, cause: str, effect: str) -> bool:
+        """Whether [cause] is a but-for cause of [effect]."""
+        return bool(call(lambda: self._causality.butFor(cause, effect)))
+
+
+def _optional(value: Any) -> Optional[Value]:
+    return None if value is None else from_jvm(value)
+
+
+class Arg2p:
+    """
+    A solver of arg2p for a theory, as Prolog text, with its flags: it answers queries (answer), gives the graph of
+    each labelling (graphs), solves Prolog goals (solve) and tests causality (causality).
+
+        >>> Arg2p.of("r1 : [] => a.\\nr2 : [] => -a.\\nsup(r1, r2).").answer("a").in_statements
+        ['a']
+
+    The context of the solver keeps a branch for every stage of a resolution, numbered from 0: active_branch is the
+    last one, graph_at the graph of any of them, and context_facts what a branch stores.
+    """
+
+    def __init__(self, arg2p: Any) -> None:
+        self._arg2p = arg2p
+        self.causality = Causality(arg2p.getCausality())
+
+    @staticmethod
+    def of(theory: str = "", flags: Optional[Flags] = None) -> Arg2p:
+        """A solver of arg2p for [theory], Prolog text, with [flags] (Flags.defaults() otherwise)."""
+        return Arg2p.builder().theory(theory).flags(flags or Flags.defaults()).build()
+
+    @staticmethod
+    def builder() -> Builder:
+        """A solver of arg2p, as it is described."""
+        return Builder()
+
+    @staticmethod
+    def version() -> str:
+        """The version of arg2p, the released one for a release."""
+        return str(_jvm.jclass(f"{_API}.Arg2p").version())
+
+    @property
+    def theory(self) -> str:
+        """The theory, as Prolog text."""
+        return str(self._arg2p.getTheory())
+
+    def answer(self, query: str) -> Answer:
+        """The statements for [query], Prolog text, labelled in, out and und (raises Arg2pError if it halts)."""
+        answer = call(lambda: self._arg2p.answer(query))
+        return Answer(
+            [from_jvm(it) for it in answer.getInStatements()],
+            [from_jvm(it) for it in answer.getOutStatements()],
+            [from_jvm(it) for it in answer.getUndStatements()],
+            answer,
+        )
+
+    def graphs(self) -> list[Graph]:
+        """The graph of each labelling of the theory: several for a semantics with several (preferred, stable, ...)."""
+        return call(lambda: [graph_from_jvm(graph) for graph in self._arg2p.graphs()])
+
+    def graph(self) -> Graph:
+        """The graph of the last resolution: the one of its last stage."""
+        return call(lambda: graph_from_jvm(self._arg2p.graph()))
+
+    def graph_at(self, branch: int) -> Graph:
+        """The graph of the context branch [branch]."""
+        return call(lambda: graph_from_jvm(self._arg2p.graphAt(branch)))
+
+    @property
+    def active_branch(self) -> int:
+        """The context branch of the last stage of the last resolution."""
+        return int(call(self._arg2p.getActiveBranch))
+
+    def solve(self, goal: str) -> Solutions:
+        """The solutions of [goal], Prolog text, computed one at a time as they are asked for."""
+        return Solutions(call(lambda: self._arg2p.solve(goal)))
+
+    def context_facts(self, branch: int, goal: str) -> Solutions:
+        """What the context branch [branch] stores matching [goal], Prolog text: the solutions of context_check/2."""
+        return Solutions(call(lambda: self._arg2p.contextFacts(branch, goal)))
+
+    def add(self, theory: str) -> None:
+        """Adds the clauses of [theory], Prolog text, to the theory."""
+        call(lambda: self._arg2p.add(theory))
+
+    def load(self, theory: str) -> None:
+        """Replaces the theory with [theory], Prolog text."""
+        call(lambda: self._arg2p.load(theory))
+
+
+class Builder:
+    """A solver of arg2p, as it is described: its theory, its flags, and where what it prints goes."""
+
+    def __init__(self) -> None:
+        self._builder = _jvm.jclass(f"{_API}.Arg2p").builder()
+
+    def theory(self, theory: str) -> Builder:
+        """The theory, as Prolog text."""
+        self._builder.theory(theory)
+        return self
+
+    def flags(self, flags: Flags) -> Builder:
+        """The flags (Flags.defaults() otherwise)."""
+        self._builder.flags(flags.jvm())
+        return self
+
+    def output(self, consumer: Callable[[str], Any]) -> Builder:
+        """The function receiving what the solver prints (the standard output otherwise)."""
+        self._builder.output(_jvm.function1(lambda printed: consumer(str(printed))))
+        return self
+
+    def build(self) -> Arg2p:
+        return Arg2p(call(self._builder.build))