API Reference

subcompose.get_groups_from_data(data)[source]

Extracts group definitions from the compose data.

Parameters:

data (Dict[str, Any]) – The parsed YAML data from the compose file.

Returns:

A dictionary where keys are group names and values are lists of service names.

Return type:

Dict[str, List[str]]

subcompose.validate_groups(groups, data, fix=False)[source]

Validates the groups defined in the compose file.

This function checks for: 1. Undefined groups used in services. 2. Defined groups that are empty (no services assigned). 3. Missing dependencies within groups (services in a group depending on services not in the group).

Parameters:

  • groups (Dict[str, List[str]]) – A dictionary mapping group names to lists of service names.

  • data (Dict[str, Any) – The parsed YAML data from the compose file.

  • fix (bool) – Whether to attempt to fix the issues found.

Returns:

A tuple containing (issues_found, fixed).

Return type:

tuple[bool, bool]

subcompose.validate_volumes(data, fix=False)[source]

Validates that all defined volumes are used by at least one service.

Parameters:

  • data (Dict[str, Any]) – The parsed YAML data from the compose file.

  • fix (bool) – Whether to attempt to fix the issues found (remove unused volumes).

Returns:

A tuple containing (issues_found, fixed).

Return type:

tuple[bool, bool]

subcompose.check_service_extension_chain(parent, service_name)[source]

Checks for circular dependencies in service extensions.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_name (str) – The name of the service to check.

Return type:

None

subcompose.substitute_environment_variables(node, no_interpolate=False, ignored_vars=None, key_name='root', indent='')[source]

Recursively substitutes environment variables in the given node (dict, list, or str).

Parameters:

  • node (Any) – The data structure to process.

  • no_interpolate (bool) – If True, skips interpolation for variables in ignored_vars.

  • ignored_vars (Optional[List[str]]) – List of variable names to ignore during interpolation.

  • key_name (str) – The key name of the current node (for logging).

  • indent (str) – Indentation string for logging.

Returns:

The data structure with environment variables substituted.

Return type:

Any

subcompose.substitute_image_tags(parent, service_image_tags)[source]

Substitutes image tags in the service definitions.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_image_tags (Dict[str, Optional[str]]) – A map of service names to image tags.

Returns:

The updated compose data.

Return type:

Dict[str, Any]

subcompose.filter_by_image_tag(parent, service_image_tags)[source]

Filters services to only include those that are currently running with the specified image tags.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_image_tags (Dict[str, Optional[str]]) – A map of service names to image tags.

Returns:

The filtered compose data.

Return type:

Dict[str, Any]

subcompose.remove_dependencies_from_filtered_containers(parent, groups, only_managed=False, managed_services_set=None)[source]

Removes dependencies from services that are not in the managed groups.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • groups (Dict[str, List[str]]) – The group definitions.

  • only_managed (bool) – If True, only removes dependencies that are managed externally depending on the deployment.

  • managed_services_set (Optional[set[str]]) – Set of managed services to remove from dependencies.

Returns:

The updated compose data.

Return type:

Dict[str, Any]

subcompose.represent_none(self, _)[source]

Custom representer for None.

Parameters:
Return type:

Any

subcompose.remove_subcompose_keys(data)[source]

Recursively removes keys starting with ‘x-subcompose-’ from the data.

Parameters:

data (Any) – The data structure to clean.

Returns:

The cleaned data structure.

Return type:

Any

subcompose.main()[source]
Return type:

None

subcompose.cli

🐳 subcompose: a command line utility to manage subsets of services in Docker compose.yaml files.

Usage:

subcompose ( -h | –help | -? ) subcompose ( -v | –version ) subcompose ( -l | –list ) [–compose-file=<filename>] subcompose delete-containers [–debug] [–interpolate] [–all] [–unmanaged] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose delete-images [–debug] [–interpolate] [–unmanaged] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose preview [–debug] [–interpolate] [–unmanaged] [–var-file=<filename>] [–src-tag=<src_tag>] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose pull [–interpolate] [–unmanaged] [–var-file=<filename>] [–src-tag=<src_tag>] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose push [–interpolate] [–unmanaged] [–var-file=<filename>] [–src-tag=<src_tag>] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose run [–debug] [–interpolate] [–unmanaged] [–var-file=<filename>] [–src-tag=<src_tag>] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose stop [–debug] [–interpolate] [–unmanaged] [–service=<service_tag>]… [–group=<group_tag>]… [–compose-file=<filename>] subcompose tag [–interpolate] [–unmanaged] [–var-file=<filename>] [–src-tag=<src_tag>] [–service=<service_tag>]… [–group=<group_tag>]… –registry=<registry> –dst-tag=<dst_tag> [–compose-file=<filename>] subcompose validate [–debug] [–fix] [–compose-file=<filename>]

Examples

subcompose run –group=core subcompose run –group=minimal:1.0.0-SNAPSHOT –group=elk:1.0.0-SNAPSHOT –service=elasticsearch:latest –service=kibana:latest subcompose run –group=standalone subcompose stop –group=standalone subcompose –list subcompose preview –group=minimal –service=gateway

Please note that it is also possible to launch the docker stack by passing the output of preview to docker compose. e.g.:

subcompose preview –group=all | docker compose up subcompose preview –group=core –group=elk | docker compose up

Options:

-E –env-var=<variable> Set ENV variable ( -E AWS_SECRET_ACCESS_KEY=<some_value> -E AWS_DEFAULT_REGION=<some_value> … ) -T –dst-tag=<dst_tag> Set TAG and repo for destination (-T 127.0.0.1:5000:mytag). Uses for tag option only -c –compose-file=<filename> Specify an alternate compose file [default: compose.yaml] -d –debug Display debug messages in console -f –var-file=<filename> Load variables from file -g –group=<group_tag> Group of services to use (-g group1:tag1 -g group2:tag2 …) -h -? –help Show this screen. -i –interpolate Enable variable interpolation -l –list List of available groups and services -r –registry=<registry> Set registry URL -s –service=<service_tag> Service to use (-s service1:tag1 -s service2:tag2 …) -t –src-tag=<src_tag> Default image tag -u –unmanaged Exclude managed services -v –version Show version.

Commands:

🗑️ delete-containers Removes specified containers using the auto-generated compose.yaml configuration or all system containers with –all 🖼️ delete-images Removes specified images using the auto-generated compose.yaml configuration 👁️ preview Prints the auto-generated compose.yaml configuration to the console ⬇️ pull Pulls Docker images to the registry using an auto-generated compose.yaml to obtain image links ⬆️ push Pushes Docker images to the registry using an auto-generated compose.yaml to obtain image links 🐳 run Runs the compose project using an auto-generated compose.yaml ⏹️ stop Stops specified containers using the auto-generated compose.yaml configuration 🏷️ tag Adds tag to images for services and nested services that are in the script 🛡️ validate Validates the groups and dependencies in compose.yaml

subcompose.cli.bold_subcompose(text)[source]
Parameters:

text (str)

Return type:

str

subcompose.cli.main()[source]
Return type:

None

subcompose.parsing

Parsing utilities for subcompose.

subcompose.parsing.get_groups_from_data(data)[source]

Extracts group definitions from the compose data.

Parameters:

data (Dict[str, Any]) – The parsed YAML data from the compose file.

Returns:

A dictionary where keys are group names and values are lists of service names.

Return type:

Dict[str, List[str]]

subcompose.validation

Validation logic for subcompose.

subcompose.validation.validate_groups(groups, data, fix=False)[source]

Validates the groups defined in the compose file.

This function checks for: 1. Undefined groups used in services. 2. Defined groups that are empty (no services assigned). 3. Missing dependencies within groups (services in a group depending on services not in the group).

Parameters:

  • groups (Dict[str, List[str]]) – A dictionary mapping group names to lists of service names.

  • data (Dict[str, Any) – The parsed YAML data from the compose file.

  • fix (bool) – Whether to attempt to fix the issues found.

Returns:

A tuple containing (issues_found, fixed).

Return type:

tuple[bool, bool]

subcompose.validation.validate_volumes(data, fix=False)[source]

Validates that all defined volumes are used by at least one service.

Parameters:

  • data (Dict[str, Any]) – The parsed YAML data from the compose file.

  • fix (bool) – Whether to attempt to fix the issues found (remove unused volumes).

Returns:

A tuple containing (issues_found, fixed).

Return type:

tuple[bool, bool]

subcompose.validation.check_service_extension_chain(parent, service_name)[source]

Checks for circular dependencies in service extensions.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_name (str) – The name of the service to check.

Return type:

None

subcompose.substitution

Substitution logic for subcompose.

subcompose.substitution.substitute_environment_variables(node, no_interpolate=False, ignored_vars=None, key_name='root', indent='')[source]

Recursively substitutes environment variables in the given node (dict, list, or str).

Parameters:

  • node (Any) – The data structure to process.

  • no_interpolate (bool) – If True, skips interpolation for variables in ignored_vars.

  • ignored_vars (Optional[List[str]]) – List of variable names to ignore during interpolation.

  • key_name (str) – The key name of the current node (for logging).

  • indent (str) – Indentation string for logging.

Returns:

The data structure with environment variables substituted.

Return type:

Any

subcompose.substitution.substitute_image_tags(parent, service_image_tags)[source]

Substitutes image tags in the service definitions.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_image_tags (Dict[str, Optional[str]]) – A map of service names to image tags.

Returns:

The updated compose data.

Return type:

Dict[str, Any]

subcompose.filtering

Filtering logic for subcompose.

subcompose.filtering.filter_by_image_tag(parent, service_image_tags)[source]

Filters services to only include those that are currently running with the specified image tags.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • service_image_tags (Dict[str, Optional[str]]) – A map of service names to image tags.

Returns:

The filtered compose data.

Return type:

Dict[str, Any]

subcompose.filtering.remove_dependencies_from_filtered_containers(parent, groups, only_managed=False, managed_services_set=None)[source]

Removes dependencies from services that are not in the managed groups.

Parameters:

  • parent (Dict[str, Any]) – The compose data.

  • groups (Dict[str, List[str]]) – The group definitions.

  • only_managed (bool) – If True, only removes dependencies that are managed externally depending on the deployment.

  • managed_services_set (Optional[set[str]]) – Set of managed services to remove from dependencies.

Returns:

The updated compose data.

Return type:

Dict[str, Any]

subcompose.utils

Utility functions for subcompose.

subcompose.utils.represent_none(self, _)[source]

Custom representer for None.

Parameters:
Return type:

Any

subcompose.utils.remove_subcompose_keys(data)[source]

Recursively removes keys starting with ‘x-subcompose-’ from the data.

Parameters:

data (Any) – The data structure to clean.

Returns:

The cleaned data structure.

Return type:

Any

subcompose.constants

Constants for subcompose.

subcompose.logger

Logging configuration for subcompose.

subcompose.logger.configure_logging(debug)[source]

Configure logging for the application.

Parameters:

debug (bool) – Whether to enable debug logging.

Return type:

None