poetryrun

README

Poetry Run Cloud Native Buildpack

gcr.io/paketo-buildpacks/poetry-run

The Paketo Poetry Run CNB sets the start command for a given poetry application.

This buildpack detects when one of the following conditions is met:

1. BP_POETRY_RUN_TARGET is set

Example: BP_POETRY_RUN_TARGET=default_app.server:run. The resulting start command for this example would be poetry run default_app.server:run.

1. pyproject.toml exists and contains exactly one poetry script

More specifically, the buildpack will detect if pyproject.toml looks like the following:

[tool.poetry.scripts]
some-script = "some.module:some_method"

The resulting start command for this example would be poetry run some-script.

See the poetry run documentation for more information.

Integration

This buildpacks writes a start command, so currently there is no conceivable reason to require it as a dependency.

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 <path/to/cpython.cnb> \
  -b <path/to/pip.cnb> \
  -b <path/to/poetry.cnb> \
  -b <path/to/poetry-install.cnb> \
  -b build/buildpackage.cnb

Configuration

Custom run command

This buildpack will set a start command that begins with poetry run. This can be set using BP_POETRY_RUN_TARGET and can reference either a script key from pyproject.toml or an executable on the file system. See the poetry run documentation for more information.

Enabling reloadable process types

You can configure this buildpack to wrap the entrypoint process of your app such that it kills and restarts the process whenever files change in the app's working directory in the container. With this feature enabled, copying new versions of source code into the running container will trigger your app's process to restart. Set the environment variable BP_LIVE_RELOAD_ENABLED=true at build time to enable this feature.

Run Tests

To run all unit tests, run:

./scripts/unit.sh

To run all integration tests, run:

/scripts/integration.sh

Known issues and limitations

• When BP_POETRY_RUN_TARGET is not set, only one (and exactly one) script may be defined in the pyproject.toml file. Zero scripts, or multiple scripts, will result in the buildpack failing detection and therefore not participating in the order group.

Documentation

Index

• Constants
• func Build(pyProjectParser PyProjectParser, logger scribe.Emitter, reloader Reloader) packit.BuildFunc
• func Detect(pyProjectParser PyProjectParser, reloader Reloader) packit.DetectFunc
• type BuildPlanMetadata
• type PyProjectConfig
• type PyProjectConfigParser
  • func NewPyProjectConfigParser() PyProjectConfigParser
  • func (p PyProjectConfigParser) Parse(filepath string) (string, error)
• type PyProjectParser
• type Reloader

Constants

const CPython = "cpython"

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

const CacheLayerName = "cache"

CacheLayerName holds the poetry cache.

const Poetry = "poetry"

Poetry is the name of the dependency provided by the Poetry buildpack: https://github.com/initializ-buildpacks/poetry.

const PoetryVenv = "poetry-venv"

PoetryVenv is the name of the dependency provided by the Poetry Install buildpack.

const VenvLayerName = "poetry-venv"

VenvLayerName is the name of the layer where the venv dependencies are installed to.

const Watchexec = "watchexec"

Watchexec is the name of the dependency provided by the Watchexec buildpack: https://github.com/initializ-buildpacks/watchexec

Functions

func Build

func Build(pyProjectParser PyProjectParser, logger scribe.Emitter, reloader Reloader) packit.BuildFunc

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

Build assigns the image a launch process of 'poetry run <target>' where <target> is the key of a poetry script or system executable. This can be set via `BP_POETRY_RUN_TARGET` or inferred from pyproject.toml when there is exactly one script.

func Detect

func Detect(pyProjectParser PyProjectParser, reloader Reloader) 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.

Detection is contingent on there being one or more scripts to run defined in the pyproject.toml under [tool.poetry.scripts]

Types

type BuildPlanMetadata

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

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

type PyProjectConfig

type PyProjectConfig struct {
	Tool struct {
		Poetry struct {
			Scripts map[string]string `toml:"scripts"`
		} `toml:"poetry"`
	} `toml:"tool"`
}

type PyProjectConfigParser

type PyProjectConfigParser struct {
}

func NewPyProjectConfigParser

func NewPyProjectConfigParser() PyProjectConfigParser

func (PyProjectConfigParser) Parse

func (p PyProjectConfigParser) Parse(filepath string) (string, error)

Parse returns the name of the script for Poetry to execute If there is no file, no script to run, or multiple scripts to run, Parse returns an empty string and a nil error If there is an error reading the file, Parse returns an error

type PyProjectParser

type PyProjectParser interface {
	Parse(string) (string, error)
}

type Reloader

type Reloader libreload.Reloader