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 ofapimeta.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, 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 ofapimeta.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- master_repo_names (
-
repobee.command.
clone_repos
(master_repo_names, teams, api)[source]¶ Clone all student repos related to the provided master repos and student teams.
Parameters: 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 ofapimeta.API
used to interface with the platform (e.g. GitHub or GitLab) instance.
Return type: None
- title_regex (
-
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 ofapimeta.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
- master_repo_names (
-
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: Return type: None
-
repobee.command.
open_issue
(issue, master_repo_names, teams, api)[source]¶ Open an issue in student repos.
Parameters: 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: 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: 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 ofapimeta.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
- master_repo_urls (
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.
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.
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.
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)¶ 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
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: Return type: 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: Return type:
-
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: Return type: 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: Return type: 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.
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: Returns: a (peer_review_team -> reviewers) mapping for each student repository.
- master_repo_name (
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: Returns: a (peer_review_team -> reviewers) mapping for each student repository.
- master_repo_name (