Paketo Buildpack for CPython Cloud Native

The CPython Buildpack provides CPython (reference implementation of Python) 3. The buildpack installs CPython onto the $PATH which makes it available for subsequent buildpacks and in the final running container. It also sets the $PYTHONPATH environment variable for subsequent buildpacks and launch-time processes.

The buildpack is published for consumption at paketobuildpacks/cpython.

Behavior

This buildpack always participates.

Build time

This buildpack performs the following actions at build time:

• Contributes cpython to a layer - either via a precompiled dependency or by compiling from source.
  • Python is precompiled for recognized, supported stacks (currently the Ubuntu-based stacks)
  • Python is compiled from source during the build phase for unrecognized stacks.
  • dependency/ contains more information how cpython is built.
• Sets the PYTHONPYCACHEPREFIX environment variable to the /tmp directory for this and any subsequent buildpacks.
  • This effectively disables the __pycache__ directories, in turn enabling reproducible builds.
  • It can be overridden via standard means (e.g. pack build --env "PYTHONPYCACHEPREFIX=/some/other/dir") if there is a need to keep the __pycache__ directories in place of reproducible builds.
• Sets the PYTHONPATH to the cpython layer path for this and any subsequent buildpacks.
• Adds the newly installed cpython bin dir location to the PATH.

Launch time

This buildpack does the following at launch time:

• Sets a default value for the PYTHONPATH environment variable.

Configuration

BP_CPYTHON_VERSION

The BP_CPYTHON_VERSION variable allows you to specify the version of CPython that is installed. (Available versions can be found in the buildpack.toml.)

pack build flag

pack build my-app --env BP_CPYTHON_VERSION=3.10.*

In a project.toml

[build]
  [[build.env]]
    name = 'BP_CPYTHON_VERSION'
    value = '3.10.*' # any valid semver constraints (e.g. 3.10.2, 3.*) are acceptable

BP_CPYTHON_RM_SETUPTOOLS

The BP_CPYTHON_RM_SETUPTOOLS flag when set instructs the buildpack to remove setuptools from the version of Python that is installed. The bundled setuptools version is often old and may be flagged by scanners as vulnerable to CVEs.

You may set this environment variable to true, or any value, and the buildpack will then remove setuptools from the app image when it runs.

Please note that the actual value of this flag does not matter. The buildpack only checks that it is set. If you do not want to trigger this behavior, then you need to unset the environment variable. Setting it to false will not do anything.

BP_CPYTHON_CONFIGURE_FLAGS

The BP_CPYTHON_CONFIGURE_FLAGS variable allows you to specify configure flags when python is installed from source. This is only applicable when using custom stacks. Paketo stacks such as io.buildpacks.stacks.jammy install pre-built binaries.

• The format is space-separated strings, and they are passed directly to the cpython ./configure process , e.g. --foo --bar=baz.
• See python documentation for supported flags.
• Default flags if not specified: --with-ensurepip
• Note that default flags are overridden if you specify this environment variable, which means you almost certainly want to include the defaults along with any custom flags.
  • e.g. --with-ensurepip --foo --bar=baz

BP_LOG_LEVEL

The BP_LOG_LEVEL flag controls the level of verbosity of the buildpack output logs. For more detail, set it to debug.

For example, when compiling from source, setting BP_LOG_LEVEL=debug shows the commands and outputs run to build python.

Integration

The CPython Buildpack provides cpython as a dependency. Downstream buildpacks, can require the cpython dependency by generating Build Plan TOML file that looks like the following:

[[requires]]
  # The name of the CPython dependency is "cpython". This value is considered
  # part of the public API for the buildpack and will not change without a plan
  # for deprecation.
  name = "cpython"

  # The CPython buildpack supports some non-required metadata options.
  [requires.metadata]

    # The version of the CPython dependency is not required. In the case it
    # is not specified, the buildpack will provide the default version, which can
    # be seen in the buildpack.toml file.
    # If you wish to request a specific version, the buildpack supports
    # specifying a semver constraint in the form of "3.*", "3.10.*", or even
    # "3.10.2".
    version = "3.10.2"

    # Setting the build flag to true will ensure that the CPython
    # depdendency is available on the $PATH for subsequent buildpacks during
    # their build phase. If you are writing a buildpack that needs to use CPython
    # during its build process, this flag should be set to true.
    build = true

    # Setting the launch flag to true will ensure that cpython is
    # available to the running application. If you are writing an application
    # that needs to run cpython at runtime, this flag should be set to true.
    launch = true

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh --version <version-number>

This will create a buildpackage.cnb file under the build directory which you can use to build your app as follows: pack build <app-name> -p <path-to-app> -b build/buildpackage.cnb -b <other-buildpacks..>

To run the unit and integration tests for this buildpack:

$ ./scripts/unit.sh && ./scripts/integration.sh

Compatibility

This buildpack is currently only supported on linux distributions.

Pre-compiled distributions of Python are provided for the Paketo stacks (i.e. io.buildpacks.stack.jammy and io.buildpacks.stacks.noble).

Source distributions of Python are provided for all other linux stacks.