Contributing guidelines

In General

  • PEP 8, when sensible.
  • Conventions and configuration.
  • TextBlob wraps functionality in NLTK and pattern.en. Anything outside of that should be written as an extension.
  • Test ruthlessly. Write docs for new features.
  • Even more important than Test-Driven Development–Human-Driven Development.
  • These guidelines may–and probably will–change.

In Particular

Questions, Feature Requests, Bug Reports, and Feedback…

…should all be reported on the Github Issue Tracker .

Setting Up for Local Development

  1. Fork TextBlob on Github.

    $ git clone
    $ cd TextBlob
  2. Install development requirements. It is highly recommended that you use a virtualenv.

    # After activating your virtualenv
    $ pip install -r dev-requirements.txt
  3. Install TextBlob in develop mode.

    $ python develop

Developing Extensions

Extensions are packages with the name textblob-something, where “something” is the name of your extension. Extensions should be imported with import textblob_something.

Model Extensions

To create a new extension for a part-of-speech tagger, sentiment analyzer, noun phrase extractor, classifier, tokenizer, or parser, simply create a module that has a class that implements the correct interface from textblob.base. For example, a tagger might look like this:

from textblob.base import BaseTagger

class MyTagger(BaseTagger):
    def tag(self, text):
        # Your implementation goes here

Language Extensions

The process for developing language extensions is the same as developing model extensions. Create your part-of-speech taggers, tokenizers, parsers, etc. in the language of your choice. Packages should be named textblob-xx where “xx” is the two- or three-letter language code (Language code reference).

To see examples of existing extensions, visit the Extensions page.

Check out the API reference for more info on the model interfaces.

Git Branch Structure

TextBlob loosely follows Vincent Driessen’s Successful Git Branching Model . In practice, the following branch conventions are used:

The next release branch.
Current production release on PyPI.

Pull Requests

1. Create a new local branch.

$ git checkout -b name-of-feature

2. Commit your changes. Write good commit messages.

$ git commit -m "Detailed commit message"
$ git push origin name-of-feature
  1. Before submitting a pull request, check the following:
  • If the pull request adds functionality, it is tested and the docs are updated.
  • If you’ve developed an extension, it is on the Extensions List.
  • The pull request works on Python 2.7, 3.4, 3.5, 3.6, and PyPy. Use tox to verify that it does.
  • You’ve added yourself to AUTHORS.rst.
  1. Submit a pull request to the sloria:dev branch.

Running tests

To run all the tests:

$ python

To skip slow tests:

$ python fast

To skip tests that require internet:

$ python no-internet

To get test coverage reports (must have coverage installed):

$ python cover

To run tests on Python 2.7, 3.4, 3.5, and 3.6 virtual environments (must have each interpreter installed):

$ tox


Contributions to the documentation are welcome. Documentation is written in reStructuredText (rST). A quick rST reference can be found here. Builds are powered by Sphinx.

To build docs:

$ invoke docs -b

The -b (for “browse”) automatically opens up the docs in your browser after building.