Minor audit findings (omnibus): docstring overclaims, broad fallback, pickle codec, import-time side effects

[thorwhalen]

Summary

Companion to #13 / #14 / #15 — collecting the lower-priority items from the same audit so they're not lost. Each is minor in isolation. Cherry-pick whichever feel worthwhile; close the rest.

---

1. EnvironmentVariables docstring overpromises

config2py/util.py:55-64 — class docstring says "wraps environment variables without revealing sensitive information." The __repr__ override at line 64 does redact, but values are still exposed by:

• dict(envvar), envvar.maps[0], envvar.items(), envvar.values()
• pickle.dumps(envvar)
• structured loggers that walk the mapping

The protection covers only the repr / print / f-string path. Either tighten the class (override __iter__ / items / values / __reduce__ to redact) or soften the docstring to "hides values from repr only, not from iteration or serialization."

---

2. config_not_found_exceptions=(Exception,) swallows everything by default

config2py/base.py:107 and :283 — default is (Exception,), which catches and silently moves to the next (less-trusted) source on any error. Network blips, programming bugs, missing imports — all indistinguishable from "not found."

Suggest narrowing the default to (KeyError, LookupError, FileNotFoundError) and keeping the broad catch as opt-in. Stricter default surfaces real bugs early; opt-in preserves the current ergonomics for callers who genuinely want it.

---

3. pickle.loads as the default .pkl / .pickle decoder

config2py/codecs.py:350-354 registers pickle.loads as the default decoder. If a user calls decode_by_extension('something.pkl', untrusted_bytes) (e.g. fetched from a remote store), they get arbitrary code execution.

At minimum, document the deserialization risk in the registration's docstring. Stronger fix: require explicit opt-in (register_codec(".pkl", ..., trusted=True) or similar), or only register the encoder (writing pickle is safe; reading untrusted pickle isn't).

---

4. Filesystem side effects at import time

config2py/tools.py:107 and :122 — import config2py triggers simple_config_getter() and get_configs_local_store(), which create ~/.config/config2py/ and ~/.config/config2py/configs/ and write marker files.

Side effects on import are surprising (containers, read-only filesystems, sandboxed test runners) and slow import config2py for callers who only need a small slice of the API. Move to lazy cached_property / module-level __getattr__.

---

5. Silent fallback in ConfigReader source-kind detection

config2py/s_configparser.py:227-247 — kind detection is a chain of isinstance checks ending in:

else:
    self.read(source)
    source_kind = "unknown"

configparser.read() silently returns an empty list when given a path that doesn't exist, so a wrong/typo'd source produces an empty config rather than an error. Suggest raise TypeError(f"Unsupported source: {type(source).__name__}") in the else branch.

---

6. extract_exports silently returns {} for non-existent paths

config2py/tools.py:140 — if the argument has no newline and isn't an existing file, falls through to "no exports." A typo'd path (extract_exports("path/to/.env") where the file doesn't exist) returns {} rather than raising. Same root cause as #5: detect-and-fall-through where detect-and-raise would catch user error earlier.

---

7. get_configs_local_store OS-inconsistent path detection

config2py/tools.py:31 — if os.path.sep in config_src and os.path.isdir(config_src): decides "treat as path vs. app name" by sniffing os.path.sep. On Windows, simple_config_getter("my.app") and simple_config_getter("my\\app") will be classified differently than on POSIX. Use os.path.isabs(config_src) or accept an explicit kind= argument.

---

8. Dead commented-out code

config2py/base.py:82-90 — commented block referencing OPENAI_API_KEY and getpass.getpass. Suggests a pattern the package no longer implements; safe to delete.

---

Why one ticket

These are all small, none warrant maintainer scheduling on its own, and bundling lets you triage in one pass. Happy to split any item into its own ticket if you'd rather track it that way. Top-3 items (mask-input default, KeyError value leakage, file umask) are filed separately as #13 / #14 / #15.

[thorwhalen]

Item 1 (EnvironmentVariables docstring overclaim) fixed in #21 (merged) -- softened to clarify it only redacts repr()/print, not iteration or pickling.

Items 2 and 3 deliberately not touched this pass, both because they're real behaviour changes rather than metadata/hardening fixes, and config2py has 33 known fleet dependents (3 not checked out on this box, so a full dependents-test run isn't possible right now):

• Item 2 (narrow config_not_found_exceptions default from (Exception,)): changes what currently-silently-swallowed errors would start propagating for every existing caller of the broad-catch default -- a behaviour change, not just a hardening addition.
• Item 3 (pickle as default .pkl/.pickle decoder): removing/gating it changes what decode_by_extension('*.pkl', ...) does for existing callers who use it for trusted round-tripping -- also a real design tradeoff (security vs. functionality), not something to flip unattended.

Leaving open for those two; happy to implement either behind explicit review once the dependents question is settled (or once you weigh in directly).

[thorwhalen]

Split this omnibus so each item can be tracked and closed on its own:

Item	Status
1. EnvironmentVariables docstring	Done in #21
2. Broad (Exception,) fallback	Docstring warning added in #31. Behaviour change is tracked in #25
3. Pickle decoder	Security warnings added in #31: module docstring, decode_by_extension, and the registration site. The eval in the register_codec example is also replaced. Making the decoder opt-in is tracked in #29
4. Import-time folder creation	Reproduced and commented at the call site in #31. Lazy creation is tracked in #26
5 and 6. Silent empty results for typo'd paths	Reproduced, and the current behaviour is now stated in the docstrings in #31. Raising instead is tracked in #27. For item 5, the typo'd path goes through the str filepath branch, not the final else
7. os.path.sep path sniffing	Docstring note added in #31. The fix is tracked in #28, labelled needs-local because the Windows half needs Windows
8. Dead commented-out code	Removed in #31

#31 carries Fixes #16, so this issue closes when that PR merges. The follow-ups stay open.

---

Generated by Claude Code