API

Include

class faff.include.Include(path)

Include class, collects docstring and decorated rule, option functions from a python module specified by path.

path

Path to python module.

classmethod descriptions()

Return dictionary of description strings for included modules.

classmethod get_description(path)

Return description string for included module of path.

path

Path used to include module.

classmethod get_option(name)

Return included option of name.

name

Option name string.

classmethod get_rule(name)

Return included rule of name.

name

Rule name string.

classmethod options()

Return dictionary of all included options.

classmethod rules()

Return dictionary of all included rules.

Option

faff.option.option(*args, **kwargs)

Option function decorator, function and arguments used to create an Option instance.

*args

Arguments to ArgumentParser.add_argument() method.

**kwargs

Keyword arguments to ArgumentParser.add_argument() method.

faff.option.is_option(obj)

Return true if object is an option instance.

obj

Object instance.

class faff.option.Option(func, *args, **kwargs)

Option function decorator, used to add command line arguments to decorated rules in input files. This is a convenience wrapper for the .add_argument() method of ArgumentParser.

func

Decorated function.

*args

Arguments to ArgumentParser.add_argument() method.

**kwargs

Keyword arguments to ArgumentParser.add_argument() method.

add(parser)

Add self as argument to parser using name as destination key.

parser

ArgumentParser instance.

description

Return option description string.

name

Return option name string.

Targets

class faff.targets.FileTarget(*args, **kwargs)

File target class for file paths. Casting an instance to string will return the expanded file path string.

*args

File path string list.

**kwargs

Keyword arguments to base target class.

ext

File extension replacement.

copy(*path)

Copy file target to expanded path list.

path

File copy path string list.

dirname

Return the directory path of the expanded file path string.

exists()

Return true if file exists.

extension

Return file extension of target.

original_extension

Return original file extension of target.

updated(**kwargs)

Return the time in seconds when file was modified. A value of zero indicates file does not exist.

**kwargs

Optional keyword arguments to method.

class faff.targets.RuleTarget(rule, **kwargs)

Rule target for rule interdependencies. Casting an instance to string will return single spaced, concatenated target strings.

rule

Target rule instance.

**kwargs

Keyword arguments to base target class.

exists()

Return true if rule dependencies exist.

updated(**kwargs)

Return time in seconds when rule was last updated. A value of zero indicates an error condition.

**kwargs

opt_values

Dictionary of option values, used to pass values between interdependent rules.

class faff.targets.Target(**kwargs)

Base target class providing default methods for target functionality.

**kwargs

args

Optional arguments stored in target.

context

Optional variable context.

arguments

Return optional target arguments.

context

Return optional variable context.

exists()

Return true if target exists.

updated(**kwargs)

Return the time in seconds when target was last updated.

**kwargs

Optional keyword arguments to method.

Rule

faff.rule.rule(*args, **kwargs)

Rule function decorator, function and arguments used to create a Rule instance.

*args

Positional arguments to Rule class.

**kwargs

Keyword arguments to Rule class.

faff.rule.is_rule(obj)

Return true if object is a rule instance.

obj

Object instance.

class faff.rule.Rule(func, *args, **kwargs)

Default rule function decorator, decorated function is called based on the state of targets, their dependencies and other keyword arguments to the decorator.

func

Decorated function.

*args

Target arguments in a defined rule pattern.

**kwargs

depends

Optional additional dependencies applied to all rule arguments.

options

Optional decorated option functions for command line configuration.

args

Optional arguments passed to decorated function on call.

context

Optional variable context.

Decorated functions must have the arguments:

@rule(...)
def func(**kwargs):
    ...

Where keyword arguments contain the following:

target

Out of date Target instance.

depends

List of Target instance dependencies associated with target.

options

Dictionary of option decorator argument values.

args

Optional arguments passed to decorator.

Where target is an out of date Target instance, depends is a list of Target instance dependencies associated with the target, and args is the value passed to the keyword argument of the same name in the decorator.

When instance is called, rule function will run based on state of targets and dependencies, returning a boolean indicating success and results dictionary containing more information.

add_options(parser)

Add rule options to argument parser instance.

parser

Instance of ArgumentParser.

call_options(args)

Call rule options with arguments returned by argument parser.

args

Instance of argparse.Namespace.

description

Return rule description string.

exists()

Return true if rule dependencies exist.

name

Return rule name string.

targets

Return list of rule targets.

update(targets=None, depends=None, **kwargs)

Update rule targets and dependencies, serial implementation.

targets

List of out of date targets.

depends

List of lists of dependencies associated with targets.

Run

faff.run.try_run(command)

Return true if command executed without error.

faff.run.run(command, cwd, **kwargs)

Run command, uses python subprocesses to run arbitary commands, captures and displays their output on configured output streams.

command

Command string or list.

cwd

Current working directory for command.

**kwargs

hide

Do not display command output boolean, defaults to false.

text

Text displayed on configured output streams instead of command output, defaults to none.

redirect

File path to write command output, defaults to none.

context

Optional variable context.

Core

class faff.core.Core(name='faff', version='0.2.4', licence='Public Domain', author='mojzu', description='Make build tool substitute written in Python.', stdout=None, stderr=None)

Package core class, provides properties and methods for getting information, configuring and displaying output. Initialisation arguments may be used to override the defaults. Calling an instance of this class will reinitialise using new positional and keyword arguments.

name

Package name string.

version

Package version string.

licence

Package licence string.

author

Package author string.

description

Package description string.

stdout

Standard output stream, defaults to wrapped stdout provided by colorama. If false output is hidden.

stderr

Standard error stream, defaults to wrapped stderr provided by colorama. If false output is hidden.

author

Return package author string.

configure(args)

Configure instance using namespace returned by command line argument parser argparse which may have the following attributes:

log_level

Logging level string.

log_file

Logging file path.

debug(name, fmt, *args)

Log formatted debug message to configured logger instance.

name

Module name string.

fmt

Format string.

*args

Format string positional arguments.

default_input_file

Return absolute default input file path string.

description

Return package description string.

error(name, fmt, *args)

Log formatted error message to configured logger instance.

name

Module name string.

fmt

Format string.

*args

Format string positional arguments.

exception(fmt, *args, **kwargs)

Raise exception with formatted message string.

fmt

Format string.

*args

Format string positional arguments.

**kwargs

cls

Exception class, defaults to FaffError.

info(name, fmt, *args)

Log formatted informational message to configured logger instance.

name

Module name string.

fmt

Format string.

*args

Format string positional arguments.

licence

Return package licence string.

name

Return package name string.

static normalise_list(value=None)

Return value as list.

stderr(fmt, *args, **kwargs)

Write formatted string to configured standard error stream:

fmt

Format string.

*args

Format string positional arguments.

**kwargs

raw

If true the package name is not prepended to the output, defaults to false.

style

Colorama styles for output.

stdout(fmt, *args, **kwargs)

Write formatted string to configured standard output stream:

fmt

Format string.

*args

Format string positional arguments.

**kwargs

raw

If true the package name is not prepended to the output, defaults to false.

style

Colorama styles for output.

version

Return package version string.

warning(name, fmt, *args)

Log formatted warning message to configured logger instance.

name

Module name string.

fmt

Format string.

*args

Format string positional arguments.

Main

faff.main.main(argv=['-b', 'html', '-d', '_build/doctrees', '.', '_build/html'], **kwargs)

Main command line interface.

argv

Command line arguments list excluding script name.

**kwargs

Keyword arguments to internal package core configuration.

faff.main.version_argument(parser, core=<faff.core.Core object>)

Version information command line option, allows override of the core class instance where required.

parser

Instance of ArgumentParser.

core

Package core instance.

faff.main.logging_arguments(parser, core=<faff.core.Core object>)

Logging command line arguments, allows override of the core class instance where required.

parser

Instance of ArgumentParser.

core

Package core instance.

faff.main.target_arguments(parser, targets=None)

Target command line arguments.

parser

Instance of ArgumentParser.

Exceptions

exception faff.exceptions.FaffError(message)

Base package error class.

message

Error message string.

message

Return error message string.

Extensions

Change Log

class faff.ext.changelog.ChangeLogMessage(raw, warn=True)

Change log commit message format.

raw

Raw input commit message string supplied by change log.

warn

Log warning message for unknown parsed categories or audiences. Defaults to true.

By default the following commit message format is supported:

<category>(<audience>): <subject>

<body>

Custom formats can be supported by creating a subclass which overrides the class variables: CATEGORIES, AUDIENCES, TITLES. And the method .split_subject.

audience

Return commit message audience string.

classmethod audience_valid(audience)

Return true if audience is valid.

author

Return commit message author string.

body

Return commit message body string.

category

Return commit message category string.

classmethod category_valid(category)

Return true if category is valid.

date

Return commit message date object.

classmethod format()

Return git format argument.

classmethod format_separator()

Return format separator to split text into individual commits.

hash

Return commit message hash string.

split_subject(raw)

Return category, audience and subject tuple from input. If categorory or audience can not be found none is returned at their tuple index.

raw

Raw subject line string.

subject

Return commit message subject string.

classmethod title(key)

Return title for key.

class faff.ext.changelog.ChangeLog(path, options={}, message_cls=<class 'faff.ext.changelog.ChangeLogMessage'>)

Change log generation using Git version control commit messages.

path

Absolute path to git repository.

options

Dictionary of command line options.

changelog_release

Optional name of release to to use for untagged commits.

changelog_warn

Optionally disable warnings about unknown parsed message categories and audiences.

changelog_template

Optional override of template file used to generate change log.

changelog_title

Optional override of generated change log title.

message_cls

Message format class, defaults to ChangeLogMessage.

classmethod release_option(flag='--changelog-release')

Return change log release command line option.