tox-travis: Integrate tox and Travis¶
tox-travis is a plugin for tox that simplifies the setup between tox and Travis.
Usage¶
Configure the Python versions to test with in .travis.yml
,
and install tox-travis
with pip:
language: python
python:
- "3.6"
- "3.7"
install: pip install tox-travis
script: tox
tox will only run the py36
or py37
env
(or envs that have a factor that matches)
as appropriate for the version of Python
that is being run by each Travis job.
Topics¶
Env Detection¶
Env detection is the primary feature of Tox-Travis.
Based on the matrix created in .travis.yml
,
it decides which Tox envs
need to be run for each Travis job.
Usage¶
Configure the Python versions to test with in .travis.yml
:
language: python
python:
- "3.6"
- "3.7"
install: pip install tox-travis
script: tox
And it will run the appropriate testenvs,
which by default are any declared env with
py36
or py37
as factors of the name.
If no environments match a given factor,
the py36
or py37
envs are used as a fallback.
Advanced Configuration¶
To customize what environments tox will run on Travis,
add a section to tox.ini
telling it what environments
to run under which versions of Python:
[tox]
envlist = py{36,37}-django{21,22}, docs
[travis]
python =
3.6: py36
3.7: py37, docs
This would run the Python 3.6 variants under 3.6,
and the Python 3.7 variants and the docs
env under 3.7.
Note that Travis won’t run all the envs simultaneously, because its build matrix is only aware of the Python versions. Only one Travis build will be run per Python version, unless other settings are specified in the Travis build matrix.
If you are using multiple Travis factors,
then you can use those factors to decide what will run.
For example, see the following .travis.yml
and tox.ini
:
language: python
python:
- "3.6"
- "3.7"
env:
- DJANGO="2.1"
- DJANGO="2.2"
matrix:
include:
- os: osx
language: generic
install: pip install tox-travis
script: tox
[tox]
envlist = py{36,37}-django{21,22}, docs
[travis]
os =
linux: py{36,37}-django{21,22}, docs
osx: py{36,37}-django{21,22}
python =
3.7: py37, docs
[travis:env]
DJANGO =
2.1: django21
2.2: django22, docs
Travis will run 5 different jobs, which will each run jobs as specified by the factors given.
os: linux (default), language: python, python: 3.6, env: DJANGO=2.1
This will run the env
py36-django21
, becausepy36
is the default, anddjango21
is specified.os: linux (default), language: python, python: 3.7, env: DJANGO=2.2
This will run the env
py37-django22
, but notdocs
, becausedocs
is not included in the DJANGO 2.2 configuration.os: linux (default), language: python, python: 3.6, env: DJANGO=2.1
This will run the env
py36-django21
, becausepy36
is the default.docs
is not run, because Python 3.6 doesn’t includedocs
in the defaults that are not overridden.os: linux (default), language: python, python: 3.7, env: DJANGO=2.2
This will run the envs
py37-django22
anddocs
, because all specified factors match, anddocs
is present in all related factors.os: osx, language: generic
This will run envs
py36-django21
,py37-django21
,py36-django22
, andpy37-django22
, because theos
factor is present, and limits it to just those envs.
Unignore Outcomes¶
By default, when using ignore_outcome
in your Tox configuration,
any build errors will show as successful on Travis. This might not
be desired, as you might want to control allowed failures inside your
.travis.yml
. To cater this need, you can set unignore_outcomes
to True
. This will override ignore_outcome
by setting it to
False
for all environments.
Configure the allowed failures in the build matrix in your .travis.yml
:
matrix:
allow_failures:
- python: 3.6
env: DJANGO=master
And in your tox.ini
:
[travis]
unignore_outcomes = True
After All¶
Deprecated since version 0.10.
Warning
This feature is deprecated.
Travis has added Build Stages, which are a better solution to this problem. You will also likely want to check out Conditions, which make it much easier to determine which jobs, stages, and builds will run.
Inspired by travis-after-all and travis_after_all, this feature allows a job to wait for other jobs to finish before it calls itself complete.
There are three environment variables that can be used to configure this feature.
GITHUB_TOKEN
. This is required, and should be encrypted in the.travis.yml
, or set securely in the repository settings. This is used as the authentication method for the Travis CI API.TRAVIS_POLLING_INTERVAL
. How often, in seconds, we should check the API to see if the rest of the jobs have completed. Defaults to 5.TRAVIS_API_URL
. The base URL to the Travis API for this build. This defaults tohttps://api.travis-ci.org
. A common override will be to the commercial version, athttps://api.travis-ci.com
.
Configure which job to wait on by adding
the [travis:after]
section to the tox.ini
file.
The travis
key looks for values that would be keys
in various items in the [travis]
section,
and the env
key looks for values that would be keys
in items in the [travis:env]
section.
For example:
[travis:after]
travis = python: 3.5
env = DJANGO: 1.8
Then run tox
in your test command like this:
tox --travis-after
For example, consider this mocked up .travis.yml
,
that corresponds to using the above travis:after
section:
language: python
python:
- "2.7"
- "3.5"
env:
global:
- GITHUB_TOKEN='spamandeggs' # Make sure this is encrypted!
matrix:
- DJANGO="1.7"
- DJANGO="1.8"
install: pip install tox-travis
script: tox --travis-after
deploy:
provider: pypi
user: spam
password: eggs # Make sure to encrypt passwords!
on:
tags: true
python: 3.5
condition: $DJANGO = "1.8"
distributions: sdist bdist_wheel
This example deploys when the build is from a tag
and the build is on Python 3.5
and the build is using DJANGO=”1.8”.
Together tox --travis-after
and Travis’ on
conditions
make sure that the deploy only happens after all tests pass.
If any configuration item does not match, or if no configuration is given, this will run exactly as it would normally. However, if the configuration matches the current job, then it will wait for all the other jobs to complete before it will be willing to return a success return code.
If the tests fail, then it will not bother waiting, but will rather return immediately. If it determines that another required job has failed, it will return an error indicating that jobs failed.
You can use this together with a deployment configuration to ensure that this job is the very last one to complete, and will only be successful if all others are successful, so that you can be more confident that you are shipping a working release.
The accepted configuration keys
in the [travis:after]
section are:
envlist
. Match with the running toxenvs. Expansion is allowed, and if set all environments listed must be run in the current Tox run.travis
. Match with known Travis factors, as is done in the[travis]
section. For instance, specifying that we should wait when python is version 2.7 would look liketravis = python: 2.7
.env
. Match with environment variable factors, as might be specified in the[travis:env]
section. For instance, if we want to match thatDJANGO
is1.9
, then it would look likeenv = DJANGO: 1.9
. The value must match exactly to succeed.
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/tox-dev/tox-travis/issues. If you are reporting a bug, please include:
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.
Write Documentation¶
Tox Travis could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/tox-dev/tox-travis/issues. If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up tox-travis for local development.
Fork the tox-travis repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/tox-travis.git
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass the tests, including testing other Python versions with tox:
$ tox
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 2.7 and 3.4+ and for PyPy, PyPy3. Check https://travis-ci.org/tox-dev/tox-travis/pull_requests and make sure that the tests pass for all supported Python versions.
Changelog¶
0.13¶
- Add Python 3.7 support in trove classifiers.
0.12 (2019-03-14)¶
- Fix reading envlist from
setup.cfg
(#110). - thanks to @voronind for the pull request. - Add docs and tests to sdist (#121). - thanks to @jayvdb for the pull request.
- Release an sdist in addition to the wheel.
0.11 (2018-09-21)¶
- Drop support for Python 3.2 and 3.3 (#113).
- Fix autogen_configs for tox 3.4.0 (#115).
- Various documentation fixes.
0.10 (2017-11-13)¶
- Deprecate the After All feature (#93). Travis now has Build Stages, which are a better solution.
0.9 (2017-11-12)¶
- Allow PyPy3 support to work with PyPy3 5.5 (#66). - thanks to @kirbyfan64 for the pull request.
- Move toxenv to tox_configure hook (#78). - thanks to @rpkilby for the pull request demonstrating the idea.
- Respect Tox config file CLI option (#59). - thanks to @giginet for the bug report.
- Move the project into the
tox-dev
GitHub organization. - thanks to @obestwalter for bringing it up, and @rpkilby for helping fix references to the old location. - Various refactors and test improvements. - thanks to @jdufresne for several pull requests and @rpkilby for many reviews.
- Only deploy the universal wheel to PyPI (#87). Due to a deployment bug, a version-specific egg was released, along with the intended sdist and wheel. The sdist has also been abandoned for release.
0.8 (2017-01-11)¶
- Add Python 3.6 support in trove classifiers.
- Skip after waiting for pull requests (#46). - thanks to @rpkilby for fixing this bug.
- Add
unignore_outcomes
setting to allow reversing Tox’signore_outcomes
setting on Travis (#48). - thanks to @Bouke for the implementation.
0.7.2 (2016-12-20)¶
- Undo the README changes, and fix HISTORY markup for PyPI.
0.7.1 (2016-12-20)¶
- Fix the README markup to display properly on PyPI.
0.7 (2016-12-20)¶
- Deprecate the
[tox:travis]
section in favor of thepython
key to the new[travis]
section. - Allow specifying envs by other Travis factors.
Includes
os
,language
, andpython
. - Allow specifying envs for environment variables,
in a new
[travis:env]
section. - Special thanks to @rpkibly for driving this work (#34)
- Backward incompatible changes:
- If any declared tox envs match the envs matched from factors,
no additional envs will be included automatically.
For example, if
envlist
isdocs
, and the configuration for python 3.4 ispy34, docs
, it previously would have run both the declareddocs
env, as well as the undeclaredpy34
env, while now it will only run the declareddocs
env. This may result in fewer envs running than expected, but in edge cases that were believed to be unlikely. - Previously, if no Python version was given in the environment, it would automatically choose an appropriate env based on the Python version running. Now if no Python version is given in the environment no env is determined by default, which may result in more envs running in a job than expected.
- If any declared tox envs match the envs matched from factors,
no additional envs will be included automatically.
For example, if
- Add the
--travis-after
command to enable a job to wait until all others have completed. (#13) - thanks to @ssbarnea for the feature suggestion.
0.6 (2016-10-13)¶
- Require pytest<3 for Python 3.2 (#33)
0.5 (2016-07-28)¶
- Prefer
TRAVIS_PYTHON_VERSION
to sys.version_info (#14) - thanks to @jayvdb for the code review - Add Python 3.2 support (#17) - thanks to @jayvdb for the bug report, discussion, and code review
- Support PyPy3 v5.2 with setuptools hackery (#24) - thanks to @jayvdb for the pull request
0.4 (2016-02-10)¶
- Generate default env from sys.version_info (#9) - thanks to @jayvdb for the bug report
0.3 (2016-01-26)¶
- Match against testenvs that are only declared as sections (#7) - thanks to @epsy
- Include unmatched envs verbatim to run (also #7) - thanks to @epsy again
0.2 (2015-12-10)¶
- Choose testenvs from
tox.ini
by matching factors.- This is a slightly backward incompatible change
- If a Python version isn’t declared in the
tox.ini
, it may not be run. - Additional envs may be run if they also match the factors,
for example,
py34-django17
andpy34-django18
will both match the default for Python 3.4 (py34
). - Factor matching extends to overrides set in
tox.ini
.
0.1 (2015-05-21)¶
- Initial Release
License¶
The MIT License (MIT)
Copyright (c) 2015 Ryan Hiebert
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.