8000 Hardening 1/4: entry points refuse bad input with a plain message, never a traceback by rafatahmed · Pull Request #118 · rafatahmed/Flahax · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
-->
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased

- Entry points refuse bad input with a plain message instead of a traceback (#117, from the entry-point audit). `flahax batch --ratio 0` crashed with a ZeroDivisionError; every number option is now checked at the command line with its range (`--ratio`, `--volume` and `--max-reagent-litres` above 0, `--ph` 0-14, `--water-share` above 0 up to 100). Every JSON file (water, targets, products, rules, saved items and sessions) and JSON on stdin is read by one reader that names the file and the line and column (`missing_file`, `invalid_json`); a water value that is not a number, or a non-numeric `--acid` assay or density, is named in the message. The `flahax batch` terminal shows the acid with the same 0.1 mL rounding as the sheet and report.
- Package identity and attribution (owner decisions 2026-10-23). Metadata: author Rafat A. Al Khashan with public contact email, maintainers Rafat A. Al Khashan and Flaha Agri Tech (affiliation), a description that names the grower command and the A/B stock planning, fuller keywords, Development Status 4 - Beta, Console and end-user audiences, Python 3.14 (now also in CI), and Changelog, Citation and Growers-guide links. NOTICE now credits every data source the package ships (USGS PHREEQC 3.8.6 minteq.v4.dat and pitzer.dat, the FlahaX chelate and phase extensions, McCleskey et al. 2012, Pethybridge et al. 2006, the CRC Handbook, Yara, the U.S. Coast Guard CHRIS database, Haifa, Sigma-Aldrich, ChemicalBook, SQM and the crop-formula authors) and reproduces the USGS User Rights Notice, which applies to PHREEQC data: it requires modified data to say what changed, by whom and when, so chemistry_25c.json and NOTICE now carry that statement (the sylvite constant, from pitzer.dat, was not credited before). CITATION.cff gains a current abstract, release date, affiliation, contact and a references list checked against Crossref. The README gains an Author and credits section; `tests/test_attribution.py` fails if a shipped data source is not credited. Zenodo archiving is documented as an owner step in the publishing procedure.
- Fix what the pre-release sweep of `flahax mix` found (19 farmer sessions, each checked across terminal, sheet at every depth and report): an unknown acid formula ('1') was accepted and the acid then silently ignored, so the plan said none was offered (#112); `flahax mix` now asks again and `flahax batch --acid` stops with the list of acids FlahaX plans with (HNO3, H3PO4, H2SO4, C6H8O7; any case). A blocked pH plan repeated its review notes (#113): a chemistry review row or advisory is listed only when not already said. A changed or new formula was titled with its file name (#114): the name typed is kept in the session and used as the title.
- Every output of one batch now agrees (#107-#110), found by generating the owner's session at all three depths. The agronomist sheet's pH path and the report's 'go from pH' used the first recipe's pH (6.71) while the report's chemistry used the weighed recipe (7.93), whose nitrate salts are reduced by the acid's nitrate: all now show the weighed recipe mixed without its reagent (`summary['ph']['mixed_ph']`), and the report also names the first recipe's pH. Weights and acid volumes use one format on the terminal, sheet and report (no more '0' weights or 86 vs 85.7 mL); each warning appears once (the pH stage no longer repeats the review rows and the iron(II) advisory); the report shows '1:100' and the status in words. A new test (`tests/test_output_consistency.py`) runs the owner's session once and checks every shared number across terminal, sheet at each depth, report and summary. Recipes and chemistry are unchanged.
Expand Down
12 changes: 10 additions & 2 deletions src/flahax/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,14 @@ def _main() -> int:
from .planning_cli import execute, interactive, serializable
try:
payload = interactive(args.command) if args.interactive else json.load(sys.stdin)
except json.JSONDecodeError as exc:
print(f'Invalid planning input: stdin is not valid JSON: {exc.msg.removesuffix(" at")} at line {exc.lineno}, '
f'column {exc.colno}', file=sys.stderr)
return 1
except (ValueError, TypeError, KeyError, OSError, EOFError) as exc:
print(f'Invalid planning input: {exc}', file=sys.stderr)
return 1
try:
result = execute(args.command, payload)
json.dump(serializable(result), sys.stdout, allow_nan=False)
sys.stdout.write('\n')
Expand All @@ -58,8 +66,8 @@ def _main() -> int:
'Growers: use flahax mix.', file=sys.stderr)
try:
payload = json.load(sys.stdin)
except json.JSONDecodeError:
print("Expected a JSON object on stdin.", file=sys.stderr)
except json.JSONDecodeError as exc:
print(f'Expected a JSON object on stdin: {exc.msg.removesuffix(" at")} at line {exc.lineno}, column {exc.colno}.', file=sys.stderr)
return 1
if not isinstance(payload, dict):
print("Expected a JSON object on stdin.", file=sys.stderr)
Expand Down
82 changes: 69 additions & 13 deletions src/flahax/batch_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
from .delivery_quantities import VolumeLitres
from .engine import load_library
from .fertilizer_workflow import plan_fertilizer_workflow
from .grower_report import render_batch_sheet, render_report, summarize_batch
from .grower_report import millilitres, render_batch_sheet, render_report, summarize_batch
from .measured_water import balance_water_analysis
from .ph_adjustment import catalogue_ph_reagents
from .planning_cli import serializable
Expand All @@ -60,13 +60,59 @@
}


def read_json(path, what):
"""A JSON file's content, or a DeliveryError that names the file and the line (#117)."""
try:
text = Path(path).read_text(encoding='utf-8-sig')
except FileNotFoundError:
raise DeliveryError('missing_file', f'{what} file {path} was not found') from None
except OSError as exc:
raise DeliveryError('missing_file', f'{what} file {path} cannot be read: {exc.strerror}') from None
try:
return json.loads(text)
except json.JSONDecodeError as exc:
raise DeliveryError('invalid_json', f'{what} file {path} is not valid JSON: {exc.msg.removesuffix(" at")} at line {exc.lineno}, '
f'column {exc.colno}') from None


def number_in(name, low, high=None, *, above=True):
"""An argparse type: a finite number above ``low`` (or at least, with ``above=False``) and at most ``high``."""
def parse(text):
try:
value = float(text)
except ValueError:
raise argparse.ArgumentTypeError(f'{name} {text!r} is not a number') from None
if not math.isfinite(value) or (value <= low if above else value < low) or (high is not None and value > high):
bound = f'above {low:g}' if above else f'at least {low:g}'
raise argparse.ArgumentTypeError(f'{name} must be {bound}' + (f' and at most {high:g}' if high else '')
+ f', not {text}')
return value
return parse


def _mg(key, value, what='water value'):
"""A water concentration in mg/L: a finite, non-negative number."""
if isinstance(value, bool) or not isinstance(value, (int, float, str)):
raise DeliveryError('invalid_value', f'{what} {key} = {value!r} is not a number of mg/L')
try:
number = float(value)
except ValueError:
raise DeliveryError('invalid_value', f'{what} {key} = {value!r} is not a number of mg/L') from None
if not math.isfinite(number) or number < 0:
raise DeliveryError('invalid_value', f'{what} {key} = {value!r} must be zero or more mg/L')
return number


def read_water(spec):
"""(label, nutrient mg/L, equilibrium configuration) from ``ro`` or a JSON file."""
if spec.lower() == 'ro':
return 'RO water, no ions', {}, dict(water_totals={}, water_analysis_id='RO')
data = json.loads(Path(spec).read_text(encoding='utf-8-sig'))
data = read_json(spec, 'water')
if not isinstance(data, dict) or not isinstance(data.get('mg_per_litre'), dict):
raise DeliveryError('invalid_type', 'water JSON needs an "mg_per_litre" object')
for key, value in data['mg_per_litre'].items():
if key in WATER_KEYS:
_mg(key, value)
if 'measured_ph' not in data:
raise DeliveryError('missing_field', 'water JSON needs "measured_ph" to close the analysis')
unknown = set(data['mg_per_litre']) - set(WATER_KEYS)
Expand All @@ -76,6 +122,8 @@ def read_water(spec):
below = data.get('below_detection') or {}
if not isinstance(below, dict) or set(below) - set(WATER_KEYS):
raise DeliveryError('unknown_field', '"below_detection" maps water keys to detection limits in mg/L')
if isinstance(data['measured_ph'], bool) or not isinstance(data['measured_ph'], (int, float)):
raise DeliveryError('invalid_value', f'"measured_ph" = {data["measured_ph"]!r} is not a number')
totals = {}
for key, mg in data['mg_per_litre'].items():
basis, grams = WATER_KEYS[key]
Expand All @@ -85,7 +133,8 @@ def read_water(spec):
analysis_id = str(data.get('id', Path(spec).stem))
label = f'{analysis_id}: laboratory analysis, measured pH {data["measured_ph"]}'
config = dict(water_totals=totals, measured_ph=data['measured_ph'], water_analysis_id=analysis_id,
below_detection={WATER_KEYS[k][0]: float(v) / WATER_KEYS[k][1] / 1000 for k, v in below.items()})
below_detection={WATER_KEYS[k][0]: _mg(k, v, 'detection limit') / WATER_KEYS[k][1] / 1000
for k, v in below.items()})
if 'balance_ion' in data:
ions = {'Cl': 'Cl-', 'Na': 'Na+'}
if data['balance_ion'] not in ions:
Expand Down Expand Up @@ -140,7 +189,13 @@ def acid_record(spec):
parts = spec.split(':')
if len(parts) not in (3, 4):
raise DeliveryError('invalid_value', f'--acid {spec}: expected FORMULA:MASS_FRACTION:DENSITY[:NAME]')
formula, fraction, density = parts[0].strip(), float(parts[1]), float(parts[2])
numbers = []
for label, text in (('assay (mass fraction)', parts[1]), ('density (kg/L)', parts[2])):
try:
numbers.append(float(text))
except ValueError:
raise DeliveryError('invalid_value', f'--acid {spec}: the {label} {text!r} is not a number') from None
formula, (fraction, density) = parts[0].strip(), numbers
formula = ACID_FORMULAS.get(formula.upper())
if formula is None:
raise DeliveryError('invalid_value', f'--acid {spec}: the acid must be one of {", ".join(ACID_FORMULAS.values())}')
Expand Down Expand Up @@ -201,18 +256,18 @@ def run_batch(options):
irrigation_litres=options.irrigation_litres)
volume = options.volume if volumes is None else volumes.irrigation_litres
library = load_library()
products = (json.loads(Path(options.products).read_text(encoding='utf-8-sig')) if options.products
products = (read_json(options.products, 'products') if options.products
else library['salts'])
if options.targets:
targets = json.loads(Path(options.targets).read_text(encoding='utf-8-sig'))
targets = read_json(options.targets, 'targets')
title = options.title or Path(options.targets).stem
else:
title = choose_formula(library, options.formula, options.crop)
targets = next(f['targets'] for f in library['formulas'] if f['name'] == title)
label, water, chemistry = read_water(options.water)
if options.water_share is not None:
label, water, chemistry = blend(label, water, chemistry, options.water_share)
rules = json.loads(Path(options.rules).read_text(encoding='utf-8-sig')) if options.rules else ()
rules = read_json(options.rules, 'rules') if options.rules else ()
reagents = [acid_record(a) for a in options.acid] + catalogue_ph_reagents()
limits = dict(options.limit)
workflow = plan_fertilizer_workflow(
Expand Down Expand Up @@ -256,18 +311,18 @@ def main(argv=None):
pick.add_argument('--targets', help='JSON file of target mg/L (N_NO3 and N_NH4 as N)')
parser.add_argument('--list-formulas', action='store_true', help='list the packaged formulas and exit')
parser.add_argument('--water', help='"ro" or a water analysis JSON file (see above)')
parser.add_argument('--water-share', type=float, metavar='PERCENT',
parser.add_argument('--water-share', type=number_in('--water-share', 0, 100), metavar='PERCENT',
help='use the analysed water as this percentage of the batch water, the rest ion-free '
'(desalinated or RO); default 100')
parser.add_argument('--volume', type=float, default=1000, help='final batch litres (default 1000)')
parser.add_argument('--ph', type=float, default=5.8, help='target feed pH (default 5.8)')
parser.add_argument('--ratio', type=float, default=100, help='final litres per litre of concentrate (default 100)')
parser.add_argument('--volume', type=number_in('--volume', 0), default=1000, help='final batch litres (default 1000)')
parser.add_argument('--ph', type=number_in('--ph', 0, 14, above=False), default=5.8, help='target feed pH (default 5.8)')
parser.add_argument('--ratio', type=number_in('--ratio', 0), default=100, help='final litres per litre of concentrate (default 100)')
parser.add_argument('--acid', action='append', default=[], metavar='FORMULA:FRACTION:DENSITY[:NAME]',
help='an acid from your certificate, e.g. HNO3:0.60:1.37; repeat for more')
parser.add_argument('--limit', action='append', default=[], type=limit_entry, metavar='SYMBOL=MG_PER_L',
help='a maximum concentration in the final solution, e.g. Cl=106.35; repeat for more. '
'Checked on the laboratory analysis; none is assumed')
parser.add_argument('--max-reagent-litres', type=float, help='largest reagent volume per batch (default volume/200)')
parser.add_argument('--max-reagent-litres', type=number_in('--max-reagent-litres', 0), help='largest reagent volume per batch (default volume/200)')
parser.add_argument('--products', help='JSON array of your product records (default: the packaged catalogue)')
parser.add_argument('--rules', help='JSON array of extra compatibilityRule records separating products')
parser.add_argument('--output', help='new directory for report.html, batch-sheet.html and summary.json')
Expand All @@ -293,6 +348,7 @@ def main(argv=None):
print(f' Tank {tank["name"]}: ' + ', '.join(p['name'] for p in tank['products']))
selected = summary['ph'] and summary['ph']['selected']
if selected:
print(f' pH: {selected["volume_ml_per_batch"]:.0f} mL {selected["product"]} per {summary["batch_litres"]:g} L')
print(f' pH: {millilitres(selected["volume_ml_per_batch"])} mL {selected["product"]} per '
f'{summary["batch_litres"]:g} L')
print(f'Wrote {", ".join(files)} to {output}')
return 3 if summary['status'] == 'blocked' else 0
1 change: 1 addition & 0 deletions src/flahax/data/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ A plan or state label does not execute hardware or prove physical mixing occurre
| CLI says salts are required | Supply a nonempty array of product records; do not send targets alone. |
| `feasible` is false | Inspect all nutrient rows and available assays; do not force approval by hiding residuals. |
| `unknown_product` or identity mismatch | Use exact catalogue names and IDs for catalogue-only chemistry. |
| `missing_file` or `invalid_json` | A file named on the command line (water, targets, products, rules, a saved item or session) is missing, unreadable or not valid JSON; the message names the file and the line and column. |
| `material_undefined` | A product has only a name. Give its formula, its ions, or its analysis by nutrient form. |
| `identity_inconsistent` | A label does not fit its chemical: its charges are more than 1 % out of balance (rounded labels and commercial grades stay well inside; a one-point typing error does not). Check the label. |
| `ph_not_planned_for_product` | A compound's data sheet is incomplete or does not balance: it is used for nutrients, but no pH reagent is planned. Complete the nitrogen forms, chelating agent and counter-ions. |
Expand Down
4 changes: 2 additions & 2 deletions src/flahax/mix_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
from pathlib import Path

from . import __version__
from .batch_cli import ACID_FORMULAS, BatchOptions, limit_entry, render, run_batch
from .batch_cli import ACID_FORMULAS, BatchOptions, limit_entry, read_json, render, run_batch
from .composition import ION_BALANCE_WARNING_PCT, target_ion_balance
from .delivery_contracts import DeliveryError
from .engine import load_library
Expand Down Expand Up @@ -416,7 +416,7 @@ def main(argv=None, *, ask=input, say=print, store=None):
try:
if args.session:
path = find_session(store, args.session)
name, session = path.stem, json.loads(path.read_text(encoding='utf-8-sig'))
name, session = path.stem, read_json(path, 'session')
else:
say(f'FlahaX {__version__} mix: five steps. Enter keeps the value in brackets; Ctrl+C stops.')
name, session, pending = interview(p, store)
Expand Down
3 changes: 2 additions & 1 deletion src/flahax/mix_store.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ def load(self, kind, name):
path = self.path(kind, name)
if not path.is_file():
raise DeliveryError('unknown_item', f'no saved {kind[:-1]} named {name!r} in {path.parent}')
return json.loads(path.read_text(encoding='utf-8-sig'))
from .batch_cli import read_json # names the file and the line if it is damaged
return read_json(path, f'saved {kind[:-1]}')

def save(self, kind, name, data):
path = self.path(kind, name)
Expand Down
Loading
Loading
0