{"id":1863,"library":"pycomposefile","title":"pycomposefile","description":"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.","status":"active","version":"0.0.34","language":"en","source_language":"en","source_url":"https://github.com/smurawski/pycomposefile","tags":["docker","compose","yaml","configuration","deserialization"],"install":[{"cmd":"pip install pycomposefile","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for parsing YAML-formatted Docker Compose files. Version ^6.0.0 or higher is specified.","package":"PyYAML","optional":false}],"imports":[{"symbol":"ComposeFile","correct":"from pycomposefile.compose_file import ComposeFile"},{"note":"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.","wrong":"from pycomposefile import load_composefile","symbol":"load_composefile","correct":"from pycomposefile.compose_file import load_composefile"}],"quickstart":{"code":"import os\nfrom pycomposefile.compose_file import load_composefile\n\n# Create a dummy docker-compose.yaml file for demonstration\ncompose_content = \"\"\"\nversion: '3.8'\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"${APP_PORT:-8080}:80\"\n    environment:\n      - DB_HOST=${DB_HOST:-localhost}\n  db:\n    image: postgres:13\n    volumes:\n      - db_data:/var/lib/postgresql/data\n\nvolumes:\n  db_data:\n\"\"\"\n\nwith open(\"docker-compose.yaml\", \"w\") as f:\n    f.write(compose_content)\n\n# Set environment variables for testing\nos.environ['APP_PORT'] = os.environ.get('APP_PORT', '9000')\n# DB_HOST is intentionally left unset to test default value\n\n# Load the compose file\ncompose_file = load_composefile(\"docker-compose.yaml\")\n\n# Access services and their properties\nweb_service = compose_file.services['web']\nprint(f\"Web service image: {web_service.image}\")\nprint(f\"Web service ports: {web_service.ports}\")\nprint(f\"Web service DB_HOST environment variable: {web_service.environment.get('DB_HOST')}\")\n\n# Clean up the dummy file\nos.remove(\"docker-compose.yaml\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to `pycomposefile>=0.0.33` to ensure correct environment variable parsing behavior.","message":"Environment 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.","severity":"gotcha","affected_versions":"<0.0.33"},{"fix":"Ensure your Docker Compose file adheres to a widely supported specification or test `pycomposefile`'s behavior thoroughly with your specific compose file version.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Attempting 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}