You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

Porting Guide

Boto supports Python versions 2.6, 2.7, 3.3, and 3.4. Python 3 support is on a per-module basis. This guide will help you to get started porting a Boto module to Python 3.

Please read the Contributing Guide before getting started.

Compat Module

Boto ships with a boto.compat module that helps to abstract the differences between Python versions. A vendored version of the six module is exposed through boto.compat.six, as well as a handful of moved functions used throughout the codebase:

# Import the six module
from boto.compat import six

# Other useful imports
from boto.compat import BytesIO, StringIO
from boto.compat import http_client
from boto.compat import urlparse

Please check the boto.compat module before writing your own logic around specialized behavior for different Python versions. Feel free to add new functionality here, too.

Porting Steps

Please follow the following steps when porting a module:

  • Install Python versions and pip install tox

  • Port your module to support Python 3. These help:

  • Whitelist your module’s unit tests in tests/

  • Make sure unit tests pass by running tox

  • Try running integration tests:

    tox tests/integration/yourmodule
    # You can also run against a specific Python version:
    tox -e py26 tests/integration/yourmodule
  • Fix any failing tests. This is the fun part!

  • If code you modified is not covered by tests, try to cover it with existing tests or write new tests. Here is how you can generate a coverage report in cover/index.html:

    # Run a test with coverage
    tox -e py33 -- default --with-coverage --cover-html --cover-package boto
  • Update README.rst and docs/source/index.rst to label your module as supporting Python 3

  • Submit a pull request!

Note: We try our best to clean up resources after a test runs, but you should double check that no resources are left after integration tests run. If they are, then you will be charged for them!