aoptk.chemical
==============

.. py:module:: aoptk.chemical


Classes
-------

.. autoapisummary::

   aoptk.chemical.Chemical


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

.. py:class:: Chemical(name: str)

   Data structure representing a chemical.

   Instances are considered equal when their `name` values are equal.
   The class implements ``__hash__`` so instances can be used as dict keys
   or set members.


   .. py:attribute:: _name


   .. py:attribute:: _heading
      :type:  str | None
      :value: None



   .. py:attribute:: _synonyms
      :type:  set[str]


   .. py:property:: synonyms
      :type: set[str]


      Synonyms of the chemical.

      :returns: All synonyms of the chemical.
      :rtype: set[str]


   .. py:property:: heading
      :type: str | None


      Heading or canonical name of the chemical.

      Only available after normalization or if it is set manually after object instantiation.

      :returns: Canonical name of the chemical or None
      :rtype: str | None


   .. py:property:: name
      :type: str


      Return the chemical's name.


   .. py:method:: __all_names() -> set[str]

      Get all names for the chemical.

      :returns: Union of synonyms, name and heading.
      :rtype: set[str]



   .. py:method:: similar(other: Chemical) -> bool

      Test if two chemicals are similar, so if any of their names match.

      Chemicals that are equal are also always similar.

      :param other: Chemical to compare to.
      :type other: Chemical

      :returns: True if any of the names match, False otherwise.
      :rtype: bool



   .. py:method:: __str__() -> str

      Return a human-friendly string for the chemical (its name).



   .. py:method:: __eq__(other: object) -> bool

      Compare two Chemical instances for equality.

      Returns ``NotImplemented`` when `other` is not a `Chemical`, allowing
      Python to try reflected comparisons or fall back to ``False``.



   .. py:method:: __eq_chemical(other: Chemical) -> bool

      Private helper to compare two chemicals.

      :param other: Chemical to compare.
      :type other: Chemical

      :returns: If headings are present, is true if heading matches. Otherwise use given name instead.
      :rtype: bool



   .. py:method:: __eq_object(other: object) -> bool

      Private helper to compare a Chemical to a non-Chemical object.

      This is called from :meth:`__eq__` when ``other`` is not a
      :class:`Chemical`. The method compares the string representation of
      ``other`` to this instance's heading (when present) and name.

      :param other: Object to compare. Its ``str()`` value is used
                    for the comparison.
      :type other: object

      :returns: ``True`` if the string representation of ``other`` equals
                the chemical's heading (if set) or name, ``False`` otherwise.
      :rtype: bool



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

      Return a hash based on the chemical name.

      This ensures objects that compare equal also have the same hash,
      which is required for correct behaviour in sets and dict keys.