web-algebra 2.0.2__tar.gz → 2.0.3__tar.gz

{web_algebra-2.0.2 → web_algebra-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: web-algebra
-Version: 2.0.2
+Version: 2.0.3
 Summary: Composable RDF operations in JSON
 Author-email: Martynas Jusevicius <martynas@atomgraph.com>
 License-Expression: Apache-2.0

{web_algebra-2.0.2 → web_algebra-2.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "web-algebra"
-version = "2.0.2"
+version = "2.0.3"
 description = "Composable RDF operations in JSON"
 readme = "README.md"
 license = "Apache-2.0"

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra/client.py

@@ -210,6 +210,7 @@ class LinkedDataClient:
         body: Optional[bytes] = None,
         content_type: Optional[str] = None,
         accept: str = "application/n-triples",
+        preconditions: Optional[dict] = None,
     ) -> HTTPResponse:
         """Send a write, conditional on the resource's current entity tag.
 
@@ -217,11 +218,14 @@ class LinkedDataClient:
         them can leave out the `If-Match` a server like LinkedDataHub requires of
         a write to an existing document (formal-semantics.md §4.4) - as the
         LinkedDataHub CLI's `LDHClient` adds it in each of its write methods.
+        A write that brings its own `preconditions` is sent with those instead:
+        `If-None-Match: *` creates only, and quoting an existing tag as well
+        would turn it back into a replace.
         """
         headers = {"Accept": accept}
         if content_type is not None:
             headers["Content-Type"] = content_type
-        headers.update(self.conditional(url, accept))
+        headers.update(preconditions if preconditions is not None else self.conditional(url, accept))
         request = urllib.request.Request(url, data=body, headers=headers, method=method)
 
         return self._send(request)
@@ -311,6 +315,20 @@ class LinkedDataClient:
         data = graph.serialize(format="nt")
         return self._write("PUT", url, data.encode("utf-8"), "application/n-triples")
 
+    def create(self, url: str, graph: Graph) -> HTTPResponse:
+        """
+        Sends RDF data to the given URL using HTTP PUT with `If-None-Match: *`,
+        so that it only ever creates: a server answers `412` where a resource
+        already exists, and leaves it as it is (formal-semantics.md Appendix A).
+
+        :param url: The URL to create the resource at.
+        :param graph: An RDFLib Graph containing the data to send.
+        :return: The HTTPResponse object.
+        """
+        data = graph.serialize(format="nt")
+        return self._write("PUT", url, data.encode("utf-8"), "application/n-triples",
+                           preconditions={"If-None-Match": "*"})
+
     def delete(self, url: str) -> HTTPResponse:
         """
         Sends an HTTP DELETE request to the given URL.

web_algebra-2.0.3/src/web_algebra/operations/linkeddatahub/create.py

@@ -0,0 +1,51 @@
+import logging
+from typing import Optional
+
+from rdflib import Graph, Literal, URIRef
+from rdflib.namespace import XSD
+from rdflib.query import Result
+
+from web_algebra.client_operation import ClientOperation
+from web_algebra.exceptions import WriteRefusedError
+from web_algebra.json_result import JSONResult
+
+PRECONDITION_FAILED = 412
+
+
+def create(op: ClientOperation, url: URIRef, graph: Graph, if_absent: Optional[Literal]) -> Result:
+    """Write `graph` as a new document at `url`, never replacing one.
+
+    The `PUT` carries `If-None-Match: *` (formal-semantics.md Appendix A), as
+    LinkedDataHub's CLI create commands and its client's create forms send it,
+    so a server refuses it `412` where a document already exists and leaves
+    that document as it is. That refusal is the operation's error, unless
+    `if_absent` is true: then the existing document is the result, as an
+    existing directory is for `mkdir -p`. Nothing was written, so it is not
+    reported to an enclosing `ForEach` as a write (§3.6).
+    """
+    try:
+        response = op.client.create(str(url), graph)
+    except WriteRefusedError as e:
+        if e.status != PRECONDITION_FAILED:
+            raise
+        if if_absent is None or not if_absent.toPython():
+            raise WriteRefusedError(
+                e.method, e.url, e.status,
+                "a document already exists at this URI and was left as it is; "
+                "pass if_absent to accept one that does",
+            ) from None
+        logging.info("A document already exists at <%s>; left as it is", url)
+        return JSONResult(
+            vars=["status", "url"],
+            bindings=[{"status": Literal(e.status, datatype=XSD.integer), "url": url}],
+        )
+
+    logging.info("PUT operation status: %s", response.status)
+    return op.written_response(response)
+
+
+def if_absent_flag(value: Optional[Literal], op_name: str) -> Optional[Literal]:
+    """`if_absent` as an operation takes it: absent, or an xsd:boolean Literal."""
+    if value is not None and not (isinstance(value, Literal) and value.datatype == XSD.boolean):
+        raise TypeError(f"{op_name} expects if_absent to be an xsd:boolean Literal, got {value!r}")
+    return value

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra/operations/linkeddatahub/create_container.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any, ClassVar, Optional
 import logging
 import urllib.parse
 import uuid
@@ -7,11 +7,17 @@ from rdflib.namespace import XSD
 from mcp import types
 from web_algebra.operation import Operation
 from web_algebra.rfc3986 import resolve
+from web_algebra.operation import OperationKind
 from web_algebra.operations.linked_data.put import PUT
+from web_algebra.operations.linkeddatahub.create import create, if_absent_flag
 from rdflib.query import Result
 
 
 class CreateContainer(PUT):
+    # creates only, with If-None-Match: *: a document already at the URI is left as it is, so
+    # nothing is ever removed
+    kind: ClassVar[OperationKind] = OperationKind.WRITE
+
     @classmethod
     def name(cls):
         return "ldh-CreateContainer"
@@ -26,7 +32,9 @@ class CreateContainer(PUT):
         - Example: if https://localhost/blog/ exists, you cannot create https://localhost/blog/posts/something/
           before creating https://localhost/blog/posts/ 
         - LinkedDataHub automatically manages timestamps (dct:created, dct:modified)
-        - LinkedDataHub automatically manages parent-child relationships (sioc:has_parent) based on URI hierarchy"""
+        - LinkedDataHub automatically manages parent-child relationships (sioc:has_parent) based on URI hierarchy
+        - It only creates: a document already at the URI is left as it is and the operation fails, unless
+          if_absent is true, which accepts it as the result (like mkdir -p). To replace a document, PUT it."""
 
     @classmethod
     def inputSchema(cls) -> dict:
@@ -43,7 +51,7 @@ class CreateContainer(PUT):
                 },
                 "slug": {
                     "type": "string",
-                    "description": "URL path segment (optional). Defaults to a random UUID. A document that already exists at this path is replaced.",
+                    "description": "URL path segment (optional). Defaults to a random UUID.",
                 },
                 "description": {
                     "type": "string",
@@ -57,6 +65,10 @@ class CreateContainer(PUT):
                     "type": "string",
                     "description": "URI reference of what the container is about, resolved against its URI (optional), e.g. #this.",
                 },
+                "if_absent": {
+                    "type": "boolean",
+                    "description": "Optional: whether a document already at the URI counts as success, left as it is (like mkdir -p). Without it the operation fails there.",
+                },
             },
             "required": ["parent", "title"],
         }
@@ -69,6 +81,7 @@ class CreateContainer(PUT):
         description: Optional[Literal] = None,
         children_view: Optional[Literal] = None,
         primary_topic: Optional[Literal] = None,
+        if_absent: Optional[Literal] = None,
     ) -> Result:
         """Pure function: create container with RDFLib terms"""
         if not isinstance(parent_uri, URIRef):
@@ -98,6 +111,8 @@ class CreateContainer(PUT):
                 f"CreateContainer.execute expects primary_topic to be Literal or None, got {type(primary_topic)}"
             )
 
+        if_absent = if_absent_flag(if_absent, "CreateContainer.execute")
+
         # URL-encode slug, or mint a fresh one - a lowercase UUID, as the LinkedDataHub CLI does - so that
         # leaving it out never lands on an existing document; deriving it from the title did, on a repeated title
         slug_str = urllib.parse.quote(str(slug) if slug else str(uuid.uuid4()), safe="")
@@ -141,8 +156,7 @@ class CreateContainer(PUT):
         # Convert the document to a Graph and call parent PUT operation
         graph = self.to_graph(data, base=url)
 
-        # Call parent PUT execute method
-        return super().execute(URIRef(url), graph)
+        return create(self, URIRef(url), graph, if_absent)
 
     def execute_json(self, arguments: dict, variable_stack: list = None) -> Result:
         """JSON execution: process arguments and call pure function"""
@@ -210,7 +224,14 @@ class CreateContainer(PUT):
                     f"ldh-CreateContainer operation expects 'primary_topic' to be Literal, got {type(primary_topic)}"
                 )
 
-        return self.execute(parent_uri, title, slug, description, children_view, primary_topic)
+        # Process optional if_absent
+        if_absent = None
+        if "if_absent" in arguments:
+            if_absent = Operation.json_to_rdflib(Operation.process_json(
+                self.settings, arguments["if_absent"], self.context, variable_stack
+            ))
+
+        return self.execute(parent_uri, title, slug, description, children_view, primary_topic, if_absent)
 
     def mcp_run(self, arguments: dict, context: Any = None) -> Any:
         """MCP execution: plain args → plain results"""
@@ -235,12 +256,16 @@ class CreateContainer(PUT):
             if "primary_topic" in arguments
             else None
         )
-        result = self.execute(parent_uri, title, slug, description, children_view, primary_topic)
+        if_absent = Literal(bool(arguments["if_absent"])) if "if_absent" in arguments else None
+        result = self.execute(parent_uri, title, slug, description, children_view, primary_topic, if_absent)
 
-        # Extract URL from PUT result
+        # Extract URL from PUT result; a 412 is the existing document if_absent accepted
         url_binding = result.bindings[0]["url"]
+        created = int(result.bindings[0]["status"]) != 412
         return [
             types.TextContent(
-                type="text", text=f"Container created successfully at: {url_binding}"
+                type="text",
+                text=f"Container created successfully at: {url_binding}" if created
+                else f"A document already exists at {url_binding}; left as it is",
             )
         ]

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra/operations/linkeddatahub/create_item.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any, ClassVar, Optional
 import logging
 import urllib.parse
 import uuid
@@ -7,11 +7,17 @@ from rdflib.namespace import XSD
 from mcp import types
 from web_algebra.operation import Operation
 from web_algebra.rfc3986 import resolve
+from web_algebra.operation import OperationKind
 from web_algebra.operations.linked_data.put import PUT
+from web_algebra.operations.linkeddatahub.create import create, if_absent_flag
 from rdflib.query import Result
 
 
 class CreateItem(PUT):
+    # creates only, with If-None-Match: *: a document already at the URI is left as it is, so
+    # nothing is ever removed
+    kind: ClassVar[OperationKind] = OperationKind.WRITE
+
     @classmethod
     def name(cls):
         return "ldh-CreateItem"
@@ -26,7 +32,9 @@ class CreateItem(PUT):
         - Example: if https://localhost/blog/ exists, you cannot create https://localhost/blog/posts/something/
           before creating https://localhost/blog/posts/
         - LinkedDataHub automatically manages timestamps (dct:created, dct:modified)
-        - LinkedDataHub automatically manages parent-child relationships (sioc:has_parent) based on URI hierarchy"""
+        - LinkedDataHub automatically manages parent-child relationships (sioc:has_parent) based on URI hierarchy
+        - It only creates: a document already at the URI is left as it is and the operation fails, unless
+          if_absent is true, which accepts it as the result (like mkdir -p). To replace a document, PUT it."""
 
     @classmethod
     def inputSchema(cls) -> dict:
@@ -40,13 +48,17 @@ class CreateItem(PUT):
                 "title": {"type": "string", "description": "The title of the item"},
                 "slug": {
                     "type": "string",
-                    "description": "URL path segment (optional). Defaults to a random UUID. A document that already exists at this path is replaced.",
+                    "description": "URL path segment (optional). Defaults to a random UUID.",
                 },
                 "description": {"type": "string", "description": "Description (optional)"},
                 "primary_topic": {
                     "type": "string",
                     "description": "URI reference of what the item is about, resolved against its URI (optional), e.g. #this.",
                 },
+                "if_absent": {
+                    "type": "boolean",
+                    "description": "Optional: whether a document already at the URI counts as success, left as it is (like mkdir -p). Without it the operation fails there.",
+                },
             },
             "required": ["container", "title"],
         }
@@ -58,6 +70,7 @@ class CreateItem(PUT):
         slug: Optional[Literal] = None,
         description: Optional[Literal] = None,
         primary_topic: Optional[Literal] = None,
+        if_absent: Optional[Literal] = None,
     ) -> Result:
         """Pure function: create item with RDFLib terms"""
         if not isinstance(container_uri, URIRef):
@@ -82,6 +95,8 @@ class CreateItem(PUT):
                 f"CreateItem.execute expects primary_topic to be Literal or None, got {type(primary_topic)}"
             )
 
+        if_absent = if_absent_flag(if_absent, "CreateItem.execute")
+
         # URL-encode slug, or mint a fresh one - a lowercase UUID, as the LinkedDataHub CLI does - so that
         # leaving it out never lands on an existing document; deriving it from the title did, on a repeated title
         slug_str = urllib.parse.quote(str(slug) if slug else str(uuid.uuid4()), safe="")
@@ -118,8 +133,7 @@ class CreateItem(PUT):
         # Convert the document to a Graph and call parent PUT operation
         graph = self.to_graph(data, base=url)
 
-        # Call parent PUT execute method
-        return super().execute(URIRef(url), graph)
+        return create(self, URIRef(url), graph, if_absent)
 
     def execute_json(self, arguments: dict, variable_stack: list = None) -> Result:
         """JSON execution: process arguments with strict type checking"""
@@ -180,7 +194,14 @@ class CreateItem(PUT):
                     f"ldh-CreateItem operation expects 'primary_topic' to be Literal, got {type(primary_topic)}"
                 )
 
-        return self.execute(container_uri, title, slug, description, primary_topic)
+        # Process optional if_absent
+        if_absent = None
+        if "if_absent" in arguments:
+            if_absent = Operation.json_to_rdflib(Operation.process_json(
+                self.settings, arguments["if_absent"], self.context, variable_stack
+            ))
+
+        return self.execute(container_uri, title, slug, description, primary_topic, if_absent)
 
     def mcp_run(self, arguments: dict, context: Any = None) -> Any:
         """MCP execution: plain args → plain results"""
@@ -202,12 +223,16 @@ class CreateItem(PUT):
             if "primary_topic" in arguments
             else None
         )
-        result = self.execute(container_uri, title, slug, description, primary_topic)
+        if_absent = Literal(bool(arguments["if_absent"])) if "if_absent" in arguments else None
+        result = self.execute(container_uri, title, slug, description, primary_topic, if_absent)
 
-        # Extract URL from PUT result
+        # Extract URL from PUT result; a 412 is the existing document if_absent accepted
         url_binding = result.bindings[0]["url"]
+        created = int(result.bindings[0]["status"]) != 412
         return [
             types.TextContent(
-                type="text", text=f"Item created successfully at: {url_binding}"
+                type="text",
+                text=f"Item created successfully at: {url_binding}" if created
+                else f"A document already exists at {url_binding}; left as it is",
             )
         ]

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra/prompts/system.md

@@ -560,9 +560,9 @@ The classes, datatype properties and object properties of the data at a SPARQL e
 
 These write to a LinkedDataHub instance. Every write returns the one-row `status`/`url` result. A document's **content** (what its page shows) is its sequence of blocks: only `ldh-AddXHTMLBlock` and `ldh-AddObjectBlock` add to it. The other `ldh-Add*` operations write a resource *into* the document (a query, a view, a chart, a service, a file) without showing it; to show it, place it with `ldh-AddObjectBlock`, its URI as `value` — so give it a `fragment`.
 
-## ldh-CreateContainer(parent: URI, title: Literal, slug?: Literal, description?: Literal, children_view?: Literal, primary_topic?: Literal) → Result
+## ldh-CreateContainer(parent: URI, title: Literal, slug?: Literal, description?: Literal, children_view?: Literal, primary_topic?: Literal, if_absent?: Literal) → Result
 
-Creates a container document at `parent` + `slug` + `/` (without `slug`, a random UUID), showing its children. A document that already exists at that URL is replaced. Its first content block lists its children through the shared `ldh:ChildrenView`, unless `children_view` is `false` — a JSON boolean, never the string `"false"`. To list them in another layout, pass `false`, add a view of `https://w3id.org/atomgraph/linkeddatahub#SelectChildren` in that mode to the container with `ldh-AddView` (with a `fragment`), and place it with `ldh-AddObjectBlock`. `primary_topic` is what the container is about, a URI reference resolved against its URL (`#this` for a resource described in it).
+Creates a container document at `parent` + `slug` + `/` (without `slug`, a random UUID), showing its children. It only creates: a document that already exists at that URL is left as it is and the operation fails, unless `if_absent` is `true` (a JSON boolean), which takes the existing document as the result and writes nothing, like `mkdir -p`. Pass it when the program means "make sure it exists"; to replace a document, `PUT` it. Its first content block lists its children through the shared `ldh:ChildrenView`, unless `children_view` is `false` — a JSON boolean, never the string `"false"`. To list them in another layout, pass `false`, add a view of `https://w3id.org/atomgraph/linkeddatahub#SelectChildren` in that mode to the container with `ldh-AddView` (with a `fragment`), and place it with `ldh-AddObjectBlock`. `primary_topic` is what the container is about, a URI reference resolved against its URL (`#this` for a resource described in it).
 
 ### Example JSON
 ```json
@@ -578,9 +578,9 @@ A container whose children are listed in another layout, here on a map:
 ]
 ```
 
-## ldh-CreateItem(container: URI, title: Literal, slug?: Literal, description?: Literal, primary_topic?: Literal) → Result
+## ldh-CreateItem(container: URI, title: Literal, slug?: Literal, description?: Literal, primary_topic?: Literal, if_absent?: Literal) → Result
 
-Creates an item document at `container` + `slug` + `/` (without `slug`, a random UUID). A document that already exists at that URL is replaced. `primary_topic` is what the item is about, a URI reference resolved against its URL (`#this` for a resource described in it).
+Creates an item document at `container` + `slug` + `/` (without `slug`, a random UUID). It only creates: a document that already exists at that URL is left as it is and the operation fails, unless `if_absent` is `true`, which takes the existing document as the result and writes nothing. To replace a document, `PUT` it. `primary_topic` is what the item is about, a URI reference resolved against its URL (`#this` for a resource described in it).
 
 ### Example JSON
 ```json

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: web-algebra
-Version: 2.0.2
+Version: 2.0.3
 Summary: Composable RDF operations in JSON
 Author-email: Martynas Jusevicius <martynas@atomgraph.com>
 License-Expression: Apache-2.0

{web_algebra-2.0.2 → web_algebra-2.0.3}/src/web_algebra.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ src/web_algebra/operations/linkeddatahub/add_generic_service.py
 src/web_algebra/operations/linkeddatahub/add_result_set_chart.py
 src/web_algebra/operations/linkeddatahub/add_select.py
 src/web_algebra/operations/linkeddatahub/add_view.py
+src/web_algebra/operations/linkeddatahub/create.py
 src/web_algebra/operations/linkeddatahub/create_container.py
 src/web_algebra/operations/linkeddatahub/create_item.py
 src/web_algebra/operations/linkeddatahub/fragments.py

{web_algebra-2.0.2 → web_algebra-2.0.3}/tests/test_operation_kind.py

@@ -37,14 +37,14 @@ def test_the_worst_of_several_kinds_is_the_most_destructive():
     assert sorted([DESTRUCTIVE, READ, WRITE]) == [READ, WRITE, DESTRUCTIVE]
 
 
-def test_an_upsert_is_destructive_and_what_extends_it_is_too():
+def test_an_upsert_is_destructive_but_a_create_is_not():
     # PUT replaces the whole document at a URL that already holds one;
-    # ldh-CreateContainer and ldh-CreateItem PUT to parent + slug (or title),
-    # so on an existing URL they replace it as well
+    # ldh-CreateContainer and ldh-CreateItem PUT with If-None-Match: *, so on
+    # an existing URL they are refused and remove nothing
     from web_algebra.operations.linked_data.put import PUT
     from web_algebra.operations.linkeddatahub.create_container import CreateContainer
     from web_algebra.operations.linkeddatahub.create_item import CreateItem
 
     assert PUT.kind is DESTRUCTIVE
-    assert CreateContainer.kind is DESTRUCTIVE
-    assert CreateItem.kind is DESTRUCTIVE
+    assert CreateContainer.kind is WRITE
+    assert CreateItem.kind is WRITE