| Name | hwh-backend JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Setuptools based backend supporting Cython extensions |
| upload_time | 2025-01-27 01:32:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
cython
build
backend
pep517
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Halfway House backend
[](https://github.com/mkgessen/hwh-backend/actions/workflows/python-publish.yml)
Provides [PEP-517](https://peps.python.org/pep-0517/) build hooks for building
Cython extensions with setuptools. Currently supports Cython 0.29.
Ideally similar functionality would be provided an actual setuptools backend.
## Requirements
- CI tests only for `Python 3.11` and `Cython` 0.29.xx at the moment
- your project should have `MANIFEST.in` file defining the `.pyx` files that
should be included
- Currently doesn't support src builds
## Intended use
HWH is intended to be bolt on replacement for projects that build Cython
extensions with setuptools. You should be able to get rid of your `setup.py` and
you don't need to call `python -m setup.py` to build extensions.
### Scenarios that HWH tries to solve
1. Project that has `.pyx` files, but doesn't is not designed to be used by
other projects. Doesn't contain `.pxd` files
2. Project that has `.pyx` and `.pxd` files and plain `.py` files
3. Project that has .`pyx` and `.pxd` files and depends on another project that
looks like #2
- dependency used in both Cython and Python
HWH backend is mainly configured through an additional section in
`pyproject.toml`. The section is entirely optional. The default behaviour is
described in [[tool.hwh.cython]] and [[tool.cython.modules]].
- You can use also use `python -m build --wheel --no-isolation` for wheel
building and recompilation of extensions (editable install)
- HWH currently provides 3 optinal arguments that can be used to control the
build process
- `python -m build --wheel --no-isolation configuration-setting annotate=true
configuration-setting nthreads=10 configuration-setting force=true`
- same arguments can be passes to `pip`, but in that case the format is
slightly different: `pip install -e . --config-settings annote=true`
- **annotate** (bool): build annotation .html files is set true
- nthreads (int): number of threads allocated defaults to `os.cpu_count()`
or 1 in case where cpu count in undefined
- force (bool): force extensions to be rebuilt if set to true
- PIP's verbosity level unfortunately doesn't work in the hooks because I can't
figure out how to implement, but verbosity level can be controlled through
`verbose`
- `pip install --configuration-settings verbose=debug`
- options are: `debug`, `info` and `warning` and they map to the same levels
of the logging facility
HWH backend provides an additional **optional** section to `pyproject.toml`.
Valid options are shown in the example below. If `[tool.hwh]` is absent
### `[tool.hwh.cython]`
- `annotate`: Defines if Cython should build the annotation html files. Valid
values are `true` and `false`. Defaults to `false`
- `language`: extension language (i.e. "c", "c++"). Will be detected from the
source extensions if not provided. Option `objc` is not supported, since I
can't test it.
- `nthreads`: Number of threads to build extensions. Defaults to
`os.cpu_count()` or 1 in case where cpu count in undefined
- `force`: Force build. Valid values are `true` and `false`. Defaults to `false`
### `[tool.hwh.cython.modules]`
Configuration options for all Cython modules.
- `include_dirs`, `runtime_library_dirs` and `library_dirs` are passed to
constructor of `Extension`
- `include_dirs`: list of directories to search for C/C++ header files (in
Unix form for portability)
- `library_dirs`: list of directories to search for C/C++ libraries at link
time. Gets extended by site-packages by default.
- `runtime_library_dirs`: list of directories to search for C/C++ libraries at
run time (for shared extensions, this is when the extension is loaded). Gets
extended by site-packages by default.
- `sources`: list of source filenames, relative to the distribution root. By
default hwh searches for all *.pyx files in all directories within the
distribution root. (=where `pyproject.toml` lives). Accepts wildcards like
`foo/*.pyx`
- `exclude_dirs` list of directories where *.pyx files shouldn't be searched
from. Gets extended by <distribution_root>/build by default. Doesn't have
impact when `sources` is present
- `site_packages`: Defines which site-packages should be used. Allows options
are:
- **purelib** -> use `sysconfig.get_path("purelib")`
- **user** -> use `site.getusersitepackages()`
- **site** -> use `site.getsitepackages()`
- **none** -> you want to explicitly use `library_dirs`, and `include_dirs`
to define what to search for and where from
For more information, see
[Cython docs](https://cython.readthedocs.io/en/0.29.x/src/userguide/source_files_and_compilation.html)
and
[Setup tools extension docs](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html)
### `[tool.hwh.cython.compiler_directives]`
HWH exposes the most of Cython's compiler directives. See
[compiler directives](https://cython.readthedocs.io/en/0.29.x/src/userguide/source_files_and_compilation.html#compiler-directives)
for more information. The `pyproject.toml` example below shows how to use the
compiler options
### Example `pyproject.toml`
```toml pyproject.toml
[build-system]
requires = ["hwh-backend", "Cython<3.0.0"]
build-backend = "hwh_backend.build"
[project]
name = "mylib"
version = "1.0.0"
[tool.hwh.cython.modules]
include_dirs = ["first", "second"]
runtime_library_dirs = ["/usr/lib"]
library_dirs = ["/usr/lib", "/home/user/lib"]
sources = ["foo.pyx", "bar.pyx"]
exclude_dirs = ["this", "that"]
site_packages = "purelib"
[tool.hwh.cython]
# language defaults to C
language="c"
# default = false
annotate=false
# default = os.cpu_count() or 1, if os.cpu_count() returns None
nthreads=1
# default = false
force=false
[tool.hwh.cython.compiler_directives]
# Cython compiler directives
binding = false # Generate Python wrapper functions
boundscheck = false # Array bounds checking
wraparound = false # Negative indexing
initializedcheck = false # Check if extension types are initialized
nonecheck = false # Generate checks for null Python references
overflowcheck = false # Check for C integer overflows
embedsignature = false # Include docstrings in the C code
cdivision = false # Division by zero checking
cdivision_warnings = false # Division by zero warning
profile = false # Enable profiling
linetrace = false # Enable line tracing
type_version_tag = true # Enable CPython's type attribute cache
```
## TODO
- [ ] Allow passing of macros `-D` and extra flags like `-O2`
Raw data
{
"_id": null,
"home_page": null,
"name": "hwh-backend",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cython, build, backend, pep517",
"author": null,
"author_email": "Mathias von Essen <3090690+mkgessen@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/73/f3/c0b1d070f3481e9bae26b4582bbde4f95c47fac2f34d869a5e62e8f49952/hwh_backend-0.2.1.tar.gz",
"platform": null,
"description": "# Halfway House backend\n\n[](https://github.com/mkgessen/hwh-backend/actions/workflows/python-publish.yml)\n\nProvides [PEP-517](https://peps.python.org/pep-0517/) build hooks for building\nCython extensions with setuptools. Currently supports Cython 0.29.\n\nIdeally similar functionality would be provided an actual setuptools backend.\n\n## Requirements\n\n- CI tests only for `Python 3.11` and `Cython` 0.29.xx at the moment\n- your project should have `MANIFEST.in` file defining the `.pyx` files that\n should be included\n- Currently doesn't support src builds\n\n## Intended use\n\nHWH is intended to be bolt on replacement for projects that build Cython\nextensions with setuptools. You should be able to get rid of your `setup.py` and\nyou don't need to call `python -m setup.py` to build extensions.\n\n### Scenarios that HWH tries to solve\n\n1. Project that has `.pyx` files, but doesn't is not designed to be used by\n other projects. Doesn't contain `.pxd` files\n2. Project that has `.pyx` and `.pxd` files and plain `.py` files\n3. Project that has .`pyx` and `.pxd` files and depends on another project that\n looks like #2\n - dependency used in both Cython and Python\n\nHWH backend is mainly configured through an additional section in\n`pyproject.toml`. The section is entirely optional. The default behaviour is\ndescribed in [[tool.hwh.cython]] and [[tool.cython.modules]].\n\n- You can use also use `python -m build --wheel --no-isolation` for wheel\n building and recompilation of extensions (editable install)\n - HWH currently provides 3 optinal arguments that can be used to control the\n build process\n - `python -m build --wheel --no-isolation configuration-setting annotate=true\n configuration-setting nthreads=10 configuration-setting force=true`\n - same arguments can be passes to `pip`, but in that case the format is\n slightly different: `pip install -e . --config-settings annote=true`\n - **annotate** (bool): build annotation .html files is set true\n - nthreads (int): number of threads allocated defaults to `os.cpu_count()`\n or 1 in case where cpu count in undefined\n - force (bool): force extensions to be rebuilt if set to true\n- PIP's verbosity level unfortunately doesn't work in the hooks because I can't\n figure out how to implement, but verbosity level can be controlled through\n `verbose`\n - `pip install --configuration-settings verbose=debug`\n - options are: `debug`, `info` and `warning` and they map to the same levels\n of the logging facility\n\nHWH backend provides an additional **optional** section to `pyproject.toml`.\nValid options are shown in the example below. If `[tool.hwh]` is absent\n\n### `[tool.hwh.cython]`\n\n- `annotate`: Defines if Cython should build the annotation html files. Valid\n values are `true` and `false`. Defaults to `false`\n- `language`: extension language (i.e. \"c\", \"c++\"). Will be detected from the\n source extensions if not provided. Option `objc` is not supported, since I\n can't test it.\n- `nthreads`: Number of threads to build extensions. Defaults to\n `os.cpu_count()` or 1 in case where cpu count in undefined\n- `force`: Force build. Valid values are `true` and `false`. Defaults to `false`\n\n### `[tool.hwh.cython.modules]`\n\nConfiguration options for all Cython modules.\n\n- `include_dirs`, `runtime_library_dirs` and `library_dirs` are passed to\n constructor of `Extension`\n - `include_dirs`: list of directories to search for C/C++ header files (in\n Unix form for portability)\n - `library_dirs`: list of directories to search for C/C++ libraries at link\n time. Gets extended by site-packages by default.\n - `runtime_library_dirs`: list of directories to search for C/C++ libraries at\n run time (for shared extensions, this is when the extension is loaded). Gets\n extended by site-packages by default.\n - `sources`: list of source filenames, relative to the distribution root. By\n default hwh searches for all *.pyx files in all directories within the\n distribution root. (=where `pyproject.toml` lives). Accepts wildcards like\n `foo/*.pyx`\n - `exclude_dirs` list of directories where *.pyx files shouldn't be searched\n from. Gets extended by <distribution_root>/build by default. Doesn't have\n impact when `sources` is present\n - `site_packages`: Defines which site-packages should be used. Allows options\n are:\n - **purelib** -> use `sysconfig.get_path(\"purelib\")`\n - **user** -> use `site.getusersitepackages()`\n - **site** -> use `site.getsitepackages()`\n - **none** -> you want to explicitly use `library_dirs`, and `include_dirs`\n to define what to search for and where from\n\nFor more information, see\n[Cython docs](https://cython.readthedocs.io/en/0.29.x/src/userguide/source_files_and_compilation.html)\nand\n[Setup tools extension docs](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html)\n\n### `[tool.hwh.cython.compiler_directives]`\n\nHWH exposes the most of Cython's compiler directives. See\n[compiler directives](https://cython.readthedocs.io/en/0.29.x/src/userguide/source_files_and_compilation.html#compiler-directives)\nfor more information. The `pyproject.toml` example below shows how to use the\ncompiler options\n\n### Example `pyproject.toml`\n\n```toml pyproject.toml\n[build-system]\nrequires = [\"hwh-backend\", \"Cython<3.0.0\"]\nbuild-backend = \"hwh_backend.build\"\n\n[project]\nname = \"mylib\"\nversion = \"1.0.0\"\n\n[tool.hwh.cython.modules]\n\ninclude_dirs = [\"first\", \"second\"]\nruntime_library_dirs = [\"/usr/lib\"]\nlibrary_dirs = [\"/usr/lib\", \"/home/user/lib\"]\nsources = [\"foo.pyx\", \"bar.pyx\"]\nexclude_dirs = [\"this\", \"that\"]\nsite_packages = \"purelib\"\n\n[tool.hwh.cython]\n# language defaults to C\nlanguage=\"c\"\n\n# default = false\nannotate=false\n\n# default = os.cpu_count() or 1, if os.cpu_count() returns None\nnthreads=1\n\n# default = false\nforce=false\n\n[tool.hwh.cython.compiler_directives]\n# Cython compiler directives\nbinding = false # Generate Python wrapper functions\nboundscheck = false # Array bounds checking\nwraparound = false # Negative indexing\ninitializedcheck = false # Check if extension types are initialized\nnonecheck = false # Generate checks for null Python references\noverflowcheck = false # Check for C integer overflows\nembedsignature = false # Include docstrings in the C code\ncdivision = false # Division by zero checking\ncdivision_warnings = false # Division by zero warning\nprofile = false # Enable profiling\nlinetrace = false # Enable line tracing\ntype_version_tag = true # Enable CPython's type attribute cache\n```\n\n## TODO\n\n- [ ] Allow passing of macros `-D` and extra flags like `-O2`\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Setuptools based backend supporting Cython extensions",
"version": "0.2.1",
"project_urls": {
"Repository": "https://github.com/mkgessen/hwh-backend.git"
},
"split_keywords": [
"cython",
" build",
" backend",
" pep517"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c9727fed3b23dfd9c5044fadc03745752a1b8c6b573c0d870a40b1f418f79dc",
"md5": "8bdb65e0cf16b479bae448354e07e367",
"sha256": "a4372aee8a1d0dc394c449f877966b0ffb0d7aafb1bc556ddb81175d98e13810"
},
"downloads": -1,
"filename": "hwh_backend-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8bdb65e0cf16b479bae448354e07e367",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13379,
"upload_time": "2025-01-27T01:32:30",
"upload_time_iso_8601": "2025-01-27T01:32:30.855505Z",
"url": "https://files.pythonhosted.org/packages/0c/97/27fed3b23dfd9c5044fadc03745752a1b8c6b573c0d870a40b1f418f79dc/hwh_backend-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "73f3c0b1d070f3481e9bae26b4582bbde4f95c47fac2f34d869a5e62e8f49952",
"md5": "13d8f568113dbeba0abfaf8d0eae1038",
"sha256": "ffc33345c71e2bccc0ba65318071ca66ba697c3122e7d85878ef30aebe1db51e"
},
"downloads": -1,
"filename": "hwh_backend-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "13d8f568113dbeba0abfaf8d0eae1038",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 15178,
"upload_time": "2025-01-27T01:32:31",
"upload_time_iso_8601": "2025-01-27T01:32:31.851547Z",
"url": "https://files.pythonhosted.org/packages/73/f3/c0b1d070f3481e9bae26b4582bbde4f95c47fac2f34d869a5e62e8f49952/hwh_backend-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-27 01:32:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkgessen",
"github_project": "hwh-backend",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hwh-backend"
}
