Merge pull request #121 from timlnx/py39-wrapup

Py39 wrapup

Author: timlnx

CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+
+## Project Overview
+
+**bitmath** is a pure-Python library (no external runtime dependencies) for representing and converting file sizes across SI (decimal) and NIST (binary) unit systems. It supports arithmetic, rich comparisons, bitwise ops, parsing, formatting, and f-string/format() support.
+
+## Project Direction
+bitmath has been around for almost 12 years, and over that lifetime it promised to deliver backwards compatibility. It delivered on that promise and gathered a strong supporting of people and eventual "critical infrastructure" project status on the PyPI.org website.
+
+As of January 2023 the project maintainer (me) has stated in this issue https://github.com/timlnx/bitmath/issues/99 that the project is still alive and the next release will be python 3 support only.
+
+Much of that porting work has already happened in the `2023-01-26-no-more-py2` branch https://github.com/timlnx/bitmath/tree/2023-01-26-no-more-py2
+
+### Current State (as of 2.0.0)
+
+Phases 1 (maintenance 1.4.0) and 2 (bitmath 2.0.0) are complete. The project:
+
+- Supports **Python 3.9 and newer only** (`requires-python = ">=3.9"` in `pyproject.toml`)
+- Uses `hatchling` as the build backend (replaces `setup.py`)
+- Uses `pytest` as the test runner (292 tests, 99% coverage — one branch in `system` property intentionally uncovered)
+- Is published on PyPI as version 2.0.0
+- Drop-in compatible with the 1.x public API
+
+## Common Commands
+
+```bash
+# Run the full test suite with coverage (creates venv, runs pytest + linting)
+make ci
+
+# Run linting only
+ruff check bitmath/ tests/
+
+# Build a wheel
+make build
+
+# Install in development mode
+pip install -e .
+```
+
+Run a single test file:
+```bash
+python -m pytest tests/test_arithmetic.py -v
+```
+
+## Architecture
+
+Almost all logic lives in a single file: `bitmath/__init__.py` (~1650 lines).
+
+**Class hierarchy:**
+- `Bitmath` — base class with all arithmetic, comparison, bitwise, formatting, and conversion logic
+  - `Byte` — byte-based units; subclasses: `KiB MiB GiB TiB PiB EiB` (NIST/base-2) and `kB MB GB TB PB EB ZB YB` (SI/base-10)
+  - `Bit` — bit-based units; subclasses: `Kib Mib Gib Tib Pib Eib` (NIST) and `kb Mb Gb Tb Pb Eb Zb Yb` (SI)
+
+All unit values are normalized to bits internally; conversion between units happens at construction time via `_norm_value` and class-level `_base_value` / `_unit_value` constants.
+
+**Key module-level functions:**
+- `best_prefix(value, system=NIST)` — pick the most human-readable unit for a raw byte value
+- `getsize(path, ...)` — file size with automatic prefix selection
+- `listdir(search_base, ...)` — recursive directory listing with sizes
+- `parse_string(s)` / `parse_string_unsafe(s, system=SI)` — string → bitmath object
+- `query_device_capacity(device_fd)` — POSIX device capacity (Linux/macOS)
+
+**Constants:** `NIST`, `SI`, `NIST_PREFIXES`, `SI_PREFIXES`, `ALL_UNIT_TYPES`
+
+## Testing Notes
+
+- Test runner: `pytest`
+- All tests are in `tests/` as `test_*.py` files
+- Test case names must be unique across the suite — enforced by `tests/test_unique_testcase_names.sh`
+- Coverage: 99% (one branch in `system` property intentionally uncovered)
+- `unittest.mock` (stdlib) is used for patching in integration tests

Makefile

@@ -55,7 +55,7 @@ docs-venv:
 	fi
 	. $(DOCSVENV)/bin/activate && pip install -q -r doc-requirements.txt
 
-docs: docs-venv conf.py $(MANPAGES) docsite/source/index.rst
+docs: docs-venv $(MANPAGES) docsite/source/index.rst
 	. $(DOCSVENV)/bin/activate && cd docsite && make html
 
 # Add examples to the RTD docs by taking it from the README
@@ -94,10 +94,6 @@ viewcover: ci-unittests
 		xdg-open htmlcov/index.html; \
 	fi
 
-conf.py: docsite/source/conf.py.in
-	sed "s/%VERSION%/$(VERSION)/" $< > docsite/source/conf.py
-
-
 build: clean
 	@echo "#############################################"
 	@echo "# Building sdist + wheel"

NEWS.rst

@@ -17,38 +17,35 @@ a major release. Version 2.0.0 is a thorough modernization: the
 Python 2 era is officially over, the library picks up several
 long-requested features, and the entire project infrastructure has
 been rebuilt from scratch. If you've been running bitmath on Python
-3.11 or later and quietly wishing it felt more modern — this release
+3.9 or later and quietly wishing it felt more modern — this release
 is for you.
 
 
 Breaking Changes
 ================
 
 **Python support**
-   Python 3.11+ only. Python 2 and Python 3.7–3.10 are no longer
+   Python 3.9+ only. Python 2 and Python < 3.9 are no longer
    supported or tested.
 
 **parse_string() default system**
-   The default unit system when ``strict=False`` is now **NIST**
-   (binary). Previously it defaulted to SI. Code that relied on the
-   old default for ambiguous strings such as ``"1g"`` will get a
-   different result. See :ref:`parse-string-non-strict` for full details.
+   The default unit system when ``strict=False`` is now **NIST** (base-2).
+   Previously it defaulted to SI (base-10). Code that relied on the old default
+   for ambiguous strings such as ``"1g"`` could get a different result. See
+   :ref:`parse-string-non-strict` for full details. All bitmath now consistently
+   defaults to the NIST system.
 
 **parse_string_unsafe() deprecated**
    Use :func:`bitmath.parse_string` with ``strict=False`` instead.
    The old name still works but emits a :exc:`DeprecationWarning`.
 
 **bitmath.integrations removed**
-   The argparse, click, and progressbar integrations have been removed
+   The ``argparse``, ``click``, and ``progressbar`` integrations have been removed
    from the package. Copy-paste replacements are provided in the new
    :ref:`Integration Examples <integration_examples>` documentation
    chapter. No changes to calling code are required — just a local
    copy of the relevant snippet.
 
-**Build and install**
-   ``setup.py`` and ``setup.py.in`` are gone. Installation is
-   ``pip install bitmath``. Source builds use ``python -m build``.
-
 **Byte and Bit display names**
    ``Byte`` and ``Bit`` now display as ``B`` and ``b`` respectively,
    matching the abbreviated style of every other unit. Code that
@@ -57,6 +54,11 @@ Breaking Changes
    ``"Byte"`` or ``"Bit"`` will need to be updated. The class names
    themselves are unchanged.
 
+**Build and install**
+   ``setup.py`` and ``setup.py.in`` are gone. Installation is
+   ``pip install bitmath``. Source builds use ``python -m build``.
+
+
 
 Library Improvements
 ====================
@@ -81,7 +83,7 @@ still works exactly the same way. What 2.0.0 adds on top of that:
    <https://github.com/timlnx/bitmath/pull/76>`_.
 
 **bitmath.sum() and built-in sum()**
-   A new :func:`bitmath.sum` function returns a unit-normalised result
+   A new :func:`bitmath.sum` function returns a unit-normalized result
    when summing mixed-type iterables. For uniform collections, the
    built-in :py:func:`sum` now works directly on bitmath sequences
    without a ``start=`` argument.

README.rst

@@ -99,14 +99,14 @@ supported <https://devguide.python.org/versions/>`_ Python releases.
    $ sudo dnf install python3-bitmath
 
 
-**PyPi**:
+**PyPI**:
 
-You could also install bitmath from `PyPi
-<https://pypi.python.org/pypi/bitmath>`_ if you like:
+You could also install bitmath from `PyPI
+<https://pypi.org/project/bitmath/>`_ if you like:
 
 .. code-block:: bash
 
-   $ sudo pip install bitmath
+   $ pip install --user bitmath