mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 4.7
85f1caccc7
Tighten the utils namespace so each subpackage owns one concern:
- utils/applications/* moves under utils/roles/applications/* (helpers
that operate on the runtime applications dict and meta/services.yml).
- utils/service_registry.py and utils/database_service.py move under
utils/roles/applications/services/ as registry.py and database.py.
- utils/entity_name_utils.py becomes utils/roles/entity_name.py.
- utils/invokable.py, utils/valid_deploy_id.py, and the existing
utils/roles/resource_validation.py group under utils/roles/validation/
as invokable.py, deploy_id.py, and resources.py.
- utils/templating.py and utils/jinja_strict.py split into
utils/templating/ansible.py (Templar + TrustedAsTemplate, lookup-env
shortcut) and utils/templating/jinja.py (vanilla Jinja2 Environment,
multi-pass strict render).
Every caller in utils, cli, plugins, roles/<role>/{filter,lookup}_plugins,
tests, and the docs that link to the moved files is updated to the new
import paths. Test files mirror the new source layout
(tests/unit/utils/{roles,templating}/...).
New READMEs at utils/cleanup/, utils/roles/, utils/roles/applications/services/,
utils/roles/validation/, and utils/templating/ follow the
documentation.md and readme_md.md guidelines.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
36 lines
1.4 KiB
Markdown
36 lines
1.4 KiB
Markdown
# Application Utilities (`utils/roles/applications/`) 🧩
|
|
|
|
This package contains shared Python helpers that operate on the central `applications` configuration dictionary.
|
|
|
|
## Purpose 🎯
|
|
|
|
Modules in `utils/roles/applications/` MUST provide reusable helpers for reading, resolving, and validating application configuration.
|
|
Helpers MUST stay independent of Ansible plugin entrypoints so the same code can be imported from filter plugins, lookup plugins, and library modules.
|
|
|
|
## Example Import ✍️
|
|
|
|
```python
|
|
from utils.roles.applications import config
|
|
|
|
value = config.get(
|
|
applications,
|
|
application_id,
|
|
"features.oidc",
|
|
strict=False,
|
|
default=False,
|
|
)
|
|
```
|
|
|
|
## Design Guidelines 📐
|
|
|
|
- Helpers SHOULD be focused, composable, and free of side effects during import.
|
|
- Helpers MUST NOT depend on Ansible plugin loader behavior at import time.
|
|
- Helpers SHOULD raise typed exceptions (e.g. `AppConfigKeyError`) so callers can react to missing keys in strict mode.
|
|
- Public functions SHOULD use concise names (e.g. `get`) and rely on module-qualified access at call sites (`config.get(...)`) for clarity.
|
|
|
|
## What Does Not Belong Here 🚫
|
|
|
|
- Standalone executable modules MUST live in `library/`.
|
|
- Ansible plugin entrypoints MUST live under `plugins/*`.
|
|
- Cross-cutting helpers that are not application-specific SHOULD live in the parent `utils/` package instead.
|