mbdlyb.fqn
==========

.. py:module:: mbdlyb.fqn

.. autoapi-nested-parse::

   Fully Qualified Name (FQN) class for hierarchical element naming.

   FQN provides a dot-separated string representation of elements' positions in
   hierarchical structures, enabling efficient lookup and navigation.



Classes
-------

.. autoapisummary::

   mbdlyb.fqn.FQN


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

.. py:class:: FQN(fqn: str)

   Represents a fully qualified name for hierarchical elements.

   FQN uses dot-separated components to represent the path through a hierarchy.
   For example, 'system.subsystem.component' represents an element 'component'
   within 'subsystem' within 'system'.

   :ivar _s: The string representation of the FQN.
   :vartype _s: str
   :ivar _l: Cached list of components, lazily computed.

   :vartype _l: Optional[list[str]]


   .. py:method:: aslist() -> list[str]

      Get the FQN as a list of components.

      :returns: List of dot-separated components (cached for efficiency).
      :rtype: list[str]



   .. py:method:: element_count() -> int

      Get the number of components in this FQN.

      :returns: The number of dot-separated components.
      :rtype: int



   .. py:method:: fromlist(l: list[str]) -> FQN
      :classmethod:


      Create an FQN from a list of components.

      :param l: List of components to join.
      :type l: list[str]

      :returns: A new FQN with components joined by dots.
      :rtype: FQN



   .. py:method:: longest_common_fqn(*fqns: FQN) -> Optional[FQN]
      :staticmethod:


      Find the longest common FQN prefix among multiple FQNs.

      :param \*fqns: Variable number of FQNs to compare.
      :type \*fqns: FQN

      :returns: The longest common FQN prefix, or None if there is no common prefix.
      :rtype: Optional[FQN]



   .. py:method:: relative_fqn(ref: FQN) -> FQN

      Get the relative FQN from a reference point.

      :param ref: The reference FQN to calculate relative position from.
      :type ref: FQN

      :returns: The relative FQN path from the reference point to this FQN.
      :rtype: FQN



   .. py:method:: with_suffix(suffix: Union[str, int]) -> FQN

      Create a new FQN with a suffix appended using double underscore.

      :param suffix: The suffix to append.
      :type suffix: Union[str, int]

      :returns: A new FQN with the suffix appended.
      :rtype: FQN



   .. py:property:: stem
      :type: FQN


      Get the FQN without the last component.

      :returns: A new FQN representing the stem (all components except the last one).
      :rtype: FQN