Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

v0.2.6 #18

Merged
merged 5 commits into from
Aug 31, 2023
Merged

v0.2.6 #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
24b716a
test: templated files
joshua-auchincloss Aug 31, 2023
963e1c3
fix: tests
joshua-auchincloss Aug 31, 2023
64bad62
chore: readme [ci skip]
joshua-auchincloss Aug 31, 2023
1fee496
feat: add pythran support [ci skip]
joshua-auchincloss Aug 31, 2023
e850ad3
chore: version [ci skip]
joshua-auchincloss Aug 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions COVERAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
| Name | Stmts | Miss | Branch | BrPart | Cover |
|----------------------------------------- | -------: | -------: | -------: | -------: | ------: |
| src/hatch\_cython/\_\_init\_\_.py | 2 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/config/\_\_init\_\_.py | 2 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/config/autoimport.py | 9 | 0 | 4 | 0 | 100% |
| src/hatch\_cython/config/config.py | 138 | 12 | 58 | 7 | 89% |
| src/hatch\_cython/config/defaults.py | 6 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/config/files.py | 22 | 1 | 12 | 2 | 91% |
| src/hatch\_cython/config/flags.py | 70 | 1 | 26 | 0 | 99% |
| src/hatch\_cython/config/includes.py | 15 | 1 | 8 | 1 | 91% |
| src/hatch\_cython/config/macros.py | 12 | 0 | 7 | 0 | 100% |
| src/hatch\_cython/config/platform.py | 71 | 2 | 28 | 2 | 96% |
| src/hatch\_cython/constants.py | 11 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/devel.py | 5 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/hooks.py | 5 | 1 | 2 | 0 | 86% |
| src/hatch\_cython/plugin.py | 192 | 9 | 142 | 8 | 95% |
| src/hatch\_cython/temp.py | 11 | 0 | 0 | 0 | 100% |
| src/hatch\_cython/utils.py | 27 | 1 | 12 | 1 | 95% |
| **TOTAL** | **598** | **28** | **299** | **21** | **94%** |
| Name | Stmts | Miss | Branch | BrPart | Cover |
| --------------------------------------- | ------: | -----: | ------: | -----: | ------: |
| src/hatch_cython/\_\_init\_\_.py | 2 | 0 | 0 | 0 | 100% |
| src/hatch_cython/config/\_\_init\_\_.py | 2 | 0 | 0 | 0 | 100% |
| src/hatch_cython/config/autoimport.py | 9 | 0 | 4 | 0 | 100% |
| src/hatch_cython/config/config.py | 138 | 12 | 58 | 7 | 89% |
| src/hatch_cython/config/defaults.py | 6 | 0 | 0 | 0 | 100% |
| src/hatch_cython/config/files.py | 22 | 1 | 12 | 2 | 91% |
| src/hatch_cython/config/flags.py | 70 | 1 | 26 | 0 | 99% |
| src/hatch_cython/config/includes.py | 15 | 1 | 8 | 1 | 91% |
| src/hatch_cython/config/macros.py | 12 | 0 | 7 | 0 | 100% |
| src/hatch_cython/config/platform.py | 71 | 2 | 28 | 2 | 96% |
| src/hatch_cython/constants.py | 11 | 0 | 0 | 0 | 100% |
| src/hatch_cython/devel.py | 5 | 0 | 0 | 0 | 100% |
| src/hatch_cython/hooks.py | 5 | 1 | 2 | 0 | 86% |
| src/hatch_cython/plugin.py | 212 | 10 | 160 | 8 | 95% |
| src/hatch_cython/temp.py | 11 | 0 | 0 | 0 | 100% |
| src/hatch_cython/utils.py | 27 | 1 | 12 | 1 | 95% |
| **TOTAL** | **618** | **29** | **317** | **21** | **94%** |
62 changes: 44 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@

- [Usage](#usage)
- [Configuration Options](#configuration-options)
- [Notes](#notes)
- [Templating (Tempita)](#templating-tempita)
- [License](#license)

## Usage
Expand Down Expand Up @@ -82,22 +84,22 @@ define_macros = [

## Configuration Options

| Field | Type |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| src | `str \| None` <br/> directory within `src` dir or `.`  which aliases the package being built. e.g. `package_a` -> `src/package_a_lib` <br/> `src = "package_a"` |
| directives | directives to cython (see [compiler directives]) |
| compile_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant |
| extra_link_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant |
| env | `{ env = "VAR1", arg = "VALUE", platforms = ["*"], arch = ["*"] }`<br/> if flag is one of:<br/> - ARFLAGS<br/> - LDSHARED <br/> - LDFLAGS<br/> - CPPFLAGS <br/> - CFLAGS <br/> - CCSHARED<br/>the current env vars will be merged with the value (provided platform & arch applies), separated by a space. This can be enabled by adding `{ env = "MYVAR" ... , merges = true }` to the definition. |
| includes | list str |
| includes\_{package} | `{ pkg = str, include = str, libraries = str\| None, library_dirs = str \| None , required_call = str \| None }` <br/>where all fields, but `pkg`, are attributes of `pkg` in the type of `callable() -> list[str] \| str` \| `list[str] \| str`. `pkg` is a module, or loadable module object, which may be imported through `import x.y.z`. |
| includes_numpy \| includes_pyarrow | bool<br/>3rd party named imports. must have the respective opt in `dependencies` |
| retain_intermediate_artifacts | bool = False <br/>whether to keep `.c` \| `.cpp` files |
| parallel | bool = False <br/>if parallel, add openmp headers<br/>important: if using macos, you need the *homebrew* llvm vs _apple's_ llvm in order to pass `-fopenmp` to clang compiler |
| compiler | compiler used at build-time. if `msvc` (Microsoft Visual Studio), `/openmp` is used as argument to compile instead of `-fopenmp`  when `parallel = true`. `default = false` |
| compile_py | whether to include `.py` files when building cython exts. note, this can be enabled & you can do per file / matched file ignores as below. `default = true` |
| define_macros | list of list str (of len 1 or 2). len 1 == [KEY] == `#define KEY FOO` . len 2 == [KEY, VALUE] == `#define KEY VALUE`. see [extensions] |
| \*\* kwargs | keyword = value pair arguments to pass to the extension module when building. see [extensions] |
| Field | Type |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| src | `str \| None` <br/> directory within `src` dir or `.`  which aliases the package being built. e.g. `package_a` -> `src/package_a_lib` <br/> `src = "package_a"` |
| directives | directives to cython (see [compiler-directives]) |
| compile_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant |
| extra_link_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant |
| env | `{ env = "VAR1", arg = "VALUE", platforms = ["*"], arch = ["*"] }`<br/> if flag is one of:<br/> - ARFLAGS<br/> - LDSHARED <br/> - LDFLAGS<br/> - CPPFLAGS <br/> - CFLAGS <br/> - CCSHARED<br/>the current env vars will be merged with the value (provided platform & arch applies), separated by a space. This can be enabled by adding `{ env = "MYVAR" ... , merges = true }` to the definition. |
| includes | list str |
| includes\_{package} | `{ pkg = str, include = str, libraries = str\| None, library_dirs = str \| None , required_call = str \| None }` <br/>where all fields, but `pkg`, are attributes of `pkg` in the type of `callable() -> list[str] \| str` \| `list[str] \| str`. `pkg` is a module, or loadable module object, which may be imported through `import x.y.z`. |
| includes_numpy \| includes_pyarrow \| includes_pythran | bool<br/>3rd party named imports. must have the respective opt in `dependencies` |
| retain_intermediate_artifacts | bool = False <br/>whether to keep `.c` \| `.cpp` files |
| parallel | bool = False <br/>if parallel, add openmp headers<br/>important: if using macos, you need the *homebrew* llvm vs _apple's_ llvm in order to pass `-fopenmp` to clang compiler |
| compiler | compiler used at build-time. if `msvc` (Microsoft Visual Studio), `/openmp` is used as argument to compile instead of `-fopenmp`  when `parallel = true`. `default = false` |
| compile_py | whether to include `.py` files when building cython exts. note, this can be enabled & you can do per file / matched file ignores as below. `default = true` |
| define_macros | list of list str (of len 1 or 2). len 1 == [KEY] == `#define KEY FOO` . len 2 == [KEY, VALUE] == `#define KEY VALUE`. see [extensions] |
| \*\* kwargs | keyword = value pair arguments to pass to the extension module when building. see [extensions] |

### Files

Expand All @@ -114,10 +116,34 @@ exclude = [
aliases = {"abclib._filewithoutsuffix" = "abclib.importalias"}
```

## Notes

### Templating (Tempita)

Tempita is supported for any files suffixed with `.in`, where the extension output is:

- `.pyx.in`
- `.pyd.in`
- `.pyi.in`
For these files, you may expect the output `.pyx.in` -> `.pyx`. Thus, with aliasing this would look like:

```toml
[build.targets.wheel.hooks.cython.options.files]
aliases = {"abclib._somemod" = "abclib.somemod"}
```

- 1. Source files `somemod.pyi.in`, `_somemod.pyx.in`
- 2. Processed templates `somemod.pyi`, `_somemod.pyx`
- 3. Compiled module `abclib.somemod{.pyi,.pyx}`

An example of this is included in:

- [pyi stub file](./example/src/example_lib/templated.pyi.in)
- [pyx cython source file](./example/src/example_lib/templated.pyx.in)

## License

`hatch-cython` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

[extensions]: (https://docs.python.org/3/distutils/apiref.html#distutils.core.Extension)

[compiler directives]:(https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#compiler-directives))
[compiler-directives]: (https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#compiler-directives)
2 changes: 2 additions & 0 deletions example/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
templated.pyi
templated.pyx
28 changes: 28 additions & 0 deletions example/src/example_lib/templated.pyi.in
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{{py:
def supported():
return ["int", "float"]
}}

{{for typ in supported()}}

# {{typ}} C adder ({{typ}})
def c{{typ[:1]}}add(a: {{typ}}, b: {{typ}}) -> {{typ}}:
"""
Takes `a` `{{typ}}` plus `b` `{{typ}}`
"""
...

# {{typ}} C mul ({{typ}})
def c{{typ[:1]}}mul(a: {{typ}}, b: {{typ}}) -> {{typ}}:
"""
Takes `a` `{{typ}}` times `b` `{{typ}}`
"""
...

def c{{typ[:1]}}pow(a: {{typ}}, b: {{typ}}) -> {{typ}}:
"""
Takes `a` `{{typ}}` to the power of `b` `{{typ}}`
"""
...

{{endfor}}
Loading