Welcome to snakehouse's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   usage
   utilities
   coverage
   accelerating

What is snakehouse?
===================

Snakehouse_ is a package that helps_ you put multiple :code:`.pyx` files in a single
Python :code:`so`/:code:`DLL`, so that each is importable by Python as if they
were just plain :code:`.py` files.

.. _helps: https://stackoverflow.com/questions/30157363/collapse-multiple-submodules-to-one-cython-extension

.. _Snakehouse: https://github.com/smok-serwis/snakehouse

How do I install it?
--------------------

Do it via

.. code-block:: bash

    pip install snakehouse

All dependencies will be installed automatically.

Mandatory reading and limitations
=================================

Take a look at example_ on how to multi-build your Cython extensions.

.. _example: https://github.com/smok-serwis/snakehouse/blob/develop/example/setup.py

Don't place modules compiled that way in root .py file's top level imports.
Wrap them in a layer of indirection instead!

So if your module is called :code:`example`, make a :code:`start_example/__main__.py` with
the following code:

.. code-block:: python

    if __name__ == '__main__':
        from example import run
        run()

Or however you do start your application.

This applies to unit tests as well!

When something goes wrong (eg. the application throws an unhandled exception)
the built module has a tendency to dump core.
Try to debug it first by passing :code:`dont_snakehouse=True` to your
modules in the debug mode.

Also note that if you are compiling in :code:`dont_snakehouse`
mode then your modules should have at least one of the following:

* a normal Python :code:`def`
* a normal Python class (not :code:`cdef class`)
* a line of Python initialization, eg.

.. code-block:: python

   a = None

or

.. code-block:: python

   import logging

   logger = logging.getLogger(__name__)

Otherwise :code:`PyInit` won't be generated by Cython
and such module will be unimportable in Python. Normal import won't suffice.

Please install Snakehouse in a separate venv. This is because it requires ancient version of
several packages, because authors of these packages were quick to drop support for
earlier Pythons.

Contributions
=============

Contributions are most welcome. Just add yourself to :code:`CONTRIBUTORS.md` list
at your pull request. At this moment most pressing issues are the segfaulting problem,
where snakehouse-built libraries segfault_ the Python interpreter when there's an unhandled
exception (sometimes, I can't really seem to pinpoint the problem source).

Try to unit test what you're changing, but that is by no way a requirement.

.. _segfault: https://github.com/smok-serwis/snakehouse/issues/7

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`