pycomposefile

library0.0.34pypypi✓ verified 26d ago

pycomposefile provides structured deserialization of Docker Compose files into Python objects, making it easier to programmatically inspect and manipulate Compose configurations. It is currently at version 0.0.34 and sees regular, minor releases.

devops serialization data

pip install pycomposefile

github ↗package ↗

INSTALL

IMPORT

SIG · PYCOMPOSEFILE

pycomposefile

devopspythonv0.0.34

Install

1.7s avg

Import

12ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.34 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.014s · 20.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.010s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ComposeFile

✓ from pycomposefile.compose_file import ComposeFile

load_composefile

✓ from pycomposefile.compose_file import load_composefile

✗ from pycomposefile import load_composefile

The primary loading function `load_composefile` and the `ComposeFile` class are located within the `pycomposefile.compose_file` submodule, not directly under the top-level package.

This quickstart demonstrates how to load a Docker Compose file and access its deserialized properties. It also shows how environment variable interpolation (e.g., `${VAR:-default}`) is handled.

import os from pycomposefile.compose_file import load_composefile # Create a dummy docker-compose.yaml file for demonstration compose_content = """ version: '3.8' services: web: image: nginx:latest ports: - "${APP_PORT:-8080}:80" environment: - DB_HOST=${DB_HOST:-localhost} db: image: postgres:13 volumes: - db_data:/var/lib/postgresql/data volumes: db_data: """ with open("docker-compose.yaml", "w") as f: f.write(compose_content) # Set environment variables for testing os.environ['APP_PORT'] = os.environ.get('APP_PORT', '9000') # DB_HOST is intentionally left unset to test default value # Load the compose file compose_file = load_composefile("docker-compose.yaml") # Access services and their properties web_service = compose_file.services['web'] print(f"Web service image: {web_service.image}") print(f"Web service ports: {web_service.ports}") print(f"Web service DB_HOST environment variable: {web_service.environment.get('DB_HOST')}") # Clean up the dummy file os.remove("docker-compose.yaml")

Debug

Known issues

gotchaEnvironment variable replacement logic, particularly with default values (e.g., `${VAR:-default}`), was subject to fixes in versions prior to 0.0.33. Older versions might exhibit incorrect parsing for complex variable patterns. Always test environment variable resolution if upgrading from older versions.

fix

Upgrade to `pycomposefile>=0.0.33` to ensure correct environment variable parsing behavior.

affects: <0.0.33

gotchaThe library deserializes Docker Compose files, which themselves have version specifications (e.g., `version: '3.8'`). While `pycomposefile` aims for broad compatibility, using it with a Docker Compose file version that introduces new, unsupported features or significantly different structures may lead to parsing errors or incomplete object models. Consult Docker Compose documentation on versioning.

fix

Ensure your Docker Compose file adheres to a widely supported specification or test `pycomposefile`'s behavior thoroughly with your specific compose file version.

affects: All versions

gotchaAs a file parsing library, common file I/O errors like `FileNotFoundError` (if the compose file path is incorrect) or `PermissionError` (if the script lacks read access) are frequent. Ensure correct file paths and appropriate permissions.

fix

Verify the existence and readability of the `docker-compose.yaml` file. Use absolute paths or ensure the file is in the expected working directory. Handle `FileNotFoundError` and `PermissionError` exceptions gracefully.

affects: All versions

gotchaAttempting to access non-existent keys (e.g., `compose_file.services['non_existent_service']`) or attributes on deserialized objects (e.g., `service.non_existent_attribute`) will result in `KeyError` or `AttributeError`. The structure of the Python objects mirrors the Compose file's YAML structure.

fix

Always check for the existence of keys/attributes before accessing them, especially when dealing with optional Compose file elements. Use `dict.get()` or `hasattr()` where appropriate, or implement validation logic.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pycomposefile'

The 'pycomposefile' library is not installed in your Python environment or the Python interpreter cannot find it.

fix

pip install pycomposefile

yaml.YAMLError: while scanning a simple key

The provided Docker Compose file has a syntax error or is malformed, preventing `pycomposefile` from parsing it correctly.

fix

Review your Docker Compose YAML file for syntax errors, especially around the indicated line and column, such as incorrect indentation, missing colons, or unclosed strings. Tools like `docker-compose config` or an online YAML validator can help identify issues.

AttributeError: 'Service' object has no attribute 'non_existent_attribute'

You are attempting to access an attribute or field (e.g., a service property, network, or volume) on a `pycomposefile` object that does not exist in the parsed Docker Compose configuration.

fix

Verify the exact structure and available attributes of the `ComposeFile` object and its nested components (like `Service` objects) against your Docker Compose file and the `pycomposefile` documentation. Ensure the attribute you're trying to access is actually present.

Upgrade

Version history

0.0.34latest on PyPI · released Jul 29, 2025

Audit

Dependencies

PyYAMLrequiredRequired for parsing YAML-formatted Docker Compose files. Version ^6.0.0 or higher is specified.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/smurawski/pycomposefile ↗

packagehttps://pypi.org/project/pycomposefile/ ↗