Development

This page is intended for developers of Zipline, people who want to contribute to the Zipline codebase or documentation, or people who want to install from source and make local changes to their copy of Zipline.

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We track issues on GitHub and also have a mailing list where you can ask questions.

Creating a Development Environment

First, you’ll need to clone Zipline by running:

$ git clone git@github.com:stefan-jansen/zipline-reloaded.git

Then check out to a new branch where you can make your changes:

$ cd zipline-reloaded
$ git checkout -b some-short-descriptive-name

If you don’t already have them, you’ll need some C library dependencies. You can follow the install guide to get the appropriate dependencies.

Once you’ve created and activated a virtual environment

$ python3 -m venv venv
$ source venv/bin/activate

Or, using virtualenvwrapper:

$ mkvirtualenv zipline

run the pip install -e .[test] to install :

After installation, you should be able to use the zipline command line interface from your virtualenv:

$ zipline --help

To finish, make sure tests pass.

During development, you can rebuild the C extensions by running:

$ ./rebuid-cython.sh

Style Guide & Running Tests

We use flake8 for checking style requirements, black for code formatting and pytest to run Zipline tests. Our continuous integration tools will run these commands.

Before submitting patches or pull requests, please ensure that your changes pass when running:

$ flake8 src/zipline tests

In order to run tests locally, you’ll need TA-lib, which you can install on Linux by running:

$ wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
$ tar -xvzf ta-lib-0.4.0-src.tar.gz
$ cd ta-lib/
$ ./configure --prefix=/usr
$ make
$ sudo make install

And for TA-lib on OS X you can just run:

$ brew install ta-lib

Then run pip install TA-lib:

You should now be free to run tests:

$ pytest tests

Continuous Integration

[TODO]

Packaging

[TODO]

Contributing to the Docs

If you’d like to contribute to the documentation on zipline.io, you can navigate to docs/source/ where each reStructuredText (.rst) file is a separate section there. To add a section, create a new file called some-descriptive-name.rst and add some-descriptive-name to appendix.rst. To edit a section, simply open up one of the existing files, make your changes, and save them.

We use Sphinx to generate documentation for Zipline, which you will need to install by running:

If you would like to use Anaconda, please follow the installation guide to create and activate an environment, and then run the command above.

To build and view the docs locally, run:

# assuming you're in the Zipline root directory
$ cd docs
$ make html
$ {BROWSER} build/html/index.html

Commit messages

Standard prefixes to start a commit message:

BLD: change related to building Zipline
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8, flake8, etc)
TST: addition or modification of tests
REL: related to releasing Zipline
PERF: performance enhancements

Some commit style guidelines:

Commit lines should be no longer than 72 characters. The first line of the commit should include one of the above prefixes. There should be an empty line between the commit subject and the body of the commit. In general, the message should be in the imperative tense. Best practice is to include not only what the change is, but why the change was made.

Example:

MAINT: Remove unused calculations of max_leverage, et al.

In the performance period the max_leverage, max_capital_used,
cumulative_capital_used were calculated but not used.

At least one of those calculations, max_leverage, was causing a
divide by zero error.

Instead of papering over that error, the entire calculation was
a bit suspect so removing, with possibility of adding it back in
later with handling the case (or raising appropriate errors) when
the algorithm has little cash on hand.

Formatting Docstrings

When adding or editing docstrings for classes, functions, etc, we use numpy as the canonical reference.

Updating the Whatsnew

We have a set of whatsnew files that are used for documenting changes that have occurred between different versions of Zipline. Once you’ve made a change to Zipline, in your Pull Request, please update the most recent whatsnew file with a comment about what you changed. You can find examples in previous whatsnew files.