unicad-kit 0.1.0__py3-none-any.whl

convert/adapters/base/AdapterInfo.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations
+
+from dataclasses import dataclass as DataClass
+from inspect import Parameter as SigParam
+from inspect import Signature as CallSignature
+
+from interchange import Capability
+
+from convert.adapters.base.AdapterInfoView import AdapterInfoView
+from convert.adapters.base.ContractCompat import ContractBase
+
+
+# legacy extension keywords need one strict translation point before document kind lookup
+def IsAssemblyFlag(NamedValues: dict[str, object]) -> bool:
+    AllowedNames = {"assembly", "Assembly"}
+    UnknownNames = tuple(
+        NameText for NameText in NamedValues if NameText not in AllowedNames
+    )
+    if UnknownNames:
+        raise TypeError(
+            "AdapterInfo.extensions_for() got an unexpected keyword argument "
+            + f"{UnknownNames[0]!r}"
+        )
+    if "assembly" in NamedValues and "Assembly" in NamedValues:
+        raise TypeError(
+            "AdapterInfo.extensions_for() got multiple values for 'assembly'"
+        )
+    if not NamedValues:
+        raise TypeError(
+            "AdapterInfo.extensions_for() missing required keyword only argument "
+            + "'assembly'"
+        )
+    Assembly = NamedValues.get("assembly", NamedValues.get("Assembly"))
+    if not isinstance(Assembly, bool):
+        raise TypeError("assembly must be a boolean")
+    return Assembly
+
+
+# adapter metadata gives discovery and selection one immutable format description
+@DataClass(frozen=True, slots=True)
+class AdapterInfo(AdapterInfoView, ContractBase):
+    format_id: str
+    name: str
+    version: str
+    extensions: tuple[str, ...]
+    aliases: tuple[str, ...] = ()
+    capabilities: frozenset[Capability] = frozenset()
+    media_types: tuple[str, ...] = ()
+    native_capabilities: frozenset[Capability] = frozenset()
+    part_extensions: tuple[str, ...] = ()
+    assembly_extensions: tuple[str, ...] = ()
+
+    # canonical extension access remains typed because selectors consume this storage field
+    @property
+    def Extensions(self) -> tuple[str, ...]:
+        return self.extensions
+
+    # document kind lookup belongs here so clients need no format specific branching
+    def ExtensionsFor(self, **NamedValues: object) -> tuple[str, ...]:
+        Assembly = IsAssemblyFlag(NamedValues)
+        return self.assembly_extensions if Assembly else self.part_extensions
+
+    # historical keyword lookup remains typed because api consumers call this public selector
+    def extensions_for(self, **NamedValues: object) -> tuple[str, ...]:
+        return self.ExtensionsFor(**NamedValues)
+
+    # historical representation keeps logs and diagnostics comparable across package upgrades
+    def RenderIdentity(self) -> str:
+        FieldValues = ", ".join(
+            f"{ModelName}={getattr(self, ModelName)!r}" for ModelName in KModelFields
+        )
+        return f"AdapterInfo({FieldValues})"
+
+    __repr__ = RenderIdentity
+
+
+# canonical field order remains necessary for immutable slot pickle restoration
+KModelFields: tuple[str, ...] = (
+    "format_id",
+    "name",
+    "version",
+    "extensions",
+    "aliases",
+    "capabilities",
+    "media_types",
+    "native_capabilities",
+    "part_extensions",
+    "assembly_extensions",
+)
+
+
+# immutable slot pickles read canonical storage despite historical field reflection
+def GetPickleState(SelfValue: AdapterInfo) -> tuple[object, ...]:
+    return tuple(getattr(SelfValue, ModelName) for ModelName in KModelFields)
+
+
+# canonical restoration prevents historical reflected names from targeting invalid slots
+def SetPickleState(SelfValue: AdapterInfo, FieldValues: tuple[object, ...]) -> None:
+    for ModelName, FieldValue in zip(KModelFields, FieldValues):
+        object.__setattr__(SelfValue, ModelName, FieldValue)
+
+
+setattr(AdapterInfo, "__getstate__", GetPickleState)
+setattr(AdapterInfo, "__setstate__", SetPickleState)
+
+
+# reflected signatures keep the historical keyword only assembly contract introspectable
+def ApplySignatures() -> None:
+    setattr(AdapterInfo.extensions_for, "__module__", "convert.adapters.base")
+    setattr(
+        AdapterInfo.extensions_for,
+        "__annotations__",
+        {"assembly": "bool", "return": "tuple[str, ...]"},
+    )
+    setattr(
+        AdapterInfo.extensions_for,
+        "__signature__",
+        CallSignature(
+            (
+                SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+                SigParam(
+                    "assembly",
+                    SigParam.KEYWORD_ONLY,
+                    annotation="bool",
+                ),
+            ),
+            return_annotation="tuple[str, ...]",
+        ),
+    )
+
+
+ApplySignatures()
+
+setattr(
+    AdapterInfo,
+    "__match_args__",
+    (
+        "format_id",
+        "name",
+        "version",
+        "extensions",
+        "aliases",
+        "capabilities",
+        "media_types",
+        "native_capabilities",
+        "part_extensions",
+        "assembly_extensions",
+    ),
+)
+
+setattr(
+    AdapterInfo.__init__,
+    "__signature__",
+    CallSignature(
+        (
+            SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+            *AdapterInfo.__signature__.parameters.values(),
+        ),
+        return_annotation=None,
+    ),
+)
+setattr(
+    AdapterInfo.__init__,
+    "__annotations__",
+    {
+        **AdapterInfo.__annotations__,
+        "return": None,
+    },
+)

convert/adapters/base/AdapterInfoView.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations
+
+from typing import cast as CastValue
+
+from interchange import Capability
+
+
+# registry internals read adapter metadata through typed accessors rather than raw storage
+class AdapterInfoView:
+    __slots__ = ()
+
+    # canonical format access remains typed because registry internals read this storage field
+    @property
+    def FormatId(self) -> str:
+        return CastValue(str, getattr(self, "format_id"))
+
+    # canonical display access remains typed because catalogs render this storage field
+    @property
+    def DisplayName(self) -> str:
+        return CastValue(str, getattr(self, "name"))
+
+    # canonical version access remains typed because plugin diagnostics expose this storage field
+    @property
+    def VersionText(self) -> str:
+        return CastValue(str, getattr(self, "version"))
+
+    # canonical alias access remains typed because registry namespaces consume this storage field
+    @property
+    def AliasNames(self) -> tuple[str, ...]:
+        return CastValue(tuple[str, ...], getattr(self, "aliases"))
+
+    # canonical capability access remains typed because policy callers compare this storage field
+    @property
+    def Capabilities(self) -> frozenset[Capability]:
+        return CastValue(frozenset[Capability], getattr(self, "capabilities"))
+
+    # canonical media access remains typed because discovery consumers inspect this storage field
+    @property
+    def MediaTypes(self) -> tuple[str, ...]:
+        return CastValue(tuple[str, ...], getattr(self, "media_types"))
+
+    # canonical native capability access remains typed because transfer policy consumes this field
+    @property
+    def NativeCaps(self) -> frozenset[Capability]:
+        return CastValue(
+            frozenset[Capability],
+            getattr(self, "native_capabilities"),
+        )
+
+    # canonical part extension access remains typed because document routing consumes this field
+    @property
+    def PartExts(self) -> tuple[str, ...]:
+        return CastValue(tuple[str, ...], getattr(self, "part_extensions"))
+
+    # canonical assembly extension access remains typed because document routing consumes this field
+    @property
+    def AssemblyExts(self) -> tuple[str, ...]:
+        return CastValue(tuple[str, ...], getattr(self, "assembly_extensions"))

convert/adapters/base/AdapterMetadata.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations
+
+from typing import Protocol
+from typing import TypeGuard
+
+from interchange import Capability
+
+from convert.adapters.base.AdapterInfo import AdapterInfo
+from convert.adapters.registry.RegistryErrors import RegistryError
+
+
+# adapter discovery needs an inspectable metadata boundary before trusting plugin values
+class InfoSource(Protocol):
+
+    # object output preserves runtime validation for plugins outside static checking
+    @property
+    def info(self) -> object:
+        raise TypeError("adapter metadata requires a concrete implementation")
+
+
+# tuple narrowing keeps untyped plugin values inspectable without weakening member types
+def IsObjectTuple(FieldValue: object) -> TypeGuard[tuple[object, ...]]:
+    return isinstance(FieldValue, tuple)
+
+
+# frozen set narrowing keeps capability validation concrete after plugin boundaries
+def IsObjectSet(FieldValue: object) -> TypeGuard[frozenset[object]]:
+    return isinstance(FieldValue, frozenset)
+
+
+# scalar metadata must remain normalized text because registry keys depend on it
+def CheckText(FieldName: str, FieldValue: object) -> None:
+    if not isinstance(FieldValue, str):
+        raise RegistryError(f"adapter {FieldName} has an invalid type")
+    if not FieldValue.strip() or FieldValue != FieldValue.strip():
+        raise RegistryError(f"adapter {FieldName} must be a non-empty string")
+
+
+# string tuple validation rejects whitespace and case insensitive duplicates before lookup begins
+def CheckTextTuple(FieldName: str, FieldValue: object) -> None:
+    if not IsObjectTuple(FieldValue):
+        raise RegistryError(f"adapter {FieldName} has an invalid type")
+    TextValues: list[str] = []
+    for MemberValue in FieldValue:
+        if (
+            not isinstance(MemberValue, str)
+            or not MemberValue.strip()
+            or MemberValue != MemberValue.strip()
+        ):
+            raise RegistryError(f"adapter {FieldName} must be a string tuple")
+        TextValues.append(MemberValue)
+    if len({MemberValue.casefold() for MemberValue in TextValues}) != len(TextValues):
+        raise RegistryError(f"adapter {FieldName} must be unique")
+
+
+# capability sets stay immutable and enum bounded so selection evidence is trustworthy
+def CheckCapSet(FieldName: str, FieldValue: object) -> None:
+    if not IsObjectSet(FieldValue) or any(
+        not isinstance(MemberValue, Capability) for MemberValue in FieldValue
+    ):
+        raise RegistryError(f"adapter {FieldName} has an invalid type")
+
+
+# metadata field checks stay isolated because schema validation changes independently from namespace rules
+def CheckInfoFields(InfoData: AdapterInfo) -> None:
+    TextFields: tuple[tuple[str, object], ...] = (
+        ("format_id", InfoData.FormatId),
+        ("name", InfoData.DisplayName),
+        ("version", InfoData.VersionText),
+    )
+    TupleFields: tuple[tuple[str, object], ...] = (
+        ("extensions", InfoData.Extensions),
+        ("aliases", InfoData.AliasNames),
+        ("media_types", InfoData.MediaTypes),
+        ("part_extensions", InfoData.PartExts),
+        ("assembly_extensions", InfoData.AssemblyExts),
+    )
+    CapFields: tuple[tuple[str, object], ...] = (
+        ("capabilities", InfoData.Capabilities),
+        ("native_capabilities", InfoData.NativeCaps),
+    )
+    for FieldName, FieldValue in TextFields:
+        CheckText(FieldName, FieldValue)
+    for FieldName, FieldValue in TupleFields:
+        CheckTextTuple(FieldName, FieldValue)
+    for FieldName, FieldValue in CapFields:
+        CheckCapSet(FieldName, FieldValue)
+
+
+# extension validation keeps document kind subsets consistent with the advertised format
+def CheckExtensions(InfoData: AdapterInfo) -> None:
+    ExtensionKeys = {ValueText.casefold() for ValueText in InfoData.Extensions}
+    if any(not ValueText.startswith(".") for ValueText in InfoData.Extensions):
+        raise RegistryError("adapter extensions must begin with a dot")
+    for KindName, ExtensionValues in (
+        ("part", InfoData.PartExts),
+        ("assembly", InfoData.AssemblyExts),
+    ):
+        if any(
+            ValueText.casefold() not in ExtensionKeys for ValueText in ExtensionValues
+        ):
+            raise RegistryError(
+                f"adapter {KindName} extensions must also be declared extensions"
+            )
+
+
+# complete validation returns the trusted object so registration remains expression friendly
+def ValidateInfo(AdapterData: InfoSource) -> AdapterInfo:
+    InfoValue = AdapterData.info
+    if not isinstance(InfoValue, AdapterInfo):
+        raise RegistryError("adapter info must be AdapterInfo")
+    InfoData = InfoValue
+    CheckInfoFields(InfoData)
+    if InfoData.FormatId.casefold() in {
+        AliasName.casefold() for AliasName in InfoData.AliasNames
+    }:
+        raise RegistryError("adapter alias must differ from its format id")
+    CheckExtensions(InfoData)
+    if not InfoData.NativeCaps <= InfoData.Capabilities:
+        raise RegistryError(
+            "adapter native capabilities must also be preservation capabilities"
+        )
+    return InfoData

convert/adapters/base/AdapterProtocols.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations
+
+from inspect import Parameter as SigParam
+from inspect import Signature as CallSignature
+from typing import Protocol
+from typing import runtime_checkable as RuntimeCheck
+
+from interchange import CadDocument
+
+from convert.adapters.base.AdapterInfo import AdapterInfo
+from convert.adapters.base.ContractTypes import KSourceType
+from convert.adapters.base.ContractTypes import KTargetType
+from convert.adapters.base.ProbeResult import ProbeResult
+from convert.adapters.base.ReadOptions import ReadOptions
+from convert.adapters.base.WriteOptions import WriteOptions
+from convert.adapters.base.WriteResult import WriteResult
+
+# compatibility annotations retain their public contract names for reflection
+Source = KSourceType
+
+# compatibility annotations retain their public contract names for reflection
+Destination = KTargetType
+
+
+# reader registration needs a statically visible structural adapter boundary
+@RuntimeCheck
+class CadReaderAdapter(Protocol):
+
+    # discovery needs metadata before it attempts to consume source data
+    @property
+    def info(self) -> AdapterInfo:
+        raise TypeError("reader info requires a concrete implementation")
+
+    # selection needs a non destructive source compatibility assessment
+    def probe(self, source: Source) -> ProbeResult:
+        raise TypeError("reader probing requires a concrete implementation")
+
+    # conversion needs one neutral document result across reader implementations
+    def read(
+        self,
+        source: Source,
+        options: ReadOptions | None = None,
+    ) -> CadDocument:
+        raise TypeError("reader loading requires a concrete implementation")
+
+
+# writer registration needs a statically visible structural adapter boundary
+@RuntimeCheck
+class CadWriterAdapter(Protocol):
+
+    # discovery needs metadata before it attempts to stage destination output
+    @property
+    def info(self) -> AdapterInfo:
+        raise TypeError("writer info requires a concrete implementation")
+
+    # selection needs a non mutating destination compatibility assessment
+    def supports(self, DocValue: CadDocument, Target: Destination) -> bool:
+        raise TypeError("writer support requires a concrete implementation")
+
+    # conversion needs structured preservation evidence from every writer
+    def write(
+        self,
+        document: CadDocument,
+        destination: Destination,
+        options: WriteOptions | None = None,
+    ) -> WriteResult:
+        raise TypeError("writer output requires a concrete implementation")
+
+
+# bidirectional integrations need one contract combining both adapter directions
+@RuntimeCheck
+class CadAdapter(CadReaderAdapter, CadWriterAdapter, Protocol):
+    __slots__ = ()
+
+
+# reader protocols expose a stable public module so runtime introspection and generated docs agree
+CadReaderAdapter.__module__ = "convert.adapters.base"
+
+# writer protocols need matching module attribution so structural checks treat both directions as one contract
+CadWriterAdapter.__module__ = "convert.adapters.base"
+
+# combined protocol keeps public attribution so callers reflecting the union see the contract package
+CadAdapter.__module__ = "convert.adapters.base"
+
+# string annotations resolve against the public module because runtime signatures carry names not imports
+CadReaderAdapter.read.__module__ = "convert.adapters.base"
+
+# signature metadata must live in the public module so compatibility callers resolve annotations identically
+CadWriterAdapter.write.__module__ = "convert.adapters.base"
+
+setattr(
+    CadReaderAdapter.probe,
+    "__signature__",
+    CallSignature(
+        (
+            SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+            SigParam("source", SigParam.POSITIONAL_OR_KEYWORD, annotation="Source"),
+        ),
+        return_annotation="ProbeResult",
+    ),
+)
+setattr(
+    CadReaderAdapter.read,
+    "__signature__",
+    CallSignature(
+        (
+            SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+            SigParam("source", SigParam.POSITIONAL_OR_KEYWORD, annotation="Source"),
+            SigParam(
+                "options",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                default=None,
+                annotation="ReadOptions | None",
+            ),
+        ),
+        return_annotation="CadDocument",
+    ),
+)
+setattr(
+    CadWriterAdapter.supports,
+    "__signature__",
+    CallSignature(
+        (
+            SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+            SigParam(
+                "DocValue",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                annotation="CadDocument",
+            ),
+            SigParam(
+                "Target",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                annotation="Destination",
+            ),
+        ),
+        return_annotation="bool",
+    ),
+)
+setattr(
+    CadWriterAdapter.write,
+    "__signature__",
+    CallSignature(
+        (
+            SigParam("self", SigParam.POSITIONAL_OR_KEYWORD),
+            SigParam(
+                "document",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                annotation="CadDocument",
+            ),
+            SigParam(
+                "destination",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                annotation="Destination",
+            ),
+            SigParam(
+                "options",
+                SigParam.POSITIONAL_OR_KEYWORD,
+                default=None,
+                annotation="WriteOptions | None",
+            ),
+        ),
+        return_annotation="WriteResult",
+    ),
+)

convert/adapters/base/CapabilityView.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations
+
+from typing import cast as CastValue
+
+from interchange import Capability
+
+from convert.adapters.base.TransferContract import CapTransfer
+from convert.adapters.base.TransferContract import CarrierReason
+from convert.adapters.base.TransferContract import TransferMode
+from convert.adapters.base.WriteValidate import GetCarrierCaps
+from convert.adapters.base.WriteValidate import GetNativeCaps
+
+
+# preservation evidence and verdicts stay readable through one typed capability view
+class CapabilityView:
+    __slots__ = ()
+
+    # callers need one complete preservation view independent from representation mode
+    @property
+    def TransferCaps(self) -> frozenset[Capability]:
+        Transfers = CastValue(tuple[CapTransfer, ...], getattr(self, "transfers"))
+        return frozenset(TransferData.capability for TransferData in Transfers)
+
+    # canonical native capability access supports both modern and historical result consumers
+    @property
+    def NativeCaps(self) -> frozenset[Capability]:
+        Transfers = CastValue(tuple[CapTransfer, ...], getattr(self, "transfers"))
+        return GetNativeCaps(Transfers)
+
+    # canonical carrier capability access keeps reversible preservation evidence directly typed
+    @property
+    def CarrierCaps(self) -> frozenset[Capability]:
+        Transfers = CastValue(tuple[CapTransfer, ...], getattr(self, "transfers"))
+        return GetCarrierCaps(Transfers)
+
+    # roundtrip safety means no source capability was discarded regardless of dependencies
+    @property
+    def IsRoundtripSafe(self) -> bool:
+        return not getattr(self, "dropped")
+
+    # near losslessness requires usable output and only intrinsic target format limitations
+    @property
+    def IsNearLossless(self) -> bool:
+        ApplicationUsable = CastValue(bool, getattr(self, "application_usable"))
+        VendorLoadable = CastValue(bool, getattr(self, "vendor_loadable"))
+        Requirements = CastValue(tuple[str, ...], getattr(self, "requirements"))
+        Dropped = CastValue(frozenset[Capability], getattr(self, "dropped"))
+        Transfers = CastValue(tuple[CapTransfer, ...], getattr(self, "transfers"))
+        return (
+            ApplicationUsable
+            and VendorLoadable
+            and not Requirements
+            and not Dropped
+            and all(
+                TransferData.carrier_reason is CarrierReason.KTargetGap
+                for TransferData in Transfers
+                if TransferData.mode in {TransferMode.KCarrier, TransferMode.KMixed}
+            )
+        )