RepoBee Module Reference¶

command¶

_repobee.command.open_issue(issue, master_repo_names, teams, api)[source]¶

Open an issue in student repos.

Parameters:	master_repo_names (`Iterable`[`str`]) – Names of master repositories. teams (`Iterable`[`Team`]) – Team objects specifying student groups. issue (`Issue`) – An issue to open. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`None`

_repobee.command.close_issue(title_regex, repos, api)[source]¶

Close issues whose titles match the title_regex in student repos.

Parameters:	title_regex (`str`) – A regex to match against issue titles. master_repo_names – Names of master repositories. teams – Team objects specifying student groups. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`None`

_repobee.command.list_issues(repos, api, state=<IssueState.OPEN: 'open'>, title_regex='', show_body=False, author=None)[source]¶

List all issues in the specified repos.

Parameters:

repos (Iterable[Repo]) – The repos from which to fetch issues.
api (API) – An implementation of repobee_plug.API used to interface with the platform (e.g. GitHub or GitLab) instance.
state (IssueState) – state of the repo (open or closed). Defaults to open.
title_regex (str) – If specified, only issues with titles matching the regex are displayed. Defaults to the empty string (which matches everything).
show_body (bool) – If True, the body of the issue is displayed along with the default info.
author (Optional[str]) – Only show issues by this author.

Return type:

Mapping[str, List[Result]]

_repobee.command.assign_peer_reviews(master_repo_names, teams, num_reviews, issue, api)[source]¶

Assign peer reviewers among the students to each student repo. Each student is assigned to review num_reviews repos, and consequently, each repo gets reviewed by num_reviews reviewers.

In practice, each student repo has a review team generated (called <student-repo-name>-review), to which num_reviews _other_ students are assigned. The team itself is given pull-access to the student repo, so that reviewers can view code and open issues, but cannot modify the contents of the repo.

Parameters:

master_repo_names (Iterable[str]) – Names of master repos.
teams (Iterable[Status]) – Team objects specifying student groups.
num_reviews (int) – Amount of reviews each student should perform (consequently, the amount of reviews of each repo)
issue (Optional[Issue]) – An issue with review instructions to be opened in the considered repos.
api (API) – An implementation of repobee_plug.API used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type:

None

_repobee.command.purge_review_teams(master_repo_names, students, api)[source]¶

Delete all review teams associated with the given master repo names and students.

Parameters:	master_repo_names (`Iterable`[`str`]) – Names of master repos. students (`Iterable`[`Team`]) – An iterble of student teams. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`None`

_repobee.command.check_peer_review_progress(master_repo_names, teams, title_regex, num_reviews, api)[source]¶

Check which teams have opened peer review issues in their allotted review repos

Parameters:

master_repo_names (Iterable[str]) – Names of master repos.
teams (Iterable[Team]) – An iterable of student teams.
title_regex (str) – A regex to match against issue titles.
num_reviews (int) – Amount of reviews each student is expected to have made.
api (API) – An implementation of repobee_plug.API used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type:

None

_repobee.command.setup_student_repos(master_repo_urls, teams, api)[source]¶

Setup student repositories based on master repo templates. Performs three primary tasks:

1. Create the specified teams on the target platform and add the specified members to their teams. If a team already exists, it is left as-is. If a student is already in a team they are assigned to, nothing happens. If no account exists for some specified username, that particular student is ignored, but any associated teams are still created (even if a missing user is the only member of that team).

2. For each master repository, create one student repo per team and add it to the corresponding student team. If a repository already exists, it is skipped.

Push files from the master repos to the corresponding student repos.

Parameters:	master_repo_urls (`Iterable`[`str`]) – URLs to master repos. teams (`Iterable`[`Team`]) – An iterable of student teams specifying the teams to be setup. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`Mapping`[`str`, `List`[`Result`]]

_repobee.command.clone_repos(repos, api)[source]¶

Clone all student repos related to the provided master repos and student teams.

Parameters:	repos (`Iterable`[`Repo`]) – The repos to be cloned. This function does not use the `implementation` attribute, so it does not need to be set. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`Mapping`[`str`, `List`[`Result`]]
Returns:	A mapping from repo name to a list of hook results.

_repobee.command.update_student_repos(master_repo_urls, teams, api, issue=None)[source]¶

Attempt to update all student repos related to one of the master repos.

Parameters:

master_repo_urls (Iterable[str]) – URLs to master repos. Must be in the organization that the api is set up for.
teams (Iterable[Team]) – An iterable of student teams.
api (API) – An implementation of repobee_plug.API used to interface with the platform (e.g. GitHub or GitLab) instance.
issue (Optional[Issue]) – An optional issue to open in repos to which pushing fails.

Return type:

Mapping[str, List[Result]]

_repobee.command.migrate_repos(master_repo_urls, api)[source]¶

Migrate a repository from an arbitrary URL to the target organization. The new repository is added to the master_repos team, which is created if it does not already exist.

Parameters:	master_repo_urls (`Iterable`[`str`]) – HTTPS URLs to the master repos to migrate. the username that is used in the push. api (`API`) – An implementation of `repobee_plug.API` used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:	`None`

_repobee.command.show_config()[source]¶

Print the configuration file to the log.

Return type:	`None`

cli¶

mainparser¶

Definition of the primary parser for RepoBee.

_repobee.cli.mainparser.create_parser(show_all_opts, ext_commands)[source]¶

Create the primary parser.

Parameters:	show_all_opts (`bool`) – If False, help sections for options with configured defaults are suppressed. Otherwise, all options are shown. ext_commands (`Optional`[`List`[`ExtensionCommand`]]) – A list of extension commands.
Return type:	`ArgumentParser`
Returns:	The primary parser.

_repobee.cli.mainparser.create_parser_for_docs()[source]¶

Create a parser showing all options for the default CLI documentation.

Return type:	`ArgumentParser`
Returns:	The primary parser, specifically for generating documentation.

parsing¶

Parsing logic for RepoBee’s primary parser.

This is separated into its own module as it is a relatively complex affair. Any non-trivial parsing logic should go in here, whereas definitions of the primary parser should go int _repobee.cli.mainparser.

_repobee.cli.parsing.handle_args(sys_args, show_all_opts=False, ext_commands=None)[source]¶

Parse and process command line arguments and instantiate the platform API (if it’s needed).

Parameters:	sys_args (`Iterable`[`str`]) – Raw command line arguments for the primary parser. show_all_opts (`bool`) – If False, help sections for options that have configured defaults are suppressed. Otherwise, all options are shown. ext_commands (`Optional`[`List`[`ExtensionCommand`]]) – An optional list of extension commands.
Return type:	`Tuple`[`Namespace`, `Optional`[`API`]]
Returns:	A tuple of a namespace with parsed and processed arguments, and an instance of the platform API if it is required for the command.

_repobee.cli.parsing.setup_logging()[source]¶

Setup logging by creating the required log directory and setting up the logger.

Return type:	`None`

dispatch¶

Module dispatching CLI commands to RepoBee’s internal.

This module essentially translates parsed and processed arguments from the CLI into commands for RepoBee’s core.

_repobee.cli.dispatch.dispatch_command(args, api, ext_commands=None)[source]¶

Handle parsed CLI arguments and dispatch commands to the appropriate functions. Expected exceptions are caught and turned into SystemExit exceptions, while unexpected exceptions are allowed to propagate.

Parameters:	args (`Namespace`) – A namespace of parsed command line arguments. api (`API`) – An initialized plug.API instance. ext_commands (`Optional`[`List`[`ExtensionCommand`]]) – A list of active extension commands.

preparser¶

Module for the preparser.

The preparser runs before the primary parser (see _repobee.cli.mainparser). The reason for this somewhat convoluted setup is that:

1. Plugins need to be able to add options to the CLI, which is only possible if a separate parser runs before the primary parser. 2. Certain options affect how the CLI behaves, such as --show-all-opts.

_repobee.cli.preparser.parse_args(sys_args)[source]¶

Parse all arguments that can somehow alter the end-user CLI, such as plugins.

Parameters:	sys_args (`List`[`str`]) – Command line arguments.
Return type:	`Namespace`
Returns:	The parsed arguments.

_repobee.cli.preparser.separate_args(args)[source]¶

Separate args into preparser args and primary parser args.

Parameters:	args (`List`[`str`]) – Raw command line arguments.
Return type:	(typing.List[str], typing.List[str])
Returns:	A tuple of lists (preparser_args, mainparser_args).

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, config_file)[source]¶

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

Parameters:	defaults (`Mapping`[`str`, `str`]) – A dictionary of defaults. config_file (`Union`[`str`, `Path`]) – Path to the config file.

_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_all_tasks()[source]¶

Return all plugin tasks, regardless of which command they are intended for.

Return type:	`List`[`Task`]
Returns:	All plugin tasks.

_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.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.PluginLoadError(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.

util¶

Some general utility functions.

_repobee.util.atomic_write(content, dst)[source]¶

Write the given contents to the destination “atomically”. Achieved by writin in a temporary directory and then moving the file to the destination.

Parameters:	content (`str`) – The content to write to the new file. dst (`Path`) – Path to the file.
Return type:	`None`

_repobee.util.call_if_defined(func, *args, **kwargs)[source]¶

Call the function with the provided args and kwargs if it is defined (i.e. not None). This is mostly useful for plugin data structures that have optional functions.

Parameters:	func (`Callable`[…, ~T]) – A function to call. args – Positional arguments. kwargs – Keyword arguments.
Return type:	~T
Returns:	What `func` returns, or `None` if `func` is `None`.

_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.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.

github¶

GitHub API module.

This module contains the GitHubAPI class, which is meant to be the prime means of interacting with the GitHub API in repobee. The methods of GitHubAPI are mostly high-level bulk operations.

class _repobee.ext.github.DefaultAPIHooks[source]¶

class _repobee.ext.github.GitHubAPI(base_url, token, org_name, user)[source]¶

A highly specialized GitHub API class for _repobee. The API is affiliated both with an organization, and with the whole GitHub instance. Almost all operations take place on the target organization.

add_repos_to_review_teams(team_to_repos, issue=None)[source]¶

See repobee_plug.API.add_repos_to_review_teams().

Return type:	`None`

close_issue(title_regex, repo_names)[source]¶

See repobee_plug.API.close_issue().

Return type:	`None`

create_repos(repos)[source]¶: See repobee_plug.API.create_repos().

delete_teams(team_names)[source]¶

See repobee_plug.API.delete_teams().

Return type:	`None`

discover_repos(teams)[source]¶

See repobee_plug.APISpec.discover_repos().

Return type:	`Generator`[`Repo`, `None`, `None`]

ensure_teams_and_members(teams, permission=<TeamPermission.PUSH: 'push'>)[source]¶

See repobee_plug.API.ensure_teams_and_members().

Return type:	`List`[`Team`]

extract_repo_name(repo_url)[source]¶

See repobee_plug.API.extract_repo_name().

Return type:	`str`

get_issues(repo_names, state=<IssueState.OPEN: 'open'>, title_regex='')[source]¶

See repobee_plug.API.get_issues().

Return type:	`Generator`[`Tuple`[`str`, `Generator`[`Issue`, `None`, `None`]], `None`, `None`]

get_repo_urls(master_repo_names, org_name=None, teams=None)[source]¶

See repobee_plug.API.get_repo_urls().

Return type:	`List`[`str`]

get_review_progress(review_team_names, teams, title_regex)[source]¶

See repobee_plug.API.get_review_progress().

Return type:	`Mapping`[`str`, `List`[`Review`]]

get_teams()[source]¶

See repobee_plug.API.get_teams().

Return type:	`List`[`Team`]

open_issue(title, body, repo_names)[source]¶

See repobee_plug.API.open_issue().

Return type:	`None`

static verify_settings(user, org_name, base_url, token, master_org_name=None)[source]¶

See repobee_plug.API.verify_settings().

Return type:	`None`

gitlab¶

GitLab API module.

This module contains the GitLabAPI class, which is meant to be the prime means of interacting with the GitLab API in RepoBee. The methods of GitLabAPI are mostly high-level bulk operations.

class _repobee.ext.gitlab.GitLabAPI(base_url, token, org_name)[source]¶

add_repos_to_review_teams(team_to_repos, issue=None)[source]¶

See repobee_plug.API.add_repos_to_review_teams().

Return type:	`None`

close_issue(title_regex, repo_names)[source]¶

See repobee_plug.API.close_issue().

Return type:	`None`

create_repos(repos)[source]¶

See repobee_plug.API.create_repos().

Return type:	`List`[`str`]

delete_teams(team_names)[source]¶

See repobee_plug.API.delete_teams().

Return type:	`None`

discover_repos(teams)[source]¶

See repobee_plug.APISpec.discover_repos().

Return type:	`Generator`[`Repo`, `None`, `None`]

ensure_teams_and_members(teams, permission=<TeamPermission.PUSH: 'push'>)[source]¶

See repobee_plug.API.ensure_teams_and_members().

Return type:	`List`[`Team`]

extract_repo_name(repo_url)[source]¶

See repobee_plug.API.extract_repo_name().

Return type:	`str`

get_issues(repo_names, state=<IssueState.OPEN: 'open'>, title_regex='')[source]¶

See repobee_plug.API.get_issues().

Return type:	`Generator`[`Tuple`[`str`, `Generator`[`Issue`, `None`, `None`]], `None`, `None`]

get_repo_urls(master_repo_names, org_name=None, teams=None)[source]¶

See repobee_plug.API.get_repo_urls().

Return type:	`List`[`str`]

get_review_progress(review_team_names, teams, title_regex)[source]¶

See repobee_plug.API.get_review_progress().

Return type:	`Mapping`[`str`, `List`[`Review`]]

get_teams()[source]¶

See repobee_plug.API.get_teams().

Return type:	`List`[`Team`]

open_issue(title, body, repo_names)[source]¶

See repobee_plug.API.open_issue().

Return type:	`None`

static verify_settings(user, org_name, base_url, token, master_org_name=None)[source]¶: See repobee_plug.API.verify_settings().

class _repobee.ext.gitlab.GitLabAPIHook[source]¶

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(teams, num_reviews=1)[source]¶

Generate peer review allocations such that if team_a reviews team_b, then team_b reviews team_a, and no others!

The num_reviews argument is ignored by this plugin.

Parameters:	teams (`List`[`Team`]) – Student teams for which to allocate reviews. num_reviews (`int`) – Ignored by this plugin.
Return type:	`List`[`ReviewAllocation`]
Returns:	A list of allocations that

Extension plugins¶

javac¶

Plugin that runs javac on all files in a repo.

Important

Requires javac to be installed and accessible by the script!

This plugin is mostly for demonstrational purposes, showing off some of the more advanced features of the plugin system. It, very unintelligently, finds all of the .java files in a repository and tries to compile them all at the same time. Duplicate files etc. will cause this to fail.

The point of this plugin is however mostly to demonstrate how to use the hooks, and specifically the more advanced use of the clone_parser_hook and parse_args hooks.

class _repobee.ext.javac.JavacCloneHook[source]¶

Containe for the plugin hooks allowing for persistence between adding/parsing arguments and acting on the repo.

config_hook(config_parser)[source]¶

Check for configured ignore files.

Parameters:	config – the config parser after config has been read.
Return type:	`None`

pylint¶

Plugin that runs pylint on all files in a repo.

Important

Requires pylint to be installed and accessible by the script!

This plugin is mostly for demonstrational purposes, showing how to make the most barebones of plugins using only a single function. It finds all .py files in a repo, and runs pylint on them, storing the results in files named <filename>.lint for any .py file named filename.

_repobee.ext.pylint.act(path, api)[source]¶

Run pylint on all Python files in a repo.

Parameters:	path (`Path`) – Path to the repo. api (`API`) – A platform API class instance.
Returns:	a plug.Result specifying the outcome.

config-wizard¶

A plugin that adds the config-wizard command to RepoBee. It runs through a short configuration wizard that lets the user set RepoBee’s defaults.

_repobee.ext.configwizard.callback(args, api)[source]¶

Run through a configuration wizard.

Return type:	`None`

query¶

A plugin that adds the query command to RepoBee, allowing users to query a hook results JSON file.