fix: harden API responses and package tooling

Author: StefaniOSApps

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test Python ${{ matrix.python-version }}
@@ -25,18 +28,14 @@ jobs:
       - name: Install dependencies
         run: make install-dev
 
-      - name: Run tests
-        run: make test
-
-      - name: Run coverage
-        if: matrix.python-version == '3.14'
+      - name: Run tests with coverage
         run: make coverage
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.14'
         uses: codecov/codecov-action@v4
         with:
-          file: ./coverage.xml
+          files: ./coverage.xml
           fail_ci_if_error: false
 
   lint:
@@ -59,3 +58,18 @@ jobs:
 
       - name: Run type check
         run: make type-check
+
+  package:
+    name: Build & Validate Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Build, validate and install wheel
+        run: make check-dist

.github/workflows/release.yml

@@ -50,8 +50,8 @@ jobs:
       - name: Install dependencies
         run: make install-dev
 
-      - name: Build package
-        run: make build
+      - name: Build and validate package
+        run: make check-dist
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -23,6 +23,7 @@ wheels/
 
 # Virtual environments
 venv/
+.venv/
 env/
 ENV/
 
@@ -35,6 +36,7 @@ ENV/
 # Testing
 .pytest_cache/
 .coverage
+coverage.xml
 htmlcov/
 
 # mypy

Makefile

@@ -1,4 +1,7 @@
-.PHONY: help install install-dev clean test coverage lint format type-check build upload upload-test venv
+PYTHON ?= python3.14
+SOURCES = energy_tracker_api/ tests/ scripts/ example.py
+
+.PHONY: help install install-dev clean test coverage lint format type-check build check-dist upload upload-test venv all
 
 help:
 	@echo "Available commands:"
@@ -12,22 +15,24 @@ help:
 	@echo "  make format        - Format code with black and isort"
 	@echo "  make type-check    - Run type checking with mypy"
 	@echo "  make build         - Build distribution packages"
+	@echo "  make check-dist    - Validate packages and test an isolated wheel installation"
 	@echo "  make upload-test   - Upload to TestPyPI"
 	@echo "  make upload        - Upload to PyPI"
 
 venv/bin/python:
 	@echo "Creating virtual environment..."
-	python3 -m venv venv
+	$(PYTHON) -m venv venv
 	@echo "Upgrading pip..."
 	venv/bin/pip install --upgrade pip
 
-.install-stamp: venv/bin/python requirements.txt
-	venv/bin/pip install -r requirements.txt
+venv: venv/bin/python
+
+.install-stamp: venv/bin/python pyproject.toml
 	venv/bin/pip install -e .
 	@touch .install-stamp
 
-.install-dev-stamp: .install-stamp requirements-dev.txt
-	venv/bin/pip install -r requirements-dev.txt
+.install-dev-stamp: .install-stamp pyproject.toml
+	venv/bin/pip install -e '.[dev]'
 	@touch .install-dev-stamp
 
 install: .install-stamp
@@ -42,35 +47,39 @@ clean:
 	rm -rf .mypy_cache/
 	rm -rf htmlcov/
 	rm -rf .coverage
-	rm -rf venv/
+	rm -f coverage.xml
 	rm -rf .install-stamp .install-dev-stamp
-	find . -type d -name __pycache__ -exec rm -rf {} +
-	find . -type f -name "*.pyc" -delete
+	find energy_tracker_api tests scripts -type d -name __pycache__ -exec rm -rf {} +
 
 test: .install-dev-stamp
 	venv/bin/python -m pytest tests/ -v
 
 coverage: .install-dev-stamp
-	venv/bin/python -m pytest tests/ --cov=energy_tracker_api --cov-report=html --cov-report=term
+	venv/bin/python -m pytest tests/ --cov=energy_tracker_api --cov-report=html --cov-report=term --cov-report=xml
 
 lint: .install-dev-stamp
-	venv/bin/python -m black --check energy_tracker_api/ tests/
-	venv/bin/python -m isort --check-only energy_tracker_api/ tests/
+	venv/bin/python -m black --check $(SOURCES)
+	venv/bin/python -m isort --check-only $(SOURCES)
 
 format: .install-dev-stamp
-	venv/bin/python -m black energy_tracker_api/ tests/
-	venv/bin/python -m isort energy_tracker_api/ tests/
+	venv/bin/python -m isort $(SOURCES)
+	venv/bin/python -m black $(SOURCES)
 
 type-check: .install-dev-stamp
-	venv/bin/python -m mypy energy_tracker_api/
+	venv/bin/python -m mypy energy_tracker_api/ scripts/ example.py
 
 build: .install-dev-stamp
+	rm -rf build/ dist/
 	venv/bin/python -m build
 
-upload-test: .install-dev-stamp build
+check-dist: build
+	venv/bin/python -m twine check dist/*
+	venv/bin/python scripts/check_distribution.py
+
+upload-test: check-dist
 	venv/bin/python -m twine upload --repository testpypi dist/*
 
-upload: .install-dev-stamp build
+upload: check-dist
 	venv/bin/python -m twine upload dist/*
 
-all: clean format lint type-check test
+all: lint type-check coverage check-dist

README.md

@@ -58,6 +58,8 @@ client = EnergyTrackerClient(
 ## Error Handling
 
 All API errors inherit from `EnergyTrackerAPIError` and carry an `api_message` list with details from the server.
+Each operation accepts only its documented success status (200, 201 or 204).
+Unexpected statuses and redirects raise `EnergyTrackerAPIError`; redirects are not followed.
 
 ```python
 from energy_tracker_api import (
@@ -86,8 +88,20 @@ make test         # Run tests
 make type-check   # mypy
 make format       # black + isort
 make lint         # Linters
+make check-dist   # Build, validate and import an isolated wheel installation
 ```
 
+Package metadata, version and dependencies are maintained in `pyproject.toml`.
+The requirements files are compatibility entry points for installing the package
+and its development extra. The Makefile uses `python3.14` by default; override it
+with `make install-dev PYTHON=/path/to/python3.14` when needed.
+
+Meter reading values must be finite `Decimal` values. The client serializes them
+as fixed-point strings without redundant fractional zeros and never rounds them.
+Server-side range and precision validation still applies. When creating and
+deleting the same reading, reuse its timestamp; prefer UTC-aware timestamps
+with whole seconds as shown in `example.py`.
+
 ## License
 
 MIT