Library-appropriate configuration: no argv parsing, config discovery

[roed-math]

Ports the configuration redesign from LMFDB/lmfdb#7069 to psycodict itself, ahead of 1.0. Three checkout-era behaviors were wrong for a general-purpose PyPI library; each is the kind of breaking change 1.0 exists for.

1. Configuration() no longer parses the host program's argv

readargs auto-detected "running as a script" (hasattr(__main__, "__file__")) — so any script constructing PostgresDatabase() bare had psycodict's argparse run over its command line, and an unrecognized option printed psycodict's usage and raised SystemExit. readargs now defaults to False; a script that wants psycodict to own its command line passes readargs=True explicitly.

2. Config discovery — nothing is ever created in the cwd

With no explicit config_file, the path is discovered: $PSYCODICT_CONFIG → ./config.ini if it already exists → ~/.psycodict/config.ini. A missing file is auto-created only at an explicit location (defaults dict, CLI, env var) or the ~/.psycodict fallback — the current-directory candidate requires the file to already exist, so first use no longer sprinkles config.ini into whatever directory Python ran in. Existing cwd-config workflows keep working unchanged. The secrets file defaults to secrets.ini next to the resolved config file (same value as before for cwd configs).

When no home directory can be determined either (HOME unset and a uid with no passwd entry — expanduser returns the literal ~), the fallback raises a RuntimeError pointing at PSYCODICT_CONFIG instead of creating a literal ./~/.psycodict in the cwd; a homeless container with a configured location never consults the home directory.

3. The default slow-query log moves out of the cwd

The default slow_queries.log now resolves to the first usable of <config dir>/logs/ and ~/.psycodict/logs/ — probed by creating them and checking writability, since PostgresDatabase attaches its FileHandler at construction. The fallback means reading a configuration never requires write access beside it (a system-managed config in a read-only /etc/psycodict/ gets its default log under ~/.psycodict/logs/); if neither candidate is usable the plain name is kept (the historical cwd behavior). Any explicitly configured value — from the defaults dict or the config file — is used verbatim; only the bare default name is treated as "unconfigured", the same transparent redirect #7069 uses. Callers supplying their own parser are exempt from the redirect entirely.

In passing

postgresql_dbname was the one option whose default ignored the defaults dictionary (hardcoded "lmfdb"); it now honors defaults.get("postgresql_dbname", "lmfdb").

Downstream compatibility

LMFDB and seminars both subclass Configuration with their own parser, their own config_file default anchored to their checkout, and explicit readargs/writeargstofile — none of the changed defaults reach them, and the log redirect is additionally gated to the builtin parser. The downstream CI jobs verify this mechanically.

Tests

tests/test_config.py grows a discovery section (env var / cwd / home-fallback precedence, explicit-beats-env, nothing-created-in-cwd), slow-log location coverage (default redirected + written file keeps the plain name, explicit values respected, config-file values respected, custom parsers exempt), the argv regression (a fake __main__ with __file__ and hostile argv → no SystemExit), the postgresql_dbname fix, and — from review — the homeless-container case (no HOME, no passwd entry → clear RuntimeError, no literal ./~; a discoverable config still works) and the read-only-config-directory case (0555 config dir parses fine, log falls back to ~/.psycodict/logs; with no home either, the plain name survives). Full suite 833 passed / 36 skipped locally (PG18, psycopg 3.3.4); ruff clean.

#113's README quickstart and CHANGELOG describe the old cwd behavior; I'm updating that branch to match in tandem.

🤖 Generated with Claude Code