httk.core.register
==================

.. py:module:: httk.core.register


Attributes
----------

.. autoapisummary::

   httk.core.register.loaders
   httk.core.register.loader_filenames
   httk.core.register.format_adapters
   httk.core.register.entry_providers
   httk.core.register.CLIHandler


Classes
-------

.. autoapisummary::

   httk.core.register.CLICommand


Functions
---------

.. autoapisummary::

   httk.core.register.register_loader
   httk.core.register.known_extensions
   httk.core.register.known_filenames
   httk.core.register.register_format_adapter
   httk.core.register.known_format_adapters
   httk.core.register.register_entry_provider
   httk.core.register.known_entry_providers
   httk.core.register.register_cli_command
   httk.core.register.known_cli_commands
   httk.core.register.cli_command


Module Contents
---------------

.. py:data:: loaders

.. py:data:: loader_filenames

.. py:data:: format_adapters

.. py:function:: register_loader(*, name: str, loader: str, extensions: tuple[str, Ellipsis] = (), filenames: tuple[str, Ellipsis] = ()) -> None

   Register a loader under one or more file ``extensions`` and/or ``filenames``.

   ``extensions`` are matched (case-insensitively) against a file's suffix, e.g.
   ``".cif"``. ``filenames`` are exact basenames matched (case-insensitively)
   against a file's name with any recognized compression suffix stripped, e.g.
   ``"POSCAR"`` matches ``POSCAR``, ``poscar``, and ``POSCAR.bz2``.


.. py:function:: known_extensions() -> list[str]

.. py:function:: known_filenames() -> list[str]

.. py:function:: register_format_adapter(*, name: str, adapter: str | collections.abc.Callable[Ellipsis, Any], formats: collections.abc.Sequence[str]) -> None

   Register one lazy adapter for each neutral payload format in ``formats``.

   ``adapter`` may be a callable or a lazy ``"module:callable"`` reference.
   A format tag has one owner: registering it again raises an error naming both
   the existing and attempted registrants.


.. py:function:: known_format_adapters() -> dict[str, str]

   Return format tags mapped to their registered adapter names.


.. py:data:: entry_providers

.. py:function:: register_entry_provider(*, name: str, factory: str) -> None

   Register an :class:`~httk.core.entry_provider.EntryProvider` factory under ``name``.

   ``factory`` is a lazy ``"module:callable"`` reference to a callable that
   constructs a provider (providers need data, so applications call the factory
   themselves; the registry only records how to reach it). This mirrors
   ``register_loader``.


.. py:function:: known_entry_providers() -> list[str]

.. py:data:: CLIHandler

.. py:class:: CLICommand

   Registration metadata for one top-level :command:`httk` command.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: handler
      :type:  str | collections.abc.Callable[Ellipsis, Any]


   .. py:attribute:: summary
      :type:  str


   .. py:method:: resolve() -> CLIHandler

      Import and return the registered command implementation.



.. py:function:: register_cli_command(name: str, handler: str | collections.abc.Callable[Ellipsis, Any], summary: str) -> None

   Register a lazy top-level :command:`httk` command.

   A handler is either a callable or a lazy ``"module:callable"`` reference
   with the contract ``(argv: Sequence[str], context: CLIContext) -> int``.
   Names use lowercase, hyphen-separated command syntax. Registration is
   intentionally strict: reserved names and duplicate registrations are
   errors rather than order-dependent overrides.


.. py:function:: known_cli_commands() -> list[str]

   Return registered top-level command names without resolving handlers.


.. py:function:: cli_command(name: str) -> CLICommand | None

   Return command metadata without importing its implementation.