Metadata-Version: 1.1
Name: coveralls
Version: 1.1
Summary: Show coverage stats online via coveralls.io
Home-page: http://github.com/coagulant/coveralls-python
Author: Ilya Baryshev
Author-email: baryshev@gmail.com
License: MIT
Description: Coveralls for python
        ====================
        
        .. image:: https://img.shields.io/coveralls/coagulant/coveralls-python.svg
            :target: https://coveralls.io/r/coagulant/coveralls-python
        
        .. image:: https://img.shields.io/travis/coagulant/coveralls-python/master.svg
            :target: https://travis-ci.org/coagulant/coveralls-python
        
        .. image:: https://img.shields.io/pypi/v/coveralls.svg
            :target: https://pypi.python.org/pypi/coveralls
        
        .. image:: https://img.shields.io/pypi/pyversions/coveralls.svg
            :target: https://pypi.python.org/pypi/coveralls/
        
        .. image:: https://img.shields.io/pypi/dd/coveralls.svg
            :target: https://pypi.python.org/pypi/coveralls/
        
        `Coveralls.io`_ is service to publish your coverage stats online with a lot of `nice features`_.
        This package provides seamless integration with ``coverage.py`` in your python projects.
        
        .. _Coveralls.io: http://coveralls.io
        .. _nice features: https://coveralls.io/features
        
        How it works
        ------------
        It makes custom report for data generated by ``coverage.py`` package and sends it to `json API`_ of coveralls.io service.
        All python files in your coverage analysis are posted to this service along with coverage stats,
        so please make sure you're not ruining your own security! For private projects there is `Coveralls Pro`_.
        
        .. _json API: https://coveralls.io/docs/api_reference
        .. _Coveralls Pro: https://coveralls.io/docs/pro
        
        Usage (Travis CI)
        -----------------
        
        This package works with any CI environments. Instructions for `Travis CI`_:
        
        1. Log in and `add your repo`_ on Coveralls website.
        2. Add ``pip install coveralls`` to ``install`` section of ``.travis.yml``
        3. Make sure you run your tests with coverage during the build in ``script`` part. Example::
        
            # --source specifies what packages to cover, you probably want to use that option
            script:
              coverage run --source=yourpackagename setup.py test
        
           Note, that example command will gather coverage for specified package.
           If you wish to customize what's included in your reports, consult `coverage docs`_.
        
        .. _coverage docs: http://nedbatchelder.com/code/coverage/
        
        4. Execute run ``coveralls`` in ``after_success`` section::
        
            after_success:
              coveralls
        
        Full example of .travis.yml::
        
            language: python
            python:
              - 2.7
              - 3.3
            install:
              - pip install -r requirements.txt
              - pip install coveralls
            script:
              coverage run --source=moscowdjango,meetup manage.py test
            after_success:
              coveralls
        
        Usage (Tox >= v2.0)
        ~~~~~~~~~~~~~~~~~~~
        
        Running coveralls from within a `tox`_ environment (`tox`_ v2.0 and above)
        on Travis CI (or Circle CI or Codeship) requires one extra step:
        
        Pass the environment variables ``TRAVIS``, ``TRAVIS_JOB_ID``, ``TRAVIS_BRANCH`` to all tox environments
        that submit the coverage report.
        
        Example of tox.ini::
        
            [tox]
            envlist = py27,py33,py34
        
            [testenv]
            passenv = TRAVIS TRAVIS_JOB_ID TRAVIS_BRANCH
            deps = 
                coveralls
            commands =
                coverage run --source=yourpackagename setup.py test
                coveralls
        
        Circle CI users should pass ``CIRCLE_BRANCH``, Codeship users - ``CI_BRANCH``.
        
        .. _tox: https://testrun.org/tox/latest/
        
        Usage (another CI)
        ~~~~~~~~~~~~~~~~~~
        
        The difference from Travis is coveralls authentication via repo token.
        Circle CI is supported since version 1.1, so no need to add env variables.
        It's required to set environment variable ``COVERALLS_REPO_TOKEN`` in you CI build.
        This is your own secret token, which is available at the right sidebar of your repository's page on Coveralls.
        Launch ``coveralls`` after gathering python coverage in your build script.
        
        Example::
        
            coverage run --source=myapp setup.py test
            COVERALLS_REPO_TOKEN=tGSdG5Qcd2dcQa2oQN9GlJkL50wFZPv1j coveralls
        
        .. _add your repo: https://coveralls.io/repos/new
        .. _Travis CI: http://travis-ci.org
        
        Multiple languages (experimental)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Tracking multi-language repo coverage requires extra setup of merging coverage data for submission.
        If you already have json file from coveralls library from another language (example from `coveralls-lcov`_)::
        
            # Generate data with lcov
            lcov --compat-libtool --directory . --capture --output-file coverage.info
        
            # Or: generate data with mocha
            mocha --reporter mocha-lcov-reporter */tests/static/js/* > coverage.info
        
            # Convert data with coveralls-lcov
            coveralls-lcov -v -n coverage.info > coverage.json
        
            # Merge python coverage with coveralls-style json file and send it to api endpoint
            # Note: This file must contain "source_files" data or it will not be merged
            coveralls --merge=coverage.json
        
        If you'd like to just use json data from coveralls (with other tools)::
        
            coveralls --output=coverage.json  # output single json with python coverage in coveralls format
        
        .. _coveralls-lcov: https://github.com/okkez/coveralls-lcov
        
        Tips for .coveragerc config
        ---------------------------
        
        This section is a list of most common options for coverage.py, which collects all the data.
        Coveralls feeds from this data, so it's good to know `how to to configure coverage.py`_.
        
        To limit the `report with only your packages`_, specify their names (or directories)::
        
            [run]
            source = pkgname,your_otherpackage
        
        To exclude parts of your source from coverage, for example migrations folders::
        
            [report]
            omit = */migrations/*
        
        Some lines are never executed in your tests, but that can be ok. 
        To mark those lines use inline comments right in your source code::
        
            if debug:   # pragma: no cover
                msg = "blah blah"
                log_message(msg, a)
        
        Sometimes it can be tedious to mark them in code, so you can `specify whole lines to .coveragerc`_::
        
            [report]
            exclude_lines =
                pragma: no cover
                def __repr__
                raise AssertionError
                raise NotImplementedError
                if __name__ == .__main__.:
        
        Finally, if you're using non-default configuration file, specify it to coveralls command::
        
            $ coveralls --rcfile=<file>
        
        .. _how to to configure coverage.py: http://nedbatchelder.com/code/coverage/config.html
        .. _report with only your packages: http://nedbatchelder.com/code/coverage/source.html#source
        .. _specify whole lines to .coveragerc: http://nedbatchelder.com/code/coverage/excluding.html
        
        
        Nosetests
        ~~~~~~~~~
        
        `Nosetests`_ provide a plugin for coverage measurement of your code::
        
            $ nosetests  --with-coverage --cover-package=<your_package_name>
        
        However, it gathers coverage for all executed code, ignoring ``source`` config option in ``.coveragerc``.
        It means, that ``coveralls`` will report unnecessary files, which is inconvenient.
        Here is a workaround, use ``omit`` option in your ``.coveragerc`` to specify a list of filename patterns,
        the files to leave out of reporting (your paths might differ) ::
        
            [report]
            omit =
                */python?.?/*
                */site-packages/nose/*
        
        Note, that native coverage.py and py.test are not affected by this problem and do not require this workaround.
        
        .. _Nosetests: http://nose.readthedocs.org/en/latest/plugins/cover.html
        
        
        Troubleshooting
        ---------------
        
        In case your coverage is not submitted to coveralls.io, despite your best efforts to configure,
        you can use debug::
        
            $ coveralls debug
        
        Debug mode doesn't send anything, just outputs prepared json and reported files list to stdout.
        
        
        Contributing
        ------------
        
        Run tests::
        
            $ python setup.py test
        
        
        
        Changelog
        ---------
        
        1.1 (2015-10-04)
        ~~~~~~~~~~~~~~~~
        * Suupport for Circle CI
        
        1.0 (2015-09-17)
        ~~~~~~~~~~~~~~~~
        * Official coverage 4.0 support
        
        1.0b1 (2015-08-14)
        ~~~~~~~~~~~~~~~~~~
        * Coverage 4 beta support
        * Codeship experimetal support (CI_BRANCH env variable)
        * Drop python 3.2 support (as coverage 4 does not support it)
        * Repo token usage is deprecated (but still supported) in favor of env variable.
        * Error reporting is improved, exist status codes added
        
        1.0a2 (2015-02-19)
        ~~~~~~~~~~~~~~~~~~
        * Fix latest alpha coverage.py support
        * Remove erroneous warning message when writing output to a file
        
        1.0a1 (2015-02-19)
        ~~~~~~~~~~~~~~~~~~
        * **Backwards incompatible**: make pyyaml optional. If you're using .coveralls.yml, make sure to install coveralls[yaml]
        * Coverage 4 alpha support
        * Allow debug and output options to work without repo_token
        * Fix merge command for python 3.X
        
        0.5 (2014-12-10)
        ~~~~~~~~~~~~~~~~
        * Add option --output=<file> for saving json to file for possible merging with coverages from other languages
        * Add merge command for sending coverage stats from multiple languages
        
        0.4.4 (2014-09-28)
        ~~~~~~~~~~~~~~~~~~
        * Proper fix coverage.py dependency version
        
        0.4.3 (2014-09-28)
        ~~~~~~~~~~~~~~~~~~
        * Fix coverage.py dependency version
        
        0.4.2 (2014-05-05)
        ~~~~~~~~~~~~~~~~~~
        * Handle 503 errors from coveralls.io
        
        0.4.1 (2014-01-15)
        ~~~~~~~~~~~~~~~~~~
        * Fix gitlog output with utf8
        
        0.4 (2013-12-27)
        ~~~~~~~~~~~~~~~~
        * Added support for --rcfile=<file> option to cli
        * Improved docs: nosetests and troubleshooting sections added
        * Added debug in case of UnicodeDecodeError
        * Removed sh dependency in favor of Windows compatibility
        
        0.3 (2013-10-02)
        ~~~~~~~~~~~~~~~~
        * Added initial support for Circle CI
        * Fixed Unicode not defined error in python 3
        
        0.2 (2013-05-26)
        ~~~~~~~~~~~~~~~~
        * Python 3.2 and PyPy support
        * Graceful handling of coverage exceptions
        * Fixed UnicodeDecodeError in json encoding
        * Improved readme
        
        0.1.1 (2013-02-13)
        ~~~~~~~~~~~~~~~~~~
        * Introduced COVERALLS_REPO_TOKEN environment variable as a fallback for Travis
        * Removed repo_token from verbose output for security reasons
        
        0.1 (2013-02-12)
        ~~~~~~~~~~~~~~~~
        * Initial release
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Testing
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python :: Implementation :: CPython
