triplemodel 0.1.0__py3-none-any.whl

triplemodel/__init__.py

@@ -0,0 +1,46 @@
+"""TripleModel — Pydantic models backed by RDF graphs via rdflib.
+
+Install: ``pip install triplemodel``
+"""
+
+from triplemodel._config import (
+    RDF,
+    RDFS,
+    RDF_TYPE,
+    XSD,
+    RdfConfig,
+    id_from_subject_uri,
+    subject_base,
+)
+from triplemodel._fields import Predicate, rdf_field
+from triplemodel._graph import (
+    OnDuplicate,
+    graph_to_model,
+    graph_to_models,
+    model_to_graph,
+    model_to_triples,
+    models_to_graph,
+)
+from triplemodel.model import TripleModel
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OnDuplicate",
+    "RDF",
+    "RDFS",
+    "RDF_TYPE",
+    "XSD",
+    "Predicate",
+    "RdfConfig",
+    "TripleModel",
+    "graph_to_model",
+    "graph_to_models",
+    "id_from_subject_uri",
+    "model_to_graph",
+    "model_to_triples",
+    "models_to_graph",
+    "rdf_field",
+    "subject_base",
+    "__version__",
+]

triplemodel/_config.py

@@ -0,0 +1,72 @@
+"""RDF configuration attached to Pydantic models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, unquote
+
+
+def subject_base(namespace: str) -> str:
+    """Return the prefix used when appending an id to ``namespace``."""
+    return namespace if namespace.endswith(("/", "#")) else namespace + "/"
+
+
+def id_from_subject_uri(namespace: str, uri: str) -> str | None:
+    """Extract the id segment from ``uri`` when it was built from ``namespace``."""
+    base = subject_base(namespace)
+    if not uri.startswith(base):
+        return None
+    return unquote(uri[len(base) :])
+
+
+@dataclass(frozen=True)
+class RdfConfig:
+    """RDF metadata for an :class:`~triplemodel.TripleModel` subclass."""
+
+    namespace: str = ""
+    type_uri: str | None = None
+    id_field: str | None = None
+    """Model field whose value is appended to ``namespace`` for the subject IRI."""
+
+    def subject_uri(self, instance: Any) -> str:
+        if not self.namespace:
+            raise ValueError(
+                "Rdf.namespace is required to derive a subject IRI; "
+                "set it on the model's Rdf class or pass uri= explicitly."
+            )
+        if not self.id_field:
+            raise ValueError(
+                "Rdf.id_field is required to derive a subject IRI; "
+                "set it on the model's Rdf class or pass uri= explicitly."
+            )
+        raw = getattr(instance, self.id_field, None)
+        if raw is None or raw == "":
+            raise ValueError(
+                f"Cannot build subject IRI: field {self.id_field!r} is empty."
+            )
+        base = subject_base(self.namespace)
+        segment = quote(str(raw), safe="")
+        return f"{base}{segment}"
+
+
+def get_rdf_config(model_cls: type) -> RdfConfig:
+    for cls in model_cls.__mro__:
+        if cls is object:
+            continue
+        rdf = getattr(cls, "Rdf", None)
+        if rdf is not None:
+            return RdfConfig(
+                namespace=getattr(rdf, "namespace", "") or "",
+                type_uri=getattr(rdf, "type_uri", None),
+                id_field=getattr(rdf, "id_field", None),
+            )
+    return RdfConfig()
+
+
+# Namespace constants used by the package
+RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+RDFS = "http://www.w3.org/2000/01/rdf-schema#"
+XSD = "http://www.w3.org/2001/XMLSchema#"
+
+RDF_TYPE = f"{RDF}type"

triplemodel/_fields.py

@@ -0,0 +1,60 @@
+"""Field helpers and predicate metadata for RDF mapping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Any, cast, get_args, get_origin
+
+from pydantic import Field
+from pydantic.fields import FieldInfo
+
+
+@dataclass(frozen=True)
+class Predicate:
+    """Marks a model field with its RDF predicate IRI."""
+
+    uri: str
+
+
+def rdf_field(
+    predicate: str,
+    *,
+    default: Any = ...,
+    **field_kwargs: Any,
+) -> Any:
+    """Create a Pydantic field bound to an RDF predicate.
+
+    Example::
+
+        name: str = rdf_field("http://xmlns.com/foaf/0.1/name")
+    """
+    extra = field_kwargs.pop("json_schema_extra", None) or {}
+    if not isinstance(extra, dict):
+        extra = {}
+    extra = {**extra, "rdf_predicate": predicate}
+    return Field(default=default, json_schema_extra=extra, **field_kwargs)
+
+
+def predicate_for_field(field_info: FieldInfo) -> str | None:
+    """Resolve the RDF predicate URI for a Pydantic field, if any."""
+    extra = field_info.json_schema_extra
+    if isinstance(extra, dict):
+        predicate = cast(dict[str, Any], extra).get("rdf_predicate")
+        if predicate is not None:
+            return str(predicate)
+
+    for meta in field_info.metadata:
+        if isinstance(meta, Predicate):
+            return meta.uri
+
+    return None
+
+
+def predicate_from_annotation(annotation: Any) -> str | None:
+    """Read :class:`Predicate` from ``Annotated[..., Predicate(...)]``."""
+    if get_origin(annotation) is not Annotated:
+        return None
+    for meta in get_args(annotation)[1:]:
+        if isinstance(meta, Predicate):
+            return meta.uri
+    return None

triplemodel/_graph.py

@@ -0,0 +1,191 @@
+"""Build and parse rdflib graphs from Pydantic models."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from typing import Any, Literal, TypeVar, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError
+from rdflib import Graph, URIRef
+
+from triplemodel._config import RDF_TYPE, RdfConfig, get_rdf_config, id_from_subject_uri
+from triplemodel._fields import predicate_for_field, predicate_from_annotation
+from triplemodel._types import python_to_term, term_to_python
+
+T = TypeVar("T", bound=BaseModel)
+
+OnDuplicate = Literal["ignore", "warn", "error"]
+
+
+def model_to_triples(
+    model: BaseModel,
+    *,
+    uri: str | None = None,
+    config: RdfConfig | None = None,
+) -> list[tuple[str, str, Any]]:
+    """Return (subject, predicate, object) tuples for a model instance."""
+    cls = type(model)
+    cfg = config or get_rdf_config(cls)
+    subject = uri or cfg.subject_uri(model)
+    triples: list[tuple[str, str, Any]] = []
+
+    if cfg.type_uri:
+        triples.append((subject, RDF_TYPE, cfg.type_uri))
+
+    id_field = cfg.id_field
+    for name, field_info in cls.model_fields.items():
+        if id_field and name == id_field:
+            continue
+        predicate = predicate_for_field(field_info) or predicate_from_annotation(
+            field_info.annotation
+        )
+        if predicate is None:
+            continue
+        value = getattr(model, name)
+        if value is None:
+            continue
+        triples.append((subject, predicate, value))
+
+    return triples
+
+
+def model_to_graph(
+    model: BaseModel,
+    graph: Graph | None = None,
+    *,
+    uri: str | None = None,
+    config: RdfConfig | None = None,
+) -> Graph:
+    """Add triples for ``model`` to ``graph`` (or a new graph) and return it."""
+    # rdflib Graph() is falsy when empty — must not use `graph or Graph()`.
+    g = Graph() if graph is None else graph
+    for subj, pred, obj in model_to_triples(model, uri=uri, config=config):
+        g.add((URIRef(subj), URIRef(pred), python_to_term(obj)))
+    return g
+
+
+def models_to_graph(
+    models: Sequence[BaseModel],
+    graph: Graph | None = None,
+) -> Graph:
+    """Serialize multiple model instances into one graph."""
+    g = Graph() if graph is None else graph
+    for model in models:
+        model_to_graph(model, g)
+    return g
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    import types
+    from typing import Annotated, Union
+
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        return _unwrap_optional(get_args(annotation)[0])
+    if origin is None:
+        return annotation
+    if origin in (Union, types.UnionType):
+        non_none = [a for a in get_args(annotation) if a is not type(None)]
+        return non_none[0] if len(non_none) == 1 else annotation
+    return annotation
+
+
+def graph_to_model(
+    graph: Graph,
+    model_cls: type[T],
+    uri: str,
+    *,
+    config: RdfConfig | None = None,
+    validate_type: bool = True,
+    on_duplicate: OnDuplicate = "warn",
+) -> T:
+    """Hydrate a single model instance from triples about ``uri``."""
+    cfg = config or get_rdf_config(model_cls)
+    subject = URIRef(uri)
+
+    if validate_type and cfg.type_uri:
+        type_ref = URIRef(cfg.type_uri)
+        if (subject, URIRef(RDF_TYPE), type_ref) not in graph:
+            raise ValueError(
+                f"Subject {uri!r} does not have rdf:type {cfg.type_uri!r} required by "
+                f"{model_cls.__name__}."
+            )
+
+    data: dict[str, Any] = {}
+
+    if cfg.id_field and cfg.namespace:
+        extracted = id_from_subject_uri(cfg.namespace, uri)
+        if extracted is not None:
+            data[cfg.id_field] = extracted
+
+    for name, field_info in model_cls.model_fields.items():
+        if cfg.id_field and name == cfg.id_field:
+            continue
+        predicate = predicate_for_field(field_info) or predicate_from_annotation(
+            field_info.annotation
+        )
+        if predicate is None:
+            continue
+        pred_ref = URIRef(predicate)
+        objects = list(graph.objects(subject, pred_ref))
+        if not objects:
+            continue
+        if len(objects) > 1:
+            dup_msg = (
+                f"Multiple objects ({len(objects)}) for field {name!r} "
+                f"(predicate {predicate!r}, subject {uri!r}); using the first only "
+                f"(multi-value fields planned for 0.2.0)."
+            )
+            if on_duplicate == "error":
+                raise ValueError(dup_msg)
+            if on_duplicate == "warn":
+                warnings.warn(dup_msg, stacklevel=2)
+        # Multi-valued predicates: first object only until 0.2.0.
+        target = _unwrap_optional(field_info.annotation)
+        py_type = target if isinstance(target, type) else None
+        try:
+            data[name] = term_to_python(objects[0], py_type)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Cannot convert object for field {name!r} "
+                f"(predicate {predicate!r}, subject {uri!r}): {exc}"
+            ) from exc
+
+    try:
+        return model_cls.model_validate(data)
+    except ValidationError as exc:
+        raise ValueError(
+            f"Cannot validate {model_cls.__name__} from graph for subject {uri!r}: {exc}"
+        ) from exc
+
+
+def graph_to_models(
+    graph: Graph,
+    model_cls: type[T],
+    *,
+    type_uri: str | None = None,
+    config: RdfConfig | None = None,
+    validate_type: bool = True,
+    on_duplicate: OnDuplicate = "warn",
+) -> list[T]:
+    """Load all resources of ``type_uri`` (or the model's configured type) as models."""
+    cfg = config or get_rdf_config(model_cls)
+    rdf_type = type_uri or cfg.type_uri
+    if not rdf_type:
+        raise ValueError("type_uri is required when the model has no Rdf.type_uri.")
+
+    instances: list[T] = []
+    for subject in graph.subjects(URIRef(RDF_TYPE), URIRef(rdf_type)):
+        if isinstance(subject, URIRef):
+            instances.append(
+                graph_to_model(
+                    graph,
+                    model_cls,
+                    str(subject),
+                    config=cfg,
+                    validate_type=validate_type,
+                    on_duplicate=on_duplicate,
+                )
+            )
+    return instances

triplemodel/_types.py

@@ -0,0 +1,68 @@
+"""Convert between Python values and RDF terms."""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime
+from typing import Any
+
+from rdflib import BNode, Literal, URIRef, XSD
+from rdflib.term import Node
+
+
+def python_to_term(value: Any) -> Node:
+    """Serialize a Python scalar to an RDF term."""
+    if isinstance(value, Node):
+        return value
+    if isinstance(value, bool):
+        return Literal(value, datatype=XSD.boolean)
+    if isinstance(value, int) and not isinstance(value, bool):
+        return Literal(value, datatype=XSD.integer)
+    if isinstance(value, float):
+        return Literal(value, datatype=XSD.double)
+    if isinstance(value, datetime):
+        return Literal(value.isoformat(), datatype=XSD.dateTime)
+    if isinstance(value, date):
+        return Literal(value.isoformat(), datatype=XSD.date)
+    if isinstance(value, str):
+        if _looks_like_iri(value):
+            return URIRef(value)
+        return Literal(value, datatype=XSD.string)
+    return Literal(value)
+
+
+def term_to_python(term: Node, target_type: type | None = None) -> Any:
+    """Deserialize an RDF term to a Python value."""
+    if isinstance(term, URIRef):
+        return str(term)
+
+    if not isinstance(term, Literal):
+        if isinstance(term, BNode) and target_type is str:
+            raise TypeError(
+                "BNode objects cannot be assigned to str fields; "
+                "blank node support is planned for a future release."
+            )
+        return term
+
+    if target_type is bool:
+        if term.datatype == XSD.boolean:
+            return bool(term.toPython())
+        return term.value in (True, "true", "1", 1)
+    if target_type is int:
+        return int(term)
+    if target_type is float:
+        return float(term)
+    if target_type is datetime:
+        return datetime.fromisoformat(str(term))
+    if target_type is date:
+        return date.fromisoformat(str(term))
+
+    return term.toPython()
+
+
+_SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.-]*:")
+
+
+def _looks_like_iri(value: str) -> bool:
+    """True when ``value`` has an RFC 3986 scheme (e.g. http:, mailto:, file:)."""
+    return bool(_SCHEME_RE.match(value))

triplemodel/model.py

@@ -0,0 +1,102 @@
+"""Base Pydantic model with RDF serialization."""
+
+from __future__ import annotations
+
+from typing_extensions import Self
+
+from pydantic import BaseModel, ConfigDict
+from rdflib import Graph
+
+from triplemodel._config import RdfConfig, get_rdf_config
+from triplemodel._graph import (
+    OnDuplicate,
+    graph_to_model,
+    graph_to_models,
+    model_to_graph,
+    model_to_triples,
+)
+
+
+class TripleModel(BaseModel):
+    """Pydantic model that can be serialized to and from an RDF graph.
+
+    Subclasses declare RDF metadata on a nested ``Rdf`` class and map fields
+    with :func:`~triplemodel.rdf_field` or ``Annotated[..., Predicate(...)]``.
+    A nested ``Rdf`` on a subclass **replaces** the parent's config entirely;
+    do not declare an empty ``class Rdf:`` on a child if you intend to inherit
+    the parent's ``namespace``, ``type_uri``, or ``id_field``.
+
+    Example::
+
+        class Person(TripleModel):
+            class Rdf:
+                namespace = "http://example.org/people/"
+                type_uri = "http://xmlns.com/foaf/0.1/Person"
+                id_field = "slug"
+
+            slug: str
+            name: str = rdf_field("http://xmlns.com/foaf/0.1/name")
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        str_strip_whitespace=False,
+    )
+
+    def subject_uri(self, *, uri: str | None = None) -> str:
+        """Return the RDF subject IRI for this instance."""
+        if uri is not None:
+            return uri
+        return get_rdf_config(type(self)).subject_uri(self)
+
+    def to_triples(self, *, uri: str | None = None) -> list[tuple[str, str, object]]:
+        """Export instance data as (subject, predicate, object) tuples."""
+        return model_to_triples(self, uri=uri)
+
+    def to_graph(self, graph: Graph | None = None, *, uri: str | None = None) -> Graph:
+        """Serialize this instance into an rdflib ``Graph``."""
+        return model_to_graph(self, graph, uri=uri)
+
+    @classmethod
+    def from_graph(
+        cls,
+        graph: Graph,
+        uri: str,
+        *,
+        validate_type: bool = True,
+        on_duplicate: OnDuplicate = "warn",
+    ) -> Self:
+        """Construct an instance from triples about ``uri``."""
+        return graph_to_model(
+            graph,
+            cls,
+            uri,
+            validate_type=validate_type,
+            on_duplicate=on_duplicate,
+        )
+
+    @classmethod
+    def all_from_graph(
+        cls,
+        graph: Graph,
+        *,
+        type_uri: str | None = None,
+        validate_type: bool = True,
+        on_duplicate: OnDuplicate = "warn",
+    ) -> list[Self]:
+        """Load every resource of this model's RDF type from ``graph``."""
+        return graph_to_models(
+            graph,
+            cls,
+            type_uri=type_uri,
+            validate_type=validate_type,
+            on_duplicate=on_duplicate,
+        )
+
+    @classmethod
+    def rdf_config(cls) -> RdfConfig:
+        """Return resolved RDF configuration for this model class."""
+        return get_rdf_config(cls)
+
+
+__all__ = ["TripleModel"]

triplemodel-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: triplemodel
+Version: 0.1.0
+Summary: Pydantic TripleModel classes ↔ RDF triples via rdflib (alpha). SparqlModel ORM integration planned from 0.2.
+Project-URL: Homepage, https://github.com/eddiethedean/triplemodel
+Project-URL: Documentation, https://github.com/eddiethedean/triplemodel#readme
+Project-URL: Repository, https://github.com/eddiethedean/triplemodel
+Project-URL: Changelog, https://github.com/eddiethedean/triplemodel/blob/main/CHANGELOG.md
+Author: TripleModel contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: linked-data,pydantic,rdf,rdflib,semantic-web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: rdflib<8,>=7.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: ty>=0.0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TripleModel
+
+[![CI](https://github.com/eddiethedean/triplemodel/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/triplemodel/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/eddiethedean/triplemodel)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/eddiethedean/triplemodel/blob/main/LICENSE)
+
+**Pydantic models for RDF graphs.** Map typed Python classes to [rdflib](https://github.com/RDFLib/rdflib) triples and back — without hand-writing `graph.add` for every field.
+
+| | |
+|--|--|
+| PyPI / import | `triplemodel` |
+| Base class | `TripleModel` |
+
+```text
+Person(slug="alice", name="Alice")  →  (ex:alice, foaf:name, "Alice")  →  Person(...)
+```
+
+**TripleModel** is the **typed mapping layer** in a small ecosystem: Pydantic models ↔ RDF triples via field types and predicates. [SparqlModel](https://github.com/eddiethedean/sqarqlmodel) (session, SPARQL queries, ORM) is planned to depend on TripleModel from **0.2** — see the [ecosystem guide](https://github.com/eddiethedean/triplemodel/blob/main/docs/ECOSYSTEM.md).
+
+> **0.1.0 is alpha.** The API may change until 1.0. See [CHANGELOG](https://github.com/eddiethedean/triplemodel/blob/main/CHANGELOG.md) and the [roadmap](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md).
+
+## Features
+
+- **Pydantic v2** models with `validate_assignment=True`
+- **Declarative mapping** — nested `Rdf` config + `rdf_field()` or `Annotated[..., Predicate(...)]`
+- **Subject IRIs** — build from `namespace` + `id_field`, percent-encoded segments, safe import (no prefix collisions)
+- **XSD round-trip** — `str`, `int`, `float`, `bool`, `date`, `datetime`; IRI-like strings → `URIRef`
+- **Stateless I/O** — `to_graph` / `from_graph` / `all_from_graph` / `models_to_graph` on in-memory `Graph`
+- **Typed package** — `py.typed` for type checkers
+
+**Not in 0.1.0** (on the [roadmap](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md)): file parse/serialize, multi-valued fields, nested models, sync/remove, SPARQL helpers.
+
+## Requirements
+
+- Python **3.10+**
+- [Pydantic](https://docs.pydantic.dev/) v2
+- [rdflib](https://rdflib.readthedocs.io/) v7
+
+## Install
+
+```bash
+pip install triplemodel
+```
+
+## Quick start
+
+```python
+from triplemodel import TripleModel, rdf_field
+
+FOAF = "http://xmlns.com/foaf/0.1/"
+
+class Person(TripleModel):
+    class Rdf:
+        namespace = "http://example.org/people/"
+        type_uri = f"{FOAF}Person"
+        id_field = "slug"
+
+    slug: str
+    name: str = rdf_field(f"{FOAF}name")
+    age: int | None = rdf_field(f"{FOAF}age", default=None)
+
+alice = Person(slug="alice", name="Alice", age=30)
+
+graph = alice.to_graph()
+print(alice.subject_uri())  # http://example.org/people/alice
+
+assert Person.from_graph(graph, alice.subject_uri()) == alice
+assert len(Person.all_from_graph(graph)) == 1
+```
+
+## Concepts
+
+### RDF metadata (`class Rdf`)
+
+| Attribute | Role |
+|-----------|------|
+| `namespace` | Base IRI for subject resources |
+| `type_uri` | Emitted as `rdf:type`; used to filter `all_from_graph()` |
+| `id_field` | Field value appended to `namespace` for the subject IRI |
+
+Subject IRIs use `subject_base(namespace)` + percent-encoded id (`quote` / `unquote`). Override the subject IRI per call with `uri=` (round-trip works when the URI still matches `namespace`):
+
+```python
+alice = Person(slug="alice", name="Alice")
+custom_uri = "http://example.org/people/alice"
+graph = alice.to_graph(uri=custom_uri)
+assert Person.from_graph(graph, custom_uri) == alice
+```
+
+Shared helpers (also on the package root):
+
+```python
+from triplemodel import id_from_subject_uri, subject_base
+
+base = subject_base("http://example.org/people")  # ensures trailing / or #
+id_from_subject_uri("http://example.org/people", "http://example.org/people/alice")  # "alice"
+```
+
+### Field → predicate
+
+```python
+name: str = rdf_field("http://xmlns.com/foaf/0.1/name")
+```
+
+Or with **`Annotated`**:
+
+```python
+from typing import Annotated
+from triplemodel import Predicate
+
+title: Annotated[str, Predicate("http://purl.org/dc/terms/title")]
+```
+
+Fields **without** a predicate mapping are skipped on export and import (handy for computed or app-only fields).
+
+Subclasses **inherit** a parent’s nested `Rdf` class when the child does not define `Rdf`. If the child declares `class Rdf:`, it **replaces** the parent’s config entirely — do not use an empty nested `Rdf` on a subclass.
+
+### Term conversion
+
+| Python | RDF (export) |
+|--------|----------------|
+| `str` (not IRI-like) | `xsd:string` literal |
+| `str` with an RFC 3986 scheme (`http:`, `https:`, `urn:`, `mailto:`, `file:`, …) | `URIRef` |
+| `int`, `float`, `bool`, `date`, `datetime` | XSD-typed literal |
+
+Import uses each field’s type annotation. `BNode` objects cannot be coerced into `str` fields.
+
+## API reference
+
+### `TripleModel` methods
+
+| | Method | Description |
+|---|--------|-------------|
+| Instance | `subject_uri(uri=None)` | Subject IRI |
+| Instance | `to_triples(uri=None)` | `(subject, predicate, object)` tuples |
+| Instance | `to_graph(graph=None, uri=None)` | Serialize into a `Graph` |
+| Class | `from_graph(graph, uri, validate_type=True, on_duplicate="warn")` | Load one resource |
+| Class | `all_from_graph(graph, type_uri=None, validate_type=True, on_duplicate="warn")` | Load all resources of this `type_uri` |
+| Class | `rdf_config()` | Resolved `RdfConfig` |
+
+### Module-level API
+
+| Name | Description |
+|------|-------------|
+| `rdf_field`, `Predicate`, `OnDuplicate` | Predicate metadata; duplicate-import policy type |
+| `RdfConfig`, `TripleModel` | Config dataclass and base model |
+| `model_to_graph`, `model_to_triples`, `models_to_graph` | Export without subclassing |
+| `graph_to_model`, `graph_to_models` | Import into a model class |
+| `subject_base`, `id_from_subject_uri` | Subject IRI building and parsing |
+| `RDF`, `RDFS`, `XSD`, `RDF_TYPE` | Common namespace IRIs |
+
+## Examples
+
+### Batch export into one graph
+
+```python
+from rdflib import Graph
+from triplemodel import TripleModel, models_to_graph, rdf_field
+
+FOAF = "http://xmlns.com/foaf/0.1/"
+
+
+class Person(TripleModel):
+    class Rdf:
+        namespace = "http://example.org/people/"
+        type_uri = f"{FOAF}Person"
+        id_field = "slug"
+
+    slug: str
+    name: str = rdf_field(f"{FOAF}name")
+
+
+people = [
+    Person(slug="alice", name="Alice"),
+    Person(slug="bob", name="Bob"),
+]
+graph = models_to_graph(people)
+
+# Or merge into an existing graph (rdflib Graph() is falsy when empty — pass explicitly)
+existing = Graph()
+models_to_graph(people, existing)
+```
+
+### Encoded subject ids
+
+```python
+from triplemodel import TripleModel, rdf_field
+
+FOAF = "http://xmlns.com/foaf/0.1/"
+
+
+class Person(TripleModel):
+    class Rdf:
+        namespace = "http://example.org/people/"
+        type_uri = f"{FOAF}Person"
+        id_field = "slug"
+
+    slug: str
+    name: str = rdf_field(f"{FOAF}name")
+
+
+bob = Person(slug="bob jones", name="Bob")
+uri = bob.subject_uri()  # .../bob%20jones
+restored = Person.from_graph(bob.to_graph(), uri)
+assert restored == bob
+```
+
+## TripleModel vs SparqlModel
+
+| Need | Use |
+|------|-----|
+| Turn a model instance into triples / load from a `Graph` | **TripleModel** (`pip install triplemodel`) |
+| Turtle/JSON-LD files, namespaces, datasets (roadmap) | **TripleModel** |
+| `session.put`, queries, cascade delete, HTTP store | **[SparqlModel](https://github.com/eddiethedean/sqarqlmodel)** |
+
+Details: [project plan](https://github.com/eddiethedean/triplemodel/blob/main/docs/PLAN.md) · [ecosystem guide](https://github.com/eddiethedean/triplemodel/blob/main/docs/ECOSYSTEM.md).
+
+## Limitations (0.1.x)
+
+- **Single value per predicate** — multiple objects import only the first; a warning is emitted by default (`on_duplicate="warn"`). Full multi-value fields land in [0.2.0](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md).
+- **Flat models** — no nested `TripleModel` or RDF lists yet.
+- **In-memory graphs only** — no `parse` / `serialize` until [0.4.0](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md).
+- **No sync/remove** — re-export does not drop triples for cleared fields until [0.2.0](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md).
+- **`from_graph` type check** — when `Rdf.type_uri` is set, import requires that triple unless `validate_type=False`.
+- **`uri=` override** — `from_graph` can only derive `id_field` when the subject URI is under `Rdf.namespace`; off-namespace URIs fail validation unless you add triples another way.
+- **Empty child `class Rdf:`** — shadows the parent and clears `namespace` / `type_uri` / `id_field`; omit `Rdf` on the child to inherit.
+- **`type_uri=""` or other falsy config** — treated as unset (no `rdf:type` on export, no type filter on import).
+- **`id_from_subject_uri`** — returns the URI suffix after the namespace base (may include extra `/` segments); not a single-segment validator.
+- **`id_field` values `False` or `0`** — are valid ids (not treated as empty).
+- **BNode subjects** — skipped in `all_from_graph()`.
+- **Non-XSD boolean literals** — `bool` fields without `xsd:boolean` use a loose truthiness heuristic on import.
+- **Union field types** (e.g. `str | int`) rely on rdflib `toPython()` when the annotation is not a single scalar type.
+
+## Development
+
+```bash
+git clone https://github.com/eddiethedean/triplemodel.git
+cd triplemodel
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+ruff format src tests && ruff check src tests
+ty check src tests
+PYTHONPATH=src python examples/readme_examples.py
+```
+
+CI runs on Python 3.10, 3.11, 3.12, and 3.13. Release steps: [RELEASING.md](https://github.com/eddiethedean/triplemodel/blob/main/RELEASING.md).
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [CHANGELOG](https://github.com/eddiethedean/triplemodel/blob/main/CHANGELOG.md) | Release notes |
+| [Roadmap](https://github.com/eddiethedean/triplemodel/blob/main/docs/ROADMAP.md) | Versions and rdflib parity |
+| [Plan](https://github.com/eddiethedean/triplemodel/blob/main/docs/PLAN.md) | Strategy and priorities |
+| [Ecosystem](https://github.com/eddiethedean/triplemodel/blob/main/docs/ECOSYSTEM.md) | triplemodel ↔ SparqlModel boundaries |
+
+## License
+
+MIT — see [LICENSE](https://github.com/eddiethedean/triplemodel/blob/main/LICENSE).

triplemodel-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+triplemodel/__init__.py,sha256=4vlR2emen_9IUBZb3bh-czNFlDeYnyypgGIPrzy-i_4,855
+triplemodel/_config.py,sha256=ShND_M2hbznWXBw2GwNbFCXMU3dkwy6njP0lwd91lSg,2421
+triplemodel/_fields.py,sha256=vgQ_GwZSIDKVt-wnzhrUjMLN5jX6UYvNJZmLzUCXNTY,1665
+triplemodel/_graph.py,sha256=3-Pwe5r9FFlpK5xasmTH7tM5Rv49v0eGcDacp4q4q78,6294
+triplemodel/_types.py,sha256=cOFDt8ZAH0lzTbeINIMOSipZ8MyQvuyQZ9wcktAYPP0,2193
+triplemodel/model.py,sha256=6aJ5EnIWXwRwuirPTko2SE0i94VBMMI7DIr9DsGj8zs,3060
+triplemodel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+triplemodel-0.1.0.dist-info/METADATA,sha256=7dcGR5pFV4aVzqDDEpstPaPpQ9q6tkdz1mmiB4nL_sQ,12044
+triplemodel-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+triplemodel-0.1.0.dist-info/licenses/LICENSE,sha256=dR0Xh1E79TnwCBAWMMOKGrPofjGpAkfiAP1jmYWQ3pg,1081
+triplemodel-0.1.0.dist-info/RECORD,,

triplemodel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

triplemodel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TripleModel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.