Configuration

For the sake of brevity, a complete example configuration is

---
akellehe:
    base_url: 'https://api.gitub.com'
    token: '*****'
    repos:
        github_watcher:
            paths:
                docs/: <null>,
                github_watcher/settings.py:
                    - [0, 1]
                    - [4, 5]
            regexes:
                - foo
                - bar
            users:
                - akellehe

If the configuration above doesn’t answer your questions, more explanation is below.

Configurations are defined per user (account) being watched. The github_watcher.commands.config.User is the “top-level” configuration. Each user can have many repositories.

The parameters in a repository are

parameter	type	description
name	str	The name of the repository to watch. e.g. github_watcher
paths	Dict	Relative file/directory paths (from the root of the project) are the keys. Lists of lists containing line ranges are the value. If you pass a directory, you can just pass null as the line ranges.
regexes	List[str]	A list of regexes for which to scan every pull request.
token	str	Your secret user token that grants User and Repo privileges on the target repository.
base_url	str	The base URL for the target github API. Defaults to https://api.gitub.com
users	List[str]	A list of users. You’ll receive an alert any time one of them submits a PR

Particular classes related to the grammar in configuration files follow.

class github_watcher.commands.config.Configuration(users: List[github_watcher.commands.config.User], silent: bool = False, verbose: bool = False)

Parameters:

• users (List[User]) – A list of users with repository configurations to watch.
• silent (bool) – Silent audio alerts. This is a commandline options, –silent.
• verbose (bool) – Verbose logging (warning: prints access tokens). This is a commandline arg, –verbose.

class github_watcher.commands.config.Path(path: str, ranges: List[github_watcher.commands.config.Range])

Parameters:

• path (str) – Represents a path to watch. Container for line ranges in that path. This can be a file or a directory
• ranges (List[Range]) – A list of line ranges to watch at path. This can be an empty list if there are no ranges.

class github_watcher.commands.config.Range(start: float = -inf, end: float = inf)

Represents a line range being watched.

Parameters:

• start (float) – Defaults to -inf. Starting point in the line range on the file to watch.
• end (float) – Defaults to inf. Ending point in the line range on the file to watch.

class github_watcher.commands.config.Repo(name: str, paths: List[github_watcher.commands.config.Path] = None, regexes: List[str] = None, users: List[str] = None)

Parameters:

• name (str) – The name of the repository being watched.
• paths (List[Path]) – A list of path configurations to watch in the repository.
• regexes (List[str]) – A list of strings, regular expressions to search in the pull request diffs.
• users (List[str]) – A list of authors to watch. If any submit any PR it will be alerted.

class github_watcher.commands.config.User(name: str, repos: List[github_watcher.commands.config.Repo], token: str, base_url: str)

Parameters:

• name (str) – The user’s username in github.
• repos (List[Repo]) – A list of repository configurations for the repositories that will be watched.
• token (str) – The authentication token giving User and Repo grants on the target repositories.
• base_url (str) – The API base url on which this user exists (enterprise github is supported)