httk.core.property_definitions ============================== .. py:module:: httk.core.property_definitions .. autoapi-nested-parse:: First-class OPTIMADE property and entry-type definitions. An OPTIMADE *property definition* is a self-describing JSON document giving a property's canonical identifier, type, unit, requirements, and human-readable description. An *entry-type definition* bundles the property definitions of one entry type (``structures``, ``references``, ...) together with the entry type's own description. This module models both as immutable Python objects: - :class:`PropertyDefinition` wraps one full property-definition document. It can be built from a vendored OPTIMADE definition (:meth:`PropertyDefinition.from_optimade`) or generated from a compact description (:meth:`PropertyDefinition.from_simple`). - :class:`EntryTypeDefinition` wraps an entry type's description and the ordered mapping of its property definitions, and can be :meth:`~EntryTypeDefinition.extended` with database-specific custom properties. The vendored OPTIMADE standard definitions shipped with httk-core (the ``references``, ``files``, and ``calculations`` entry types) are loaded through :func:`load_entry_type_definition` / :func:`standard_entry_type`. The authoritative, supported copies are the JSON files checked in under ``httk/core/optimade_defs/`` (see the README there). **On the "1.2" definition-format stamp:** :meth:`PropertyDefinition.from_simple` generates only property-definition features that already exist in format ``"1.2"`` of the OPTIMADE property-definition schema, so every generated definition is stamped ``x-optimade-definition.format == "1.2"``. The definition *format* is versioned in lockstep with the OPTIMADE specification and is only bumped when a definition actually uses features introduced by a newer format; custom generated definitions therefore keep the ``"1.2"`` stamp even for entry types (such as ``calculations``) whose specification version is newer. Attributes ---------- .. autoapisummary:: httk.core.property_definitions.PROPERTY_DEFINITION_META_SCHEMA Classes ------- .. autoapisummary:: httk.core.property_definitions.PropertyDefinition httk.core.property_definitions.EntryTypeDefinition Functions --------- .. autoapisummary:: httk.core.property_definitions.register_definition_prefix httk.core.property_definitions.known_definition_prefixes httk.core.property_definitions.load_entry_type_definition httk.core.property_definitions.standard_entry_type Module Contents --------------- .. py:data:: PROPERTY_DEFINITION_META_SCHEMA :value: 'https://schemas.optimade.org/meta/v1.2/optimade/property_definition.json' .. py:function:: register_definition_prefix(prefix: str, id_base: str) -> None Register a database-specific OPTIMADE property-name ``prefix``. A custom property served by a database MUST use such a prefix (see the OPTIMADE specification, "Database-Specific Properties"). Once registered, a property name carrying ``prefix`` gets its ``$id`` synthesized under ``id_base`` by :meth:`PropertyDefinition.from_simple`, and :meth:`EntryTypeDefinition.extended` accepts it as a custom property. ``prefix`` must be a lower-case alphanumeric token wrapped in single underscores (matching ``_[a-z0-9]+_``); anything else raises a clear :class:`ValueError`. Re-registering an existing prefix overwrites its base. .. py:function:: known_definition_prefixes() -> tuple[str, Ellipsis] Return the registered database-specific property-name prefixes. The tuple reflects the current state of the prefix registry (see :func:`register_definition_prefix`); ``_httk_`` and ``_omdb_`` are pre-registered. .. py:class:: PropertyDefinition(name: str, payload: collections.abc.Mapping[str, Any]) An immutable wrapper around one full OPTIMADE property definition. Instances are constructed from a vendored definition document (:meth:`from_optimade`) or generated from a compact description (:meth:`from_simple`). The wrapped document is always deep-copied on the way in and out, so an instance never shares mutable state with its inputs or its callers. .. py:method:: from_optimade(name: str, definition: collections.abc.Mapping[str, Any]) -> Self :classmethod: Wrap a full vendored OPTIMADE property definition. ``definition`` must at least carry ``$id``, ``description``, ``x-optimade-type``, and ``type``; a clear :class:`ValueError` is raised otherwise. The document is deep-copied. .. py:method:: from_simple(name: str, *, description: str, fulltype: str = 'string', unit: str | None = None, dimensions: collections.abc.Mapping[str, Any] | None = None, dict_properties: collections.abc.Mapping[str, str] | None = None, metadata_definition: collections.abc.Mapping[str, Any] | None = None, required_response: bool = False, definition_id: str | None = None) -> Self :classmethod: Generate a property definition from a compact description. This mirrors the OPTIMADE property-definition generator: it emits the ``$schema`` meta-schema reference, a synthesized ``$id`` (under the base registered for a matching prefix via :func:`register_definition_prefix` — e.g. ``httk.org`` for ``_httk_`` / ``_omdb_`` — under ``schemas.optimade.org`` otherwise, unless ``definition_id`` overrides it), a title, the ``description``, the OPTIMADE type derived from ``fulltype`` (``"string"``, ``"integer"``, ``"float"``, ``"boolean"``, ``"timestamp"``, ``"dict"``, or ``"list of ..."``), the ``x-optimade-unit`` (with an ångström unit definition when ``unit == "angstrom"``), the ``x-optimade-definition`` stamp (format ``"1.2"``; see the module docstring), the JSON ``type`` with nullability derived from ``required_response``, ``items`` for lists, a ``date-time`` format for timestamps, inner ``properties`` for dicts (from ``dict_properties``), ``x-optimade-dimensions`` from ``dimensions``, and an ``x-optimade-metadata-definition`` (explicit, or a generated ``list_axes`` definition when ``dimensions`` is given). The result is implementation-neutral: per-deployment ``sortable`` and ``response-default`` flags are layered on later via :meth:`with_implementation`. .. py:property:: name :type: str .. py:property:: definition_id :type: str .. py:property:: title :type: str | None .. py:property:: description :type: str .. py:property:: optimade_type :type: str .. py:property:: json_type :type: Any .. py:property:: nullable :type: bool .. py:property:: unit :type: str | None .. py:property:: format_version :type: str | None .. py:property:: requirements :type: collections.abc.Mapping[str, Any] .. py:property:: dimensions :type: collections.abc.Mapping[str, Any] | None .. py:property:: metadata_definition :type: collections.abc.Mapping[str, Any] | None .. py:method:: with_implementation(*, sortable: bool | None = None, response_default: bool | None = None) -> Self Return a copy carrying this deployment's implementation flags. Adds an ``x-optimade-implementation`` object with the ``sortable`` and ``response-default`` keys that are provided (a ``None`` argument leaves that key unset), and — when ``sortable`` is given — mirrors it in a top-level ``sortable`` field. The original instance is untouched. .. py:method:: as_optimade() -> dict[str, Any] Return a deep copy of the wrapped property-definition document. .. py:class:: EntryTypeDefinition(name: str, description: str, properties: collections.abc.Mapping[str, PropertyDefinition]) An immutable OPTIMADE entry-type definition. Bundles the entry type's ``name`` and ``description`` with an insertion-ordered mapping of :class:`PropertyDefinition` objects (one per described property). A standard definition typically describes more properties than any given deployment serves; the served subset is chosen separately (an :class:`~httk.core.EntryProvider` names it through its :meth:`~httk.core.EntryProvider.columns`). .. py:method:: from_optimade(name: str, entrytype: collections.abc.Mapping[str, Any]) -> Self :classmethod: Build an entry-type definition from a vendored OPTIMADE entry type. ``entrytype`` is the vendored document shape: a ``description`` string and a ``properties`` mapping of property name to full property definition. A clear :class:`ValueError` is raised when either is missing. .. py:property:: name :type: str .. py:property:: description :type: str .. py:property:: properties :type: collections.abc.Mapping[str, PropertyDefinition] .. py:method:: extended(extra: collections.abc.Mapping[str, PropertyDefinition], *, allow_unprefixed: bool = False) -> Self Return a copy with ``extra`` custom property definitions merged in. Each name in ``extra`` MUST be new (a collision with an existing property raises :class:`ValueError` naming it) and, unless ``allow_unprefixed`` is set, MUST carry a registered database-specific prefix (see :func:`register_definition_prefix` / :func:`known_definition_prefixes`); a custom property that does not is rejected with a :class:`ValueError` explaining the OPTIMADE prefix rule. .. py:method:: as_optimade() -> dict[str, Any] Return the entry type as a vendored-shape OPTIMADE document. .. py:function:: load_entry_type_definition(package: str, name: str) -> EntryTypeDefinition Load a vendored OPTIMADE entry-type definition JSON from a package. Reads ``optimade_defs/.json`` from ``package`` (via :mod:`importlib.resources`) and models it as an :class:`EntryTypeDefinition`. Results are cached per ``(package, name)``. .. py:function:: standard_entry_type(name: str) -> EntryTypeDefinition Return one of httk-core's vendored standard OPTIMADE entry types. Supported names are ``"references"``, ``"files"``, and ``"calculations"``; an unknown name raises a :class:`ValueError` listing the known ones. The ``structures`` standard is vendored by *httk-atomistic*, not httk-core.