plesty.lib.data.units
=====================

.. py:module:: plesty.lib.data.units

.. autoapi-nested-parse::

   Unit parsing, composition, and conversion utilities for Plesty.



Classes
-------

.. autoapisummary::

   plesty.lib.data.units.Units


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

.. py:class:: Units(dims: Optional[Dict[str, int]] = None, factor: float = 1.0)

   Standardized unit expression parser and composer.

   The internal representation tracks:
   - ``dims``: dimension exponents, e.g. {"L": 1, "T": -1} for speed
   - ``factor``: numeric scaling factor to SI base units

   Initialize a Units instance with dimension exponents and a scaling factor.


   .. py:attribute:: SYMBOLS
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: BASE_SYMBOLS


   .. py:attribute:: dims


   .. py:attribute:: factor


   .. py:method:: scalar() -> Units
      :classmethod:


      Return a dimensionless scalar Units instance.



   .. py:method:: parse(unit_str: Optional[str]) -> Optional[Units]
      :classmethod:


      Parse a unit string into a Units instance, returning None if unparseable.



   .. py:method:: standardize(unit_str: Optional[str]) -> Optional[str]
      :classmethod:


      Return a normalized whitespace-free unit string, or None for empty input.



   .. py:method:: compatible(other: Units) -> bool

      Return True if this unit has the same dimensions as other.



   .. py:method:: conversion_scale_to(target: Units) -> float

      Return the numeric factor to convert this unit to the target unit.



   .. py:method:: multiply(other: Units) -> Units

      Return the unit resulting from multiplying this unit by other.



   .. py:method:: divide(other: Units) -> Units

      Return the unit resulting from dividing this unit by other.



   .. py:method:: power(exponent: int) -> Units

      Return this unit raised to an integer exponent.



   .. py:method:: to_unit_string() -> Optional[str]

      Render the unit dimensions as a human-readable string.