bec_widgets.utils.plugin_utils
==============================

.. py:module:: bec_widgets.utils.plugin_utils


Classes
-------

.. autoapisummary::

   bec_widgets.utils.plugin_utils.BECClassContainer
   bec_widgets.utils.plugin_utils.BECClassInfo


Functions
---------

.. autoapisummary::

   bec_widgets.utils.plugin_utils._collect_classes_from_package
   bec_widgets.utils.plugin_utils._filter_auto_updates
   bec_widgets.utils.plugin_utils._filter_plugins
   bec_widgets.utils.plugin_utils.get_custom_classes
   bec_widgets.utils.plugin_utils.get_plugin_auto_updates
   bec_widgets.utils.plugin_utils.get_plugin_widgets


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

.. py:class:: BECClassContainer(initial: Iterable[BECClassInfo] = [])

   .. py:method:: __add__(other: BECClassContainer)


   .. py:method:: __iter__()


   .. py:method:: __repr__()


   .. py:method:: add_class(class_info: BECClassInfo)

      Add a class to the collection.

      :param class_info: The class information
      :type class_info: BECClassInfo



   .. py:method:: as_dict(ignores: list[str] = []) -> dict[str, type[bec_widgets.utils.bec_widget.BECWidget]]

      get a dict of {name: Type} for all the entries in the collection.

      :param ignores: a list of class names to exclude from the dictionary.
      :type ignores: list[str]



   .. py:property:: classes

      Get all classes.


   .. py:property:: collection

      Get the collection of classes.


   .. py:property:: connector_classes

      Get all connector classes.


   .. py:property:: names

      Return a list of class names


   .. py:property:: plugins

      Get all plugins. These are all classes that are on the top level and are widgets.


   .. py:property:: rpc_top_level_classes

      Get all top-level classes that are RPC-enabled. These are all classes that users can choose from.


   .. py:property:: top_level_classes

      Get all top-level classes.


   .. py:property:: widgets

      Get all widgets. These are all classes inheriting from BECWidget.


.. py:class:: BECClassInfo

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


   .. py:attribute:: is_connector
      :type:  bool
      :value: False



   .. py:attribute:: is_plugin
      :type:  bool
      :value: False



   .. py:attribute:: is_widget
      :type:  bool
      :value: False



   .. py:attribute:: module
      :type:  str


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


   .. py:attribute:: obj
      :type:  type[bec_widgets.utils.bec_widget.BECWidget]


.. py:function:: _collect_classes_from_package(repo_name: str, package: str) -> BECClassContainer

   Collect classes from a package subtree (for example ``widgets`` or ``applications``).


.. py:function:: _filter_auto_updates(obj)

.. py:function:: _filter_plugins(obj)

.. py:function:: get_custom_classes(repo_name: str, packages: tuple[str, Ellipsis] | None = None) -> BECClassContainer

   Get all relevant classes for RPC/CLI in the specified repository.

   By default, discovery is limited to ``<repo>.widgets`` for backward compatibility.
   Additional package subtrees (for example ``applications``) can be included explicitly.

   :param repo_name: The name of the repository.
   :type repo_name: str
   :param packages: Optional tuple of package names to scan. Defaults to ("widgets",) for backward compatibility.
   :type packages: tuple[str, ...] | None

   :returns: Container with collected class information.
   :rtype: BECClassContainer


.. py:function:: get_plugin_auto_updates() -> dict[str, type[bec_widgets.widgets.containers.auto_update.auto_updates.AutoUpdates]]

   Get all available auto update classes from the plugin directory. AutoUpdates must inherit from AutoUpdate and be
   placed in the plugin repository's bec_widgets/auto_updates directory. The entry point for the auto updates is
   specified in the respective pyproject.toml file using the following key:
       [project.entry-points."bec.widgets.auto_updates"]
       plugin_widgets_update = "<beamline_name>.bec_widgets.auto_updates"

   e.g.
       [project.entry-points."bec.widgets.auto_updates"]
       plugin_widgets_update = "pxiii_bec.bec_widgets.auto_updates"

   :returns: A dictionary of widget names and their respective classes.
   :rtype: dict[str, AutoUpdates]


.. py:function:: get_plugin_widgets() -> dict[str, bec_widgets.utils.BECConnector]

   Get all available widgets from the plugin directory. Widgets are classes that inherit from BECConnector.
   The plugins are provided through python plugins and specified in the respective pyproject.toml file using
   the following key:

       [project.entry-points."bec.widgets.user_widgets"]
       plugin_widgets = "path.to.plugin.module"

   e.g.
       [project.entry-points."bec.widgets.user_widgets"]
       plugin_widgets = "pxiii_bec.bec_widgets.widgets"

       assuming that the widgets module for the package pxiii_bec is located at pxiii_bec/bec_widgets/widgets and
       contains the widgets to be loaded within the pxiii_bec/bec_widgets/widgets/__init__.py file.

   :returns: A dictionary of widget names and their respective classes.
   :rtype: dict[str, BECConnector]