Configuration

Bork is configured using pyproject.toml.

Build System/Backend

You always need to specify the [build-system] table. This should be configured according to the build backend you’re using.

If you are not using Bork to create ZipApps, this should be the only configuration that Bork requires. The build system (aka “backend”) you use will likely want at least project.name and project.version or equivalent. See “Recommended pyproject.toml Configuration” below.

Python Packaging User Guide: Writing your pyproject.toml explains this well if you’re using Hatchling, Setuptools, Flit, or PDM. The information for Hatchling and Setuptool are also included below.

For Setuptools, this looks like:

[build-system]
requires = ["setuptools >= 61", "wheel"]
build-backend = "setuptools.build_meta"

If you are working on an existing Setuptools project with setup.py or setup.cfg, creating a pyproject.toml file with those contents should be enough to start using Bork and other PEP 517-compliant frontends.

For Hatchling it looks like:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Recommended pyproject.toml Configuration

In addition to the [build-system] configuration, it is recommended to include at least project.name and project.version (or equivalent). Some systems (e.g. Poetry) require the values to be specified in a different way.

If you wish to have these values defined in pyproject.toml directly, it will look like this:

[project]
name = "some-project-name"
version = "0.0.1"

For more advanced configurations, check Python Packaging User Guide: Writing your pyproject.toml or open a GitHub Discussion for Bork.

ZipApps

To have Bork build a ZipApp, you need the entire recommended configuration described above.

You also need to:

enable ZipApp functionality
specify the main function/entrypoint.

For Emanate, which has the ZipApp call the emanate.cli.main() function, this looks like:

[tool.bork.zipapp]
enabled = true
main = "emanate.cli:main"

Releasing to PyPi and GitHub

Configuring the release process for Bork happens in the [tool.bork.release] table in pyproject.toml.

As an example, Bork releases itself on PyPi and GitHub, and uses this configuration:

[tool.bork.release]
pypi = true
github = true
github_repository = "duckinator/bork"
strip_zipapp_version = true

Here’s what each option does:

pypi: If true, release to PyPi using the project name reported by the build system.
github: If true, release to GitHub using the specified github_repository.
github_repository: The name of the GitHub repository to publish releases to.
strip_zipapp_version: If true, remove the version number from the ZipApp name.

Setting strip_zipapp_version to true is recommended, because it means the latest ZipApp is always available at the same URL.

For Bork, this URL is: https://github.com/duckinator/bork/releases/latest/download/bork.pyz

You can provide a template for GitHub Releases by providing a GitHub Release Template.

Aliases

Aliases can be configured in the [tool.bork.aliases] section of pyproject.toml.

Each alias can be either a string (one command) or a list of strings (multiple commands, ran one at a time, stopping if any of them fail).

An example configuration (if your code is in a directory named example-project) might look something like this:

[tool.bork.aliases]
lint = [
    "pylint example-project tests",
    "mypy example-project",
]
test = "pytest --verbose"