Skip to main content

A PEP 517 backend for PDM that supports PEP 621 metadata

Project description

PDM-PEP517

Yet another PEP 517 backend.

PyPI Tests pre-commit.ci status pdm-managed

This is the backend for PDM projects, while you can also use it alone. It reads the metadata of PEP 621 format and coverts it to Core metadata.

Use as PEP 517 build backend

Edit your pyproject.toml as follows:

[build-system]
requires = ["pdm-pep517"]
build-backend = "pdm.pep517.api"

Tool specific settings

Besides of the standard fields specified in PEP 621, PDM-PEP517 honors some other settings to change the build behavior. They should be defined under [tool.pdm.build] table:

[tool.pdm.build]
# Specify where the Python packages live.
package-dir = "src"
# File patterns to include, the paths are relative to the project root.
includes = []
# File patterns to exclude, the paths are relative to the project root.
excludes = []
# File patterns to include in source distribution and exclude in wheel distribution.
source-includes = []
# An extra script to populate the arguments of `setup()`, one can build C extensions with this script. Or a custom build() function to generate files.
setup-script = "build.py"
# If true, the setup-script will run in a generated `setup.py` file.
run-setuptools = false
# Override the Is-Purelib value in the wheel.
is-purelib = true
# Change the editable-backend: path(default) or editables
editable-backend = "editables"

You don't have to specify all of them, PDM-PEP517 can also derive these fields smartly, based on some best practices of Python packaging.

Dynamic project version

pdm-pep517 can also determine the version of the project dynamically. To do this, you need to leave the version field out from your pyproject.toml and add dynamic = ["version"]:

[project]
...
- version = "0.1.0" remove this line
+ dynamic = ["version"]

Then in [tool.pdm.version] table, specify how to get the version info. There are two ways supported:

  1. Read from a static string in the given file path:
[tool.pdm.version]
source = "file"
path = "mypackage/__init__.py"

In this way, the file MUST contain a line like:

__version__ = "0.1.0" # Single quotes and double quotes are both OK, comments are allowed.
  1. Read from SCM tag, supporting git and hg:
[tool.pdm.version]
source = "scm"

When building from a source tree where SCM is not available, you can use the env var PDM_PEP517_SCM_VERSION to pretend the version is set.

PDM_PEP517_VERSION=0.1.0 python -m build

Writing SCM version to file

You can instruct PDM-PEP517 to write back the dynamic version fetched from SCM to a file:

[tool.pdm.version]
source = "scm"
write_to = "foo/version.txt"

By default, PDM-PEP517 will just write the SCM version itself. You can provide a template as a Python-formatted string to create a syntactically correct Python assignment:

[tool.pdm.version]
source = "scm"
write_to = "foo/_version.py"
write_template = "__version__ = '{}'"

Note that PDM-PEP517 will rewrite the whole file each time, so you can't have additional contents in that file.

Custom Build Script

With custom build script, you can call other tools to generates files to be included in the wheel. Just set the setup-script field under [tool.pdm.build] table to the path of the script.

In the script, you expose a function named build, which takes two arguments:

  • src(str): the path of the source directory
  • dst(str): the path of the destination directory

Example:

def build(src, dst):
    with open(os.path.join(dst, "myfile.txt"), "w") as f:
        # Put a file in the wheel
        f.write("Hello World!")

Note that the generated file hierarchy will be preserved in the wheel: $dst/myfile.txt -> $wheel_root/myfile.txt.

When run-setuptools is true, the build function will be called in a generated setup.py file, with the setup parameters as the only argument.

Example:

def build(setup_params):
    # add ext_modules to the setup() arguments
    setup_parms.update(ext_modules=[Extension("myextension", ["myextension.c"])])

The will result in a setup() call like following:

setup(
    name="mypackage",
    # Other metadata fields
    ext_modules=[Extension("myextension", ["myextension.c"])],
)

By default, when setup-script is set, the resulted wheel will be platform-specific, but you can override this behavior by setting is-purelib to false

Supported config settings

pdm-pep517 allows passing config_settings to modify the build behavior. It use the same option convention as python setup.py bdist_wheel.

--python-tag
    Override the python implementation compatibility tag(e.g. cp37, py3, pp3)
--py-limited-api
    Python tag (cp32|cp33|cpNN) for abi3 wheel tag
--plat-name
    Override the platform name(e.g. win_amd64, manylinux2010_x86_64)

For example, you can supply these options with build:

python -m build --sdist --wheel --outdir dist/ --config-setting="--python-tag=cp37" --config-setting="--plat-name=win_amd64"

pip doesn't support passing config_settings yet, please stick to build as the recommended frontend.

License

This project is licensed under MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pdm-pep517-1.0.4.tar.gz (295.1 kB view details)

Uploaded Source

Built Distribution

pdm_pep517-1.0.4-py3-none-any.whl (305.9 kB view details)

Uploaded Python 3

File details

Details for the file pdm-pep517-1.0.4.tar.gz.

File metadata

  • Download URL: pdm-pep517-1.0.4.tar.gz
  • Upload date:
  • Size: 295.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.13

File hashes

Hashes for pdm-pep517-1.0.4.tar.gz
Algorithm Hash digest
SHA256 392f8c2b47c6ec20550cb8e19e24b9dbd27373413f067b56ecd75f9767f93015
MD5 82e3158434f45d7301f858c33ff90e91
BLAKE2b-256 8a8f799f7b88c1333115db197dfc0ea3c3a7d57f1b9fb7d9f9151a92ebd2d2d6

See more details on using hashes here.

Provenance

File details

Details for the file pdm_pep517-1.0.4-py3-none-any.whl.

File metadata

  • Download URL: pdm_pep517-1.0.4-py3-none-any.whl
  • Upload date:
  • Size: 305.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.13

File hashes

Hashes for pdm_pep517-1.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 8fd42caeaa2031a41d86bce6519ad96edaf1dfc99cf0c2b6d310d1ae2089bb39
MD5 4cf57cfa274c67d82099db81a4abf9bc
BLAKE2b-256 32561d4b069d8c406ba85ef2992a56f6780de6f8e76fef98af7d291138c4221e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page