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
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 ofrepobee_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
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 ofrepobee_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 theimplementation
attribute, so it does not need to be set.api (
PlatformAPI
) – An implementation ofrepobee_plug.PlatformAPI
used to interface with the platform (e.g. GitHub or GitLab) instance.
- Return type
- 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 ofrepobee_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
teams (
Iterable
[StudentTeam
]) – An iterable of teams to create.permission (
TeamPermission
) – The permission to assign to the team with respect to its repositories.api (
PlatformAPI
) – A platform API instance.
- Return type
- 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 ofrepobee_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.
- Return type
-
_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 ofrepobee_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
teams (
Iterable
[StudentTeam
]) – Team objects specifying student groups.issue (
Issue
) – An issue to open.api (
PlatformAPI
) – An implementation ofrepobee_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
students (
Iterable
[StudentTeam
]) – An iterble of student teams.api (
PlatformAPI
) – An implementation ofrepobee_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.
Push files from the master repos to the corresponding student repos.
- Parameters
teams (
Iterable
[StudentTeam
]) – An iterable of student teams specifying the teams to be setup.api (
PlatformAPI
) – An implementation ofrepobee_plug.PlatformAPI
used to interface with the platform (e.g. GitHub or GitLab) instance.
- Return type
-
_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 ofrepobee_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
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
- Returns
The primary parser.
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
- Return type
- 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.
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.
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.
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.
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.
-
_repobee.config.
check_defaults
(defaults, config_file)[source]¶ Raise an exception if defaults contain keys that are not configurable arguments.
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.
git¶
Wrapper functions for git commands.
-
_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.
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.
-
_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, orNone
iffunc
isNone
.
-
_repobee.util.
find_files_by_extension
(root, *extensions)[source]¶ Find all files with the given file extensions, starting from root.
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.
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.
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
-
create_issue
(title, body, repo, assignees=None)[source]¶ See
repobee_plug.PlatformAPI.create_issue()
.- Return type
-
create_repo
(name, description, private, team=None)[source]¶ See
repobee_plug.PlatformAPI.create_repo()
.- Return type
-
create_team
(name, members=None, permission=<TeamPermission.PUSH: 'push'>)[source]¶ See
repobee_plug.PlatformAPI.create_team()
.- Return type
-
get_repo_urls
(assignment_names, org_name=None, team_names=None, insert_auth=False)[source]¶ See
repobee_plug.PlatformAPI.get_repo_urls()
.
-
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
-
create_issue
(title, body, repo, assignees=None)[source]¶ See
repobee_plug.PlatformAPI.create_issue()
.- Return type
-
create_repo
(name, description, private, team=None)[source]¶ See
repobee_plug.PlatformAPI.create_repo()
.- Return type
-
create_team
(name, members=None, permission=<TeamPermission.PUSH: 'push'>)[source]¶ See
repobee_plug.PlatformAPI.create_team()
.- Return type
-
get_repo_urls
(assignment_names, org_name=None, team_names=None, insert_auth=False)[source]¶ See
repobee_plug.PlatformAPI.get_repo_urls()
.
-
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
repo (
StudentRepo
) – A student repo.api (
PlatformAPI
) – A platform API class instance.
- 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
- Returns
A list of allocations that