pipinstall

README

Pip Install Cloud Native Buildpack

The Paketo Buildpack for Pip Install is a Cloud Native Buildpack that installs packages using pip and makes it available to the application.

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

Behavior

This buildpack participates if requirements.txt exists at the root the app.

The buildpack will do the following:

• At build time:
  • Installs the application packages to a layer made available to the app.
  • Prepends the layer site-packages onto PYTHONPATH.
  • If a vendor directory is available, will attempt to run pip install in an offline manner.
• At run time:
  • Does nothing

Integration

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

[[requires]]

  # The name of the dependency provided by the Pip Install Buildpack is
  # "site-packages". This value is considered part of the public API for the
  # buildpack and will not change without a plan for deprecation.
  name = "site-packages"

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

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

    # Setting the launch flag to true will ensure that the site-packages
    # dependency is available on the $PYTHONPATH for the running
    # application. If you are writing an application that needs site-packages
    # 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 <cpython buildpack> -b <pip buildpack> -b build/buildpackage.cnb -b <other-buildpacks..>.

To run the unit and integration tests for this buildpack:

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

Configuration

BP_PIP_DEST_PATH

The BP_PIP_DEST_PATH variable allows you to specify a custom vendor directory. This should be a directory underneath the working directory. Will use ./vendor if not provided.

BP_PIP_DEST_PATH=my/custom/vendor-dir

BP_PIP_REQUIREMENT

The BP_PIP_REQUIREMENT variable allows you to specify a custom pip requirement path. This should be a file underneath the working directory. Will use ./requirements.txt if not provided.

BP_PIP_REQUIREMENT=requirements-dev.txt

BP_PIP_FIND_LINKS

The BP_PIP_FIND_LINKS variable allows you to specify one or more directories to pass to --find-links. This should be a local path or file:// URL.

BP_PIP_FIND_LINKS=./vendor-dir

PIP_<UPPER_LONG_NAME>

It is worth noting that the PIP_<UPPER_LONG_NAME> configuration is respected by this buildpack and can be used to tweak the build time CLI properties for Pip as documented in Pip's configuration.

Documentation

Index

• Constants
• func Build(installProcess InstallProcess, siteProcess SitePackagesProcess, ...) packit.BuildFunc
• func Detect() packit.DetectFunc
• type BuildPlanMetadata
• type EntryResolver
• type Executable
• type InstallProcess
• type PipInstallProcess
  • func NewPipInstallProcess(executable Executable, logger scribe.Emitter) PipInstallProcess
  • func (p PipInstallProcess) Execute(workingDir, targetPath, cachePath string) error
• type SBOMGenerator
• type SitePackagesProcess
• type SiteProcess
  • func NewSiteProcess(executable Executable) SiteProcess
  • func (p SiteProcess) Execute(layerPath 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 CacheLayerName = "cache"

The layer name for cache layer. This layer holds the pip cache.

const PackagesLayerName = "packages"

The layer name for packages layer. This layer is where dependencies are installed to.

const Pip = "pip"

Pip is the name of the dependency provided by the Pip buildpack: https://github.com/paketo-buildpacks/pip.

const SitePackages = "site-packages"

SitePackages is the name of the dependency provided by the Pip Install buildpack.

Functions

func Build

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

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

Build will install the pip dependencies by using the requirements.txt file to a packages layer. It also makes use of a cache layer to reuse the pip cache.

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 will contribute a Build Plan that provides site-packages, and requires cpython and pip at build.

Types

type BuildPlanMetadata

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

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

type EntryResolver

type EntryResolver interface {
	MergeLayerTypes(name string, entries []packit.BuildpackPlanEntry) (launch, build bool)
}

EntryResolver defines the interface for picking the most relevant entry from the Buildpack Plan entries.

type Executable

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

Executable defines the interface for invoking an executable.

type InstallProcess

type InstallProcess interface {
	Execute(workingDir, targetDir, cacheDir string) error
}

InstallProcess defines the interface for installing the pip dependencies.

type PipInstallProcess

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

PipInstallProcess implements the InstallProcess interface.

func NewPipInstallProcess

func NewPipInstallProcess(executable Executable, logger scribe.Emitter) PipInstallProcess

NewPipInstallProcess creates an instance of the PipInstallProcess given an Executable.

func (PipInstallProcess) Execute

func (p PipInstallProcess) Execute(workingDir, targetPath, cachePath string) error

Execute installs the pip dependencies from workingDir/requirements.txt into the targetPath. The cachePath is used for the pip cache directory.

The pip install command will install from local packages if they are found at the directory specified by `BP_PIP_DEST_PATH`, which defaults to `vendor`.

type SBOMGenerator

type SBOMGenerator interface {
	Generate(dir string) (sbom.SBOM, error)
}

type SitePackagesProcess

type SitePackagesProcess interface {
	Execute(layerPath string) (sitePackagesPath string, err error)
}

SitePackagesProcess defines the interface for determining the site-packages path.

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(layerPath string) (string, error)

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