| Name | pdm-pep517 JSON |
| Version |
1.1.3
JSON |
| download |
| home_page | |
| Summary | A PEP 517 backend for PDM that supports PEP 621 metadata |
| upload_time | 2023-03-23 05:03:29 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
packaging
pep 517
build
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PDM-PEP517
**This project has been renamed and re-published as [pdm-backend](https://pypi.org/project/pdm-backend)**
Yet another [PEP 517][1] backend.
[](https://pypi.org/project/pdm-pep517)
[](https://github.com/pdm-project/pdm-pep517/actions/workflows/ci.yml)
[](https://results.pre-commit.ci/latest/github/pdm-project/pdm-pep517/master)
[](https://pdm.fming.dev)
This is the backend for [PDM](https://pdm.fming.dev) projects, while you can also use it alone.
It reads the metadata of [PEP 621][2] format and coverts it to [Core metadata][3].
[1]: https://www.python.org/dev/peps/pep-0517/
[2]: https://www.python.org/dev/peps/pep-0621/
[3]: https://packaging.python.org/specifications/core-metadata/
## Use as PEP 517 build backend
Edit your `pyproject.toml` as follows:
```toml
[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:
```toml
[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"]`:
```diff
[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:
```toml
[tool.pdm.version]
source = "file"
path = "mypackage/__init__.py"
```
In this way, the file MUST contain a line like:
```python
__version__ = "0.1.0" # Single quotes and double quotes are both OK, comments are allowed.
```
2. Read from SCM tag, supporting `git` and `hg`:
```toml
[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.
```bash
PDM_PEP517_SCM_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:
```toml
[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:
```toml
[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:
```python
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:
```python
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:
```python
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](https://pypi.org/project/build/):
```bash
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](/LICENSE).
Raw data
{
"_id": null,
"home_page": "",
"name": "pdm-pep517",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "packaging,PEP 517,build",
"author": "",
"author_email": "Frost Ming <mianghong@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d6/d7/bee6e16a0a5e93f38f2f8224183ea6c36cfde1ee93cf5e941f1d6cdb20cf/pdm-pep517-1.1.3.tar.gz",
"platform": null,
"description": "# PDM-PEP517\n\n**This project has been renamed and re-published as [pdm-backend](https://pypi.org/project/pdm-backend)**\n\nYet another [PEP 517][1] backend.\n\n[](https://pypi.org/project/pdm-pep517)\n[](https://github.com/pdm-project/pdm-pep517/actions/workflows/ci.yml)\n[](https://results.pre-commit.ci/latest/github/pdm-project/pdm-pep517/master)\n[](https://pdm.fming.dev)\n\nThis is the backend for [PDM](https://pdm.fming.dev) projects, while you can also use it alone.\nIt reads the metadata of [PEP 621][2] format and coverts it to [Core metadata][3].\n\n[1]: https://www.python.org/dev/peps/pep-0517/\n[2]: https://www.python.org/dev/peps/pep-0621/\n[3]: https://packaging.python.org/specifications/core-metadata/\n\n## Use as PEP 517 build backend\n\nEdit your `pyproject.toml` as follows:\n\n```toml\n[build-system]\nrequires = [\"pdm-pep517\"]\nbuild-backend = \"pdm.pep517.api\"\n```\n\n## Tool specific settings\n\nBesides 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:\n\n```toml\n[tool.pdm.build]\n# Specify where the Python packages live.\npackage-dir = \"src\"\n# File patterns to include, the paths are relative to the project root.\nincludes = []\n# File patterns to exclude, the paths are relative to the project root.\nexcludes = []\n# File patterns to include in source distribution and exclude in wheel distribution.\nsource-includes = []\n# 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.\nsetup-script = \"build.py\"\n# If true, the setup-script will run in a generated `setup.py` file.\nrun-setuptools = false\n# Override the Is-Purelib value in the wheel.\nis-purelib = true\n# Change the editable-backend: path(default) or editables\neditable-backend = \"editables\"\n```\n\nYou don't have to specify all of them, PDM-PEP517 can also derive these fields smartly, based on some best practices of Python packaging.\n\n## Dynamic project version\n\n`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\"]`:\n\n```diff\n[project]\n...\n- version = \"0.1.0\" remove this line\n+ dynamic = [\"version\"]\n```\n\nThen in `[tool.pdm.version]` table, specify how to get the version info. There are two ways supported:\n\n1. Read from a static string in the given file path:\n\n```toml\n[tool.pdm.version]\nsource = \"file\"\npath = \"mypackage/__init__.py\"\n```\n\nIn this way, the file MUST contain a line like:\n\n```python\n__version__ = \"0.1.0\" # Single quotes and double quotes are both OK, comments are allowed.\n```\n\n2. Read from SCM tag, supporting `git` and `hg`:\n\n```toml\n[tool.pdm.version]\nsource = \"scm\"\n```\n\nWhen 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.\n\n```bash\nPDM_PEP517_SCM_VERSION=0.1.0 python -m build\n```\n\n## Writing SCM version to file\n\nYou can instruct PDM-PEP517 to write back the dynamic version fetched from SCM to a file:\n\n```toml\n[tool.pdm.version]\nsource = \"scm\"\nwrite_to = \"foo/version.txt\"\n```\n\nBy default, PDM-PEP517 will just write the SCM version itself.\nYou can provide a template as a Python-formatted string to create a syntactically correct Python assignment:\n\n```toml\n[tool.pdm.version]\nsource = \"scm\"\nwrite_to = \"foo/_version.py\"\nwrite_template = \"__version__ = '{}'\"\n```\n\nNote that PDM-PEP517 will rewrite the whole file each time, so you can't have additional contents in that file.\n\n## Custom Build Script\n\nWith custom build script, you can call other tools to generates files to be included in the wheel.\nJust set the `setup-script` field under `[tool.pdm.build]` table to the path of the script.\n\nIn the script, you expose a function named `build`, which takes two arguments:\n\n- `src`(str): the path of the source directory\n- `dst`(str): the path of the destination directory\n\nExample:\n\n```python\n\ndef build(src, dst):\n with open(os.path.join(dst, \"myfile.txt\"), \"w\") as f:\n # Put a file in the wheel\n f.write(\"Hello World!\")\n```\nNote that the generated file hierarchy will be preserved in the wheel: `$dst/myfile.txt` -> `$wheel_root/myfile.txt`.\n\nWhen `run-setuptools` is `true`, the `build` function will be called in a generated `setup.py` file, with the setup parameters as the only argument.\n\nExample:\n\n```python\n\ndef build(setup_params):\n # add ext_modules to the setup() arguments\n setup_parms.update(ext_modules=[Extension(\"myextension\", [\"myextension.c\"])])\n```\n\nThe will result in a `setup()` call like following:\n\n```python\nsetup(\n name=\"mypackage\",\n # Other metadata fields\n ext_modules=[Extension(\"myextension\", [\"myextension.c\"])],\n)\n```\n\n**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`**\n\n## Supported config settings\n\n`pdm-pep517` allows passing `config_settings` to modify the build behavior. It use the same option convention as `python setup.py bdist_wheel`.\n\n```\n--python-tag\n Override the python implementation compatibility tag(e.g. cp37, py3, pp3)\n--py-limited-api\n Python tag (cp32|cp33|cpNN) for abi3 wheel tag\n--plat-name\n Override the platform name(e.g. win_amd64, manylinux2010_x86_64)\n```\n\nFor example, you can supply these options with [build](https://pypi.org/project/build/):\n\n```bash\npython -m build --sdist --wheel --outdir dist/ --config-setting=\"--python-tag=cp37\" --config-setting=\"--plat-name=win_amd64\"\n```\n\n`pip` doesn't support passing `config_settings` yet, please stick to `build` as the recommended frontend.\n\n## License\n\nThis project is licensed under [MIT license](/LICENSE).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A PEP 517 backend for PDM that supports PEP 621 metadata",
"version": "1.1.3",
"split_keywords": [
"packaging",
"pep 517",
"build"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b9f8906d917365ace0175d579831982a71f0590cf126f39dfd8fd96ec3422fe",
"md5": "6c2c9e6ac3a920665054fc5a6ce59504",
"sha256": "b2999e66ea55711f248f4d5f2e759bdb4ec06008d015102c7e0fdc589c816e3b"
},
"downloads": -1,
"filename": "pdm_pep517-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c2c9e6ac3a920665054fc5a6ce59504",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 216355,
"upload_time": "2023-03-23T05:03:27",
"upload_time_iso_8601": "2023-03-23T05:03:27.450296Z",
"url": "https://files.pythonhosted.org/packages/7b/9f/8906d917365ace0175d579831982a71f0590cf126f39dfd8fd96ec3422fe/pdm_pep517-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6d7bee6e16a0a5e93f38f2f8224183ea6c36cfde1ee93cf5e941f1d6cdb20cf",
"md5": "a9fe9e77bf9eee69cda44fbc1437a13b",
"sha256": "761177e8a49e54bd126ed21da2cb91531aacf47a5027cb704e7461eed6685d03"
},
"downloads": -1,
"filename": "pdm-pep517-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "a9fe9e77bf9eee69cda44fbc1437a13b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 211651,
"upload_time": "2023-03-23T05:03:29",
"upload_time_iso_8601": "2023-03-23T05:03:29.251897Z",
"url": "https://files.pythonhosted.org/packages/d6/d7/bee6e16a0a5e93f38f2f8224183ea6c36cfde1ee93cf5e941f1d6cdb20cf/pdm-pep517-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 05:03:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pdm-pep517"
}
