Skip to content

Latest commit

 

History

History
137 lines (91 loc) · 4.14 KB

config.rst

File metadata and controls

137 lines (91 loc) · 4.14 KB
Raw

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"