As the aim of Biotite is to create a comprehensive library, we welcome developers who would like to extend the package with new functionalities or improve existing code.
The complete development workflow is hosted on GitHub. This is also the place where you would post feature propositions, questions, bug reports, etc.
If you are interested in improving Biotite, you feel free join our chat on Discord. We are happy to answer questions, discuss ideas and provide mentoring for newcomers. Alternatively, you can also contact mailto:firstname.lastname@example.org. A good place to find projects to start with are the Open Issues and the Project Boards.
The following page explains the development guidelines in order to keep Biotite’s source code consistent.
The scope of Biotite are methods that make up the backbone of computational molecular biology. Thus, new functionalities added to Biotite should be relatively general and well established.
Code of which the purpose is too special could be published as extension package.
New functionalities should work with existing types, if applicable.
Specifically, this includes for example
and of course
Python version and interpreter¶
Biotite is made for usage with Python 3.6 and upwards. Therefore, no compatibility hacks for Python 2.x are necessary. Furthermore, this package is currently made for use with CPython. Support for PyPy might be added someday.
Biotite is in compliance with PEP 8. The maximum line length is 79 for code lines and 72 for docstring and comment lines. An exception is made for docstring lines, if it is not possible to use a maximum of 72 characters (e.g. tables), and for doctest style lines, where the actual code may take up to 79 characters.
Biotite currently depends on numpy, requests, msgpack. The usage of these packages is not only allowed but even encouraged. Further packages might be added to the dependencies in the future, so if you need a specific package, you might open an issue on GitHub. But keep in mind, that a simple installation process is a central aim of Biotite, so the new dependency should neither be hard to install on any system nor be poorly supported.
Another approach is adding your special dependency to the list of extra
In this case, put the import statement for the dependency directly into the
function or class, rather than module level, to ensure that the package is not
required for any other functionality or for building the API documentation.
If your added code has a dependency that is too special, consider publishing the code as extension package.
Although convenient usage is a primary aim of Biotite, code efficiency plays also an important role. Therefore time consuming tasks should be C-accelerated, if possible. The most convenient way to achieve this, is using NumPy. In cases the problem is not vectorizable, writing modules in Cython are the preferred way to go. Writing pure C-extensions is discouraged due to the bad readability.
formatted docstrings for its documentation.
The docstrings can be interpreted by Sphinx via the numpydoc extension.
All publicly accessible attributes must be fully documented.
This includes functions, classes, methods, instance and class variables and the
__init__ module documentation summarizes the content of the entire
subpackage, since the single modules are not visible to the user.
Consequently, all other modules do not need to be fully documented on the
module level, one or two short sentences are sufficient.
In the class docstring, the class itself is described and the constructor is
The publicly accessible instance variables are documented under the
Attributes headline, while class variables are documented in their separate
Methods do not need to be summarized in the class docstring.
In Biotite, the user imports packages in contrast to single modules
(similar to NumPy).
In order for that to work, the
__init__.py file of each Biotite
subpackage needs to import all of its modules, whose content is publicly
accessible, in a relative manner.
from .module1 import * from .module2 import *
Import statements should be the only statements in a
In case a module needs functionality from another subpackage of Biotite, use a relative import. This import should target the module directly and not the package. So import statements like the following are totally OK:
from ...package.subpackage.module import foo
In order to prevent namespace pollution, all modules must define the __all__ variable with all publicly accessible attributes of the module.
When using Biotite internal imports, always use relative imports. Otherwise in-development testing is not possible.
Writing the documentation¶
Any documentation apart from the API reference is placed in the
Biotite uses Sphinx for building its documentation and therefore the
documentation is based on reStructuredText files.
The line length of these
*.rst files is also limited to
79 characters, with the exceptions already mentioned above.
Do you have an application of Biotite and you want to share it with the
Then the example gallery is the way to go.
For gallery generation the package sphinx-gallery is used.
Please refer to its
for further information on script formatting.
The example scripts are placed in
Static images and molecular visualizations¶
In addition to Matplotlib plots, the Biotite example gallery can also show molecular visualizations, via the PyMOL software, and static images.
Static images can be included by adding the following comment in the corresponding code block:
# biotite_static_image = <name_of_the_image>.png
The image file must be stored in the same directory as the example script.
To visualize images using PyMOL, the Ammolite package is required. Please make sure to use open-source PyMOL to avoid licensing issues.
Let’s assume you have an example script <example_name>.py. The visualization is initiated by adding the comment line
# Visualization with PyMOL..
in the code block where you want show the visualization.
Then the visualization script
<example_name>_pymol.py is executed, which
can use the global variables from the example script and the special
__image_destination__ is a string representing the path to the output image
The PyMOL visualization can be saved to this file with e.g.
The rendered image is saved in the directory of the example script as
<example_name>.png and is added to version control.
The visualization script is only executed, if the rendered image does not
The traceback of errors in the visualization script are printed, if
sphinx-build is run in verbose (
An example of this can be seen in the
Updating the tutorial¶
When adding new content for broad audience, it is appreciated to update the
tutorial pages (
doc/tutorial/src) as well.
The tutorial uses functionality from
sphinx-gallery to generate
the tutorial from example scripts.
This has the advantage that the output of code snippets is not static but
dynamically generated based on the current state of the Biotite source
Consequently, the same script formatting as for the example gallery is
Figures that cannot be dynamically generated are put into
Structuring the API reference¶
Each Biotite subpackage has a dedicated reference page, describing
its classes and functions.
The categories and classes/functions that are assigned to it can be set
Classes/functions that are not assigned to any category are placed in
the ‘Miscellaneous’ category or, if no class/function is assigned,
in the ‘Content’ category.
creating references in docstrings, examples, etc.
The references are stored in
doc/references.bib with citation keys
References are cited with the
:footcite: role and the bibliography
is rendered where the
.. footbibliography:: directive is placed.
For simple tests of your code, you are free to use a
test.py file in the
top-level directory since this file is ignored in the
Remember you have to have to use relative imports, as long as you do not want
to build and install the package after each small code change.
Therefore, the import statements in
test.py will look similar to this:
import src.biotite import src.biotite.sequence as seq import src.biotite.structure as struc ...
Alternatively, you can install Biotite in development mode via pip install -e ..
If you are writing or using an extension module in Cython, consider using
pyximport at the beginning of
import pyximport pyximport.install()
In order to check if your new awesome code breaks anything in Biotite,
you should run unit tests before you open a pull request.
To achieve that, install the package and run
pytest in the top-level
$ pip install . $ pytest
Adding your own unit tests for your new module (if possible), is appreciated.
The unit tests are found in the
tests folder (big surprise!).
If there is already an appropriate module for you, then just add your own test
function to it.
If not, create your own module and put your test function into it.
The binary distribution and the source distribution are created with the following commands, respectively:
$ python setup.py bdist_wheel $ python setup.py sdist
Building the documentation¶
The Sphinx documentation is created using
$ pip install -e . $ sphinx-build doc build/doc
in the top-level directory. The building process can take a while, since the code from the tutorial and the example gallery is executed. In order to omit building the tutorial and gallery, type
$ sphinx-build -D plot_gallery=0 doc build/doc
The following packages are required for the complete build process including the creation of the entire documentation:
Furthermore, the following software must be installed:
If you use the Conda package manager, there is a shortcut:
You can download a Conda environment from
that contains all of these requirements.
How to create and activate the environment from the
is explained in the
Biotite extension packages are Python packages that provide further
functionality for Biotite objects (
or offer objects that build up on these ones.
There can be good reasons why one could choose to publish code as extension package instead of contributing it directly to the Biotite project:
An incompatible license
The code’s use cases are too specialized
Acceleration by C/C++ code (in contrast to Cython code)
If your code fulfills the following conditions
extends Biotite functionality
is well tested
you can contact the Biotite maintainer or open an issue to ask for official acceptance as extension package.
The current extension packages are displayed on the extensions section in the documentation.