Authors Activity (rever.activities.authors)

Activity for keeping a contributors listing.

class rever.activities.authors.Authors(*, deps=frozenset({}))

Manages keeping a contributors listing up-to-date.

This activity may be configured with the following envionment variables:

$AUTHORS_FILENAME

str, path to input file. The default is ‘AUTHORS’.

$AUTHORS_TEMPLATE

str, This value goes at the top of the authors file. The default value is:

All of the people who have made at least one contribution to $PROJECT
Authors are sorted by {sorting_text}.

{authors}

This is evaluated in the current environment and,

• “{sorting_text}” is a special textual description of the sort method.

• “{authors}” is a contcatenated string of all formatted authors.

which the template is formatted with.

$AUTHORS_FORMAT

str, the string that formats each author in the author file. The default is ``”* {name}

“``. The valid fields are all of those present

in the author metadata (see below).

$AUTHORS_LATEST

str, file to write just the latest contribuors to, i.e. this is the listing of the contributors for just this release. This defaults to $REVER_DIR/LATEST-AUTHORS.json. This is evaluated in the current environment.

$AUTHORS_METADATA

str, path to YAML file that stores author metadata. The default is ‘.authors.yml’. This is evaluated in the current environment. This file has the following format:

# required fields
- name: Princess Buttercup
  email: buttercup@florin.gov

  # optional fields
  github: bcup
  is_org: False
  aliases:
    - Buttercup
    - beecup
  alternate_emails:
    - b.cup@gmail.com

  # autogenerated fields
  num_commits: 1000
  first_commit: '1987-09-25'
- name: Westley
  email: westley@gamil.com
  github: westley
  aliases:
    - Dread Pirate Roberts
  alternate_emails:
    - dpr@pirates.biz
- name: Florin
  email: help@florin.gov
  github: florin
  is_org: True

$AUTHORS_SORTBY

str, flag that specifies how authors should be sorted in the authors file. Valid options are:

• "num_commits": Number of commits per author

• "first_commit": Sort by first commit.

• "alpha": Alphabetically.

$AUTHORS_INCLUDE_ORGS

bool, Whether or not to include organizations in the authors file, defaults to False.

$AUTHORS_MAILMAP

str, bool, or None, If this is a non-empty string, it will be interperted as a file path to a mailmap file that will be generated based on the metadata provided. The default value is ".mailmap". This is evaluated in the current environment.

Parameters

namestr, optional

Name of the activity.

depsset of str, optional

Set of activities that must be completed before this activity is executed.

funccallable, optional

Function to perform as activity when this activities is executed (called).

undocallable, optional

Function to undo this activities behaviour and reset the repo state.

setupcallable, optional

Function to help initialize the activity.

checkcallable, optional

Function to check if the activity can be run sucessfully on the user’s machine, with their credentials, etc. This function should return True if the activity can be run, and False otherwise.

requiresdict or None, optional

A dict of dicts of the following form that specifies the command line utility and import requirements for this activity.

{
    "commands": {"<cli name>": "<package name>", ...}
    "imports": {"<module name>": "<package name>", ...}
}

The top-level keys are both optional, and this will default to an empty dict.

argstuple, optional

Arguments to be supplied to the func(*args), if needed.

kwargsmapping, optional

Keyword arguments to be supplied to the func(**kwargs), if needed.

descstr, optional

A short description of this activity

all_kwargs()

Returns all kwargs for this activity.

check()

Calls this activity’s check() function.

check_func()

Checks that authors can be run.

check_requirements()

Checks that an activities requirements are actually available.

checker(check)

Decorator that sets the check function for this activity.

clear_kwargs_from_env()

Removes kwarg from the environment, if they exist.

kwargs_from_env()

Obtains possible func() kwarg from the environment.

setup()

Calls this activity’s setup() initialization function.

setup_func()

Initializes the authors activity by (re-)starting an authors file from the current repo.

setupper(setup)

Decorator that sets the setup function for this activity.

undo()

Reverts to the last instance of this activity. This default implementation uses the revision in the log file from the last time that the activity was started. This may be overridden in a subclass.

undoer(undo)

Decorator that sets the undo function for this activity.

property env_names

Dictionary mapping parameter names to the names of environment varaibles that the activity looks for when it is executed.