diff --git a/README.md b/README.md index d8ad23f12ba9f7d5042ae6e980e2b7d8efed1a87..ffc25dc6d83aa284a2dba9bbaa101e3c0455cd74 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ snakehouse snakehouse is a tool to pack mutiple .pyx files into a single extension. +_There's a **MANDATORY READING** part at the end of this README. Read it or you will be sure to run into trouble._ + Inspired by [this StackOverflow discussion](https://stackoverflow.com/questions/30157363/collapse-multiple-submodules-to-one-cython-extension). Tested and works on CPython 3.5-3.9, @@ -24,8 +26,8 @@ a part of your pull request as well! Note what have you changed in [CHANGELOG.md](/CHANGELOG.md) as well! -Usage notes ------------ +Usage notes - MANDATORY READING +------------------------------- Take a look at [example](example/) on how to multi-build your Cython extensions. Don't place modules compiled that way in root .py file's top level imports. @@ -38,3 +40,22 @@ the built module has a tendency to dump core. Try to debug it first by passing `dont_snakehouse=True` to your modules in the debug mode. +Also note that if you are compiling in `dont_snakehouse` +mode then your modules should have at least one of the following: +* a normal Python `def` +* a normal Python class (not `cdef class`) +* a line of Python initialization, eg. + +```python +a = None +``` + +or +```python +import logging + +logger = logging.getLogger(__name__) +``` + +Otherwise `PyInit` won't be generated by Cython +and such module will be unimportable in Python. Normal import won't suffice.