Skip to content

Docs: reframe shared CONSTANTS as an application-startup contract #262

Description

@derek73

The shared module-level CONSTANTS is sound — it's the only channel that reaches parses happening inside code you don't own (helpers, pipelines, third-party libraries using nameparser internally), the same justification logging and locale have. The gotchas all come from mutating it casually. The docs should state that as a contract instead of warning about it:

CONSTANTS is for application-level configuration, set once at startup. For anything scoped — one dataset, one library, one test — pass your own Constants instance.

Changes:

  • customize.rst: lead the customization docs with the contract; demote the "Potential Gotcha" section to a consequence of violating it rather than a surprise property of the API
  • nameparser/config/__init__.py module docstring: same reframe (it currently teaches the None sentinel first)
  • Fold in the three-spelling vocabulary from Add Constants.copy(); deprecate constants=None #260 once Constants.copy() exists

No code changes. Depends on #260 only for the vocabulary mention; the reframe itself is true today.

Metadata

Metadata

Assignees

Labels

docsDocumentation fixes and updates

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions