arguebuf 2.7.2__tar.gz → 3.0.0__tar.gz

{arguebuf-2.7.2/src/arguebuf.egg-info → arguebuf-3.0.0}/PKG-INFO

@@ -1,28 +1,33 @@
 Metadata-Version: 2.4
 Name: arguebuf
-Version: 2.7.2
+Version: 3.0.0
 Summary: Create and analyze argument graphs and serialize them via Protobuf
+Keywords: argument-graph,argument-mining,argumentation,nlp,protobuf
+Author: Mirko Lenz
 Author-email: Mirko Lenz <mirko@mirkolenz.com>
-Project-URL: Repository, https://github.com/recap-utr/arguebuf-python
+License-Expression: MIT
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: arg-services>=2,<3
+Requires-Dist: lxml>=6,<7
+Requires-Dist: networkx>=3,<4
+Requires-Dist: pygraphviz>=2,<3
+Requires-Dist: arg-services[grpcio]>=2,<3 ; extra == 'cli'
+Requires-Dist: deepl>=1,<2 ; extra == 'cli'
+Requires-Dist: typer>=0.27,<0.28 ; extra == 'cli'
+Requires-Python: >=3.13, <4
+Project-URL: Changelog, https://github.com/recap-utr/arguebuf-python/releases
 Project-URL: Documentation, https://arguebuf.readthedocs.io
 Project-URL: Issues, https://github.com/recap-utr/arguebuf-python/issues
-Project-URL: Changelog, https://github.com/recap-utr/arguebuf-python/releases
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: arg-services<2,>=1
-Requires-Dist: networkx<4,>=3
-Requires-Dist: pendulum<4,>=3
-Requires-Dist: graphviz<1,>=0.20
-Requires-Dist: lxml<6,>=5
-Provides-Extra: all
-Requires-Dist: arguebuf[cli,graphviz]; extra == "all"
+Project-URL: Repository, https://github.com/recap-utr/arguebuf-python
 Provides-Extra: cli
-Requires-Dist: typer<1,>=0.9; extra == "cli"
-Requires-Dist: deepl<2,>=1; extra == "cli"
-Provides-Extra: graphviz
-Requires-Dist: pygraphviz<2,>=1; extra == "graphviz"
-Dynamic: license-file
+Description-Content-Type: text/markdown
 
 # Arguebuf Python
 
@@ -117,8 +122,9 @@ This also makes it really easy to integrate the popular [`spacy` library](http:/
 
 ```python
 import spacy
+
 nlp = spacy.load("en_core_web_lg")
-graph = ag.load.file("graph.json", nlp=nlp)
+graph = ag.load.file("graph.json", config=ag.load.Config(nlp=nlp))
 ```
 
 ### Programmatically Create a New Graph

{arguebuf-2.7.2 → arguebuf-3.0.0}/README.md

@@ -91,8 +91,9 @@ This also makes it really easy to integrate the popular [`spacy` library](http:/
 
 ```python
 import spacy
+
 nlp = spacy.load("en_core_web_lg")
-graph = ag.load.file("graph.json", nlp=nlp)
+graph = ag.load.file("graph.json", config=ag.load.Config(nlp=nlp))
 ```
 
 ### Programmatically Create a New Graph

arguebuf-3.0.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "arguebuf"
+version = "3.0.0"
+description = "Create and analyze argument graphs and serialize them via Protobuf"
+readme = "README.md"
+requires-python = ">=3.13,<4"
+license = "MIT"
+keywords = [
+    "argument-graph",
+    "argument-mining",
+    "argumentation",
+    "nlp",
+    "protobuf",
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "arg-services>=2,<3",
+    "lxml>=6,<7",
+    "networkx>=3,<4",
+    "pygraphviz>=2,<3",
+]
+
+[[project.authors]]
+name = "Mirko Lenz"
+email = "mirko@mirkolenz.com"
+
+[project.urls]
+Changelog = "https://github.com/recap-utr/arguebuf-python/releases"
+Documentation = "https://arguebuf.readthedocs.io"
+Issues = "https://github.com/recap-utr/arguebuf-python/issues"
+Repository = "https://github.com/recap-utr/arguebuf-python"
+
+[project.scripts]
+arguebuf = "arguebuf.cli.app:cli"
+
+[project.optional-dependencies]
+cli = [
+    "arg-services[grpcio]>=2,<3",
+    "deepl>=1,<2",
+    "typer>=0.27,<0.28",
+]
+
+[dependency-groups]
+dev = [
+    "lxml-stubs>=0.5,<0.6",
+    "types-networkx>=3,<4",
+    { include-group = "docs" },
+    { include-group = "test" },
+]
+docs = ["pdoc>=16,<17"]
+test = [
+    "deepdiff>=9,<10",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "pytest-xdist>=3,<4",
+]
+
+[build-system]
+requires = ["uv-build>=0.13,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest]
+addopts = [
+    "--numprocesses=auto",
+    "--cov=arguebuf",
+    "--cov-report=term-missing",
+    "--doctest-modules",
+    "--ignore=src/arguebuf/cli",
+]
+doctest_optionflags = [
+    "ELLIPSIS",
+    "IGNORE_EXCEPTION_DETAIL",
+    "NORMALIZE_WHITESPACE",
+]
+testpaths = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["arguebuf.load._config.Config"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.uv.exclude-newer-package]
+arg-services = false

arguebuf-3.0.0/pyproject.toml.orig

@@ -0,0 +1,77 @@
+[project]
+name = "arguebuf"
+version = "3.0.0"
+description = "Create and analyze argument graphs and serialize them via Protobuf"
+readme = "README.md"
+requires-python = ">=3.13,<4"
+license = "MIT"
+authors = [{ name = "Mirko Lenz", email = "mirko@mirkolenz.com" }]
+keywords = ["argument-graph", "argument-mining", "argumentation", "nlp", "protobuf"]
+classifiers = [
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = [
+  "arg-services>=2,<3",
+  "lxml>=6,<7",
+  "networkx>=3,<4",
+  "pygraphviz>=2,<3",
+]
+
+[project.urls]
+Changelog = "https://github.com/recap-utr/arguebuf-python/releases"
+Documentation = "https://arguebuf.readthedocs.io"
+Issues = "https://github.com/recap-utr/arguebuf-python/issues"
+Repository = "https://github.com/recap-utr/arguebuf-python"
+
+[project.scripts]
+arguebuf = "arguebuf.cli.app:cli"
+
+[project.optional-dependencies]
+cli = ["arg-services[grpcio]>=2,<3", "deepl>=1,<2", "typer>=0.27,<0.28"]
+
+[dependency-groups]
+dev = [
+  "lxml-stubs>=0.5,<0.6",
+  "types-networkx>=3,<4",
+  { include-group = "docs" },
+  { include-group = "test" },
+]
+docs = ["pdoc>=16,<17"]
+test = [
+  "deepdiff>=9,<10",
+  "pytest>=9,<10",
+  "pytest-cov>=7,<8",
+  "pytest-xdist>=3,<4",
+]
+
+[build-system]
+requires = ["uv-build>=0.13,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest]
+addopts = [
+  "--numprocesses=auto",
+  "--cov=arguebuf",
+  "--cov-report=term-missing",
+  "--doctest-modules",
+  "--ignore=src/arguebuf/cli",
+]
+doctest_optionflags = ["ELLIPSIS", "IGNORE_EXCEPTION_DETAIL", "NORMALIZE_WHITESPACE"]
+testpaths = ["src", "tests"]
+
+[tool.ruff.lint.flake8-bugbear]
+# frozen and thus safe to use as default argument
+extend-immutable-calls = ["arguebuf.load._config.Config"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.uv.exclude-newer-package]
+arg-services = false

{arguebuf-2.7.2 → arguebuf-3.0.0}/src/arguebuf/__init__.py

@@ -30,32 +30,29 @@ from .utils import copy
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 __all__ = (
-    # submodules
-    "load",
-    "dump",
-    "render",
-    "traverse",
-    "schemas",
-    "model",
-    # functions
-    "uuid",
-    "copy",
-    # classes
-    "Graph",
+    "AbstractNode",
+    "Analyst",
     "AtomNode",
-    "SchemeNode",
+    "AtomOrSchemeNode",
+    "Attack",
     "Edge",
+    "Graph",
     "Metadata",
-    "Userdata",
-    "Analyst",
     "Participant",
-    "Resource",
+    "Preference",
     "Reference",
-    "AbstractNode",
-    "AtomOrSchemeNode",
+    "Rephrase",
+    "Resource",
     "Scheme",
+    "SchemeNode",
     "Support",
-    "Attack",
-    "Rephrase",
-    "Preference",
+    "Userdata",
+    "copy",
+    "dump",
+    "load",
+    "model",
+    "render",
+    "schemas",
+    "traverse",
+    "uuid",
 )

{arguebuf-2.7.2 → arguebuf-3.0.0}/src/arguebuf/cli/app.py

@@ -2,7 +2,10 @@ from typer import Typer
 
 from . import graph, server, text
 
-cli = Typer()
+cli = Typer(
+    help="Convert, render, translate, and serve argument graphs.",
+    no_args_is_help=True,
+)
 cli.add_typer(
     graph.cli, name="graph", help="Commands for dealing with argument graphs."
 )

arguebuf-3.0.0/src/arguebuf/cli/graph.py

@@ -0,0 +1,240 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from deepl import DeepLClient
+
+import arguebuf as ag
+
+from . import model
+from .translator import Translator
+
+cli = typer.Typer(no_args_is_help=True)
+
+OutputFormat = Annotated[
+    ag.dump.Format, typer.Option(help="Format of the exported graphs.")
+]
+
+
+@cli.command()
+def translate(
+    input_folder: model.InputFolder,
+    source_lang: model.SourceLang,
+    target_lang: model.TargetLang,
+    auth_key: model.AuthKey,
+    input_glob: model.InputGlob,
+    output_folder: model.OutputFolder = None,
+    output_format: OutputFormat = ag.dump.Format.ARGUEBUF,
+    clean: model.Clean = False,
+    overwrite: model.Overwrite = False,
+    start: model.Start = 1,
+) -> None:
+    """Translate the texts of atom nodes, references, and resources with DeepL."""
+    translator = Translator(DeepLClient(auth_key), source_lang, target_lang)
+
+    for path_pair in model.pending_pairs(
+        input_folder, output_folder, input_glob, ".json", clean, overwrite, start
+    ):
+        graph = ag.load.file(path_pair.source)
+        translator.translate_graph(graph)
+        ag.dump.file(graph, path_pair.target, ag.dump.Config(format=output_format))
+
+
+def node_label_formatter(
+    strip_labels: bool, strip_labels_char: str | None
+) -> Callable[[ag.AbstractNode], str] | None:
+    _replace_char = "–" if strip_labels_char is None else strip_labels_char
+
+    def _node_label(node: ag.AbstractNode) -> str:
+        return "".join(char if char.isspace() else _replace_char for char in node.label)
+
+    if strip_labels:
+        return _node_label
+
+    return None
+
+
+@cli.command()
+def render(
+    input_folder: model.InputFolder,
+    input_glob: model.InputGlob,
+    output_folder: model.OutputFolder = None,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            help="Suffix of the rendered files that determines their format,"
+            " e.g., '.pdf', '.png', or '.svg'."
+        ),
+    ] = ".pdf",
+    strip_scheme_nodes: Annotated[
+        bool,
+        typer.Option(help="Remove scheme nodes and connect their atoms directly."),
+    ] = False,
+    strip_node_labels: Annotated[
+        bool,
+        typer.Option(help="Mask node labels, e.g., to show only the structure."),
+    ] = False,
+    strip_node_labels_char: Annotated[
+        str | None,
+        typer.Option(
+            help="Character replacing all non-whitespace characters of masked labels,"
+            " defaults to an en dash.",
+            show_default=False,
+        ),
+    ] = None,
+    edge_style: Annotated[
+        ag.schemas.graphviz.EdgeStyle, typer.Option(help="Shape of the edges.")
+    ] = ag.schemas.graphviz.EdgeStyle.STEP,
+    nodesep: Annotated[
+        float,
+        typer.Option(help="Minimum space between nodes of the same rank in inches."),
+    ] = 0.25,
+    ranksep: Annotated[
+        float, typer.Option(help="Minimum space between ranks in inches.")
+    ] = 0.5,
+    node_wrap_col: Annotated[
+        int, typer.Option(help="Maximum number of characters per line in labels.")
+    ] = 36,
+    node_margin: Annotated[
+        tuple[float, float],
+        typer.Option(help="Horizontal and vertical padding of labels in inches."),
+    ] = (0.15, 0.1),
+    font_name: Annotated[str, typer.Option(help="Font of the labels.")] = "Arial",
+    font_size: Annotated[
+        float, typer.Option(help="Font size of the labels in points.")
+    ] = 11,
+    clean: model.Clean = False,
+    overwrite: model.Overwrite = False,
+    start: model.Start = 1,
+    max_nodes: Annotated[
+        int, typer.Option(help="Skip graphs with more nodes than this limit.")
+    ] = 1000,
+    prog: Annotated[
+        str, typer.Option(help="Graphviz layout engine, e.g., 'dot' or 'neato'.")
+    ] = "dot",
+    dpi: Annotated[
+        int, typer.Option(help="Resolution of raster formats such as PNG.")
+    ] = 300,
+    monochrome: Annotated[
+        bool, typer.Option(help="Render in black and white instead of color.")
+    ] = False,
+) -> None:
+    """Render graphs as images with Graphviz."""
+    label_formatter = node_label_formatter(strip_node_labels, strip_node_labels_char)
+
+    for path_pair in model.pending_pairs(
+        input_folder, output_folder, input_glob, output_format, clean, overwrite, start
+    ):
+        g = ag.load.file(path_pair.source)
+
+        if strip_scheme_nodes:
+            g.strip_scheme_nodes()
+
+        gv = ag.dump.graphviz(
+            g,
+            nodesep=nodesep,
+            ranksep=ranksep,
+            wrap_col=node_wrap_col,
+            margin=node_margin,
+            font_name=font_name,
+            font_size=font_size,
+            atom_label=label_formatter,
+            scheme_label=label_formatter,
+            edge_style=edge_style,
+            max_nodes=max_nodes,
+            monochrome=monochrome,
+        )
+
+        # graphs exceeding `max_nodes` are skipped
+        if gv is not None:
+            ag.render.graphviz(gv, path_pair.target, prog, dpi)
+
+
+@cli.command()
+def convert(
+    input_folder: model.InputFolder,
+    input_glob: model.InputGlob,
+    output_folder: model.OutputFolder = None,
+    output_format: OutputFormat = ag.dump.Format.ARGUEBUF,
+    clean: model.Clean = False,
+    overwrite: model.Overwrite = False,
+    start: model.Start = 1,
+    text_folder: Annotated[
+        Path | None,
+        typer.Option(
+            help="Folder mirroring INPUT_FOLDER with plain texts to add as resources,"
+            " defaults to the text files next to the graphs.",
+            show_default=False,
+        ),
+    ] = None,
+    text_suffix: Annotated[
+        str, typer.Option(help="Suffix of the files in TEXT_FOLDER.")
+    ] = ".txt",
+    reconstruct_dialog: Annotated[
+        bool,
+        typer.Option(
+            help="Connect AIF and xAIF atoms only linked through dialog nodes"
+            " to the atoms of adjacent turns, otherwise they become isolated."
+        ),
+    ] = False,
+) -> None:
+    """Convert graphs between formats, the input format is derived from the suffix."""
+    load_config = ag.load.Config(reconstruct_dialog=reconstruct_dialog)
+    dump_config = ag.dump.Config(format=output_format)
+
+    for path_pair in model.pending_pairs(
+        input_folder, output_folder, input_glob, ".json", clean, overwrite, start
+    ):
+        text_file = (
+            text_folder
+            / path_pair.source.relative_to(input_folder).with_suffix(text_suffix)
+            if text_folder
+            else None
+        )
+        graph = ag.load.file(path_pair.source, text_file=text_file, config=load_config)
+        ag.dump.file(graph, path_pair.target, dump_config)
+
+
+@cli.command()
+def statistics(
+    input_folder: Annotated[
+        Path,
+        typer.Argument(
+            help="Folder to search with INPUT_GLOB.", exists=True, file_okay=False
+        ),
+    ],
+    input_glob: model.InputGlob,
+) -> None:
+    """Print node and edge counts of the selected graphs."""
+    files = sorted(input_folder.glob(input_glob))
+
+    graphs = [ag.load.file(file) for file in files]
+    atom_nodes = [len(graph.atom_nodes) for graph in graphs]
+    scheme_nodes = [len(graph.scheme_nodes) for graph in graphs]
+    edges = [len(graph.edges) for graph in graphs]
+
+    total_graphs = len(graphs)
+    total_atom_nodes = sum(atom_nodes)
+    total_scheme_nodes = sum(scheme_nodes)
+    total_edges = sum(edges)
+
+    typer.echo(
+        f"""Total Graphs: {total_graphs}
+
+Total Atom Nodes: {total_atom_nodes}
+Total Scheme Nodes: {total_scheme_nodes}
+Total Edges: {total_edges}
+
+Atom Nodes per Graph: {total_atom_nodes / total_graphs}
+Scheme Nodes per Graph: {total_scheme_nodes / total_graphs}
+Edges per Graph: {total_edges / total_graphs}
+
+Max. Atom Nodes: {max(atom_nodes)}
+Max. Scheme Nodes: {max(scheme_nodes)}
+Max. Edges: {max(edges)}
+
+Min. Atom Nodes: {min(atom_nodes)}
+Min. Scheme Nodes: {min(scheme_nodes)}
+Min. Edges: {min(edges)}"""
+    )

arguebuf-3.0.0/src/arguebuf/cli/model.py

@@ -0,0 +1,148 @@
+import shutil
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Self
+
+import typer
+
+InputFolder = Annotated[
+    Path,
+    typer.Argument(
+        help="File or folder to process, folders are searched with INPUT_GLOB.",
+        exists=True,
+    ),
+]
+InputGlob = Annotated[
+    str,
+    typer.Argument(
+        help="Glob pattern selecting the files within INPUT_FOLDER, e.g., '**/*.json'."
+    ),
+]
+OutputFolder = Annotated[
+    Path | None,
+    typer.Option(
+        help="File or folder to write the results to, defaults to INPUT_FOLDER.",
+        show_default=False,
+    ),
+]
+Clean = Annotated[
+    bool, typer.Option(help="Delete the output folder before processing.")
+]
+Overwrite = Annotated[
+    bool, typer.Option(help="Overwrite existing output files instead of skipping.")
+]
+Start = Annotated[
+    int,
+    typer.Option(
+        help="Position of the first input file to process, used to resume a run.",
+        min=1,
+    ),
+]
+SourceLang = Annotated[
+    str, typer.Argument(help="DeepL code of the source language, e.g., 'DE'.")
+]
+TargetLang = Annotated[
+    str, typer.Argument(help="DeepL code of the target language, e.g., 'EN-US'.")
+]
+AuthKey = Annotated[
+    str,
+    typer.Option(
+        help="DeepL API authentication key, prefer the environment variable.",
+        envvar="DEEPL_AUTH_KEY",
+        show_default=False,
+    ),
+]
+
+
+@dataclass(slots=True, frozen=True)
+class PathPair:
+    """A pair of paths for modification of files."""
+
+    source: Path
+    target: Path
+
+    @classmethod
+    def create(
+        cls,
+        path_in: Path,
+        path_out: Path,
+        input_glob: str | None,
+        output_suffix: str | None,
+    ) -> list[Self]:
+        pairs: list[Self] = []
+
+        if path_in.is_file():
+            if path_out.suffix:
+                pairs.append(cls(path_in, path_out))
+            elif output_suffix:
+                pairs.append(cls(path_in, path_out.with_suffix(output_suffix)))
+            else:
+                raise ValueError(
+                    "File given as input. Please also provide a file as output."
+                )
+
+        elif path_in.is_dir() and input_glob and output_suffix:
+            path_out.mkdir(parents=True, exist_ok=True)
+
+            files_in = sorted(path_in.glob(input_glob))
+            files_out: list[Path] = []
+
+            for file_in in files_in:
+                file_out = path_out / file_in.relative_to(path_in)
+                file_out = file_out.with_suffix(output_suffix)
+                file_out.parent.mkdir(parents=True, exist_ok=True)
+
+                files_out.append(file_out)
+
+            pairs.extend(
+                cls(file_in, file_out)
+                for file_in, file_out in zip(files_in, files_out, strict=True)
+            )
+
+        else:
+            raise ValueError(
+                "Folder given as input. Please also provide a folder as output together"
+                " with a shell globbing pattern and an output suffix."
+            )
+
+        return pairs
+
+
+def _label(path_pair: PathPair | None) -> str:
+    return path_pair.source.name if path_pair else ""
+
+
+def pending_pairs(
+    input_folder: Path,
+    output_folder: Path | None,
+    input_glob: str | None,
+    output_suffix: str | None,
+    clean: bool,
+    overwrite: bool,
+    start: int,
+) -> Iterator[PathPair]:
+    """Yield the path pairs still to be processed while showing a progress bar.
+
+    The output folder defaults to the input folder.
+    """
+    output_folder = output_folder or input_folder
+
+    if clean:
+        # cleaning an output folder that contains the inputs would delete them
+        if input_folder.resolve().is_relative_to(output_folder.resolve()):
+            raise typer.BadParameter(
+                "The output folder must not contain the input when using --clean."
+            )
+
+        shutil.rmtree(output_folder, ignore_errors=True)
+        output_folder.mkdir(parents=True)
+
+    pairs = PathPair.create(input_folder, output_folder, input_glob, output_suffix)
+
+    with typer.progressbar(
+        pairs[start - 1 :], item_show_func=_label, show_pos=True
+    ) as bar:
+        for path_pair in bar:
+            if overwrite or not path_pair.target.exists():
+                yield path_pair