pip

README

PIP Cloud Native Buildpack

The Paketo Buildpack for Pip is a Cloud Native Buildpack that installs pip into a layer and places it on the PATH.

The buildpack is published for consumption at gcr.io/paketo-buildpacks/pip and paketobuildpacks/pip.

Behavior

This buildpack always participates.

The buildpack will do the following:

• At build time:
  • Contributes the pip binary to a layer
  • Prepends the pip layer to the PYTHONPATH
  • Adds the newly installed pip location to PATH
• At run time:
  • Does nothing

Configuration

Environment Variable	Description
$BP_PIP_VERSION	Configure the version of pip to install. Buildpack releases (and the pip versions for each release) can be found here.

Note that Pip releases are of the form X.Y instead of X.Y.0, so providing X.Y will attempt to match that exact version. Providing X.Y.Z will select the exact patch version, and providing X.Y.* or ~X.Y will select the latest patch version.

Integration

The Pip CNB provides pip as a dependency. Downstream buildpacks can require the pip dependency by generating a Build Plan TOML file that looks like the following:

[[requires]]

  # The name of the Pip dependency is "pip". This value is considered
  # part of the public API for the buildpack and will not change without a plan
  # for deprecation.
  name = "pip"

  # The version of the Pip dependency is not required. In the case it
  # is not specified, the buildpack will select the latest supported version in
  # the buildpack.toml.
  # If you wish to request a specific version, the buildpack supports
  # specifying a semver constraint in the form of "21.*", "21.0.*", or even
  # "21.0.1".
  version = "21.0.1"

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

    # Setting the build flag to true will ensure that the Pip dependency is
    # available on the $PATH, and the $PYTHONPATH contains the path to pip for
    # subsequent buildpacks during their build phase. If you are writing a
    # buildpack that needs to run Pip during its build process, this flag should
    # be set to true.
    build = true

    # Setting the launch flag to true will ensure that the Pip
    # dependency is available on the $PATH, and the $PYTHONPATH contains the
    # path to pip for the running application. If you are writing an
    # application that needs to run Pip at runtime, this flag should be set to
    # true.
    launch = true

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh --version x.x.x

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

Documentation

Index

• Constants
• Variables
• func Build(dependencies DependencyManager, installProcess InstallProcess, ...) packit.BuildFunc
• func Detect() packit.DetectFunc
• type BuildPlanMetadata
• type DependencyManager
• type Executable
• type InstallProcess
• type PipInstallProcess
  • func NewPipInstallProcess(executable Executable) PipInstallProcess
  • func (p PipInstallProcess) Execute(srcPath, targetLayerPath string) error
• type SBOMGenerator
• type SitePackageProcess
• type SiteProcess
  • func NewSiteProcess(executable Executable) SiteProcess
  • func (p SiteProcess) Execute(targetLayerPath string) (string, error)

Constants

const CPython = "cpython"

CPython is the name of the python runtime dependency provided by the CPython buildpack: https://github.com/paketo-buildpacks/cpython

const DependencyChecksumKey = "dependency_checksum"

DependencyChecksumKey is the name of the key in the pip layer TOML whose value is pip dependency's SHA256.

const Pip = "pip"

Pip is the name of the layer into which pip dependency is installed.

const PipSrc = "pip-source"

Variables

var Priorities = []interface{}{"BP_PIP_VERSION"}

Priorities is a list of possible places where the buildpack could look for a specific version of Pip to install, ordered from highest to lowest priority.

Functions

func Build

func Build(
	dependencies DependencyManager,
	installProcess InstallProcess,
	siteProcess SitePackageProcess,
	sbomGenerator SBOMGenerator,
	logger scribe.Emitter,
	clock chronos.Clock,
) packit.BuildFunc

Build will return a packit.BuildFunc that will be invoked during the build phase of the buildpack lifecycle.

Build will find the right pip dependency to install, install it in a layer, and generate Bill-of-Materials. It also makes use of the checksum of the dependency to reuse the layer when possible.

func Detect

func Detect() packit.DetectFunc

Detect will return a packit.DetectFunc that will be invoked during the detect phase of the buildpack lifecycle.

Detection always passes, and will contribute a Build Plan that provides pip, and requires cpython OR python, python_packages, and requirements.

If a version is provided via the $BP_PIP_VERSION environment variable, that version of pip will be a requirement.

Types

type BuildPlanMetadata

type BuildPlanMetadata struct {
	// Build denotes the dependency is needed at build-time.
	Build bool `toml:"build"`

	// Launch denotes the dependency is needed at runtime.
	Launch bool `toml:"launch"`

	// Version denotes the version of a dependency, if there is one.
	Version string `toml:"version"`

	// VersionSource denotes where dependency version came from (e.g. an environment variable).
	VersionSource string `toml:"version-source"`
}

BuildPlanMetadata is the buildpack specific data included in build plan requirements.

type DependencyManager

type DependencyManager interface {
	Resolve(path, id, version, stack string) (postal.Dependency, error)
	Deliver(dependency postal.Dependency, cnbPath, destinationPath, platformPath string) error
	GenerateBillOfMaterials(dependencies ...postal.Dependency) []packit.BOMEntry
}

DependencyManager defines the interface for picking the best matching dependency and installing it.

type Executable

type Executable interface {
	Execute(pexec.Execution) error
}

Executable defines the interface for invoking an executable.

type InstallProcess

type InstallProcess interface {
	Execute(srcPath, targetLayerPath string) error
}

InstallProcess defines the interface for installing the pip dependency into a layer.

type PipInstallProcess

type PipInstallProcess struct {
	// contains filtered or unexported fields
}

PipInstallProcess implements the InstallProcess interface.

func NewPipInstallProcess

func NewPipInstallProcess(executable Executable) PipInstallProcess

NewPipInstallProcess creates an instance of the PipInstallProcess given an Executable that runs `python`.

func (PipInstallProcess) Execute

func (p PipInstallProcess) Execute(srcPath, targetLayerPath string) error

Execute installs the pip binary from source code located in the given srcPath into the a layer path designated by targetLayerPath.

type SBOMGenerator

type SBOMGenerator interface {
	GenerateFromDependency(dependency postal.Dependency, dir string) (sbom.SBOM, error)
}

type SitePackageProcess

type SitePackageProcess interface {
	Execute(targetLayerPath string) (string, error)
}

SitePackageProcess defines the interface for looking site packages within a layer.

type SiteProcess

type SiteProcess struct {
	// contains filtered or unexported fields
}

SiteProcess implements the Executable interface.

func NewSiteProcess

func NewSiteProcess(executable Executable) SiteProcess

NewSiteProcess creates an instance of the SiteProcess given an Executable that runs `python`

func (SiteProcess) Execute

func (p SiteProcess) Execute(targetLayerPath string) (string, error)

Execute runs a python command to locate the site packages within the pip targetLayerPath.