filabel package

Submodules

filabel.core module

This module contain core routines for filabel, namely process_pull_request(). It is responsible for retrieving pull request information, matching its list of changed files against label patterns and updating pull request labels accordingly.

This functionality is shared by both CLI and web modes.

filabel.core.calculate_label_status(labels_hit, labels_miss, current_labels, delete_old)[source]

Calculate which labels has been added or removed after pattern matching.

Basing on 3 sets of labels:
  • current - labels that are already assigned to a PR
  • hit - currently matched labels
  • miss - currently mismatched labels

deduce which labels have been newly assigned/removed and which remained unchanged.

List of (LABEL, STATUS) is returned, where
LABEL
label from the hit or miss set
STATUS
One of:
  • '+' - the label is matched and has been newly assigned
  • '-' - the label is mismatched and has been newly removed
  • '=' - the label is matched but is already presented in PR

If label is not matched and NOT removed (either it has not been presented in the PR or delete_old is False), it is omitted in the result list.

Parameters:
  • labels_hit (set[str]) – set of matching labels
  • labels_miss (set[str]) – set of mismatching labels
  • current_labels (set[str]) – set of labels currently presented in the PR
  • delete_old (bool) – decide whether to remove labels that are both in current_labels and in labels_miss
Returns:

labels with their status

Return type:

list[(str, {‘+’, ‘-‘, ‘=’})]

filabel.core.match_any_file_any_pattern(files, patterns)[source]

Test whenever any file matches any pattern.

Patterns are in fnmatch format. To learn more, see fnmatch.fnmatch().

Parameters:
  • files (list[str]) – the list of filenames
  • patterns (list[str]) – the list of patterns
Return type:

bool

filabel.core.process_pull_request(gh_handler, pull_request, label_rules, delete_old)[source]

Update labels for the pull request based on the provided rules.

This routine loads the list of changed files for the requested PR. Basing on the provided label rules and this list, the sets of matched and mismatched labels are calculated.

Then matched labels that are not currently present in the PR are added. If delete_old is True, labels that are currently present in the PR but have been mismatched are removed.

Finally, label statuses are returned. See calculate_label_status().

pull_request parameter represents a response from GitHub API as defined in https://developer.github.com/v3/pulls/#get-a-single-pull-request

Raises:

RuntimeError – when gh_handler raises

Parameters:
  • gh_handler (GitHubAPI) – authorized GitHub API wrapper
  • pull_request (dict) – see docstring
  • label_rules (dict[str,list[str]]) – dictionary of labels and corresponding rules in`fnmatch` format.
  • delete_old (bool) – decide whether to remove mismatched labels, that are already assigned to the PR
Returns:

changed label status, see calculate_label_status()

Return type:

list[(str, {‘+’, ‘-‘, ‘=’})]

filabel.filabel module

This module contains entry points for both filabel modes - as a CLI tool and as a Flask application.

Additionally, it contains some helper functions, mainly for configuration loading.

filabel.filabel.create_app(flask_conf)[source]

Create Flask application.

Filabel can operate as a Flask application. This function is the entrypoint for this mode.

When launched as a server with a public IP address, it can be set up for a repository as a GitHub webhook target. These webhooks can be used to trigger filabel routine automatically.

To learn more about this mode, see filabel as Webhook server.

filabel.filabel.load_config_from_file(config_file, role)[source]

Load configuration in configparser format.

If error occurs (file not exists, unknown format, etc), application is terminated with return code 1.

Parameters:
  • config_file (str) – path to the configuration file
  • role (str) – human-readable configuration role, used to improve error messages
Return type:

configparser.ConfigParser

filabel.filabel.main(state, delete_old, base, config_auth, config_labels, reposlugs)[source]

Entry point for filabel CLI mode.

This function is called when filabel is invoked as a CLI tool.

Its task is to establish a connection to the GItHub API endpoint using credentials, provided in config_auth file (see Auth configuration). Then the list of pull requests of the repository (specified by reposlug is retrieved). Then each PR is processed as described in filabel.core.process_pull_request().

To learn more about this mode, see filabel as CLI tool.

Parameters:
  • state (str) – filter pulls by the state, one of [“open”, “closed”, “all”]
  • base (str) – filter pulls by base (PR target) branch name
  • delete_old (bool) – delete labels that do not match anymore
  • config_auth – file with authorization configuration
  • config_labels – file with labels configuration
  • reposlugs – target GitHub repositories in reposlug format
filabel.filabel.process_repo(gh_handler, reposlug, label_rules, state, base, delete_old)[source]

Update labels for each pull request in the repository based on the provided rules.

Load list of pull requests in the given repository. Process each PR as defined in filabel.core.process_pull_request().

Parameters:
  • gh_handler (GitHubAPI) – authorized GitHub API wrapper
  • reposlug (str) – GitHub repository name in reposlug format
  • label_rules (dict[str,list[str]]) – dictionary of labels and corresponding rules in`fnmatch` format.
  • state (str) – filter list of pull requests by their state, one of [“open”, “closed”, “all”]
  • base (str) – filter pulls by base (PR target) branch name, optional
  • delete_old (bool) – delete labels that do not match anymore
filabel.filabel.split_rule_list(label_rules)[source]

Covert raw label rules parsed from a config to the dict[str, list[str]] format.

When config file is parsed, all patterns of a rule are encoded as a single string with each pattern on its own line. This function constructs new dictionary with labels as keys and list of split patterns as a value.

Parameters:label_rules (dict[str,str]) – raw label-rule mapping
Returns:label-rule mapping with rules encoded as a list
Return type:dict[str, list[str]]

filabel.github_api module

This module contains a GitHub API wrapper.

class filabel.github_api.GitHubAPI(auth_token)[source]

Bases: object

GitHub API wrapper.

User is required to be authenticated using GitHub token. See GitHub OAuth token to learn how to obtain it.

Once initialized, GitHubAPI maintains a persistent connection to the GitHub API endpoint.

This provides convenient methods to retrieve information about user, repositories and PRs as well as change some properties of a PR (namely, add/remove PR labels).

pr_add_labels(pull_request, labels)[source]

Add labels to the given pull request.

Raises:

RuntimeError – if endpoint is inaccessible

Parameters:
pr_get_changed_files(pull_request)[source]

Get list of changed files fot the given pull request.

Raises:RuntimeError – if endpoint is inaccessible
Parameters:pull_request (dict) – pull request info as returned by repo_get_pr_list()
Returns:list of filenames that have been changed in the current PR
Return type:list[str]
pr_remove_labels(pull_request, labels)[source]

Add labels to the given pull request.

Raises:

RuntimeError – if endpoint is inaccessible

Parameters:
repo_get_pr(reposlug, pr_numer)[source]

Get a particular pull requests in the given repository.

Raises:

RuntimeError – if endpoint is inaccessible

Parameters:
  • reposlug (str) – repository in reposlug format
  • pr_numer (int) – pull request number
Returns:

API response as defined in https://developer.github.com/v3/pulls/#response

Return type:

dict

repo_get_pr_list(reposlug, state='all', base=None)[source]

Get list of pull requests for the given repository.

Raises:

RuntimeError – if endpoint is inaccessible

Parameters:
  • reposlug (str) – repository in reposlug format
  • state (str) – filter pull requests based on their state Allowed values: [“open”, “closed”, “all”]
  • base (Optional[str]) – filter pulls by base (PR target) branch name
Returns:

API response as defined in https://developer.github.com/v3/pulls/#response

Return type:

list[dict]

user_get_info()[source]

Retrieve info about the logged user.

Raises:RuntimeError – if endpoint is inaccessible
Returns:API response as defined in https://developer.github.com/v3/users/#response
Return type:dict

filabel.pretty_logging module

This module provides helper function for formatted logging to terminal.

filabel.pretty_logging.STATUS2COLOR = {'+': 'green', '-': 'red', '=': None, 'FAIL': 'red', 'OK': 'green'}

A mapping from status string to the corresponding color.

filabel.pretty_logging.print_label(label, status)[source]

Print label status in the predefined format.

Format is:

<status> <label>
Parameters:
  • label (str) – label name
  • status (str) – one of ["-", "+", "="]
filabel.pretty_logging.print_pr(pull_request, status)[source]

Print pull request name in the predefined format.

Format is:

PR <url> - <status>

where url is pull request address and status is either OK or FAIL.

Parameters:
  • pull_request (dict) – pull request info
  • status (str) – one of ["OK", "FAIL"]
filabel.pretty_logging.print_repo(reposlug, status)[source]

Print repo name in the predefined format.

Format is:

REPO <user>/<repo> - <status>

where status is either OK or FAIL

Parameters:
  • reposlug (str) – repository identifier
  • status (str) – one of ["OK", "FAIL"]

filabel.web module

This module defines a Flask blueprint for GET requests.

filabel.web.index()[source]

Index page handler.

It renders index page with a name of the logged-in GitHub user and loaded labeling rules.

filabel.web_hooks module

This module defines a Flask blueprint for handling GitHub Webhook requests. Learn more about Webhooks: https://developer.github.com/webhooks/

filabel.web_hooks.json_error_response(msg, code)[source]

Create REST error response.

Parameters:
  • msg (str) – additional info message
  • code (int) – HTTP response code
filabel.web_hooks.ping()[source]

Handle Webhook ping event.

Ping event is noop. No need to build any meaningful response. This handler just prints some debug info and replies with HTTP 200.

filabel.web_hooks.pull_request()[source]

Handle Webhook pull_request event.

This event is triggered when a pull request of a subscribed repository is changed.

This handler runs Main filabel routine for the pull request that triggered the hook.

filabel.web_hooks.verify_signature(data, remote_digest, secret)[source]

Compare received data signature with the expected one.

This function calculates the request data SHA1 digest using private application secret and compares it with the one, received in the response header.

Parameters:
  • data (str) – request body
  • remote_digest (str) – remotely calculated digest to be confirmed
  • secret (str) – application SHA1 secret
filabel.web_hooks.web_hook_dispatcher()[source]

Handle incoming request from GitHub WebHook API.

At first, request digest (X-Hub-Signature header) is verified. Then this handler invokes a particular handler based on the hook event (X-GitHub-Event header).

Supported actions:
  • ping
  • pull_request

Module contents