doit-py - documentation


doit tasks for python stuff

Project Details

module: pyflakes

Helper to create tasks that execute pyflakes.

Example to create a task for every python module (found recursively from current path), excluding test modules and also doc/

from doitpy.pyflakes import Pyflakes

def task_pyflakes():
    flaker = Pyflakes(exclude_patterns=['test_*'])
    yield flaker.tasks('**/*.py', exclude_paths=['doc/'])
class doitpy.pyflakes.Pyflakes(**kwargs)[source]

generate tasks for pyflakes

config = Config({'base_dir': '.', 'exclude_paths': [], 'exclude_patterns': []})


  • base_dir (str) – list of path patterns of files to be linted
  • exclude_patterns (list-str) – list of pattern of files to be removed from selection
  • exclude_paths (list-str) – list of path of files to be removed from selection
Parameters:kwargs – config params

Return a task for single file.

Parameters:pyfile (str) – path to file
Returns:task metadata to run pyflakes on a single module
tasks(pattern, **kwargs)[source]

run pyflakes on python module

yield one task for each file as given by pattern

Parameters:pattern (str) – path pattern of files to be linted

module: coverage

create tasks for

Add coverage related tasks to

from doitpy.coverage import Coverage, PythonPackage

def task_coverage():
    """show coverage for all modules including tests"""
    cov = Coverage([PythonPackage('my_pkg_name', 'tests')],
                   config={'branch':False, 'parallel':True,
                           'omit': ['tests/']},
    yield cov.all() # create task `coverage`
    yield cov.src() # create task `coverage_src`
    yield cov.by_module() # create tasks `coverage_module:<path/to/test>`
class doitpy.coverage.PythonModule(path, test_path)[source]

reference to a single python module / test for the module

  • src (list-str) – list of path of source modules
  • test (list-str) – list of path of all modules from test folder
__init__(path, test_path)[source]
  • path (str/pathlib.Path) – path to python module.
  • test_path (str/pathlib.Path) – path to module with tests.
class doitpy.coverage.PythonPackage(path, test_path=None, config=None)[source]

Contain list of modules of the package (does not handle sub-packages)

  • src_dir (str) – path to dir containing package modules
  • test_dir (str) – path to dir containing package tests
  • src (list-str) – list of path of source modules
  • test (list-str) – list of path of all modules from test folder
config = Config({'pkg_test_dir': 'tests', 'test_prefix': 'test_'})


  • test_prefix (str) – string prefix on name of files
  • pkg_test_dir (str) – path to location of test files
__init__(path, test_path=None, config=None)[source]
  • path (str/pathlib.Path) – dir path to package.
  • test_path (str/pathlib.Path) – if test_path is not given assume it is on config.pkg_test_dir inside source package.

Yield all source and test modules.

class doitpy.coverage.Coverage(pkgs, config=None)[source]

generate tasks for

config = Config({'branch': True, 'cmd_run_test': '`which py.test`', 'concurrency': '', 'omit': [], 'parallel': False})


  • cmd_run_test (string) – shell command used to run tests
  • bool (parallel) – measure branche coverage
  • bool – measure using –parallel-mode (needed for subprocess and multiprocess coverage
  • str (concurrency) – –concurrency library
  • omit (list-str) – list of paths to omit from coverage
__init__(pkgs, config=None)[source]
Parameters:pkgs (list-PythonFiles) – packages/modules to measure coverage

show coverage for all modules including tests


show coverage for all modules (exclude tests)


show coverage for individual modules

module: docs

create tasks related to documentation generation

Example to create tasks to:
  • spell check all restructured text files (including README)
  • build sphinx docs in doc folder
  • upload built sphinx docs to pythonhosted using setuptools
def task_docs():
    doc_files = glob.glob('doc/*.rst') + ['README.rst']
    yield docs.spell(doc_files, 'doc/dictionary.txt')
    yield docs.sphinx('doc/', 'doc/_build/html/', task_dep=['spell'])
    yield docs.pythonhosted_upload('doc/_build/html/', task_dep=['sphinx']), dictionary)[source]

spell checker for doc files

  • files (list-str) – list of files to spell check
  • dictionary (str) – path of dictionary with extra words, build_path, sphinx_opts='', task_dep=None)[source]

build sphinx docs

  • root_path (str) – root path of sphinx docs
  • build_path (str) – path generated sphinx docs will be saved in
  • sphinx_opts (str) – sphinx-build command line options
  • task_dep (list-str) – list of tasks this task will depend on, task_dep)[source]

deploy website (sphinx docs)

  • www_path (str) – path to folder containig www files
  • task_dep (list-str) – list of tasks this task will depend on

module: package

tasks to create python distribution packages (distutils/setuptools)

  • create a file with all tracked files in a git repo
  • upload an sdist package
from doitpy.package import Package

def task_package():
    pkg = Package()
    yield pkg.manifest_git()  # package:manifest
    yield pkg.sdist()         # package:sdist
    yield pkg.sdist_upload()  # pypi:sdist_upload
class doitpy.package.Package[source]

helper to create tasks to upload a python package to PyPi


create file with repo rev number


create file for distutils/setuptools

Put all files being tracked by git into the manifest


create sdist package


upload sdist package to pypi