0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 02:54:26 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 4.7 85f1caccc7 refactor(utils): consolidate role-scoped helpers under utils/roles and split templating

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>

2026-05-08 03:53:43 +02:00

1.4 KiB

Raw Permalink Blame History

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 ✍️

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.

1.4 KiB Raw Permalink Blame History

Application Utilities (utils/roles/applications/) 🧩