httk.core.plugins.installed
===========================

.. py:module:: httk.core.plugins.installed

.. autoapi-nested-parse::

   Read installed httk plugins.



Attributes
----------

.. autoapisummary::

   httk.core.plugins.installed.PLUGIN_MANIFEST
   httk.core.plugins.installed.PLUGIN_METADATA


Classes
-------

.. autoapisummary::

   httk.core.plugins.installed.PluginManifest
   httk.core.plugins.installed.PluginProgram
   httk.core.plugins.installed.InstalledPlugin


Functions
---------

.. autoapisummary::

   httk.core.plugins.installed.parse_plugin_manifest
   httk.core.plugins.installed.plugins_home
   httk.core.plugins.installed.shims_home
   httk.core.plugins.installed.installed_plugins
   httk.core.plugins.installed.plugin_root
   httk.core.plugins.installed.plugin_program


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

.. py:data:: PLUGIN_MANIFEST
   :value: 'httk_plugin.toml'


.. py:class:: PluginManifest

   Describe a validated plugin manifest.

   :param name: Name the plugin.
   :param description: Describe the plugin, when supplied.
   :param templates: Name project-template directories.
   :param workflows: Name workflow-package directories.
   :param programs: Describe declared utility programs.
   :param build: Describe the optional build.
   :param root: Locate the parsed plugin directory.


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


   .. py:attribute:: description
      :type:  str | None


   .. py:attribute:: templates
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: workflows
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: programs
      :type:  tuple[PluginProgram, Ellipsis]


   .. py:attribute:: build
      :type:  httk.core.building.BuildSpec | None


   .. py:attribute:: root
      :type:  pathlib.Path


.. py:class:: PluginProgram

   Describe one declared plugin program.

   :param name: Name the program and its shim.
   :param file: Name the program member relative to the plugin root.
   :param description: Describe the program, when supplied.


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


   .. py:attribute:: file
      :type:  str


   .. py:attribute:: description
      :type:  str | None


.. py:function:: parse_plugin_manifest(directory)

   Parse and validate one plugin manifest.

   :param directory: Locate the plugin directory.
   :return: The validated plugin manifest.
   :raises ValueError: If the plugin directory or manifest is malformed.


.. py:data:: PLUGIN_METADATA
   :value: 'plugin.json'


.. py:class:: InstalledPlugin

   Describe one installed plugin and its installer metadata.

   :param name: Name the installed plugin directory.
   :param root: Locate the installed plugin directory.
   :param manifest: Provide the parsed plugin.json object.
   :param metadata: Provide the parsed plugin.json object.


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


   .. py:attribute:: root
      :type:  pathlib.Path


   .. py:attribute:: manifest
      :type:  httk.core.plugins.manifest.PluginManifest


   .. py:attribute:: metadata
      :type:  collections.abc.Mapping[str, object]


.. py:function:: plugins_home()

   Return the installed plugin directory.

   :return: The plugin data directory.


.. py:function:: shims_home()

   Return the plugin shim directory.

   :return: The shim data directory.


.. py:function:: installed_plugins()

   Read all valid installed plugins.

   :return: Valid installed plugins in directory-name order.


.. py:function:: plugin_root(name)

   Return the root of an installed plugin.

   :param name: Name the installed plugin directory.
   :return: The installed plugin directory.
   :raises ValueError: If the plugin is not installed.


.. py:function:: plugin_program(name, program)

   Return the absolute path of an installed plugin program.

   :param name: Name the installed plugin.
   :param program: Name the declared program.
   :return: The program's absolute path.
   :raises ValueError: If the plugin or program is unavailable.