repobee Module Reference

command

Primary API for repobee.

This module contains high level functions for administrating repositories, such as creating student repos from some master repo template. All functions follow the conventions specified in Conventions.

Each public function in this module is to be treated as a self-contained program.

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[Team]) – 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 apimeta.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, students, title_regex, num_reviews, api)[source]

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

Parameters:
  • master_repo_names (Iterable[str]) – Names of master repos.
  • students (Iterable[Team]) – An iterable of student GitHub usernames.
  • 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 apimeta.API used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:

None

repobee.command.clone_repos(master_repo_names, teams, api)[source]

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

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

None

repobee.command.close_issue(title_regex, master_repo_names, teams, 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 (Iterable[str]) – Names of master repositories.
  • teams (Iterable[Team]) – Team objects specifying student groups.
  • api (API) – An implementation of apimeta.API used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:

None

repobee.command.list_issues(master_repo_names, teams, api, state='open', title_regex='', show_body=False, author=None)[source]

List all issues in the specified repos.

Parameters:
  • master_repo_names (Iterable[str]) – Names of master repositories.
  • teams (Iterable[Team]) – An iterable of student teams.
  • api (API) – An implementation of apimeta.API used to interface with the platform (e.g. GitHub or GitLab) instance.
  • state (str) – 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:

None

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 apimeta.API used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:

None

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 apimeta.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 iterable of student GitHub usernames.
  • api (API) – An implementation of apimeta.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.

  1. 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 apimeta.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
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 apimeta.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:

None

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