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.
- property 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.
base
Config, Date, User and Exceptions
- class did.base.Config(config=None, path=None)
User config file
- property 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
- property plugins
Custom plugins
- property quarter
The first month of the quarter, 1 by default
- section(section, skip=['type', 'order'])
Return section items, skip selected (type/order by default)
- sections(kind=None)
Return all sections (optionally of given kind only)
- property separator
Separator character to use for the report
- property separator_width
Number of separator characters to use for the report
- property 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 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 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
orstats: 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.
- did.base.get_token(config: dict, token_key: str = 'token', token_file_key: str = 'token_file') str
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.
utils
Logging, config, constants & utilities
- class did.utils.Coloring(*args, **kwargs)
Coloring configuration
- MODES = ['COLOR_OFF', 'COLOR_ON', '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='did')
Logging Configuration
- COLORS = {4: 'magenta', 7: 'cyan', 10: 'green', 20: 'blue', 30: 'yellow', 40: 'red'}
- class ColoredFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)
Custom color formatter for logging
- format(record)
Format the specified record as text.
The record's attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.
- LEVELS = ['CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'INFO', 'NOTSET', 'WARN', 'WARNING']
- MAPPING = {0: 30, 1: 20, 2: 10, 3: 7, 4: 4, 5: 1}
- get()
Get the current log level
- 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_DETAILS 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.header(text, separator='~', separator_width=79)
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='')
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.load_components(*paths, **kwargs)
Load all components on the paths
Each path should be a package or module. All components beneath a path are loaded. This method works whether the package or module is on the filesystem or in an .egg. If it's in an egg, the egg must already be on the
PYTHONPATH
.- Args:
paths (str): A package or module to load
- Keyword Args:
- include (str): A regular expression of packages and modules to
include. Defaults to '.*'
- exclude (str): A regular expression of packges and modules to
exclude. Defaults to 'test'
- continue_on_error (bool): If True, continue importing even if
something raises an ImportError. If False, raise the first ImportError.
- Returns:
int: The total number of modules loaded.
- Raises:
ImportError
- 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=re.compile('[ ,]+'))
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()
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.