====== 13.3 Python Utility Script Conventions ======

[[fxdemo:05-part:start | Go To Top ]]

[[fxdemo:05-part:13-build-and-run-scripts:start | Return to Build and Run Scripts ]]

Python utility scripts may support setup, validation, type-generation orchestration, log inspection, test harnesses, catalogue extraction, documentation generation, and Evidence preparation. Python utilities should support repeatability and review; they should not become undocumented logic hidden outside the architecture and handbook.

Each Python utility script should:

  - Include a module docstring that identifies the script purpose, expected inputs, outputs, and failure behavior.
  - Provide a clear command-line interface where developers run it directly.
  - Validate inputs before reading, writing, generating, or deleting files.
  - Use Repository-relative paths where practical.
  - Avoid hard-coded machine-specific paths.
  - Return meaningful process exit codes.
  - Write useful diagnostic output.
  - Keep generated [[dido:99_annexes:annex-b-terms-and-definitions:a:artifact|Artifacts]] separate from handwritten source files.
  - Use functions with docstrings for non-trivial behavior.
  - Avoid silently swallowing exceptions.
  - Document any dependencies on Python packages or external tools.

Python scripts should use the project-local virtual environment defined in the Development Environment section. The Repository should declare dependencies through the approved dependency file or package Configuration.

----

<WRAP centeralign>

© 2026 Dido Solutions, Inc. and Jackrabbit Consulting, Inc.

</WRAP>