repobee Module Reference

command

cli

config

config module.

Contains the code required for pre-configuring user interfaces.

repobee.config.check_config_integrity(config_file=PosixPath('/home/docs/.config/repobee/config.cnf'))[source]

Raise an exception if the configuration file contains syntactical errors, or if the defaults are misconfigured. Note that plugin options are not checked.

Parameters:config_file (Union[str, Path]) – path to the config file.
Return type:None
repobee.config.check_defaults(defaults)[source]

Raise an exception if defaults contain keys that are not configurable arguments.

Parameters:defaults (Mapping[str, str]) – A dictionary of defaults.
repobee.config.execute_config_hooks(config_file=PosixPath('/home/docs/.config/repobee/config.cnf'))[source]

Execute all config hooks.

Parameters:config_file (Union[str, Path]) – path to the config file.
Return type:None
repobee.config.get_configured_defaults(config_file=PosixPath('/home/docs/.config/repobee/config.cnf'))[source]

Access the config file and return a ConfigParser instance with its contents.

Parameters:config_file (Union[str, Path]) – Path to the config file.
Return type:dict
Returns:a dict with the contents of the config file. If there is no config file, the return value is an empty dict.
repobee.config.get_plugin_names(config_file=PosixPath('/home/docs/.config/repobee/config.cnf'))[source]

Return a list of unqualified names of plugins listed in the config. The order of the plugins is preserved.

Parameters:config_file (Union[str, Path]) – path to the config file.
Return type:List[str]
Returns:a list of unqualified names of plugin modules, or an empty list if no plugins are listed.

exception

Modules for all custom repobee exceptions.

All exceptions extend the RepoBeeException base class, which itself extends Exception. In other words, exceptions raised within repobee can all be caught by catching RepoBeeException.

exception repobee.exception.APIError(msg='', status=None)[source]

An exception raised when the API responds with an error code.

exception repobee.exception.APIImplementationError(msg='', *args, **kwargs)[source]

Raise when an API is defined incorrectly.

exception repobee.exception.BadCredentials(msg='', status=None)[source]

Raise when credentials are rejected.

exception repobee.exception.CloneFailedError(msg, returncode, stderr, url)[source]

An error to raise when cloning a repository fails.

exception repobee.exception.FileError(msg='', *args, **kwargs)[source]

Raise when reading or writing to a file errors out.

exception repobee.exception.GitError(msg, returncode, stderr)[source]

A generic error to raise when a git command exits with a non-zero exit status.

exception repobee.exception.NotFoundError(msg='', status=None)[source]

An exception raised when the API responds with a 404.

exception repobee.exception.ParseError(msg='', *args, **kwargs)[source]

Raise when something goes wrong in parsing.

exception repobee.exception.PluginError(msg='', *args, **kwargs)[source]

Generic error to raise when something goes wrong with loading plugins.

exception repobee.exception.PushFailedError(msg, returncode, stderr, url)[source]

An error to raise when pushing to a remote fails.

exception repobee.exception.RepoBeeException(msg='', *args, **kwargs)[source]

Base exception for all repobee exceptions.

exception repobee.exception.ServiceNotFoundError(msg='', status=None)[source]

Raise if the base url can’t be located.

exception repobee.exception.UnexpectedException(msg='', status=None)[source]

An exception raised when an API request raises an unexpected exception.

git

Wrapper functions for git commands.

class repobee.git.Push(local_path, repo_url, branch)
branch

Alias for field number 2

local_path

Alias for field number 0

repo_url

Alias for field number 1

repobee.git.captured_run(*args, **kwargs)[source]

Run a subprocess and capture the output.

repobee.git.clone(repo_urls, cwd='.')[source]

Clone all repos asynchronously.

Parameters:
  • repo_urls (Iterable[str]) – URLs to repos to clone.
  • cwd (str) – Working directory. Defaults to the current directory.
Return type:

List[Exception]

Returns:

URLs from which cloning failed.

repobee.git.clone_single(repo_url, branch='', cwd='.')[source]

Clone a git repository.

Parameters:
  • repo_url (str) – HTTPS url to repository on the form https://<host>/<owner>/<repo>.
  • branch (str) – The branch to clone.
  • cwd (str) – Working directory. Defaults to the current directory.
repobee.git.push(push_tuples, tries=3)[source]

Push to all repos defined in push_tuples asynchronously. Amount of concurrent tasks is limited by CONCURRENT_TASKS. Pushing to repos is tried a maximum of tries times (i.e. pushing is _retried_ tries - 1 times.)

Parameters:
  • push_tuples (Iterable[Push]) – Push namedtuples defining local and remote repos.
  • tries (int) – Amount of times to try to push (including initial push).
Return type:

List[str]

Returns:

urls to which pushes failed with exception.PushFailedError. Other errors are only logged.

tuples

Tuples module.

This module contains various namedtuple containers used throughout repobee. There are still a few namedtuples floating about in their own modules, but the goal is to collect all container types in this module.

class repobee.tuples.Args(subparser, org_name, github_base_url, user, master_repo_urls, master_repo_names, students, issue, title_regex, traceback, state, show_body, author, num_reviews, master_org_name, token)
author

Alias for field number 12

github_base_url

Alias for field number 2

issue

Alias for field number 7

master_org_name

Alias for field number 14

master_repo_names

Alias for field number 5

master_repo_urls

Alias for field number 4

num_reviews

Alias for field number 13

org_name

Alias for field number 1

show_body

Alias for field number 11

state

Alias for field number 10

students

Alias for field number 6

subparser

Alias for field number 0

title_regex

Alias for field number 8

token

Alias for field number 15

traceback

Alias for field number 9

user

Alias for field number 3

class repobee.tuples.Deprecation(replacement, remove_by)
remove_by

Alias for field number 1

replacement

Alias for field number 0

class repobee.tuples.Review(repo, done)
done

Alias for field number 1

repo

Alias for field number 0

util

Some general utility functions.

repobee.util.find_files_by_extension(root, *extensions)[source]

Find all files with the given file extensions, starting from root.

Parameters:
  • root (Union[str, Path]) – The directory to start searching.
  • extensions (str) – One or more file extensions to look for.
Return type:

Generator[Path, None, None]

Returns:

a generator that yields a Path objects to the files.

repobee.util.generate_repo_name(team_name, master_repo_name)[source]

Construct a repo name for a team.

Parameters:
  • team_name (str) – Name of the associated team.
  • master_repo_name (str) – Name of the template repository.
Return type:

str

repobee.util.generate_repo_names(team_names, master_repo_names)[source]

Construct all combinations of generate_repo_name(team_name, master_repo_name) for the provided team names and master repo names.

Parameters:
  • team_names (Iterable[str]) – One or more names of teams.
  • master_repo_names (Iterable[str]) – One or more names of master repositories.
Return type:

Iterable[str]

Returns:

a list of repo names for all combinations of team and master repo.

repobee.util.generate_review_team_name(student, master_repo_name)[source]

Generate a review team name.

Parameters:
  • student (str) – A student username.
  • master_repo_name (str) – Name of a master repository.
Return type:

str

Returns:

a review team name for the student repo associated with this master repo and student.

repobee.util.is_git_repo(path)[source]

Check if a directory has a .git subdirectory.

Parameters:path (str) – Path to a local directory.
Return type:bool
Returns:True if there is a .git subdirectory in the given directory.
repobee.util.read_issue(issue_path)[source]

Attempt to read an issue from a textfile. The first line of the file is interpreted as the issue’s title.

Parameters:issue_path (str) – Local path to textfile with an issue.
Return type:Issue
repobee.util.repo_name(repo_url)[source]

Extract the name of the repo from its url.

Parameters:repo_url (str) – A url to a repo.
Return type:str

Core plugins

defaults

The defaults plugin contains all default hook implementations.

The goal is to make core parts of repobee pluggable using hooks that only return the first result that is not None. The standard behavior will be provided by the default plugin (this one), which implements all of the required hooks. The default plugin will always be run last, so any user-defined hooks will run before it and therefore effectively override the default hooks.

Currently, only the peer review related generate_review_allocations hook has a default implementation.

repobee.ext.defaults.generate_review_allocations(master_repo_name, students, num_reviews, review_team_name_function)[source]

Generate a (peer_review_team -> reviewers) mapping for each student repository (i.e. <student>-<master_repo_name>), where len(reviewers) = num_reviews.

review_team_name_function should be used to generate review team names. It should be called like:

review_team_name_function(master_repo_name, student)

Important

There must be strictly more students than reviewers per repo (num_reviews). Otherwise, allocation is impossible.

Parameters:
  • master_repo_name (str) – Name of a master repository.
  • students (Iterable[str]) – Students for which to generate peer review allocations.
  • num_reviews (int) – Amount of reviews each student should perform (and
  • amount of reviewers per repo) (consequently) –
  • review_team_name_function (Callable[[str, str], str]) – A function that takes a master repo name
  • its first argument, and a student username as its second, and (as) –
  • a review team name. (returns) –
Return type:

Mapping[str, List[str]]

Returns:

a (peer_review_team -> reviewers) mapping for each student repository.

pairwise

A peer review plugin which attempts to assign pairwise peer reviews. Intended for students to sit and discuss their code bases with each other, as well as leave feedback. More specifically, N students are split into N/2 groups, each group member assigned to peer review the other person in the group.

If N is odd, the students are split into (N-1)/2 groups, in which one group has 3 members.

repobee.ext.pairwise.generate_review_allocations(master_repo_name, students, review_team_name_function, num_reviews=1)[source]

Generate a (peer_review_team -> reviewers) mapping for each student repository (i.e. <student>-<master_repo_name>), where len(reviewers) = 1 or 2.

The num_reviews argument is ignored by this plugin.

Parameters:
  • master_repo_name (str) – Name of a master repository.
  • students (Iterable[str]) – Students for which to generate peer review allocations.
  • review_team_name_function (Callable[[str, str], str]) – A function that takes a master repo name as its first argument, and a student username as its second, and returns a review team name.
  • num_reviews (int) – Ignored by this plugin.
Return type:

Mapping[str, List[str]]

Returns:

a (peer_review_team -> reviewers) mapping for each student repository.

Extension plugins

javac

pylint