sysml2kit 0.0.1__py3-none-any.whl

sysml2kit/__init__.py

@@ -0,0 +1,14 @@
+"""API-first Python tooling for building, querying, validating, and automating SysML v2 models.
+
+The 0.0.x releases are a published skeleton; the object model, writer, and
+queries land in 0.1.0. See https://github.com/jman4162/sysml2kit.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sysml2kit")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

sysml2kit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

sysml2kit/cli.py

@@ -0,0 +1,26 @@
+"""Command line for sysml2kit.
+
+Subcommands ``show``, ``validate``, ``diff``, and ``export`` arrive with the
+0.1.0 core; this module currently exposes ``version`` only.
+"""
+
+import typer
+
+import sysml2kit
+
+app = typer.Typer(no_args_is_help=True, help=__doc__)
+
+
+@app.callback()
+def main() -> None:
+    """Work with SysML v2 models from the command line."""
+
+
+@app.command()
+def version() -> None:
+    """Print the installed sysml2kit version."""
+    typer.echo(sysml2kit.__version__)
+
+
+if __name__ == "__main__":
+    app()

sysml2kit/interchange/__init__.py

@@ -0,0 +1,13 @@
+"""Systems Modeling API JSON interchange: the primary lossless format."""
+
+from sysml2kit.interchange.reader import InterchangeError, model_from_json, record_to_element
+from sysml2kit.interchange.writer import element_to_record, model_to_json, write_json
+
+__all__ = [
+    "InterchangeError",
+    "element_to_record",
+    "model_from_json",
+    "model_to_json",
+    "record_to_element",
+    "write_json",
+]

sysml2kit/interchange/reader.py

@@ -0,0 +1,106 @@
+"""Read Systems Modeling API JSON records into a Model.
+
+Unknown ``@type`` records become :class:`OpaqueElement` with the raw record
+preserved verbatim (and ownership links kept), so re-export reproduces them
+unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from pydantic import ValidationError
+
+from sysml2kit.model.base import Element, OpaqueElement, Ref
+from sysml2kit.model.container import Model
+from sysml2kit.model.values import AttributeValue
+
+from .typemap import TYPE_TO_CLASS
+
+
+class InterchangeError(ValueError):
+    """A record could not be turned into an element."""
+
+
+def _snake(name: str) -> str:
+    out = []
+    for ch in name:
+        if ch.isupper():
+            out.append("_")
+            out.append(ch.lower())
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def _decode(field_type: Any, value: Any) -> Any:
+    if isinstance(value, dict) and set(value) == {"@id"}:
+        return Ref(target=UUID(value["@id"]))
+    if isinstance(value, dict) and field_type is AttributeValue:
+        return AttributeValue(**value)
+    if isinstance(value, list):
+        return [_decode(None, item) for item in value]
+    return value
+
+
+def record_to_element(record: dict[str, Any]) -> Element:
+    """Deserialize one interchange record to an element."""
+    type_name = record.get("@type")
+    if not isinstance(type_name, str):
+        raise InterchangeError(f"record without a string @type: {record.get('@id', '?')}")
+    eid = record.get("@id")
+    if not isinstance(eid, str):
+        raise InterchangeError(f"record without a string @id (type {type_name})")
+    cls = TYPE_TO_CLASS.get(type_name)
+    if cls is None:
+        return OpaqueElement(element_id=UUID(eid), type_name=type_name, raw=dict(record))
+    kwargs: dict[str, Any] = {"element_id": UUID(eid)}
+    fields = cls.model_fields
+    for key, value in record.items():
+        if key in {"@id", "@type", "owningRelatedElement"}:
+            continue
+        field = _snake(key)
+        if field not in fields:
+            continue
+        annotation = fields[field].annotation
+        target_type = (
+            AttributeValue if annotation in (AttributeValue, AttributeValue | None) else None
+        )
+        kwargs[field] = _decode(target_type, value)
+    try:
+        return cls(**kwargs)
+    except ValidationError as exc:
+        raise InterchangeError(f"invalid {type_name} record {eid}: {exc}") from exc
+
+
+def model_from_json(data: list[dict[str, Any]] | str | Path) -> Model:
+    """Build a Model from a record list, a JSON string, or a file path."""
+    if isinstance(data, Path):
+        records = json.loads(data.read_text())
+    elif isinstance(data, str):
+        source = Path(data)
+        text = source.read_text() if source.exists() else data
+        records = json.loads(text)
+    else:
+        records = data
+    if not isinstance(records, list):
+        raise InterchangeError("interchange JSON must be a list of records")
+
+    model = Model()
+    owners: dict[UUID, UUID] = {}
+    for record in records:
+        element = record_to_element(record)
+        model.elements[element.element_id] = element
+        owning = record.get("owningRelatedElement")
+        if isinstance(owning, dict) and "@id" in owning:
+            owners[element.element_id] = UUID(owning["@id"])
+
+    for eid, oid in owners.items():
+        if oid in model.elements:
+            model.owner[eid] = oid
+            model.owned.setdefault(oid, []).append(eid)
+    model.roots = [eid for eid in model.elements if eid not in model.owner]
+    return model

sysml2kit/interchange/typemap.py

@@ -0,0 +1,62 @@
+"""The ``@type`` vocabulary mapping, pinned to SysML-v2-Release 2026-05.
+
+This is the only module allowed to hard-code spec ``@type`` strings; spec
+bumps start (and mostly end) here. The reified traceability relationships
+serialize under the closest standard names with a simplified
+``source``/``target`` structure — a documented deviation, see SPEC.md.
+"""
+
+from __future__ import annotations
+
+from sysml2kit.model.analysis import AnalysisCaseDefinition, AnalysisCaseUsage
+from sysml2kit.model.base import Element
+from sysml2kit.model.metadata import MetadataDefinition, MetadataUsage
+from sysml2kit.model.relations import (
+    AllocateRelationship,
+    DeriveRelationship,
+    SatisfyRelationship,
+    VerifyRelationship,
+)
+from sysml2kit.model.requirements import (
+    ConstraintUsage,
+    RequirementDefinition,
+    RequirementUsage,
+)
+from sysml2kit.model.structure import (
+    AttributeDefinition,
+    AttributeUsage,
+    ConnectionUsage,
+    InterfaceDefinition,
+    Package,
+    PartDefinition,
+    PartUsage,
+    PortDefinition,
+    PortUsage,
+)
+
+#: Class -> interchange ``@type`` string.
+CLASS_TO_TYPE: dict[type[Element], str] = {
+    Package: "Package",
+    PartDefinition: "PartDefinition",
+    PartUsage: "PartUsage",
+    PortDefinition: "PortDefinition",
+    PortUsage: "PortUsage",
+    InterfaceDefinition: "InterfaceDefinition",
+    ConnectionUsage: "ConnectionUsage",
+    AttributeDefinition: "AttributeDefinition",
+    AttributeUsage: "AttributeUsage",
+    RequirementDefinition: "RequirementDefinition",
+    RequirementUsage: "RequirementUsage",
+    ConstraintUsage: "ConstraintUsage",
+    AnalysisCaseDefinition: "AnalysisCaseDefinition",
+    AnalysisCaseUsage: "AnalysisCaseUsage",
+    MetadataDefinition: "MetadataDefinition",
+    MetadataUsage: "MetadataUsage",
+    SatisfyRelationship: "SatisfyRequirementUsage",
+    VerifyRelationship: "VerifyRequirementUsage",
+    DeriveRelationship: "DeriveRequirementUsage",
+    AllocateRelationship: "AllocationUsage",
+}
+
+#: Interchange ``@type`` string -> class (inverse of CLASS_TO_TYPE).
+TYPE_TO_CLASS: dict[str, type[Element]] = {name: cls for cls, name in CLASS_TO_TYPE.items()}

sysml2kit/interchange/writer.py

@@ -0,0 +1,73 @@
+"""Write a Model as Systems Modeling API JSON records.
+
+Output is deterministic — elements sorted by qualified name, keys sorted
+within each record — so committed interchange files diff cleanly.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from sysml2kit.model.base import Element, OpaqueElement, Ref
+from sysml2kit.model.container import Model
+from sysml2kit.model.values import AttributeValue
+
+from .typemap import CLASS_TO_TYPE
+
+#: Element fields serialized by the generic path for every class.
+_COMMON_FIELDS = ("declared_name", "declared_short_name", "doc")
+
+
+def _camel(name: str) -> str:
+    head, *tail = name.split("_")
+    return head + "".join(word.capitalize() for word in tail)
+
+
+def _encode(value: Any) -> Any:
+    if isinstance(value, Ref):
+        return {"@id": str(value.target)}
+    if isinstance(value, UUID):
+        return {"@id": str(value)}
+    if isinstance(value, AttributeValue):
+        return {k: v for k, v in value.model_dump().items() if v is not None}
+    if isinstance(value, list):
+        return [_encode(item) for item in value]
+    return value
+
+
+def element_to_record(model: Model, element: Element) -> dict[str, Any]:
+    """Serialize one element to its interchange record."""
+    if isinstance(element, OpaqueElement):
+        return dict(element.raw)
+    type_name = CLASS_TO_TYPE.get(type(element))
+    if type_name is None:
+        raise TypeError(f"no @type mapping for {type(element).__name__}")
+    record: dict[str, Any] = {"@id": str(element.element_id), "@type": type_name}
+    owner = model.owner.get(element.element_id)
+    if owner is not None:
+        record["owningRelatedElement"] = {"@id": str(owner)}
+    for field in type(element).model_fields:
+        if field == "element_id":
+            continue
+        value = getattr(element, field)
+        if value is None or value == [] or value == {}:
+            continue
+        record[_camel(field)] = _encode(value)
+    return record
+
+
+def model_to_json(model: Model) -> list[dict[str, Any]]:
+    """Serialize the model to a sorted list of interchange records."""
+    ordered = sorted(model.elements.values(), key=lambda el: model.qualified_name(el))
+    return [
+        {k: record[k] for k in sorted(record)}
+        for record in (element_to_record(model, el) for el in ordered)
+    ]
+
+
+def write_json(model: Model, path: str | Path) -> None:
+    """Write the model to a JSON file with a trailing newline."""
+    Path(path).write_text(json.dumps(model_to_json(model), indent=2) + "\n")

sysml2kit/model/__init__.py

@@ -0,0 +1,59 @@
+"""The sysml2kit object model: the pragmatic profile plus the Model container."""
+
+from sysml2kit.model.analysis import AnalysisCaseDefinition, AnalysisCaseUsage
+from sysml2kit.model.base import Element, OpaqueElement, Ref, Relationship
+from sysml2kit.model.container import STABLE_ID_NAMESPACE, Model
+from sysml2kit.model.metadata import MetadataDefinition, MetadataUsage
+from sysml2kit.model.relations import (
+    AllocateRelationship,
+    DeriveRelationship,
+    SatisfyRelationship,
+    VerifyRelationship,
+)
+from sysml2kit.model.requirements import (
+    ConstraintUsage,
+    RequirementDefinition,
+    RequirementUsage,
+)
+from sysml2kit.model.structure import (
+    AttributeDefinition,
+    AttributeUsage,
+    ConnectionUsage,
+    InterfaceDefinition,
+    Package,
+    PartDefinition,
+    PartUsage,
+    PortDefinition,
+    PortUsage,
+)
+from sysml2kit.model.values import AttributeValue
+
+__all__ = [
+    "STABLE_ID_NAMESPACE",
+    "AllocateRelationship",
+    "AnalysisCaseDefinition",
+    "AnalysisCaseUsage",
+    "AttributeDefinition",
+    "AttributeUsage",
+    "AttributeValue",
+    "ConnectionUsage",
+    "ConstraintUsage",
+    "DeriveRelationship",
+    "Element",
+    "InterfaceDefinition",
+    "MetadataDefinition",
+    "MetadataUsage",
+    "Model",
+    "OpaqueElement",
+    "Package",
+    "PartDefinition",
+    "PartUsage",
+    "PortDefinition",
+    "PortUsage",
+    "Ref",
+    "Relationship",
+    "RequirementDefinition",
+    "RequirementUsage",
+    "SatisfyRelationship",
+    "VerifyRelationship",
+]

sysml2kit/model/analysis.py

@@ -0,0 +1,17 @@
+"""Analysis case elements (stubs in v0.1: subject and objective, no actions)."""
+
+from __future__ import annotations
+
+from sysml2kit.model.base import Element, Ref
+
+
+class AnalysisCaseDefinition(Element):
+    """A reusable definition of an analysis to run against a subject."""
+
+
+class AnalysisCaseUsage(Element):
+    """An analysis occurrence with a subject and an objective statement."""
+
+    definition: Ref | None = None
+    subject: Ref | None = None
+    objective: str | None = None

sysml2kit/model/base.py

@@ -0,0 +1,73 @@
+"""Base element classes and the cross-reference type.
+
+Every cross-reference between elements is a :class:`Ref` (a UUID wrapper),
+never a direct Python object reference, so any element serializes on its own
+and maps 1:1 onto the Systems Modeling API JSON ``{"@id": ...}`` form.
+Ownership is not stored on elements either; the ``Model`` container keeps it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from sysml2kit.model.container import Model
+
+
+class Ref(BaseModel):
+    """Reference to another element by id."""
+
+    model_config = ConfigDict(frozen=True)
+
+    target: UUID
+
+    @classmethod
+    def to(cls, element: Element | UUID | Ref) -> Ref:
+        """Build a Ref from an element, a UUID, or another Ref."""
+        if isinstance(element, Ref):
+            return element
+        if isinstance(element, UUID):
+            return cls(target=element)
+        return cls(target=element.element_id)
+
+    def resolve(self, model: Model) -> Element:
+        """Return the referenced element, raising KeyError if absent."""
+        return model.elements[self.target]
+
+
+class Element(BaseModel):
+    """Common base for every model element in the pragmatic profile."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    element_id: UUID = Field(default_factory=uuid4)
+    declared_name: str | None = None
+    declared_short_name: str | None = None
+    doc: str | None = None
+
+    @property
+    def label(self) -> str:
+        """A human-readable identifier: name, short name, or the id."""
+        return self.declared_name or self.declared_short_name or str(self.element_id)
+
+
+class Relationship(Element):
+    """Common base for reified relationships with a source and a target."""
+
+    source: Ref
+    target: Ref
+
+
+class OpaqueElement(Element):
+    """An element outside the pragmatic profile, preserved verbatim.
+
+    ``raw`` holds the original JSON interchange record; it re-exports
+    unchanged, so reading and writing a model does not drop content the
+    profile has no class for.
+    """
+
+    type_name: str
+    raw: dict[str, Any] = Field(default_factory=dict)