RepoBee Module Reference

command

_repobee.command.assign_peer_reviews(assignment_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
  • assignment_names (Iterable[str]) – Names of assginments.

  • teams (Iterable[StudentTeam]) – 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 (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

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

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

Parameters
  • assignment_names (Iterable[str]) – Names of assignments.

  • 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 (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

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

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

Parameters
  • repos (Iterable[StudentRepo]) – The repos to be cloned. This function does not use the implementation attribute, so it does not need to be set.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI 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.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.

  • assignment_names – Names of assignments.

  • teams – Team objects specifying student groups.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

_repobee.command.create_teams(teams, permission, api)[source]

Create teams.

Parameters
Return type

Iterable[Team]

Returns

An iterable of wrappers around created teams.

_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[StudentRepo]) – The repos from which to fetch issues.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI 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.migrate_repos(template_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
  • template_repo_urls (SizedIterable[str]) – Local urls to repos to migrate.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

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

Open an issue in student repos.

Parameters
  • assignment_names (Iterable[str]) – Names of assignments.

  • teams (Iterable[StudentTeam]) – Team objects specifying student groups.

  • issue (Issue) – An issue to open.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

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

Delete all review teams associated with the given assignment names and student teams.

Parameters
  • assignment_names (Iterable[str]) – Names of assignments.

  • students (Iterable[StudentTeam]) – An iterble of student teams.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

None

_repobee.command.setup_student_repos(template_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.

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

Parameters
  • template_repo_urls (Iterable[str]) – URLs to master repos.

  • teams (Iterable[StudentTeam]) – An iterable of student teams specifying the teams to be setup.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI used to interface with the platform (e.g. GitHub or GitLab) instance.

Return type

Mapping[str, List[Result]]

_repobee.command.show_config(config_file, show_secrets)[source]

Echo the config file.

Parameters
  • config_file (Path) – The config file to echo.

  • show_secrets (bool) – Whether or not to show configured secrets.

Return type

None

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

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

Parameters
  • template_repo_urls (SizedIterable[str]) – URLs to master repos. Must be in the organization that the api is set up for.

  • teams (SizedIterable[StudentTeam]) – An iterable of student teams.

  • api (PlatformAPI) – An implementation of repobee_plug.PlatformAPI 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]]

cli

mainparser

Definition of the primary parser for RepoBee.

_repobee.cli.mainparser.create_parser(config_file)[source]

Create the primary parser.

Parameters

config_file (Path) – Path to the config file.

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, config_file=PosixPath('/home/docs/.config/repobee/config.ini'))[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.

  • config_file (Path) – Path to the config file.

Return type

Tuple[Namespace, Optional[PlatformAPI]]

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(terminal_level=30)[source]

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

Parameters

terminal_level (int) – The logging level to use for printing to stderr.

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, config_file)[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 (PlatformAPI) – An initialized plug.API instance.

  • config_file (Path) – Path to the config file.

Return type

Mapping[str, List[Result]]

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 plugins need to be able to add options to the CLI. As we want to be able to specify plugins on the command line, which may add options to the command line, this becomes a chicken or egg problem. The preparser solves this.

_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

Tuple[List[str], List[str]]

Returns

A tuple of lists (preparser_args, mainparser_args).

argparse_ext

RepoBee extensions of argparse.

class _repobee.cli.argparse_ext.OrderedFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]

A formatter class for putting out the help section in a proper order. All of the arguments that are configurable in the configuration file should appear at the bottom (in arbitrary, but always the same, order). Any other arguments should appear in the order they are added.

The internals of the formatter classes are technically not public, so this class is “unsafe” when it comes to new versions of Python. It may have to be disabled for future versions, but it works for 3.6, 3.7 and 3.8 at the time of writing. If this turns troublesome, it may be time to switch to some other CLI library.

add_arguments(actions)[source]

Order actions by the name of the long argument, and then add them as arguments.

The order is the following:

[ NON-CONFIGURABLE | CONFIGURABLE | DEBUG ]

Non-configurable arguments added without modification, which by default is the order they are added to the parser. Configurable arguments are added in the order defined by constants.ORDERED_CONFIGURABLE_ARGS. Finally, debug commands (such as --traceback) are added in arbitrary (but consistent) order.

class _repobee.cli.argparse_ext.RepobeeParser(*args, is_core_command=False, **kwargs)[source]

A thin wrapper around argparse.ArgumentParser. The primary functionality of this class is to group the core CLI arguments into argument groups such that the CLI doesn’t get too cluttered.

add_argument(*args, **kwargs)[source]

Add an argument to this parser, placing it in an appropriate argument group.

add_argument_group(title=None, description=None)[source]

Create a new argument group if the title does not exist, or return an existing one if it does.

Return type

_ArgumentGroup

config

config module.

Contains the code required for pre-configuring user interfaces.

_repobee.config.check_config_integrity(config_file)[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
_repobee.config.execute_config_hooks(config_file)[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)[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.

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

git

Wrapper functions for git commands.

class _repobee.git.CloneStatus(value)[source]

An enumeration.

class _repobee.git.Push(local_path, repo_url, branch, metadata=<factory>)[source]
_repobee.git.active_branch(repo_path)[source]

Get the active branch from the given repo.

Parameters

repo_path (Path) – Path to a repo.

Return type

str

Returns

The active branch of the repo.

_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[str]

Returns

URLs from which cloning failed.

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

Clone a git repository with git clone.

This should only be used for temporary cloning, as any secure tokens in the repo URL are stored in the 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

Tuple[List[Push], List[Push]]

Returns

A tuple of lists of push tuples on the form (successful, failures).

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

Default plugins

These plugins are loaded by default.

configwizard

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.

class _repobee.ext.defaults.configwizard.Wizard(plugin_name)[source]
_repobee.ext.defaults.configwizard.callback(args)[source]

Run through a configuration wizard.

Return type

None

genreviews

The default implementation of generate_review_allocations.

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.defaults.github.DefaultAPIHooks(plugin_name)[source]
class _repobee.ext.defaults.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.

assign_members(team, members, permission=<TeamPermission.PUSH: 'push'>)[source]

See repobee_plug.PlatformAPI.assign_members().

Return type

None

assign_repo(team, repo, permission)[source]

See repobee_plug.PlatformAPI.assign_repo().

Return type

None

close_issue(issue)[source]

See repobee_plug.PlatformAPI.close_issue().

Return type

None

create_issue(title, body, repo, assignees=None)[source]

See repobee_plug.PlatformAPI.create_issue().

Return type

Issue

create_repo(name, description, private, team=None)[source]

See repobee_plug.PlatformAPI.create_repo().

Return type

Repo

create_team(name, members=None, permission=<TeamPermission.PUSH: 'push'>)[source]

See repobee_plug.PlatformAPI.create_team().

Return type

Team

delete_team(team)[source]

See repobee_plug.PlatformAPI.delete_team().

Return type

None

extract_repo_name(repo_url)[source]

See repobee_plug.PlatformAPI.extract_repo_name().

Return type

str

get_repo(repo_name, team_name)[source]

See repobee_plug.PlatformAPI.get_repo().

Return type

Repo

get_repo_issues(repo)[source]

See repobee_plug.PlatformAPI.get_repo_issues().

Return type

Iterable[Issue]

get_repo_urls(assignment_names, org_name=None, team_names=None, insert_auth=False)[source]

See repobee_plug.PlatformAPI.get_repo_urls().

Return type

List[str]

get_repos(repo_urls=None)[source]

See repobee_plug.PlatformAPI.get_repos().

Return type

Iterable[Repo]

get_team_repos(team)[source]

See repobee_plug.PlatformAPI.get_team_repos().

Return type

Iterable[Repo]

get_teams(team_names=None)[source]

See repobee_plug.PlatformAPI.get_teams().

Return type

Iterable[Team]

insert_auth(url)[source]

See repobee_plug.PlatformAPI.insert_auth().

Return type

str

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

See repobee_plug.PlatformAPI.verify_settings().

Return type

None

Additional plugins

These plugins ship with RepoBee, but are not loaded by default.

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]
assign_members(team, members, permission=<TeamPermission.PUSH: 'push'>)[source]

See repobee_plug.PlatformAPI.assign_members().

Return type

None

assign_repo(team, repo, permission)[source]

See repobee_plug.PlatformAPI.assign_repo().

Return type

None

close_issue(issue)[source]

See repobee_plug.PlatformAPI.close_issue().

Return type

None

create_issue(title, body, repo, assignees=None)[source]

See repobee_plug.PlatformAPI.create_issue().

Return type

Issue

create_repo(name, description, private, team=None)[source]

See repobee_plug.PlatformAPI.create_repo().

Return type

Repo

create_team(name, members=None, permission=<TeamPermission.PUSH: 'push'>)[source]

See repobee_plug.PlatformAPI.create_team().

Return type

Team

delete_team(team)[source]

See repobee_plug.PlatformAPI.delete_team().

Return type

None

extract_repo_name(repo_url)[source]

See repobee_plug.PlatformAPI.extract_repo_name().

Return type

str

get_repo(repo_name, team_name)[source]

See repobee_plug.PlatformAPI.get_repo().

Return type

Repo

get_repo_issues(repo)[source]

See repobee_plug.PlatformAPI.get_repo_issues().

Return type

Iterable[Issue]

get_repo_urls(assignment_names, org_name=None, team_names=None, insert_auth=False)[source]

See repobee_plug.PlatformAPI.get_repo_urls().

Return type

List[str]

get_repos(repo_urls=None)[source]

See repobee_plug.PlatformAPI.get_repos().

Return type

Iterable[Repo]

get_team_repos(team)[source]

See repobee_plug.PlatformAPI.get_team_repos().

Return type

Iterable[Repo]

get_teams(team_names=None)[source]

See repobee_plug.PlatformAPI.get_teams().

Return type

Iterable[Team]

insert_auth(url)[source]

See repobee_plug.PlatformAPI.insert_auth().

Return type

str

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

See repobee_plug.PlatformAPI.verify_settings().

class _repobee.ext.gitlab.GitLabAPIHook(plugin_name)[source]

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(plugin_name)[source]

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

post_clone(repo, api)[source]

Run javac on all .java files in the repo.

Parameters
Return type

Result

Returns

a Result specifying the outcome.

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.post_clone(repo, api)[source]

Run pylint on all Python files in a repo.

Parameters
  • path – Path to the repo.

  • api (PlatformAPI) – A platform API class instance.

Return type

Result

Returns

a plug.Result specifying the outcome.

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[StudentTeam]) – Student teams for which to allocate reviews.

  • num_reviews (int) – Ignored by this plugin.

Return type

List[ReviewAllocation]

Returns

A list of allocations that

query

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

class _repobee.ext.query.Query(plugin_name)[source]