Feat: Core contract (Models, Protocols, exceptions) issue #16

.pre-commit-config.yaml

@@ -39,3 +39,4 @@ repos:
     hooks:
       - id: mypy
         exclude: tests
+        additional_dependencies: ["pydantic>=2.0.0"]

docs/index.md

@@ -0,0 +1,6 @@
+# interCEde
+
+Unified interfaces to Computing Elements and batch systems for DIRAC / DiracX.
+
+The contract is described in IC-ADR-001. See the [API reference](user/api-reference.md)
+for the protocols, data types and exceptions a consumer may import.

docs/user/api-reference.md

@@ -0,0 +1,16 @@
+# API reference
+
+Everything listed here is importable from `intercede` and follows SemVer.
+Anything else, including every name starting with `_`, is internal.
+
+## Protocols
+
+::: intercede.protocols
+
+## Data types
+
+::: intercede.models
+
+## Exceptions
+
+::: intercede.exceptions

mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: interCEde
+site_description: Unified interfaces to Computing Elements and batch systems for DIRAC / DiracX
+repo_url: https://github.com/DIRACGrid/intercede
+
+theme:
+  name: material
+  logo: assets/intercede-icon.svg
+  favicon: assets/intercede-icon.svg
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_source: false
+            members_order: source
+            merge_init_into_class: true
+
+validation:
+  links:
+    # The developer docs link to repository files outside docs/ (e.g. renovate.json),
+    # which resolve on GitHub but not in the built site.
+    not_found: info

pyproject.toml

@@ -17,7 +17,9 @@ requires-python = ">=3.11"
 keywords = []
 license = { text = "GPL-3.0-only" }
 dynamic = ["version"]
-dependencies = []
+dependencies = [
+  "pydantic>=2"
+]
 classifiers = [
   "Intended Audience :: Science/Research",
   "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
@@ -39,9 +41,6 @@ testing = [
   "ty",
 ]
 
-[tool.setuptools.packages.find]
-where = ["src"]
-
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
@@ -51,6 +50,10 @@ markers = [
   "xfail_backend: strict xfail a test on the named backend fixture(s)",
 ]
 
+[tool.mypy]
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src"]
 
 [tool.ruff]
 src = ["src", "tests"]
@@ -113,6 +116,7 @@ py311 = { features = ["testing", "py311"] }
 py312 = { features = ["testing", "py312"] }
 py313 = { features = ["testing", "py313"] }
 py314 = { features = ["testing", "py314"] }
+docs = { features = ["docs"], solve-group = "default" }
 
 [tool.pixi.feature.testing.pypi-dependencies]
 intercede = { path = ".", editable = true }
@@ -125,6 +129,16 @@ pre-commit = "*"
 pre-commit = { cmd = "pre-commit", description = "Run pre-commit" }
 
 
+# Features for building the documentation
+[tool.pixi.feature.docs.pypi-dependencies]
+intercede = { path = ".", editable = true }
+mkdocs = "<2"
+mkdocs-material = "*"
+mkdocstrings = { version = "*", extras = ["python"] }
+[tool.pixi.feature.docs.tasks]
+docs = { cmd = "mkdocs build --strict", description = "Build the documentation" }
+
+
 [tool.pixi.tasks]
 unit-test = { cmd = "pytest -v", description = "Run the unit tests" }
 

src/intercede/__init__.py

@@ -5,10 +5,76 @@
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as get_version
 
+from intercede.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    InterCEdeError,
+    ResourceUnavailableError,
+    SpecificationRejectedError,
+)
+from intercede.models import (
+    ContainerSpec,
+    CopyVars,
+    Diagnostics,
+    FileRef,
+    JobHandle,
+    JobID,
+    JobOutput,
+    JobStatus,
+    OpOutcome,
+    OutputMember,
+    OutputSpec,
+    Resources,
+    StatusMap,
+    Submission,
+    SubmissionSpec,
+)
+from intercede.protocols import (
+    Diagnosable,
+    JobBackend,
+    Killable,
+    OutputRetriever,
+    Purgeable,
+    StatusReporter,
+    Submitter,
+)
+
 try:
     __version__ = get_version(__name__)
-    version = __version__
 except PackageNotFoundError:
-    version = "Unknown"
+    __version__ = "unknown"
+version = __version__
 
-__all__ = ["__version__"]
+__all__ = [
+    "__version__",
+    # protocols
+    "Diagnosable",
+    "JobBackend",
+    "Killable",
+    "OutputRetriever",
+    "Purgeable",
+    "StatusReporter",
+    "Submitter",
+    # data types
+    "ContainerSpec",
+    "CopyVars",
+    "Diagnostics",
+    "FileRef",
+    "JobHandle",
+    "JobID",
+    "JobOutput",
+    "JobStatus",
+    "OpOutcome",
+    "OutputMember",
+    "OutputSpec",
+    "Resources",
+    "StatusMap",
+    "Submission",
+    "SubmissionSpec",
+    # exceptions
+    "AuthenticationError",
+    "ConfigurationError",
+    "InterCEdeError",
+    "ResourceUnavailableError",
+    "SpecificationRejectedError",
+]

src/intercede/_backends/__init__.py

@@ -0,0 +1 @@
+"""Internal backend implementations. Nothing here is public API."""

src/intercede/_backends/batch/__init__.py

@@ -0,0 +1 @@
+"""The composed backend: a transport combined with a scheduler (IC-ADR-001 §4)."""

src/intercede/_backends/batch/protocols.py

@@ -0,0 +1,78 @@
+"""Internal collaborator protocols of the composed backend (IC-ADR-001 §4).
+
+Shapes only: transports and schedulers are implemented in later issues.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from types import TracebackType
+from typing import Protocol, Self, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from intercede.models import CopyVars, JobID, JobStatus, SubmissionSpec
+
+Command = Sequence[str]  # an argv: only argv and staged files ever cross the transport
+# One resource, so its own IDs are unique: no need for handles here.
+SchedulerStatusMap = Mapping[JobID, JobStatus]
+
+
+class CommandResult(BaseModel):
+    """The outcome of running one command on the resource."""
+
+    model_config = ConfigDict(frozen=True)
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """How InterCEde reaches a resource: local shell, SSH, ...
+
+    Transports hold connections, so they share the backend lifecycle: cheap
+    construction with no I/O, and an idempotent close.
+    """
+
+    async def __aenter__(self) -> Self: ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None: ...
+
+    async def run(self, argv: Command) -> CommandResult: ...
+
+    async def put(self, local: Path, remote: str) -> None: ...
+
+    async def get(self, remote: str, local: Path) -> None: ...
+
+
+@runtime_checkable
+class Scheduler(Protocol):
+    """How work is queued: builds commands locally and parses their output."""
+
+    stages_own_files: bool  # does the scheduler move the sandbox itself?
+
+    def submit_command(
+        self, spec: SubmissionSpec, copies: Sequence[CopyVars], workdir: str
+    ) -> Command:
+        """Build the command that queues every copy; ``workdir`` is where the sandbox was staged."""
+        ...
+
+    def parse_submit(self, raw: str) -> Sequence[JobID]:
+        """Read the IDs from the submit command's output, one per copy, in copy order."""
+        ...
+
+    def status_command(self, ids: Sequence[JobID]) -> Command: ...
+
+    def parse_status(self, raw: str, ids: Sequence[JobID]) -> SchedulerStatusMap:
+        """Return a status for every id asked about; ids missing from ``raw`` are ``UNKNOWN``."""
+        ...
+
+    def kill_command(self, ids: Sequence[JobID]) -> Command: ...