TypedUnit 0.2.8__tar.gz → 0.2.10__tar.gz

{typedunit-0.2.8 → typedunit-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypedUnit
-Version: 0.2.8
+Version: 0.2.10
 Summary: A package wrapping pint for handling typed units in Python.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License

{typedunit-0.2.8 → typedunit-0.2.10}/TypedUnit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.8'
-__version_tuple__ = version_tuple = (0, 2, 8)
+__version__ = version = '0.2.10'
+__version_tuple__ = version_tuple = (0, 2, 10)
 
-__commit_id__ = commit_id = 'g3316b556e'
+__commit_id__ = commit_id = 'g156c1ff07'

{typedunit-0.2.8 → typedunit-0.2.10}/TypedUnit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypedUnit
-Version: 0.2.8
+Version: 0.2.10
 Summary: A package wrapping pint for handling typed units in Python.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License

{typedunit-0.2.8 → typedunit-0.2.10}/TypedUnit.egg-info/SOURCES.txt

@@ -42,11 +42,15 @@ docs/source/index.rst
 docs/source/references.rst
 docs/source/sg_execution_times.rst
 docs/source/theory.rst
+docs/source/units.rst
 docs/source/_static/default.css
-docs/source/_static/favicon.svg
 docs/source/_static/layout.css
-docs/source/_static/logo.svg
 docs/source/_static/thumbnail.png
+docs/source/guide/concepts.rst
+docs/source/guide/installation.rst
+docs/source/guide/pint.rst
+docs/source/guide/quickstart.rst
+docs/source/guide/validation.rst
 tests/__init__.py
 tests/test_0.py
 tools/next_release_version.py

{typedunit-0.2.8 → typedunit-0.2.10}/TypedUnit.egg-info/scm_file_list.json

@@ -30,16 +30,20 @@
     "docs/make.bat",
     "docs/redirect.html",
     "docs/source/_static/default.css",
-    "docs/source/_static/favicon.svg",
     "docs/source/_static/layout.css",
-    "docs/source/_static/logo.svg",
     "docs/source/_static/thumbnail.png",
     "docs/source/code.rst",
     "docs/source/conf.py",
+    "docs/source/guide/concepts.rst",
+    "docs/source/guide/installation.rst",
+    "docs/source/guide/pint.rst",
+    "docs/source/guide/quickstart.rst",
+    "docs/source/guide/validation.rst",
     "docs/source/index.rst",
     "docs/source/references.rst",
     "docs/source/sg_execution_times.rst",
     "docs/source/theory.rst",
+    "docs/source/units.rst",
     "pyproject.toml",
     "pytest.ini",
     "tests/__init__.py",

{typedunit-0.2.8 → typedunit-0.2.10}/TypedUnit.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.2.8",
+  "tag": "0.2.10",
   "distance": 0,
-  "node": "g3316b556e08fe9292dd89b9b94223240bc6ff784",
+  "node": "g156c1ff077ca68e8002b447cedd677d7dfa3c429",
   "dirty": true,
   "branch": "HEAD",
   "node_date": "2026-10-20"

typedunit-0.2.10/docs/source/code.rst

@@ -0,0 +1,20 @@
+.. _source_code:
+
+API reference
+=============
+
+The reference below is generated from the public modules. See the user guide
+for examples and design explanations.
+
+.. automodule:: TypedUnit
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: TypedUnit.helper
+   :members:
+   :show-inheritance:
+
+.. automodule:: TypedUnit.units
+   :members:
+   :show-inheritance:

{typedunit-0.2.8 → typedunit-0.2.10}/docs/source/conf.py

@@ -11,7 +11,8 @@ from martinpdes_docs import configure
 
 package_name = "TypedUnit"
 version = os.getenv("tag", "latest")
-thumbnail = str(Path(__file__).parent / "_static" / "thumbnail.png")
+logo = "../images/logo.png"
+thumbnail = str(Path(__file__).parent.parent / "images" / "logo.png")
 
 globals().update(
     configure(
@@ -19,8 +20,8 @@ globals().update(
         package=package_name,
         repository="MartinPdeS/TypedUnit",
         version=version,
-        logo="_static/logo.svg",
-        favicon="_static/favicon.svg",
+        logo=logo,
+        favicon=logo,
         sphinx_gallery_conf={
             "default_thumb_file": thumbnail,
             "within_subsection_order": FileNameSortKey,

typedunit-0.2.10/docs/source/guide/concepts.rst

@@ -0,0 +1,37 @@
+Core concepts
+=============
+
+TypedUnit has three complementary pieces.
+
+Dimensional types
+-----------------
+
+Classes such as ``Length`` and ``Voltage`` are lightweight marker types. They
+do not wrap or copy a quantity:
+
+.. code-block:: python
+
+   distance = 2 * ureg.kilometer
+   isinstance(distance, Length)       # True
+   isinstance(distance, Mass)         # False
+
+Pint still owns arithmetic, conversion, formatting, and NumPy integration.
+
+The shared registry
+-------------------
+
+Import ``ureg`` from TypedUnit rather than constructing a second registry.
+It includes domain units such as ``particle``, ``event``, ``photoelectron``,
+and ``sqrt_hertz``.
+
+Derived annotation types
+------------------------
+
+Unit classes can describe derived dimensions:
+
+.. code-block:: python
+
+   EnergyPerTime = Energy / Time
+   isinstance(2 * ureg.watt, EnergyPerTime)  # True
+
+These expressions describe dimensions; use Pint expressions for calculations.

typedunit-0.2.10/docs/source/guide/installation.rst

@@ -0,0 +1,21 @@
+Installation
+============
+
+.. code-block:: console
+
+   $ python -m pip install TypedUnit
+
+TypedUnit supports Python 3.10 and newer. Pydantic is optional; install it
+separately when using Pydantic models or dataclasses.
+
+For a development checkout:
+
+.. code-block:: console
+
+   $ git clone https://github.com/MartinPdeS/TypedUnit.git
+   $ cd TypedUnit
+   $ python -m pip install -e ".[testing,documentation]"
+   $ pytest
+
+The package exposes one application-wide registry, :data:`TypedUnit.ureg`.
+Use it when creating quantities so dimensional checks remain consistent.

typedunit-0.2.10/docs/source/guide/pint.rst

@@ -0,0 +1,24 @@
+Working with Pint
+=================
+
+TypedUnit is a thin layer over Pint. A quantity remains a normal
+``pint.Quantity`` and can be converted, indexed, or used with NumPy.
+
+.. code-block:: python
+
+   from TypedUnit import Length, ureg
+
+   diameter = 30 * ureg.centimeter
+   area = (diameter / 2) ** 2 * 3.14159
+   assert isinstance(diameter, Length)
+   print(area.to(ureg.square_meter))
+
+Dimensionality is the source of truth: metres and kilometres are both
+``Length``. Avoid mixing registries; use the shared ``TypedUnit.ureg`` at
+integration boundaries when external libraries return quantities.
+
+TypedUnit classes are markers, not constructors. Create values with Pint:
+
+.. code-block:: python
+
+   energy = 3 * ureg.joule

typedunit-0.2.10/docs/source/guide/quickstart.rst

@@ -0,0 +1,27 @@
+Quick start
+===========
+
+Create quantities as you would with Pint, and use TypedUnit classes where
+physical meaning matters:
+
+.. code-block:: python
+
+   from TypedUnit import Energy, Power, Time, ureg, validate_units
+
+   energy = 100 * ureg.joule
+   duration = 10 * ureg.second
+
+   assert isinstance(energy, Energy)
+   assert isinstance(duration, Time)
+
+   @validate_units
+   def average_power(energy: Energy, duration: Time) -> Power:
+       return (energy / duration).to(ureg.watt)
+
+   print(average_power(energy, duration))  # 10.0 watt
+
+Passing ``5 * ureg.meter`` as ``energy`` raises an error before the function
+body runs. Conversion remains explicit: ``energy.to(ureg.kilojoule)``.
+
+TypedUnit checks dimensionality, not the display unit. Joules and kilowatt
+hours are both ``Energy``; metres are not.

typedunit-0.2.10/docs/source/guide/validation.rst

@@ -0,0 +1,40 @@
+Validating function inputs
+==========================
+
+Decorate a function after adding TypedUnit annotations:
+
+.. code-block:: python
+
+   from TypedUnit import Energy, Time, validate_units, ureg
+
+   @validate_units
+   def energy_rate(energy: Energy, time: Time, label: str = "run"):
+       return energy / time, label
+
+Only parameters annotated with a TypedUnit class are checked. Ordinary
+annotations such as ``str`` and ``int`` are not runtime-validated, and return
+values are not checked.
+
+Optional and collection inputs
+------------------------------
+
+``Optional`` unit values and homogeneous lists or tuples are supported:
+
+.. code-block:: python
+
+   from typing import Optional
+   from TypedUnit import Length, Time, validate_units, ureg
+
+   @validate_units
+   def summarize(points: list[Length], elapsed: Optional[Time] = None):
+       return len(points), elapsed
+
+Invalid values raise ``ValueError`` with the parameter name and, for a
+collection, its index. A required ``None`` is rejected as well.
+
+Pydantic
+--------
+
+TypedUnit classes can be used as annotations in Pydantic dataclasses or
+models. Use ``@validate_units`` on calculation functions that accept those
+fields when an explicit function boundary is useful.

typedunit-0.2.10/docs/source/index.rst

@@ -0,0 +1,39 @@
+**Date**: |today|, **Version**: |version|
+
+
+.. include:: ../../README.rst
+    :start-line: 0
+
+TypedUnit documentation
+=======================
+
+TypedUnit adds readable, runtime-checkable physical quantity types to Pint.
+Keep constructing and converting quantities with Pint, then use types such as
+``Energy`` in annotations, ``isinstance`` checks, and validated boundaries.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: User guide
+
+    guide/installation
+    guide/quickstart
+    guide/concepts
+    guide/validation
+    guide/pint
+    theory
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Reference
+
+    units
+    code
+    references
+    gallery/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

typedunit-0.2.10/docs/source/references.rst

@@ -0,0 +1,11 @@
+.. _references:
+
+References
+===========
+
+* `Pint documentation <https://pint.readthedocs.io/>`_ — quantities,
+  dimensionality, conversion, and registries.
+* `Python typing documentation <https://docs.python.org/3/library/typing.html>`_
+  — annotation syntax used by the validator.
+* `Pydantic documentation <https://docs.pydantic.dev/>`_ — model and dataclass
+  validation when Pydantic is installed.

typedunit-0.2.10/docs/source/theory.rst

@@ -0,0 +1,12 @@
+.. _theory:
+
+Theoretical background
+======================
+
+TypedUnit separates values from meaning. Pint stores a magnitude and unit and
+performs dimensional arithmetic. TypedUnit maps selected Pint dimensionalities
+to Python classes, allowing the same meaning to appear in annotations and
+runtime checks without changing the quantity object.
+
+For practical usage, start with :doc:`guide/quickstart` and
+:doc:`guide/validation`.

typedunit-0.2.10/docs/source/units.rst

@@ -0,0 +1,35 @@
+Unit types
+==========
+
+All public unit classes are re-exported from ``TypedUnit``.
+
+.. list-table:: Common types
+   :header-rows: 1
+   :widths: 28 36 36
+
+   * - Type
+     - Dimension
+     - Typical units
+   * - ``Length`` / ``Area`` / ``Volume``
+     - length / length squared / volume
+     - meter, square_meter, liter
+   * - ``Mass`` / ``Time`` / ``Frequency``
+     - mass / time / inverse time
+     - kilogram, second, hertz
+   * - ``Velocity`` / ``FlowRate``
+     - length per time / liter per second
+     - meter / second, liter / second
+   * - ``Energy`` / ``Power``
+     - energy / energy per time
+     - joule, watt
+   * - ``Voltage`` / ``Current`` / ``Resistance``
+     - potential / current / resistance
+     - volt, ampere, ohm
+   * - ``Temperature`` / ``Angle``
+     - temperature / angle
+     - kelvin, degree
+   * - ``Dimensionless`` / ``AnyUnit``
+     - no dimensions / any dimensionality
+     - dimensionless / any Pint quantity
+
+See :doc:`code` for the complete generated class reference.

typedunit-0.2.8/docs/source/_static/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><circle cx="32" cy="32" r="29" fill="#172033"/><rect x="13" y="25" width="24" height="24" rx="5" fill="#6366f1"/><rect x="28" y="15" width="24" height="24" rx="5" fill="#22d3ee" opacity=".9"/></svg>

typedunit-0.2.8/docs/source/_static/logo.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 96" role="img" aria-labelledby="t d"><title id="t">TypedUnit</title><desc id="d">Interlocking dimensional unit blocks.</desc><rect x="18" y="25" width="44" height="44" rx="8" fill="#4f46e5"/><rect x="52" y="15" width="44" height="44" rx="8" fill="#06b6d4" opacity=".9"/><path fill="none" stroke="#172033" stroke-width="7" stroke-linecap="round" d="M112 48h27"/><text x="158" y="58" fill="#172033" font-family="system-ui,sans-serif" font-size="30" font-weight="650">TypedUnit</text></svg>

typedunit-0.2.8/docs/source/code.rst

@@ -1,7 +0,0 @@
-.. _source_code:
-
-Source Code
-===========
-
-This section provides an overview of the primary classes used in the `FiberFusing` package. Each class includes detailed descriptions of its members and inherited members, organized by their source order for easy reference.
-

typedunit-0.2.8/docs/source/index.rst

@@ -1,13 +0,0 @@
-**Date**: |today|, **Version**: |version|
-
-
-.. include:: ../../README.rst
-    :start-line: 0
-
-.. toctree::
-    :hidden:
-
-    theory
-    code
-    gallery/index
-    references

typedunit-0.2.8/docs/source/references.rst

@@ -1,6 +0,0 @@
-.. _references:
-
-References
-===========
-
-

typedunit-0.2.8/docs/source/theory.rst

@@ -1,5 +0,0 @@
-.. _theory:
-
-Theoretical background
-======================
-