Dockerpyze

To use Dockerpyze as a Poetry plugin, install it into your Poetry environment using poetry self add. You can then trigger the build process using the poetry dockerpyze command. Ensure you have configured the entrypoint in your pyproject.toml under the [tool.dpy] section.

# 1. Install plugin
poetry self add dockerpyze@latest

# 2. Configure pyproject.toml
# [tool.dpy]
# entrypoint = "poetry run <your-script>"

# 3. Build
poetry dockerpyze

To use Dockerpyze with uv, install it as a development dependency and then run it using uv run dockerpyze. You must configure an entrypoint in your pyproject.toml for the tool to function correctly.

Steps:

1. Install as dev dependency: uv add dockerpyze --dev
2. Configure [tool.dpy] in pyproject.toml.
3. Run the build: uv run dockerpyze

# 1. Install
uv add dockerpyze --dev

# 2. Configure pyproject.toml
# [tool.dpy]
# entrypoint = "uv run <your-script>"

# 3. Build
uv run dockerpyze

All configuration options can be passed via environment variables by prefixing the key with DPY_.

• Standard keys: Use uppercase with underscores (e.g., DPY_ENTRYPOINT).
• Dictionaries (env, labels): Set multiple values by using the pattern DPY_ENV_<VAR_NAME> or DPY_LABELS_<LABEL_NAME>.
• Dotenv: The plugin automatically loads variables from a .env file.

# Single value
export DPY_ENTRYPOINT="python -m myapp"
uv run dockerpyze

# Dictionary values (env/labels)
export DPY_ENV_MY_VAR="my_value"
export DPY_ENV_MY_OTHER_VAR="my_other_value"
export DPY_LABELS_MY_LABEL="label1"
poetry dockerpyze

Dockerpyze allows overriding or providing configuration via environment variables. It looks for variables with the following prefixes:

• DOCKERIZE_
• DPY_
• DOCKERPYZE_

To map an environment variable to a configuration key, convert the key to uppercase and replace hyphens with underscores. For example, the apt-packages key can be set via DPY_APT_PACKAGES.

If you encounter issues during the build process:

1. Enable Debug Mode: Use the --debug flag to get more execution information. poetry dockerpyze --debug or uv run dockerpyze --debug.

2. Manual Dockerfile Generation: If debug information is insufficient, generate a Dockerfile to inspect or build it manually. uv run dockerpyze --generate Then run: docker build Dockerfile .

# Generate Dockerfile for manual inspection/build
uv run dockerpyze --generate
docker build Dockerfile .

The following keys are used specifically during the Docker build stage (before poetry install). Note that modifications to the filesystem made via these instructions may be lost after the poetry install step runs.

• build-apt-packages: Installs apt packages inside the build container.
• extra-build-instructions: Adds extra instructions to the docker build (before poetry install).
• build-poetry-install-args: Additional arguments passed to the poetry install command during the build step.

[tool.dpy]
build-apt-packages = ["gcc"]
extra-build-instructions = ["RUN poetry config http-basic.foo <username> <password>"]
build-poetry-install-args = ["-E", "all", "--no-root"]

If you are integrating Dockerpyze into a Python script, use the build_image function. It parses the pyproject.toml at the specified path and executes the Docker build process.

Function Signature: build_image(path: str, verbose: bool = False, generate: bool = False) -> None

from dockerpyze.builder import build_image

# Build the image for the project at './my-app'
build_image(path='./my-app', verbose=True)

# Just generate the Dockerfile
build_image(path='./my-app', generate=True)

The dockerpyze command supports the following options:

# Command definition for reference
options = [
    option("path", "Project root path", flag=False, default=os.getcwd()),
    option("debug", flag=True, description="(dockerpyze) Debug mode"),
    option("generate", description="(dockerpyze) Generate and persist Dockerfile", flag=True),
]

You can use the entrypoint() function (intended as a CLI entrypoint) to build a Docker image from your project root.

CLI Arguments:

• --path: The root path of your project (defaults to current working directory).
• --generate: Instead of building the image, this flag generates and saves a Dockerfile to your project root.
• --debug: Enables verbose mode, printing the generated Dockerfile and build logs to the console.

# Build the image using the current directory
dpy

# Generate a Dockerfile without building
dpy --generate

# Build from a specific path with debug logs
dpy --path ./my-project --debug

When installed as a Poetry plugin, dockerpyze is available as a CLI command. It automatically generates a Docker image for your project based on the current environment.

By default, it uses the current working directory as the project root. You can customize the path, enable debug mode, or instruct the tool to generate and persist a Dockerfile to your filesystem.

poetry dockerpyze --path /path/to/project --generate --debug