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: str, name: str | None = None, parent: EmptyStatsGroup | None = None, user: User | None = None)

Custom stats group for header & footer

fetch() → None: Nothing to do for empty stats

show() → None: Name only for empty stats

class did.stats.EmptyStatsGroup(option: str, name: str | None = None, parent: StatsGroup | None = None, user: User | None = None)

Header & Footer stats group

dest: str

option: str

user: User | None

class did.stats.Stats(option: str, name: str | None = None, parent: StatsGroup | None = None, user: User | None = None, *, options: Namespace | None = None)

General statistics

add_option(parser: ArgumentParser) → None: Add option for self to the parser group object.

check() → None: Check the stats if enabled.

dest: str

enabled() → bool: Check whether we're enabled (or if parent is).

error: bool = False

fetch() → None: Fetch the stats (to be implemented by respective class).

header() → None: Show summary header.

merge(other: Stats) → None: Merge another stats.

property name: str: Use the first line of docs string unless name set.

option: str

parent: StatsGroup | None = None

show() → None: Display indented statistics.

property stats: list[Any]: Stats list; subclasses may override this property.

user: User | None

class did.stats.StatsGroup(option: str, name: str | None = None, parent: StatsGroup | None = None, user: User | None = None, *, options: Namespace | None = None)

Stats group

add_option(parser: ArgumentParser) → None: Add option group and all children options.

check() → None: Check all children stats.

dest: str

fetch() → None: Stats groups do not fetch anything

merge(other: Stats) → None: Merge all children stats.

option: str

order = 500

show() → None: List all children stats.

user: User | None

class did.stats.StatsGroupPlugin(name: str, _bases: tuple[type, ...], _attrs: dict[str, Any])

ignore = {'EmptyStatsGroup', 'StatsGroup', 'StatsGroupPlugin', 'UserStats'}

registry: dict[str, StatsGroupPlugin] = {}

class did.stats.UserStats(user: User | None = None, options: Namespace | None = None, config: Config | None = None)

User statistics in one place

add_option(parser: ArgumentParser) → None: Add options for each stats group.

configured_plugins(config: Config) → list[StatsGroup]: Create a StatsGroup instance for each configured plugin

dest: str

option: str

user: User | None

base

Config, Date, User and Exceptions

class did.base.Config(config: str | None = None, path: str | None = None)

User config file

property email: str: User email(s)

static example() → str: Return config example

item(section: str, it: str) → str: Return content of given item in selected section

parser: ConfigParser | None = None

static path() → str: Detect config file path

property plugins: str | None: Custom plugins

property quarter: int: The first month of the quarter, 1 by default

section(section: str, skip: tuple[str, ...] = ('type', 'order')) → list[tuple[str, str]]: Return section items, skip selected (type/order by default)

sections(kind: str | None = None) → list[str]: Return all sections (optionally of given kind only)

property separator: str: Separator character to use for the report

property separator_width: int: Number of separator characters to use for the report

property width: int: 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: date | str | None = None)

Date parsing for common word formats

static get_month(last: bool) → tuple[Date, Date, str]

static get_quarter(last: bool) → tuple[Date, Date, str]

static get_week(last: bool) → tuple[Date, Date, str]

static get_year(last: bool) → tuple[Date, Date, str]

static period(argument: list[str]) → tuple[Date | None, Date | None, str | None]: Detect desired time period for the argument

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: str, stats: str | None = 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: str | None, stats: str | None) → None: Apply the login/email alias if configured.

clone(stats: str) → User: Create a user copy with alias enabled for given stats.

did.base.get_token(config: dict[str, str], token_key: str = 'token', token_file_key: str = 'token_file') → str | None

Extract the authentication token from config or token file

Returns the contents of config[token_key], or the file contents of config[token_file_key] if no config[token] exists. If neither keys exist, None is returned.

Sometimes you want to be able to store a token in a file rather than in the your plain config file. Use this function to support a system wide mechanism to retrieve tokens or secrets either directly from the config file as plain text or from an outsourced file.

Parameters:

config -- A configuration dictionary.
token_key -- The dict entry to look for when the token is stored as plain text in the config.
token_file_key -- The dict entry to look for when the token is supposed to be read from file.

Returns:

The stripped token or None if no or only empty entries were found in the config dict.

did.base.setlocale(category: int, value: str | None = None) → Iterator[str]

utils

Logging, config, constants & utilities

did.utils.pretty(object, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False): Format a Python object into a pretty-printed representation.

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 | str | list[str] = None)

Command line options parser

check() → None: Perform additional check for given options

parse() → tuple[Namespace, str]: Parse the options.

did.cli.main(arguments: None | str | list[str] = None) → tuple[list[UserStats], UserStats]

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.