fixfield 0.1.0__tar.gz

fixfield-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

fixfield-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

fixfield-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `fixfield` will be documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] — 2026-05-08
+
+### Added
+- `FixedDecimal` — scalar fixed-decimal type with per-instance precision and rounding
+- `RoundingStrategy` — enum of 8 rounding modes including `ROUND_HALF_ODD`
+- `Field` — descriptor for declaring fixed-decimal fields on a `Record`
+  - `places`, `digits`, `rounding`, `default` parameters
+  - `width` property for fixed-width serialization
+- `Record` — base class for structured groups of `Field` descriptors
+  - Auto-generated `__init__`, `__repr__`, `__eq__`
+  - `to_dict()`, `to_string()`, `from_string()`
+- `RecordField[T]` — generic descriptor for embedding a nested `Record` as a field
+  - `width` delegates to nested record's total width
+  - Participates in `to_string()` / `from_string()` as a contiguous block
+- `FieldOverflowError` — raised when a value exceeds declared integer-digit capacity
+- `FieldValue` — public type alias for anything assignable to a `Field`
+- Full arithmetic on `FixedDecimal`: `+`, `-`, `*`, `/`, unary `-`, `abs()`
+- Reverse arithmetic operators: `__radd__`, `__rsub__`, `__rmul__`, `__rtruediv__`
+- Full comparison protocol: `==`, `!=`, `<`, `<=`, `>`, `>=`
+- `FixedDecimal.copy()` and `FixedDecimal.replace()` for non-destructive modification
+- Fixed-width serialization: `Record.to_string()` / `Record.from_string()`
+- `py.typed` marker for PEP 561 compliance
+- Float input safety — floats converted via `str()` to avoid binary imprecision

fixfield-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Reilly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fixfield-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: fixfield
+Version: 0.1.0
+Summary: Fixed-decimal arithmetic with per-field precision enforcement
+Author-email: Charles Reilly <charlesreilly0@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cobol,decimal,finance,fixed-point,precision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# fixfield
+
+Fixed-decimal arithmetic for Python with per-field precision enforcement.
+
+Inspired by COBOL's `PIC` clause — declare precision once on the field, and it is enforced automatically on every assignment and arithmetic result.
+
+---
+
+## Installation
+
+```bash
+uv add fixfield
+# or
+pip install fixfield
+```
+
+---
+
+## Quick Start
+
+```python
+from fixfield import Record, Field, RoundingStrategy
+
+class Invoice(Record):
+    price    = Field(places=2)
+    tax_rate = Field(places=4)
+    tax      = Field(places=2)
+    total    = Field(places=2)
+
+inv = Invoice(price="19.99", tax_rate="0.0825")
+inv.tax   = inv.price * inv.tax_rate   # 1.649175 → rounded to 1.65
+inv.total = inv.price + inv.tax        # 21.64
+
+print(inv.total)   # "21.64"
+print(repr(inv))   # Invoice(price=19.99, tax_rate=0.0825, tax=1.65, total=21.64)
+```
+
+---
+
+## Why Not Just Use `decimal.Decimal`?
+
+| | `decimal.Decimal` | `fixfield` |
+|---|---|---|
+| Precision location | Global context or per `.quantize()` call | Declared on the field, enforced automatically |
+| Rounding enforcement | Manual on every result | Automatic on every assignment |
+| Per-field rounding strategy | Manual | Declarative |
+| Domain modelling | Plain values | Named record schema |
+
+With `decimal` you must call `.quantize()` on every result or silently lose precision. With `fixfield` the field declaration is the single source of truth.
+
+---
+
+## Core Concepts
+
+### `FixedDecimal`
+
+A scalar decimal value locked to a declared precision.
+
+```python
+from fixfield import FixedDecimal, RoundingStrategy
+
+price = FixedDecimal("19.999", places=2)
+str(price)   # "20.00" — rounded on construction
+
+# Arithmetic preserves left operand's precision
+result = price + FixedDecimal("1.005", places=4)
+result.places     # 2  (left operand wins)
+str(result)       # "21.00"
+
+# Comparisons work naturally
+price > FixedDecimal("10.00")   # True
+price == "20.00"                # True
+
+# Unary operators
+str(-price)        # "-20.00"
+str(abs(-price))   # "20.00"
+```
+
+Float inputs are automatically converted via `str` to avoid binary imprecision:
+
+```python
+FixedDecimal(0.1 + 0.2, places=2)   # "0.30" not "0.30000000000000004"
+```
+
+### `Field`
+
+A descriptor that enforces precision on a class attribute. Used inside a `Record`.
+
+```python
+from fixfield import Field, RoundingStrategy
+
+price    = Field(places=2)                                    # default ROUND_HALF_UP
+tax_rate = Field(places=4, rounding=RoundingStrategy.ROUND_FLOOR)
+total    = Field(places=2, default="0.00")
+capped   = Field(places=2, digits=5)                          # max 99999.99
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `places` | `2` | Decimal places to keep |
+| `rounding` | `ROUND_HALF_UP` | Rounding strategy on assignment |
+| `default` | `None` | Default value (zero if not set) |
+| `digits` | `None` | Max integer digits — raises `FieldOverflowError` if exceeded |
+
+### `Record`
+
+A structured collection of `Field` descriptors. Generates `__init__`, `__repr__`, and `__eq__` automatically.
+
+> **Field ordering** relies on Python's guaranteed `dict` insertion order (Python 3.7+). Fields are serialised to and from fixed-width strings in the order they are declared in the class body.
+
+```python
+from fixfield import Record, Field
+
+class Payment(Record):
+    amount     = Field(places=2, digits=7)   # up to 9999999.99
+    fee        = Field(places=2, digits=4)
+    net        = Field(places=2, digits=7)
+
+p = Payment(amount="1000.00", fee="2.50")
+p.net = p.amount - p.fee
+
+print(p)          # Payment(amount=1000.00, fee=2.50, net=997.50)
+p.to_dict()       # {"amount": FixedDecimal(...), "fee": ..., "net": ...}
+```
+
+### `RecordField`
+
+Embed a nested `Record` as a field inside another `Record`. The nested record's fields participate in `to_string`/`from_string` as a contiguous block.
+
+```python
+from fixfield import Record, Field, RecordField
+
+class Address(Record):
+    zip_code = Field(places=0, digits=5)
+    state    = Field(places=0, digits=2)
+
+class Customer(Record):
+    customer_id = Field(places=0, digits=6)
+    address     = RecordField(Address)
+
+c = Customer(customer_id="42", address=Address(zip_code="90210", state="6"))
+line = c.to_string()                        # "    42 90210 6"
+parsed = Customer.from_string(line)
+str(parsed.address.zip_code)                # "90210"
+```
+
+`RecordField` is generic: `RecordField[Address]` so your IDE knows that `c.address` is an `Address`, not just a `Record`.
+
+### `RoundingStrategy`
+
+```python
+from fixfield import RoundingStrategy
+
+RoundingStrategy.ROUND_HALF_UP    # 2.5 → 3  (COBOL ROUNDED default)
+RoundingStrategy.ROUND_HALF_DOWN  # 2.5 → 2
+RoundingStrategy.ROUND_HALF_EVEN  # 2.5 → 2, 3.5 → 4  (banker's rounding)
+RoundingStrategy.ROUND_HALF_ODD   # 2.5 → 3, 3.5 → 3
+RoundingStrategy.ROUND_UP         # always away from zero
+RoundingStrategy.ROUND_DOWN       # always toward zero (truncate)
+RoundingStrategy.ROUND_CEILING    # toward +∞
+RoundingStrategy.ROUND_FLOOR      # toward -∞
+```
+
+---
+
+## Fixed-Width Serialization
+
+When every `Field` has `digits` set, records can be serialized to and from fixed-width strings — useful for mainframe flat files and legacy EDI formats.
+
+```python
+class CustomerRecord(Record):
+    customer_id = Field(places=0, digits=6)    # 7 chars:  " 123456"
+    balance     = Field(places=2, digits=8)    # 11 chars: "  99999.99"
+
+rec = CustomerRecord(customer_id="123456", balance="99999.99")
+line = rec.to_string()             # " 123456  99999.99"
+
+parsed = CustomerRecord.from_string(line)
+parsed.balance == rec.balance      # True
+```
+
+Field width formula: `1 (sign) + digits + (1 + places if places > 0 else 0)`
+
+---
+
+## Overflow Protection
+
+```python
+from fixfield import Field, Record, FieldOverflowError
+
+class Account(Record):
+    balance = Field(places=2, digits=5)   # max 99999.99
+
+a = Account()
+a.balance = "99999.99"   # ok
+a.balance = "100000.00"  # raises FieldOverflowError
+```
+
+---
+
+## Dataclass Integration
+
+For users who prefer `@dataclass`, use `FixedDecimal` directly and coerce values in `__post_init__`:
+
+```python
+from dataclasses import dataclass, field
+from fixfield import FixedDecimal, RoundingStrategy
+
+@dataclass
+class LineItem:
+    price:    FixedDecimal = field(default_factory=lambda: FixedDecimal(0, places=2))
+    quantity: int = 1
+
+    def __post_init__(self):
+        if not isinstance(self.price, FixedDecimal):
+            self.price = FixedDecimal(self.price, places=2)
+
+    @property
+    def total(self) -> FixedDecimal:
+        return self.price * self.quantity
+```
+
+For full precision enforcement without `__post_init__` boilerplate, use `Record` instead.
+
+---
+
+## License
+
+MIT

fixfield-0.1.0/README.md

@@ -0,0 +1,229 @@
+# fixfield
+
+Fixed-decimal arithmetic for Python with per-field precision enforcement.
+
+Inspired by COBOL's `PIC` clause — declare precision once on the field, and it is enforced automatically on every assignment and arithmetic result.
+
+---
+
+## Installation
+
+```bash
+uv add fixfield
+# or
+pip install fixfield
+```
+
+---
+
+## Quick Start
+
+```python
+from fixfield import Record, Field, RoundingStrategy
+
+class Invoice(Record):
+    price    = Field(places=2)
+    tax_rate = Field(places=4)
+    tax      = Field(places=2)
+    total    = Field(places=2)
+
+inv = Invoice(price="19.99", tax_rate="0.0825")
+inv.tax   = inv.price * inv.tax_rate   # 1.649175 → rounded to 1.65
+inv.total = inv.price + inv.tax        # 21.64
+
+print(inv.total)   # "21.64"
+print(repr(inv))   # Invoice(price=19.99, tax_rate=0.0825, tax=1.65, total=21.64)
+```
+
+---
+
+## Why Not Just Use `decimal.Decimal`?
+
+| | `decimal.Decimal` | `fixfield` |
+|---|---|---|
+| Precision location | Global context or per `.quantize()` call | Declared on the field, enforced automatically |
+| Rounding enforcement | Manual on every result | Automatic on every assignment |
+| Per-field rounding strategy | Manual | Declarative |
+| Domain modelling | Plain values | Named record schema |
+
+With `decimal` you must call `.quantize()` on every result or silently lose precision. With `fixfield` the field declaration is the single source of truth.
+
+---
+
+## Core Concepts
+
+### `FixedDecimal`
+
+A scalar decimal value locked to a declared precision.
+
+```python
+from fixfield import FixedDecimal, RoundingStrategy
+
+price = FixedDecimal("19.999", places=2)
+str(price)   # "20.00" — rounded on construction
+
+# Arithmetic preserves left operand's precision
+result = price + FixedDecimal("1.005", places=4)
+result.places     # 2  (left operand wins)
+str(result)       # "21.00"
+
+# Comparisons work naturally
+price > FixedDecimal("10.00")   # True
+price == "20.00"                # True
+
+# Unary operators
+str(-price)        # "-20.00"
+str(abs(-price))   # "20.00"
+```
+
+Float inputs are automatically converted via `str` to avoid binary imprecision:
+
+```python
+FixedDecimal(0.1 + 0.2, places=2)   # "0.30" not "0.30000000000000004"
+```
+
+### `Field`
+
+A descriptor that enforces precision on a class attribute. Used inside a `Record`.
+
+```python
+from fixfield import Field, RoundingStrategy
+
+price    = Field(places=2)                                    # default ROUND_HALF_UP
+tax_rate = Field(places=4, rounding=RoundingStrategy.ROUND_FLOOR)
+total    = Field(places=2, default="0.00")
+capped   = Field(places=2, digits=5)                          # max 99999.99
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `places` | `2` | Decimal places to keep |
+| `rounding` | `ROUND_HALF_UP` | Rounding strategy on assignment |
+| `default` | `None` | Default value (zero if not set) |
+| `digits` | `None` | Max integer digits — raises `FieldOverflowError` if exceeded |
+
+### `Record`
+
+A structured collection of `Field` descriptors. Generates `__init__`, `__repr__`, and `__eq__` automatically.
+
+> **Field ordering** relies on Python's guaranteed `dict` insertion order (Python 3.7+). Fields are serialised to and from fixed-width strings in the order they are declared in the class body.
+
+```python
+from fixfield import Record, Field
+
+class Payment(Record):
+    amount     = Field(places=2, digits=7)   # up to 9999999.99
+    fee        = Field(places=2, digits=4)
+    net        = Field(places=2, digits=7)
+
+p = Payment(amount="1000.00", fee="2.50")
+p.net = p.amount - p.fee
+
+print(p)          # Payment(amount=1000.00, fee=2.50, net=997.50)
+p.to_dict()       # {"amount": FixedDecimal(...), "fee": ..., "net": ...}
+```
+
+### `RecordField`
+
+Embed a nested `Record` as a field inside another `Record`. The nested record's fields participate in `to_string`/`from_string` as a contiguous block.
+
+```python
+from fixfield import Record, Field, RecordField
+
+class Address(Record):
+    zip_code = Field(places=0, digits=5)
+    state    = Field(places=0, digits=2)
+
+class Customer(Record):
+    customer_id = Field(places=0, digits=6)
+    address     = RecordField(Address)
+
+c = Customer(customer_id="42", address=Address(zip_code="90210", state="6"))
+line = c.to_string()                        # "    42 90210 6"
+parsed = Customer.from_string(line)
+str(parsed.address.zip_code)                # "90210"
+```
+
+`RecordField` is generic: `RecordField[Address]` so your IDE knows that `c.address` is an `Address`, not just a `Record`.
+
+### `RoundingStrategy`
+
+```python
+from fixfield import RoundingStrategy
+
+RoundingStrategy.ROUND_HALF_UP    # 2.5 → 3  (COBOL ROUNDED default)
+RoundingStrategy.ROUND_HALF_DOWN  # 2.5 → 2
+RoundingStrategy.ROUND_HALF_EVEN  # 2.5 → 2, 3.5 → 4  (banker's rounding)
+RoundingStrategy.ROUND_HALF_ODD   # 2.5 → 3, 3.5 → 3
+RoundingStrategy.ROUND_UP         # always away from zero
+RoundingStrategy.ROUND_DOWN       # always toward zero (truncate)
+RoundingStrategy.ROUND_CEILING    # toward +∞
+RoundingStrategy.ROUND_FLOOR      # toward -∞
+```
+
+---
+
+## Fixed-Width Serialization
+
+When every `Field` has `digits` set, records can be serialized to and from fixed-width strings — useful for mainframe flat files and legacy EDI formats.
+
+```python
+class CustomerRecord(Record):
+    customer_id = Field(places=0, digits=6)    # 7 chars:  " 123456"
+    balance     = Field(places=2, digits=8)    # 11 chars: "  99999.99"
+
+rec = CustomerRecord(customer_id="123456", balance="99999.99")
+line = rec.to_string()             # " 123456  99999.99"
+
+parsed = CustomerRecord.from_string(line)
+parsed.balance == rec.balance      # True
+```
+
+Field width formula: `1 (sign) + digits + (1 + places if places > 0 else 0)`
+
+---
+
+## Overflow Protection
+
+```python
+from fixfield import Field, Record, FieldOverflowError
+
+class Account(Record):
+    balance = Field(places=2, digits=5)   # max 99999.99
+
+a = Account()
+a.balance = "99999.99"   # ok
+a.balance = "100000.00"  # raises FieldOverflowError
+```
+
+---
+
+## Dataclass Integration
+
+For users who prefer `@dataclass`, use `FixedDecimal` directly and coerce values in `__post_init__`:
+
+```python
+from dataclasses import dataclass, field
+from fixfield import FixedDecimal, RoundingStrategy
+
+@dataclass
+class LineItem:
+    price:    FixedDecimal = field(default_factory=lambda: FixedDecimal(0, places=2))
+    quantity: int = 1
+
+    def __post_init__(self):
+        if not isinstance(self.price, FixedDecimal):
+            self.price = FixedDecimal(self.price, places=2)
+
+    @property
+    def total(self) -> FixedDecimal:
+        return self.price * self.quantity
+```
+
+For full precision enforcement without `__post_init__` boilerplate, use `Record` instead.
+
+---
+
+## License
+
+MIT

fixfield-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "fixfield"
+version = "0.1.0"
+description = "Fixed-decimal arithmetic with per-field precision enforcement"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [
+    { name = "Charles Reilly", email = "charlesreilly0@gmail.com" },
+]
+keywords = ["decimal", "fixed-point", "cobol", "finance", "precision"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fixfield"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]
+

fixfield-0.1.0/src/fixfield/__init__.py

@@ -0,0 +1,17 @@
+from fixfield.rounding import RoundingStrategy
+from fixfield.types import FixedDecimal, FieldOverflowError
+from fixfield.field import Field, FieldValue
+from fixfield.record import Record, RecordField
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "RoundingStrategy",
+    "FixedDecimal",
+    "FieldOverflowError",
+    "Field",
+    "FieldValue",
+    "Record",
+    "RecordField",
+]

fixfield-0.1.0/src/fixfield/field.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import overload
+from fixfield.rounding import RoundingStrategy
+from fixfield.types import FixedDecimal, _NUMBER
+
+type FieldValue = _NUMBER | FixedDecimal
+
+
+class Field:
+    def __init__(
+        self,
+        places: int = 2,
+        rounding: RoundingStrategy = RoundingStrategy.ROUND_HALF_UP,
+        default: _NUMBER | None = None,
+        digits: int | None = None,
+    ) -> None:
+        self.places = places
+        self.rounding = rounding
+        self.digits = digits
+        self.default = (
+            FixedDecimal(default, places, rounding, digits)
+            if default is not None
+            else None
+        )
+        self._attr: str = ""  # set by __set_name__
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._attr = f"_field_{name}"
+
+    @overload
+    def __get__(self, obj: None, objtype: type) -> Field: ...
+
+    @overload
+    def __get__(self, obj: object, objtype: type) -> FixedDecimal: ...
+
+    def __get__(self, obj: object | None, objtype: type) -> Field | FixedDecimal:
+        if obj is None:
+            return self
+        value = obj.__dict__.get(self._attr)
+        if value is None:
+            if self.default is not None:
+                return self.default
+            return FixedDecimal(0, self.places, self.rounding, self.digits)
+        return value
+
+    def __set__(self, obj: object, value: FieldValue) -> None:
+        raw = value.value if isinstance(value, FixedDecimal) else value
+        obj.__dict__[self._attr] = FixedDecimal(
+            raw, self.places, self.rounding, self.digits
+        )
+
+    @property
+    def width(self) -> int:
+        """
+        Fixed-width character length for this field.
+        Requires ``digits`` to be set.
+
+        Format: [sign(1)] + [integer digits] + [. + decimal places if places > 0]
+        Example: digits=5, places=2  →  "-99999.99"  → width 9
+        """
+        if self.digits is None:
+            raise ValueError(
+                "Field must have 'digits' set to use fixed-width serialization"
+            )
+        decimal_part = 1 + self.places if self.places > 0 else 0
+        return 1 + self.digits + decimal_part   # 1 for sign
+
+    def __repr__(self) -> str:
+        return (
+            f"Field(places={self.places}, rounding={self.rounding}, "
+            f"digits={self.digits}, default={self.default})"
+        )