Skip to main content

A demo of organizing, building and distributing a Cython package.

Project description

cypkgdemo

cypkgdemo 是一个用于演示对 Cython 模块的编译、测试、打包和安装的包。

使用方法

可以通过 pip install cypkgdemo 将 cypkgdemo 安装至 "root" package 下(建议使用虚拟环境),安装好后通过 import cypkgdemo 或者 from cypkgdemo import ... 即可调用包中函数。

若通过源文件安装,则在 pyproject.toml 所在目录运行 pip install . 命令即可。

若进行二次开发,可增加 -e 选项以便调试。若要进行单元测试,则需要附加安装 dev 依赖,即运行如下命令:

pip install -e ".[dev]"

之后使用如下命令可运行单元测试:

python -m unittest discover -p "*test.py"

上述两条命令使用引号包裹 .[test]*test.py 是为了避免 zsh 将它们当作正则表达式从而导致意外的错误。若在其他 shell 下,或已在 .zshrc 中配置了 setopt no_nomatch,则无须使用引号包裹。

注意,本包不再支持使用 python setup.py build_ext --inplace 命令生成链接库。

说明

根据 PEP 518,项目中包的基本信息、依赖关系等均在 pyproject.toml 中说明。而为了支持构建 Cython Extension,仍旧保留了 setup.py 文件,其中包含了如何为每一个 .pyx 文件构造 Extension 的方法,你可以根据自己的需求对其进行修改。

开发的一般步骤

编写源代码

参照官方教程,开发的 Python 包的源代码放在 src/cypkgdemo 目录下。

一般而言,对于一个包含了多个 Python 和 Cython 源文件的项目,每个模块(无论是纯 Python 还是 Cython 模块)在导入同一项目下的其他模块时,都应当采用相对于最顶层包的绝对路径(例如,在这里就是 from cypkgdemo.some_module import / cimport ...)。

每个 Cython .pyx 源文件可编译出一个 Cython 扩展模块,该模块可通过如下方式暴露接口给其他 Python/Cython 模块使用:

暴露的接口 其他哪些模块可以使用 使用方式
Python 对象(包括 cpdef 函数) 所有模块 通过 import 命令
在 .pxd 文件声明的 cdef/cpdef 函数 Cython 模块 通过 cimport 命令
未在 .pxd 文件声明的 cdef 函数

因此,若要让编写的 C/C++ 函数能被第三方库访问,除了要在 .pyx 文件中给出实现外,还要在同名的 .pxd 文件中声明函数接口,并确保该 .pxd 文件会被打包到安装包中。

当前默认所有 .pxd 文件都会被安装,参见 pyproject.toml [tool.setuptools.package-data] 部分。若要指定某些 .pxd 文件不被安装,则可通过类似如下代码实现:

[tool.setuptools.exclude-package-data]
cypkgdemo = ["sa.pxd"]

Cython 要求,Cython 扩展库的名称必须与源文件的无后缀名称全同(含路径),即对于目录 src/cypkgdemo/some/parent/subpackage 下名为 extmod1.pyx 的 Cython 源文件,可编译出的 Cython 扩展库必须名为 cypkgdemo.some.parent.subpackage.extmod1,否则模块中的内容无法被导入。本包通过 setup.py 中的 make_extension 函数实现该要求。

编译与测试

正如使用方法部分所述,可以通过如下命令完成可编辑安装和单元测试:

pip install -e ".[test]"
python -m unittest discover -p "*test.py"

你可以按需在 tests 文件夹下增加更多的单元测试内容。

打包

使用 build 包完成分发前的打包工作。对此,首先需要安装 build:

pip install build -i https://pypi.tuna.tsinghua.edu.cn/simple

然后在 pyproject.toml 所在目录下运行:

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple  # 可选
python -m build

此时会在 dist/ 目录下生成发行包。

上传

首先,安装工具包 twine:

pip install twine

运行 twine check,检查发行包完整性:

twine check dist/*

上述检查通过后,可采用以下步骤上传至 PyPI:

# Upload to Test PyPI
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
# To PyPI
twine upload dist/*

注意,如果是发布源文件(python setup.py sdist),开发者应当安装有 Cython,以便从 Cython 源文件生成 C/C++ 文件,进而将 C/C++ 文件包含进源发行包中(这样用户可以不用安装有 Cython)。

采用以下方式安装之前上传的包:

# From Test PyPI
pip install --index-url https://test.pypi.org/simple/ cypkgdemo
# From PyPI 
pip install cypkgdemo

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cypkgdemo-1.0.1.tar.gz (103.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page