unitx 0.3.0__tar.gz → 0.4.0__tar.gz

unitx-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} (${{ matrix.backend }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
+        backend: ["builtin", "sympy"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Install SymPy
+        if: matrix.backend == 'sympy'
+        run: python -m pip install sympy
+
+      - name: Run Ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run tests
+        run: pytest -q

unitx-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,113 @@
+name: Release
+
+# Configure a PyPI Trusted Publisher for DaitTHU/unitx, release.yml, and the
+# GitHub environment named pypi.
+# Manual runs validate distributions; publishing a GitHub release uploads them.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Validate and build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Check release version
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          tag = os.environ.get('RELEASE_TAG', '')
+          if tag and tag != f'v{version}':
+              raise SystemExit(f'Release tag {tag!r} does not match project version {version!r}.')
+          with Path(os.environ['GITHUB_OUTPUT']).open('a') as output:
+              output.write(f'version={version}\n')
+          print(f'Building unitx {version}')
+          PY
+
+      - name: Install build and validation dependencies
+        run: python -m pip install -e ".[test]" build twine
+
+      - name: Validate source
+        run: |
+          python -m ruff check .
+          python -m ruff format --check .
+          python -m pytest -q
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Install built wheel
+        run: python -m pip install --force-reinstall --no-deps dist/*.whl
+
+      - name: Check installed package
+        working-directory: ${{ runner.temp }}
+        env:
+          EXPECTED_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          from fractions import Fraction
+          from importlib.metadata import version
+          from importlib.resources import files
+
+          from unitx.quantity import Quantity
+          from unitx.unit import Unit
+
+          assert version('unitx') == os.environ['EXPECTED_VERSION']
+          assert files('unitx').joinpath('py.typed').is_file()
+          assert Quantity(1, 'cm').to('m').value == Fraction(1, 100)
+          assert 2 * Unit('m') == Quantity(200, 'cm')
+          PY
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v5
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/unitx
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

{unitx-0.3.0 → unitx-0.4.0}/.gitignore

@@ -199,7 +199,7 @@ cython_debug/
 #   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
 #   and can be added to the global gitignore or merged into this file. However, if you prefer, 
 #   you could uncomment the following to ignore the entire vscode folder
-# .vscode/
+.vscode/
 # Temporary file for partial code execution
 tempCodeRunnerFile.py
 
@@ -217,5 +217,5 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
-# vscode settings
-.vscode/
+# macOS
+.DS_Store

unitx-0.4.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## [0.4.0] - 2026-10-16
+
+Replace the implementation previously published on PyPI as 0.3.0. The 0.0.x
+entries below retain this repository's development milestones.
+
+### Changed
+
+- Require Python 3.12 or later; Python 3.11 is no longer supported.
+- Use module imports for `Quantity`, `Unit`, `Dimension`, and `DIMENSIONLESS`; the former top-level exports and `unitx.utils` namespace are no longer provided.
+- Remove `Unit` length and special truth-value behavior. Check formal identity with `unit == Unit('')`, or physical dimensions with `unit.is_dimensionless()`.
+- Compare and hash scalar quantities using exact rational coefficients and remaining irrational unit factors. Finite floats retain their stored binary rational values for equality, without a tolerance.
+- Convert finite Decimal magnitudes exactly to Fraction for scaling and arithmetic, independent of the Decimal precision context; numerical results can change type.
+- Normalize quantity exponents once for both the magnitude and unit, with approximate native evaluation for nonintegral magnitude powers.
+
+### Fixed
+
+- Interpret plain numbers as unscaled values when adding to or subtracting from scaled dimensionless quantities.
+- Preserve the original magnitude and type when multiplying or dividing a quantity by a Unit.
+- Cancel common irrational factors before evaluating quantity ordering, retaining exact ordering when the ratio is rational.
+
+### Added
+
+- Support Fraction and Decimal scalar multiplication and division alongside int and float.
+- Distribute inline type information with `py.typed` and check numerical and custom scalar contracts with Pyright.
+- Add a release workflow that validates version tags, checks distributions and the installed wheel, and publishes GitHub releases through PyPI Trusted Publishing.
+- Document construction, conversion, unit syntax, numerical rules, supported units, and migration from 0.3.0. NumPy integration remains planned and is not supported in this release.
+
+## [0.0.7] - 2026-10-15
+
+- Add `Unit` with string construction for compound unit expressions, including registered symbols, names, prefixes, and aliases.
+- Support unit multiplication and division, rational powers, and cancellation while preserving exact rational exponents.
+- Expose unit symbols, coherent SI scaling factors, physical dimensions, and dimensionless checks; dimensionless expressions can retain nontrivial scaling factors.
+- Define equality and hashing by formal unit factors regardless of insertion order, preserving distinct prefixed unit identities.
+- Provide readable Unicode display and reconstructible `repr` strings for compound units and rational powers.
+- Add executable usage examples and regression tests for alias normalization, equality and hashing, exact and approximate factors, dimensions, power cancellation, conversion round trips, state preservation, and invalid inputs.
+
+## [0.0.6] - 2026-10-15
+
+- Add `UnitParser` to parse unit expressions into `Monomial[SingleUnit]`, resolving symbols, names, prefixes, and aliases through `SingleUnit`.
+- Support explicit and implicit multiplication, division, parentheses, and exact rational powers using adjacent numbers, `^`, or `**`, including decimal exponents and parenthesized fractions.
+- Support empty and dimensionless expressions, the literal identity `1` in products such as `m 1/s`, and single-factor leading reciprocals such as `/s` and `/(m s)`.
+- Cache successful parse results so repeated calls return the same object, while allowing failed attempts to be retried.
+- Add `UnitSyntaxError` with diagnostics for malformed expressions, invalid numeric bases, zero fraction denominators, and redundant suffixes.
+- Use spaces for multiplication in ambiguous prefix warning suggestions, matching the supported expression syntax.
+- Add grammar documentation, executable examples, and regression tests for exact parsing, whitespace, diagnostics, caching, retries, and warning behavior and attribution.
+
+## [0.0.5] - 2026-10-15
+
+- Add built-in SI prefix data and initial unit definitions for `s`, `m`, `g`, `A`, `K`, `mol`, and `cd`, plus the dimensionless unit, with exact factors, dimensions, and prefix restrictions.
+- Add immutable, hashable `SingleUnit` with symbol and name parsing, canonical identity, dimension and factor queries, prefix inspection and removal, copying, and serialization.
+- Support symbol and name aliases, including `meter`, micro prefix variants `u` and `μ`, and the uppercase `K` alias for kilo, while preserving canonical symbols and names.
+- Add `UnitSymbolError` for invalid unit inputs and `UnitSymbolWarning` for potentially misleading prefix aliases, with warnings attributed to user call sites.
+- Add `Factor` hashing consistent with equality to rational numbers and individual `SymbolicConstant` instances.
+- Add regression tests for unit definitions, alias normalization, exact factors, immutability, serialization, and warning behavior, filtering, and attribution.
+
+## [0.0.4] - 2026-10-15
+
+- Add `Factor` for exact positive scaling expressions with rational exponents, multiplicative arithmetic, and exact rational or approximate float evaluation, along with predefined `ONE`, `TWO`, and `TEN` instances.
+- Add immutable `SymbolicConstant` with symbolic identity and float approximations, along with the predefined `PI` constant.
+- Support factor decomposition, compact formatting, and magnitude scaling that converts finite `Decimal` magnitudes exactly before multiplication.
+- Provide built-in bounded integer factorization and primality testing, optional SymPy support, and `IncompleteFactorWarning` for unresolved factorization or unproven primality.
+- Display negative `Monomial` powers as denominator terms, with parentheses around multiple denominator factors.
+- Attribute numerical warnings to user call sites without manually passing warning stack levels.
+- Raise the minimum supported Python version from 3.11 to 3.12.
+- Extend CI to test both built-in and SymPy backends on Python 3.12–3.15.
+
+## [0.0.3] - 2026-10-14
+
+- Add immutable, hashable `Monomial` for formal products with rational exponents.
+- Support multiplication, division, rational powers, inverses, and numerator/denominator decomposition.
+- Provide explicit exponent queries, component views, Unicode formatting, and exact representation round trips.
+- Add tests for monomial arithmetic, normalization, immutability, hashing, copying, and serialization.
+
+## [0.0.2] - 2026-10-13
+
+- Add immutable physical dimensions with rational exponents and dimensionless normalization.
+- Support dimension arithmetic, exponent aliases, and exact representation round trips.
+- Add numerical conversion utilities with inexact float warnings and Unicode exponent formatting.
+- Add tests for dimensions, numerical conversion, formatting, copying, and serialization.
+
+## [0.0.1] - 2026-10-13
+
+- Project initialization and setup.

unitx-0.4.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.5
+Name: unitx
+Version: 0.4.0
+Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
+Project-URL: Homepage, https://github.com/DaitTHU/unitx
+Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
+Author: Dait
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Provides-Extra: test
+Requires-Dist: pyright>=1.1.414; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# unitx
+
+Physical units, scalar quantities, and dimensional analysis for Python, with
+exact rational unit scales and exponents.
+
+unitx is in early development. Public APIs may change during the 0.x series.
+
+## Installation
+
+Requires **Python 3.12 or later**, with no mandatory runtime dependencies.
+
+Install a published release:
+
+```sh
+python -m pip install unitx
+```
+
+To use the current development version, run this from the repository root:
+
+```sh
+python -m pip install -e .
+```
+
+This README describes the current source tree, including unreleased changes.
+For a published release, consult the README at its matching Git tag.
+
+## Upgrading from 0.3.0
+
+Version 0.4.0 replaces the implementation previously published on PyPI as 0.3.0.
+It includes incompatible changes:
+
+- Python 3.12 or later is required; Python 3.11 is no longer supported.
+- Import classes from their modules. The former top-level exports and
+  `unitx.utils` namespace are no longer provided:
+
+  ```python
+  from unitx.dimension import DIMENSIONLESS, Dimension
+  from unitx.quantity import Quantity
+  from unitx.unit import Unit
+  ```
+
+- `Unit` no longer defines `len()` or special truth-value behavior. Use
+  `unit == Unit('')` to check the formal identity, or `unit.is_dimensionless()`
+  to check physical dimensions; these are different questions.
+- Conversion and arithmetic can produce different magnitude types, especially
+  for Decimal inputs. Review the [numerical behavior](#numerical-behavior)
+  before relying on a result's concrete type or approximate equality.
+
+## Quick start
+
+Import the classes from their modules:
+
+```pycon
+>>> from unitx.quantity import Quantity
+>>> from unitx.unit import Unit
+>>> distance = 3 * Unit('m')
+>>> elapsed = Quantity(2, 's')
+>>> speed = distance / elapsed
+>>> print(speed)
+1.5 m/s
+>>> print(speed.to('cm/s'))
+150.0 cm/s
+
+```
+
+`Quantity(value, unit)` accepts a unit expression or an existing `Unit` object.
+Multiplying a scalar by a unit constructs a quantity; dividing a scalar by a
+unit constructs a quantity with the reciprocal unit. Construction preserves the
+original magnitude and its type.
+
+## Conversion and arithmetic
+
+Use `.to()` to convert between units with the same physical dimensions.
+Addition and subtraction convert the right operand to the left operand's unit:
+
+```pycon
+>>> length = Quantity(1, 'm')
+>>> print(length + Quantity(50, 'cm'))
+3/2 m
+>>> length.to('cm').value
+100
+>>> Quantity(1, 'cm').to('m').value
+Fraction(1, 100)
+
+```
+
+Multiplication and division combine units. Powers apply to both the magnitude
+and the unit. Multiplication or division by a `Unit` alone preserves the
+magnitude unchanged.
+
+Conversion, addition, subtraction, and ordering across incompatible dimensions
+raise `unitx.exceptions.DimensionError`. Equality across incompatible dimensions
+returns `False`.
+
+For repeated conversions, reuse a target `Unit` object to avoid parsing the
+expression on every call.
+
+## Unit expressions
+
+Expressions support registered symbols, singular English names, SI prefixes,
+multiplication, division, parentheses, and rational powers:
+
+```pycon
+>>> Unit('kg m/s2') == Unit('kg*m/s**2')
+True
+>>> Unit('m^(1/2)') ** 2 == Unit('m')
+True
+>>> Unit('micrometre') == Unit('um')
+True
+>>> Unit('ms') == Unit('m s')
+False
+
+```
+
+- Multiplication can use `*` or whitespace. Adjacent letters form one unit
+  token: `ms` is a millisecond, while `m s` is metre times second.
+- Powers can use adjacent numbers, `^`, or `**`. Exponents written as ratios
+  require parentheses, as in `m^(1/2)`; decimal exponents such as `m^0.5` are exact.
+- Multiplication and division associate left to right. Use `m/(s A)` to put
+  both `s` and `A` in the denominator; `m/s A` means `(m/s)*A`.
+- Unit symbols and names are case-sensitive. `u`, `µ`, and `μ` are accepted
+  micro prefixes. Use lowercase `k` for kilo; `K` denotes kelvin.
+
+The current unit table contains `s`, `m`, `g`, `A`, `K`, `mol`, and `cd`, plus
+the dimensionless identity. Mass scales are referenced to kilograms: `g` has
+factor `1/1000`, and `kg` has factor `1`. Named derived units such as `N` are
+not registered yet; use expressions such as `kg*m/s2`.
+
+## Units, dimensions, and equality
+
+A `Unit` retains its formal factors. A `Quantity` compares physical values
+across compatible units:
+
+```pycon
+>>> Unit('m') == Unit('cm')
+False
+>>> Quantity(1, 'm') == Quantity(100, 'cm')
+True
+>>> len({Quantity(1, 'm'), Quantity(100, 'cm')})
+1
+>>> from unitx.dimension import Dimension
+>>> speed.dimension == Dimension(L=1, T=-1)
+True
+
+```
+
+Equal quantities have equal hashes when their magnitudes are hashable. Different
+formal unit expressions can have the same physical dimension and scale without
+being equal as `Unit` objects.
+
+An expression can be dimensionless and still carry a scale. Plain numbers added
+to or subtracted from dimensionless quantities represent unscaled values:
+
+```pycon
+>>> scaled = Quantity(1, 'km/m')
+>>> scaled.is_dimensionless()
+True
+>>> scaled == 1000
+True
+>>> (scaled + 1).to('').value
+Fraction(1001, 1)
+
+```
+
+## Numerical behavior
+
+Exact unit algebra and numerical magnitude evaluation have different rules:
+
+- Rational unit scales and exponents remain exact. Prefer `Fraction` or
+  `Decimal` for exact exponents; float exponents may be approximated with an
+  `InexactFloatWarning`.
+- Conversion and arithmetic can change the magnitude's type. Finite `Decimal`
+  operands are converted exactly to `Fraction`, without Decimal context
+  rounding.
+- Other magnitudes use native numerical arithmetic. In particular, integer
+  division produces a float, and nonintegral magnitude powers can round or
+  produce complex values.
+- Equality is exact, without a tolerance. Finite floats are compared as their
+  stored binary rational values. Floating-point conversions and irrational
+  powers may round; compare their values approximately in a common unit when
+  appropriate.
+
+```pycon
+>>> from decimal import Decimal
+>>> from fractions import Fraction
+>>> Quantity(Decimal('0.1'), 'm').to('cm').value
+10
+>>> (Quantity(Fraction(1), 'm') / Quantity(3, 's')).value
+Fraction(1, 3)
+>>> Quantity(0.1, '') == Quantity(Fraction(1, 10), '')
+False
+
+```
+
+The built-in integer factorization backend is bounded. Unresolved factors emit
+`IncompleteFactorWarning` and can limit simplification and comparisons. SymPy
+is an optional, more capable factorization backend:
+
+```sh
+python -m pip install sympy
+```
+
+## Current scope
+
+- **NumPy scalars, arrays, and NumPy operations are not supported yet. NumPy
+  integration is planned.** Structural compatibility with a magnitude protocol
+  does not imply NumPy support.
+- Custom magnitudes must support scalar arithmetic, return a Python `bool`
+  from equality, and defer raw operations with `Unit` operands to its reflected
+  operators.
+- Scalar multiplication and division of quantities currently accept `int`,
+  `float`, `Fraction`, and `Decimal`. Complex magnitudes are supported, including
+  results of fractional powers; ordering follows the magnitude's native rules.
+- Unit conversion is multiplicative. Offset temperature scales such as Celsius
+  and Fahrenheit are not supported.
+
+## Building blocks
+
+| Class | Import module | Purpose |
+| --- | --- | --- |
+| `Quantity` | `unitx.quantity` | Scalar values paired with units, conversion, and arithmetic |
+| `Unit` | `unitx.unit` | Compound units, scaling factors, and physical dimensions |
+| `Dimension` | `unitx.dimension` | Seven physical dimensions with rational exponents |
+| `SingleUnit` | `unitx.singleunit` | One registered unit with an optional prefix |
+| `Factor` | `unitx.factor` | Positive scaling expressions and magnitude scaling |
+| `UnitParser` | `unitx.unitparser` | Parsing unit expressions into formal products |
+| `Monomial` | `unitx.monomial` | Immutable formal products with rational exponents |
+
+The package includes inline type annotations and a `py.typed` marker. Construction
+and operations with `Unit` preserve the magnitude type in type hints; conversion
+and numerical arithmetic use result unions where the concrete type depends on
+runtime values or units. Modules whose names start with `_` are internal.
+
+## Development
+
+Install the development version and test dependencies:
+
+```sh
+python -m pip install -e ".[test]"
+python -m pytest -q
+python -m ruff check .
+python -m ruff format --check .
+```
+
+The pytest suite includes doctests and Pyright checks for the typed API. CI runs
+the suite with both the built-in and SymPy factorization backends.
+
+## Releases
+
+The [release workflow](.github/workflows/release.yml) validates the source,
+builds a wheel and source distribution, checks their metadata, and tests the
+installed wheel. Manual workflow runs store the distributions without uploading
+them to PyPI.
+
+Publishing a GitHub release runs the same checks and uploads the distributions
+to PyPI. The release tag must match the project version, for example `v0.4.0`
+for version `0.4.0`. Configure a PyPI Trusted Publisher for the repository,
+workflow `release.yml`, and GitHub environment `pypi` before publishing.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history. Licensed under the
+[MIT License](LICENSE).