Package: hatch-cython
hatch-cythonCI/CDPackageMetaTable of ContentsUsageConfiguration OptionsNotesTemplating (Tempita)LicenseUsageThe build hook name iscython.pyproject.toml# [tool.hatch.build.hooks.cython]# or# (hatch.toml)# [build.targets.wheel.hooks.cython]# or[tool.hatch.build.targets.wheel.hooks.cython]dependencies=["hatch-cython"]# [tool.hatch.build.hooks.cython.options]# or# (hatch.toml)# [build.targets.wheel.hooks.cython.options]# or[tool.hatch.build.targets.wheel.hooks.cython.options]# include .h or .cpp directoriesincludes=[]# include numpy headersinclude_numpy=falseinclude_pyarrow=false# include_{custom}include_somelib={# must be included in build-dependenciespkg="somelib",# somelib.gets_include() -> strinclude="gets_include",# somelib.gets_libraries() -> list[str]libraries="gets_libraries",# somelib.gets_library_dirs() -> list[str]library_dirs="gets_library_dirs",# somelib.some_setup_op() before buildrequired_call="some_setup_op"}compile_args=[# single string"-v",# by platform{platforms=["linux","darwin"],arg="-Wcpp"},# by platform & arch{platforms="darwin",arch="x86_64",arg="-arch x86_64"},{platforms=["darwin"],arch="arm64",arg="-arch arm64"},# with pep508 markers{platforms=["darwin"],arch="x86_64",arg="-I/usr/local/opt/llvm/include",depends_path=true,marker="python_version <= '3.10'"},]directives={boundscheck=false,nonecheck=false,language_level=3,binding=true}compile_kwargs={}hatch.toml# [build.hooks.cython]# or[build.targets.wheel.hooks.cython]dependencies=["hatch-cython"]# [build.hooks.cython.options]# or[build.targets.wheel.hooks.cython.options]directives={boundscheck=false,nonecheck=false,language_level=3,binding=true}compile_args=["-O3",]includes=[]include_numpy=false# equivalent to include_pyarrow = trueinclude_somelib={pkg="pyarrow",include="get_include",libraries="get_libraries",library_dirs="get_library_dirs",required_call="create_library_symlinks"}define_macros=[# ["ABC"] -> ["ABC", "FOO"] | ["ABC", "DEF"]["NPY_NO_DEPRECATED_API","NPY_1_7_API_VERSION"],]Configuration OptionsFieldTypesrcstr | Nonedirectory withinsrcdir or.which aliases the package being built. e.g.package_a->src/package_a_libsrc = "package_a"directivesdirectives to cython (seecompiler-directives)compile_argsstr or{ platforms = ["*"] | "*", arg = str }. seeextensionsfor what args may be relevantextra_link_argsstr or{ platforms = ["*"] | "*", arg = str }. seeextensionsfor what args may be relevantenv{ env = "VAR1", arg = "VALUE", platforms = ["*"], arch = ["*"] }if flag is one of:- ARFLAGS- LDSHARED- LDFLAGS- CPPFLAGS- CFLAGS- CCSHAREDthe 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.includeslist strinclude_{package}{ pkg = str, include = str, libraries = str| None, library_dirs = str | None , required_call = str | None }where all fields, butpkg, are attributes ofpkgin the type ofcallable() -> list[str] | str|list[str] | str.pkgis a module, or loadable module object, which may be imported throughimport x.y.z.include_numpy | include_pyarrow | include_pythranbool3rd party named imports. must have the respective opt independenciesparallelbool = Falseif parallel, add openmp headersimportant: if using macos, you need thehomebrewllvm vsapple'sllvm in order to pass-fopenmpto clang compilercompilercompiler used at build-time. ifmsvc(Microsoft Visual Studio),/openmpis used as argument to compile instead of-fopenmpwhenparallel = true.default = falsecompile_pywhether to include.pyfiles when building cython exts. note, this can be enabled & you can do per file / matched file ignores as below.default = truedefine_macroslist of list str (of len 1 or 2). len 1 == [KEY] ==#define KEY FOO. len 2 == [KEY, VALUE] ==#define KEY VALUE. seeextensions** kwargskeyword = value pair arguments to pass to the extension module when building. seeextensionsFiles[build.targets.wheel.hooks.cython.options.files]exclude=[# anything matching no_compile is ignored by cython"*/no_compile/*",# note - anything "*" is escaped to "([^\s]*)" (non whitespace).# if you need an actual * for python regex, use as below:# this excludes all pyd or pytempl extensions"([^.]\\*).(pyd$|pytempl$)",# only windows{matches="*/windows",platforms=["linux","darwin","freebsd"]},# only darwin{matches="*/darwin",platforms=["linux","freebsd","windows"]},# only linux{matches="*/linux",platforms=["darwin","freebsd","windows"]},# only freebsd{matches="*/freebsd",platforms=["linux","darwin","windows"]}]aliases={"abclib._filewithoutsuffix"="abclib.importalias"}sdistSdist archives may be generated normally.hatchmust be defined as thebuild-systembuild-backend in yourpyproject.toml. As such, hatch will automatically installhatch-cython, and perform the specified e.g. platform-specific adjustments to the compile-time arguments. This allows the full build-process to be respected, and generated following specifications of the developer.Note: If you specifyhatch-cythonto run outside of simply wheel-step processes, the extension module is skipped. As such, the.c&.cpp, as well as templated files, may be generated and stored in the sdist should you wish. However, there is currently little purpose to this, as the extension will likely have differed compile arguments.TemplatingCython tempita is supported for any files suffixed with.in, where the extension output is:.pyx.in.pyd.in.pyi.inFor these files, you may expect the output.pyx.in->.pyx. Thus, with aliasing this would look like:[build.targets.wheel.hooks.cython.options.files]aliases={"abclib._somemod"="abclib.somemod"}Source filessomemod.pyi.in,_somemod.pyx.inProcessed templatessomemod.pyi,_somemod.pyxCompiled moduleabclib.somemod{.pyi,.pyx}An example of this is included in:pyi stub filepyx cython source filepyi stub (rendered)pyx cython source (rendered)Template ArgumentsYou may also supply arguments for per-file matched namespaces. This follows the aboveplatforms,arch, &markerformats, where if supplied & passing the condition the argument is passed to the template as a named series of keyword arguments.You supply anindexvalue, and all other kwargs to templates arekeywordsfor each index value. Follows FIFO priority for all keys except global, which is evaluated first and overriden if there are other matching index directives. The engine will attempt to merge the items of the keywords, roughly following:args={"index":[{"keyword":"global",...},{"keyword":"thisenv",...},],"global":{"abc":1,"other":2},"thisenv":{"other":3},}merge(args)->{"abc":1,"other":3}In hatch.toml:[build.targets.wheel.hooks.cython.options.templates]index=[{keyword="global",matches="*"},{keyword="templated_mac",matches="templated.*.in",platforms=["darwin"]},{keyword="templated_mac_py38",matches="templated.*.in",platforms=["darwin"],marker="python == '3.8'"},{keyword="templated_win",matches="templated.*.in",platforms=["windows"]},{keyword="templated_win_x86_64",matches="templated.*.in",platforms=["windows"],arch=["x86_64"]},]# these are passed as arguments for templating# 'global' is a special directive reserved & overriden by all other matched valuesglobal={supported=["int"]}templated_mac={supported=["int","float"]}templated_mac_py38={supported=["int","float"]}templated_win={supported=["int","float","complex"]}# assuming numpy is cimported in the templatetemplated_win_x86_64={supported=["int","float","np.double"]}DevelopmentRequirementsa c / c++ compilerpython 3.8-<=3.12git-cliff(pip install git-cliff)tasksScriptstest: library & coveragehatch run covtest: src structureexampletask exampletest: simple structureexampletask simple-structurecommit: precommitttask precommitLicensehatch-cythonis distributed under the terms of theMITlicense.