From a7af72ec59a562ede00bae7022aa3e13c76f05db Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Fri, 17 Jan 2025 18:20:19 -0700 Subject: [PATCH] Add entry points documentation for RecordFactory --- doc/lsst.daf.butler/dev/entryPoints.rst | 34 +++++++++++++++++++++++++ doc/lsst.daf.butler/index.rst | 1 + 2 files changed, 35 insertions(+) create mode 100644 doc/lsst.daf.butler/dev/entryPoints.rst diff --git a/doc/lsst.daf.butler/dev/entryPoints.rst b/doc/lsst.daf.butler/dev/entryPoints.rst new file mode 100644 index 0000000000..35b2b85f31 --- /dev/null +++ b/doc/lsst.daf.butler/dev/entryPoints.rst @@ -0,0 +1,34 @@ +.. _lsst.daf.butler-dev_entry_points: + +.. py:currentmodule:: lsst.daf.butler + +Support Entry Points +-------------------- + +Some functionality is enabled by utilizing the Python entry points system. +Entry points are managed by the ``project.entry_points`` section of the ``pyproject.toml`` file. + + +Command Line Subcommands +^^^^^^^^^^^^^^^^^^^^^^^^ + +The entry points that support command-line subcommands are documented in :ref:`daf_butler_cli-entry-points`. + +ObsCore RecordFactory +^^^^^^^^^^^^^^^^^^^^^ + +`lsst.daf.butler.registry.obscore.RecordFactory` is the class that generates ObsCore records from Butler datasets. +This conversion generally requires decisions to be made that depend on the dimension universe for the butler. +The default implementation only works with the ``daf_butler`` dimension universe namespace. +Alternative implementations can be registered using the ``butler.obscore_factory`` entry point group. +The label associated with the entry point should correspond to the universe namespace. + +For example, a hypothetical entry point for the default namespace could be written in the ``pyproject.toml`` file as: + +.. code-block:: TOML + + [project.entry-points.'butler.obscore_factory'] + daf_butler = "lsst.daf.butler.registry.obscore._records.DafButlerRecordFactory" + +The function listed for the entry point should return the Python type that should be used to generate records. +It is required to be a subclass of `lsst.daf.butler.registry.obscore.RecordFactory`. diff --git a/doc/lsst.daf.butler/index.rst b/doc/lsst.daf.butler/index.rst index 3b71642a0e..90a2acc10c 100644 --- a/doc/lsst.daf.butler/index.rst +++ b/doc/lsst.daf.butler/index.rst @@ -85,6 +85,7 @@ You can find Jira issues for this module under the `daf_butler