merge: pr #18 from joshua-auchincloss/v0.2.6

v0.2.6

COVERAGE.md

@@ -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%** |

README.md

@@ -14,6 +14,8 @@
 
 - [Usage](#usage)
 - [Configuration Options](#configuration-options)
+- [Notes](#notes)
+ - [Templating (Tempita)](#templating-tempita)
 - [License](#license)
 
 ## Usage
@@ -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
 
@@ -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)

example/.gitignore

@@ -0,0 +1,2 @@
+templated.pyi
+templated.pyx

example/src/example_lib/templated.pyi.in

@@ -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}}