Login With Github

Further Development With ChatterBot

As the code for ChatterBot is written, the developers attempt to describe the logic and reasoning for the various decisions that go into creating the internal structure of the software. This internal documentation is intended for future developers and maintaners of the project. A majority of this information is unnecessary for the typical developer using ChatterBot.

It is not always possible for every idea to be documented. As a result, the need may arise to question the developers and maintainers of this project in order to pull concepts from their minds and place them in these documents. Please pull gently.

Contributing to ChatterBot

There are numerous ways to contriubte to ChatterBot. All of which are highly encouraged.

  • Contributing bug reports and feature requests
  • Contributing documentation
  • Contributing code for new features
  • Contributing fixes for bugs

Every bit of help received on this project is highly appreciated.

Setting Up a Development Environment

To contribute to ChatterBot's development, you simply need:

  • Python
  • pip
  • A few python packages:
    pip install requirements.txt
    pip install dev-requirements.txt
  •  A text editor

Reporting a Bug

If you discover a bug in ChatterBot and wish to report it, please be sure that you adhere to the following when you report it on GitHub.

  1. Before creating a new bug report, please search to see if an open or closed report matching yours already exists.
  2. Please include a description that will allow others to recreate the problem you encountered.

Requesting New Features

When requesting a new feature in ChatterBot, please make sure to include the following details in your request.

  1. Your use case. Describe what you are doing that requires this new functionality.

Contributing Documentation

ChatterBot's documentation is written in reStructuredText and is compiled by Sphinx. The reStructuredText source of the documentation is located in docs/.

To build the documentation yourself, run:

sphinx-build ./docs/ ./build/

You can then open the index.html file that will be created in the build directory.

Contributing Code

The development of ChatterBot happens on GitHub. Code contributions should be submitted there in the form of pull requests.

Pull requests should meet the following criteria.

  1. Fix one issue and fix it well.
  2. Do not include extraneous changes that do not relate to the issue being fixed.
  3. Include a descriptive title and description for the pull request.
  4. Have descriptive commit messages.

Releasing ChatterBot

ChatterBot follows the following rules when it comes to new versions and updates.


ChatterBot follows semantic versioning as a set of guidelines for release versions.

  • Major releases (2.0.0, 3.0.0, etc.) are used for large, almost entirely backwards incompatible changes.
  • Minor releases (2.1.0, 2.2.0, 3.1.0, 3.2.0, etc.) are used for releases that contain small, backwards incompatible changes. Known backwards incompatibilities will be described in the release notes.
  • Patch releases (e.g., 2.1.1, 2.1.2, 3.0.1, 3.0.10, etc.) are used for releases that contain bug fixes, features and dependency changes.

Release Process

The following procedure is used to finalize a new version of ChatterBot.

  1. We make sure that all CI tests on the master branch are passing.
  2. We tag the release on GitHub.
  3. A new package is generated from the latest version of the master branch.
    python setup.py sdist bdist_wheel
  4. The Python package files are uploaded to PyPi.
    twine upload dist/*

Unit Testing

"A true professional does not waste the time and money of other people by handing over software that is not reasonably free of obvious bugs; that has not undergone minimal unit testing; that does not meet the specifications and requirements; that is gold-plated with unnecessary features; or that looks like junk." – Daniel Read

ChatterBot tests

ChatterBot's built in tests can be run using nose. See the nose documentation for more information.


Note that nose also allows you to specify individual test cases to run. For example, the following command will run all tests in the test-module tests/logic_adapter_tests

nosetests tests/logic_adapter_tests

Django integration tests

Tests for Django integration have been included in the tests_django directory and can be run with:

python runtests.py

Django example app tests

Tests for the example Django app can be run with the following command from within the examples/django_app directory.

python manage.py test

Benchmark tests

You can run a series of benchmark tests that test a variety of different chat bot configurations for performance by running the following command.

python tests/benchmarks.py

Running all the tests

You can run all of ChatterBot's tests with a single command: tox.

Tox is a tool for managing virtual environments and running tests.

Installing tox

You can install tox with pip.

pip install tox

Using tox

When you run the tox command from within the root directory of the ChatterBot repository it will run the following tests:

  1. Tests for ChatterBot's core files.
  2. Tests for ChatterBot's integration with multiple versions of Django.
  3. Tests for each of ChatterBot's example files.
  4. Tests to make sure ChatterBot's documentation builds.
  5. Code style and validation checks (linting).
  6. Benchmarking tests for performance.

You can run specific tox environments using the -e flag. A few examples include:

# Run the documentation tests
tox -e docs
# Run the tests with Django 1.10
tox -e django110
# Run the code linting scripts
tox -e lint

To see the list of all available environments that you can run tests for:

tox -l

To run tests for all environments:


Packaging your code for ChatterBot

There are cases where developers may want to contribute code to ChatterBot but for various reasons it doesn't make sense or isn't possible to add the code to the main ChatterBot repository on GitHub.

Common reasons that code can't be contributed include:

  • Licencing: It may not be possible to contribute code to ChatterBot due to a licencing restriction or a copyright.
  • Demand: There needs to be a general demand from the open source community for a particular feature so that there are developers who will want to fix and improve the feature if it requires maintenance.

In addition, all code should be well documented and thoroughly tested.

Package directory structure

Suppose we want to create a new logic adapter for ChatterBot and add it the Python Package Index (PyPI) so that other developers can install it and use it. We would begin doing this by setting up a directory file the following structure.

Python Module Structure

|-- setup.py
|-- irony_adapter
|   |-- __init__.py
|   |-- logic.py
|-- tests
|-- |-- __init__.py
|-- |-- test_logic.py

More information on creating Python packages can be found here:https://packaging.python.org/tutorials/distributing-packages/

Register on PyPI

Create an account: https://pypi.python.org/pypi?%3Aaction=register_form

Create a .pypirc configuration file.

.pypirc file contents

index-servers =


Generate packages

python setup.py sdist bdist_wheel

Upload packages

The official tool for uploading Python packages is called twine. You can install twine with pip if you don't already have it installed.

pip install twine
twine upload dist/*

Install your package locally

cd IronyAdapter
pip install . --upgrade

Using your package

If you are creating a module that ChatterBot imports from a dotted module path then you can set the following in your chat bot.

chatbot = ChatBot(
    "My ChatBot",

Testing your code

from unittest import TestCase

class IronyAdapterTestCase(TestCase):
    Test that the irony adapter allows
    the chat bot to understand irony.

    def test_irony(self):
       # TODO: Implement test logic

0 Comment