Modules

What did you do last week, month, year?

Comfortably gather status report data (e.g. list of committed changes) for given week, month, quarter, year or selected date range. By default all available stats for this week are reported. Detailed documentation available at http://did.readthedocs.org/.

The stats module contains the core of the stats gathering functionality. Some basic functionality like exceptions, config, user and date handling is placed in the base module. Generic utilities can be found in the utils module. Option parsing and other command line stuff resides in the cli module.

stats

Stats & StatsGroup, the core of the data gathering

class did.stats.EmptyStats(option, name=None, parent=None, user=None)

Custom stats group for header & footer

fetch()

Nothing to do for empty stats

show()

Name only for empty stats

class did.stats.EmptyStatsGroup(option, name=None, parent=None, user=None)

Header & Footer stats group

class did.stats.Stats(option, name=None, parent=None, user=None, options=None)

General statistics

add_option(group)

Add option for self to the parser group object.

check()

Check the stats if enabled.

dest = None
enabled()

Check whether we’re enabled (or if parent is).

fetch()

Fetch the stats (to be implemented by respective class).

header()

Show summary header.

merge(other)

Merge another stats.

name

Use the first line of docs string unless name set.

option = None
parent = None
show()

Display indented statistics.

stats = None
class did.stats.StatsGroup(option, name=None, parent=None, user=None, options=None)

Stats group

add_option(parser)

Add option group and all children options.

check()

Check all children stats.

fetch()

Stats groups do not fetch anything

merge(other)

Merge all children stats.

order = 500
show()

List all children stats.

class did.stats.UserStats(user=None, options=None)

User statistics in one place

add_option(parser)

Add options for each stats group.

base

Config, Date, User and Exceptions

class did.base.Config(config=None, path=None)

User config file

email

User email(s)

static example()

Return config example

item(section, it)

Return content of given item in selected section

parser = None
static path()

Detect config file path

section(section, skip=None)

Return section items, skip selected (type/order by default)

sections(kind=None)

Return all sections (optionally of given kind only)

width

Maximum width of the report

exception did.base.ConfigError

Stats configuration problem

exception did.base.ConfigFileError

Problem with the config file

class did.base.Date(date=None)

Date parsing for common word formats

static last_month()

Return start and end date of this month.

static last_quarter()

Return start and end date of this quarter.

static last_week()

Return start and end date of the last week.

static last_year()

Return start and end date of the last fiscal year

static period(argument)

Detect desired time period for the argument

static this_month()

Return start and end date of this month.

static this_quarter()

Return start and end date of this quarter.

static this_week()

Return start and end date of the current week.

static this_year()

Return start and end date of this fiscal year

exception did.base.GeneralError

General stats error

exception did.base.OptionError

Invalid command line

exception did.base.ReportError

Report generation error

class did.base.User(email, stats=None)

User information

The User object holds name, login and email which are used for performing queries by individual plugins. This information is parsed from given email address. Both short & full email format are supported:

some@email.org
Name Surname <some@email.org>

In addition, it’s possible to provide email and login aliases for individual stats. This is useful if you use different email/login for different services. The syntax consists of stats: login or stats: email pairs appended at the end of the email address:

some@email.org; bz: bugzilla@email.org; gh: githublogin

Use config section name to identify stats where given alias should be used. The exactly same syntax can be used both in the config file and on the command line. Finally it’s also possible to include the alias directly in the respective config section:

[github]
type = github
url = https://api.github.com/
login = psss
alias(aliases, stats)

Apply the login/email alias if configured.

clone(stats)

Create a user copy with alias enabled for given stats.

utils

Logging, config, constants & utilities

class did.utils.Coloring(mode=None)

Coloring configuration

MODES = [u'COLOR_OFF', u'COLOR_ON', u'COLOR_AUTO']
enabled()

True if coloring is currently enabled

get()

Get the current color mode

set(mode=None)

Set the coloring mode

If enabled, some objects (like case run Status) are printed in color to easily spot failures, errors and so on. By default the feature is enabled when script is attached to a terminal. Possible values are:

COLOR=0 ... COLOR_OFF .... coloring disabled
COLOR=1 ... COLOR_ON ..... coloring enabled
COLOR=2 ... COLOR_AUTO ... if terminal attached (default)

Environment variable COLOR can be used to set up the coloring to the desired mode without modifying code.

class did.utils.Logging(name=u'did')

Logging Configuration

COLORS = {4: u'magenta', 7: u'cyan', 40: u'red', 10: u'green', 20: u'blue', 30: u'yellow'}
class ColoredFormatter(fmt=None, datefmt=None)

Custom color formatter for logging

format(record)
Logging.LEVELS = [u'CRITICAL', u'DEBUG', u'ERROR', u'FATAL', u'INFO', u'NOTSET', u'WARN', u'WARNING']
Logging.MAPPING = {0: 30, 1: 20, 2: 10, 3: 7, 4: 4, 5: 1}
Logging.get()

Get the current log level

Logging.set(level=None)

Set the default log level

If the level is not specified environment variable DEBUG is used with the following meaning:

DEBUG=0 ... LOG_WARN (default)
DEBUG=1 ... LOG_INFO
DEBUG=2 ... LOG_DEBUG
DEBUG=3 ... LOG_CACHE
DEBUG=4 ... LOG_DATA
DEBUG=5 ... LOG_ALL (log all messages)
did.utils.ascii(text)

Transliterate special unicode characters into pure ascii

did.utils.color(text, color=None, background=None, light=False, enabled=True)

Return text in desired color if coloring enabled

Available colors: black red green yellow blue magenta cyan white. Alternatively color can be prefixed with “light”, e.g. lightgreen.

did.utils.eprint(text)

Print (optionaly encoded) text

did.utils.header(text)

Show text as a header.

did.utils.info(message, newline=True)

Log provided info message to the standard error output

did.utils.item(text, level=0, options=None)

Print indented item.

did.utils.listed(items, singular=None, plural=None, max=None, quote=u'')

Convert an iterable into a nice, human readable list or description:

listed(range(1)) .................... 0
listed(range(2)) .................... 0 and 1
listed(range(3), quote='"') ......... "0", "1" and "2"
listed(range(4), max=3) ............. 0, 1, 2 and 1 more
listed(range(5), 'number', max=3) ... 0, 1, 2 and 2 more numbers
listed(range(6), 'category') ........ 6 categories
listed(7, "leaf", "leaves") ......... 7 leaves

If singular form is provided but max not set the description-only mode is activated as shown in the last two examples. Also, an int can be used in this case to get a simple inflection functionality.

did.utils.pluralize(singular=None)

Naively pluralize words

did.utils.shorted(text, width=79)

Shorten text, make sure it’s not cut in the middle of a word

did.utils.split(values, separator=<_sre.SRE_Pattern object>)

Convert space-or-comma-separated values into a single list

Common use case for this is merging content of options with multiple values allowed into a single list of strings thus allowing any of the formats below and converts them into [‘a’, ‘b’, ‘c’]:

--option a --option b --option c ... ['a', 'b', 'c']
--option a,b --option c ............ ['a,b', 'c']
--option 'a b c' ................... ['a b c']

Accepts both string and list. By default space and comma are used as value separators. Use any regular expression for custom separator.

cli

Command line interface for did

This module takes care of processing command line options and running the main loop which gathers all individual stats.

class did.cli.Options(arguments=None)

Command line options parser

check()

Perform additional check for given options

parse(arguments=None)

Parse the options.

did.cli.main(arguments=None)

Parse options, gather stats and show the results

Takes optional parameter arguments which can be either command line string or list of options. This is very useful for testing purposes. Function returns a tuple of the form:

([user_stats], team_stats)

with the list of all gathered stats objects.