dirigent-plugin 0.18.2__tar.gz → 0.18.4__tar.gz

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-plugin
-Version: 0.18.2
+Version: 0.18.4
 Summary: The dirigent plugin contract: block specs, protocols, and markers.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.18.2
+Requires-Dist: dirigent-common==0.18.4
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pluginkit>=0.5.0
 Requires-Dist: pydantic>=2.13.5

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.18.2"
+version = "0.18.4"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.18.2",
+    "dirigent-common==0.18.4",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.18.2"
+version = "0.18.4"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.18.2",
+    "dirigent-common==0.18.4",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/src/dirigent_plugin/__init__.py

@@ -2,6 +2,7 @@
 
 from dirigent_plugin.blocks import (
     BLOCK_ID_PATTERN,
+    MARK_LIMIT,
     SHELL_VARIABLE_PREFIX,
     SHELL_VARIABLES_FIELD,
     SURFACE_ID_PATTERN,
@@ -13,6 +14,7 @@ from dirigent_plugin.blocks import (
     Capture,
     ConnectionKind,
     ConnectionRef,
+    ContainerResult,
     Contribution,
     ErrorClass,
     FormatCheck,
@@ -41,6 +43,7 @@ from dirigent_plugin.blocks import (
     Storage,
     StorageBackend,
     classify_default,
+    mark_refusal,
     merge_contributions,
     shell_string_fields,
 )
@@ -78,6 +81,7 @@ __all__ = [
     "Capture",
     "ConnectionKind",
     "ConnectionRef",
+    "ContainerResult",
     "Contribution",
     "ConvertConfig",
     "ConvertOutput",
@@ -88,6 +92,7 @@ __all__ = [
     "Filterer",
     "FormatCheck",
     "Logger",
+    "MARK_LIMIT",
     "Mapper",
     "NotYet",
     "Notifier",
@@ -129,6 +134,7 @@ __all__ = [
     "extension",
     "extension_point",
     "formatters",
+    "mark_refusal",
     "merge_contributions",
     "shell_string_fields",
 ]

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/src/dirigent_plugin/blocks.py

@@ -1,5 +1,6 @@
 """The dirigent block contract: the only module a third-party plugin package needs to import."""
 
+import re
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping
 from contextlib import AbstractAsyncContextManager
@@ -18,6 +19,7 @@ from pydantic_core import CoreSchema
 from dirigent_common import API_VERSION, SHELL_MEDIA_TYPE, BlockModel, HealthReport, Issue, JsonMap, Message
 from dirigent_plugin.messages import (
     DUPLICATE_ID,
+    INVALID_MARK,
     UNSUPPORTED_API_VERSION,
 )
 
@@ -347,6 +349,19 @@ class StatResult(BaseModel):
     content_type: str | None = None
 
 
+class ContainerResult(BaseModel):
+    """What a backend did when asked to make sure a URI's container is there."""
+
+    container: str | None = None
+    """What the container is called, or None for a store that has none to make."""
+
+    created: bool = False
+    """Whether this call made it, as opposed to finding it already there."""
+
+    endpoint: str | None = None
+    """Where the store answers, carrying no credential; None for one with no endpoint."""
+
+
 class AlertMessage(BaseModel):
     """What an alert rule hands a notifier: the event, a rendered summary, and links back."""
 
@@ -729,6 +744,14 @@ class StorageBackend(ABC):
         """Remove the object at a URI."""
         ...
 
+    async def ensure_container(self, uri: str) -> ContainerResult:
+        """Create the container a URI's objects live in, unless it is already there.
+
+        A store whose containers a write makes for itself -- a filesystem and its
+        directories -- has nothing to create and says so by leaving the result empty.
+        """
+        return ContainerResult()
+
 
 class Notifier(ABC):
     """A pluggable message sender that alert rules deliver through."""
@@ -742,12 +765,50 @@ class Notifier(ABC):
         ...
 
 
+#: How much path data one mark may carry.
+MARK_LIMIT: Final = 4096
+
+#: Everything an SVG path's ``d`` is written out of: the commands, numbers, and separators.
+_PATH_DATA: Final = re.compile(r"^[MmZzLlHhVvCcSsQqTtAaEe0-9,.+\-\s]+$")
+
+
+def mark_refusal(kind: str, mark: str | None) -> str | None:
+    """Say why a connection kind may not wear the mark it declares, or ``None`` when it may.
+
+    A mark reaches a browser as the ``d`` of one path, so anything that is not path data is
+    refused here rather than drawn: non-empty, ASCII, path-data characters only, and at most
+    ``MARK_LIMIT`` of them.
+    """
+    if mark is None:
+        return None
+    detail: str | None = None
+    if not mark.strip():
+        detail = "it is empty"
+    elif not mark.isascii():
+        detail = "it is not ASCII"
+    elif len(mark) > MARK_LIMIT:
+        detail = f"it is {len(mark)} characters, and a mark holds at most {MARK_LIMIT}"
+    elif not _PATH_DATA.match(mark):
+        stray = sorted({character for character in mark if not _PATH_DATA.match(character)})
+        detail = f"it carries {''.join(stray)!r}, which path data does not"
+    if detail is None:
+        return None
+    return INVALID_MARK.render(kind=repr(kind), detail=detail)
+
+
 class ConnectionKind(ABC):
     """A named credential record of a contributed kind whose secret fields the server redacts."""
 
     id: ClassVar[str]
     config_model: ClassVar[type[BaseModel]]
 
+    mark: ClassVar[str | None] = None
+    """The ``d`` of one SVG path on a 24-unit grid, which is how a screen draws this kind.
+
+    Monochrome and filled in ``currentColor``, at the size every other kind's mark is drawn at;
+    a kind that declares none is drawn by the neutral mark.
+    """
+
     @abstractmethod
     async def check(self, config: BaseModel) -> HealthReport:
         """Verify that the configured connection can reach its external system.
@@ -796,6 +857,15 @@ class Contribution(BaseModel):
         _require_unique("format", list(self.formats))
         return self
 
+    @model_validator(mode="after")
+    def _check_marks(self) -> "Contribution":
+        """Reject a connection kind whose declared mark is not path data a browser may draw."""
+        for connection in self.connection_kinds:
+            refusal = mark_refusal(connection.id, connection.mark)
+            if refusal is not None:
+                raise ValueError(refusal)
+        return self
+
     def block_ids(self) -> list[str]:
         """List every operator and sensor id this contribution registers."""
         return [*(operator.spec.id for operator in self.operators), *(sensor.spec.id for sensor in self.sensors)]

{dirigent_plugin-0.18.2 → dirigent_plugin-0.18.4}/src/dirigent_plugin/messages.py

@@ -37,3 +37,8 @@ UNSUPPORTED_API_VERSION = PLUGIN.define(
 )
 
 DUPLICATE_ID = PLUGIN.define("duplicate_id", "duplicate {label} {value} in contribution")
+
+INVALID_MARK = PLUGIN.define(
+    "invalid_mark",
+    "the mark connection kind {kind} declares is not SVG path data: {detail}",
+)