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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_names (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- title_regex (
-
_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 ofrepobee_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: - repos (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_names (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_names (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_names (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type:
-
_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 theimplementation
attribute, so it does not need to be set. - api (
API
) – An implementation ofrepobee_plug.API
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.
- repos (
-
_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 ofrepobee_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: - master_repo_urls (
-
_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 ofrepobee_plug.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_urls (
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: Return type: 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: 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.
- sys_args (
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:
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:
-
_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.
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.
clone
(repo_urls, cwd='.')[source]¶ Clone all repos asynchronously.
Parameters: Return type: Returns: URLs from which cloning failed.
-
_repobee.git.
clone_single
(repo_url, branch='', cwd='.')[source]¶ Clone a git repository.
Parameters:
-
_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: Return type: 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: 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, orNone
iffunc
isNone
.- func (
-
_repobee.util.
find_files_by_extension
(root, *extensions)[source]¶ Find all files with the given file extensions, starting from root.
Parameters: Return type: 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.
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.
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
-
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
-
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: 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.
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
.
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.
query¶
A plugin that adds the query
command to RepoBee, allowing users to query
a hook results JSON file.