Skip to main content

conveoconfi

Reusable YAML template-backed configuration helpers for Python applications.

conveoconfi provides a small function-based API for convention-over- configuration behavior:

  • create missing application config directories
  • create missing YAML config files from application-owned default templates
  • complete existing YAML files with newly added defaults
  • preserve existing user-provided values and extra keys
  • read child parameters from config.yaml

Installation

Install the package with pip, or declare it in your project's dependency metadata.

pip install conveoconfi

conveoconfi declares PyYAML as a runtime dependency, so applications do not need to add a separate YAML dependency for these helpers.

Default Templates

Applications keep their own YAML default templates, such as config.yaml, logging.yaml, or feature_flags.yaml. Pass that template directory explicitly when reading or completing config files.

from pathlib import Path

from conveoconfi import create_and_read_config_file


APP_DIR = Path.home() / ".myapp"
DEFAULT_FILES_DIR = Path(__file__).parent / "default_files"

config = create_and_read_config_file(
    "config.yaml",
    APP_DIR,
    default_files_dir=DEFAULT_FILES_DIR,
)

The equivalent keyword default_template_dir is also supported. Pass only one of default_files_dir or default_template_dir.

Template lookup failures are explicit. If a default directory is omitted, or the requested template file is missing, conveoconfi raises a FileNotFoundError that names the lookup problem.

Template Discovery Decision

The public API requires applications to pass their template directory explicitly with default_files_dir or default_template_dir. conveoconfi does not search for templates in its own package directory because those files belong to the consuming application, not to this reusable dependency.

Explicit template paths keep behavior predictable in tests, work with any project layout, and fail with a direct FileNotFoundError when templates are not configured. Projects that want a shorter call site can wrap conveoconfi once in their own code and bind the app's template path there.

Public API

The public API exposes these function names from the package root:

  • create_and_read_config_file(file_name, default_app_dir, force_default=False, complete_file=True, default_files_dir=None, default_template_dir=None)
  • complete_config_file(file_name, default_app_dir, default_files_dir=None, default_template_dir=None)
  • overwrite_config_file(file_name, default_app_dir, data)
  • append_config_file(file_name, default_app_dir, data)
  • get_param(parent_param, param, default_app_dir, default_files_dir=None, default_template_dir=None)
  • config_file_exists(file_name, default_app_dir)
  • config_file_path(file_name, default_app_dir)

config_file_path creates the application config directory before returning the path. get_param reads from config.yaml.

Completion Behavior

By default, create_and_read_config_file completes existing config files from the matching default template and writes the completed result back to disk. Completion is recursive for dictionaries:

# Existing user config
notifications:
  email:
    enabled: false

# Default template
notifications:
  email:
    enabled: true
    sender: hello@example.com

The completed file keeps the user's enabled: false value and adds only the missing sender value. User-defined extra keys are preserved. If a current value and default value disagree on shape, such as a scalar versus a dictionary, the current user value is preserved.

Use force_default=True to deliberately replace an existing config file with template defaults. Use complete_file=False to read an existing file without mutating it.

Metadata

Release files for conveoconfi 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for conveoconfi 0.1.0
File Size Uploaded Provenance Actions
conveoconfi-0.1.0.tar.gz 28.6 kB Without provenance Details for conveoconfi-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for conveoconfi 0.1.0
File Interpreter ABI Platform Actions
conveoconfi-0.1.0-py3-none-any.whl Python 3 none any Details for conveoconfi-0.1.0-py3-none-any.whl

Total release size: 32.8 kB

Release files / conveoconfi-0.1.0.tar.gz

Download URL conveoconfi-0.1.0.tar.gz
Size 28.6 kB
Tags Source
SHA-256 checksum
How to use checksums
e440e07684f0aae31e0f75eae2fa20d0c78ee1696058a82cb5ec27a28e598d68
BLAKE2b-256 checksum
How to use checksums
ac1f9383dfc10f95b958e8b7a6accbb350c4e04b8b7e9eb91db1b8bedd2c508b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / conveoconfi-0.1.0-py3-none-any.whl

Download URL conveoconfi-0.1.0-py3-none-any.whl
Size 4.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fbbac603516247a3ac0ebaab94d46be93073d03b86da35aca53f4ea85183a824
BLAKE2b-256 checksum
How to use checksums
4db70615e902e08ee826f87640653422dc69115b5001fdac80667f6b9f2d4641
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for conveoconfi 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page