doit-py - documentation

Intro

doit tasks for python stuff

Project Details

• Source code & Project management on github - https://github.com/pydoit/doit-py
• Website & docs - http://pythonhosted.org/doit-py
• Discussion group - https://groups.google.com/forum/#!forum/python-doit
• MIT license

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/conf.py.

from doitpy.pyflakes import Pyflakes

def task_pyflakes():
    flaker = Pyflakes(exclude_patterns=['test_*'])
    yield flaker.tasks('**/*.py', exclude_paths=['doc/conf.py'])

class doitpy.pyflakes.Pyflakes(**kwargs)

generate tasks for pyflakes

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

confclass.Config

Variables:

• 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

__init__(**kwargs)

Parameters:kwargs – config params

__call__(py_file)

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)

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 coverage.py

Add coverage related tasks to dodo.py:

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/no_cover.py']},
                   )
    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)

reference to a single python module / test for the module

Variables:

• 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)

Parameters:

• 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)

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

Variables:

• 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_'})

confclass.Config

Variables:

• 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)

Parameters:

• 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.

all_modules()

Yield all source and test modules.

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

generate tasks for coverage.py

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

confclass.Config

Variables:

• 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)

Parameters:pkgs (list-PythonFiles) – packages/modules to measure coverage

all(basename='coverage')

show coverage for all modules including tests

src(basename='coverage_src')

show coverage for all modules (exclude tests)

by_module(basename='coverage_module')

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'])

doitpy.docs.spell(files, dictionary)

spell checker for doc files

Parameters:

• files (list-str) – list of files to spell check
• dictionary (str) – path of dictionary with extra words

doitpy.docs.sphinx(root_path, build_path, sphinx_opts='', task_dep=None)

build sphinx docs

Parameters:

• 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

doitpy.docs.pythonhosted_upload(www_path, task_dep)

deploy website (sphinx docs)

Parameters:

• 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)

Example:

• create a MANIFEST.in 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

helper to create tasks to upload a python package to PyPi

revision_git(file_name='revision.txt')

create file with repo rev number

manifest_git()

create MANIFEST.in file for distutils/setuptools

Put all files being tracked by git into the manifest

sdist()

create sdist package

sdist_upload()

upload sdist package to pypi