`repobee_plug` Module Reference

platform

Platform API specifications and wrappers.

class repobee_plug.platform.APIObject[source]: Base wrapper class for platform API objects.

class repobee_plug.platform.Issue(title, body, number=None, created_at=None, author=None, state=None, implementation=None)[source]

Wrapper class for an Issue API object.

static from_dict(asdict)[source]

Take a dictionary produced by Issue.to_dict and reconstruct the corresponding instance. The implementation field is lost in a to_dict -> from_dict roundtrip.

Return type:: Issue

to_dict()[source]: Return a dictionary representation of this namedtuple, without the implementation field.

class repobee_plug.platform.IssueState(value)[source]: Enum specifying a possible issue state.

class repobee_plug.platform.PlatformAPI(base_url, token, org_name, user)[source]

API base class that all API implementations should inherit from. This class functions similarly to an abstract base class, but with a few key distinctions that affect the inheriting class.

Public methods must override one of the public methods of _APISpec. If an inheriting class defines any other public method, an PlatformError is raised when the class is defined.
All public methods in _APISpec have a default implementation that simply raise a NotImplementedError. There is no requirement to implement any of them.

assign_members(team, members, permission=TeamPermission.PUSH)

Assign members to a team.

Parameters:

team (Team) – A team to assign members to.
members (Iterable[str]) – A list of usernames to assign as members to the team. Usernames that don’t exist are ignored.
permission (TeamPermission) – The permission to add users with.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform.

Return type:

None

assign_repo(team, repo, permission)

Assign a repository to a team, granting any members of the team permission to access the repository according to the specified permission.

Parameters:

team (Team) – The team to assign the repository to.
repo (Repo) – The repository to assign to the team.
permission (TeamPermission) – The permission granted to the team’s members with respect to accessing the repository.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform.

Return type:

None

close_issue(issue)

Close the provided issue.

Parameters:: issue (Issue) – The issue to close.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.
Return type:: None

create_issue(title, body, repo, assignees=None)

Create an issue in the provided repository.

Parameters:

title (str) – Title of the issue.
body (str) – Body of the issue.
repo (Repo) – The repository in which to open the issue.
assignees (Optional[Iterable[str]]) – Usernames to assign to the issue.

Return type:

Issue

Returns:

The created issue.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform.

create_repo(name, description, private, team=None)

Create a repository.

If the repository already exists, it is fetched instead of created. This somewhat unintuitive behavior is to speed up repository creation, as first checking if the repository exists can be a bit inconvenient and/or inefficient depending on the platform.

Parameters:

name (str) – Name of the repository.
description (str) – Description of the repository.
private (bool) – Visibility of the repository.
team (Optional[Team]) – The team the repository belongs to.

Return type:

Repo

Returns:

The created (or fetched) repository.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform.

create_team(name, members=None, permission=TeamPermission.PUSH)

Create a team on the platform.

Parameters:

name (str) – Name of the team.
members (Optional[List[str]]) – A list of usernames to assign as members to this team. Usernames that don’t exist are ignored.
permission (TeamPermission) – The permission the team should have in regards to repository access.

Return type:

Team

Returns:

The created team.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform, in particular if the team already exists.

delete_repo(repo)

Delete a repository.

Parameters:: repo (Repo) – The repository to delete.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.
Return type:: None

delete_team(team)

Delete the provided team.

Parameters:: team (Team) – The team to delete.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.
Return type:: None

extract_repo_name(repo_url)

Extract a repo name from the provided url.

Parameters:: repo_url (str) – A URL to a repository.
Return type:: str
Returns:: The name of the repository corresponding to the url.

for_organization(org_name)

Create a copy of this API instance, targeting the given organization.

Parameters:: org_name (str) – Name of the organization to target.
Return type:: PlatformAPI
Returns:: A copy of the receiver API, but targeting the provided organization.

get_repo(repo_name, team_name)

Get a single repository.

Parameters:

repo_name (str) – Name of the repository to fetch.
team_name (Optional[str]) – Name of the team that owns the repository. If None, the repository is assumed to belong to the target organization.

Return type:

Repo

Returns:

The fetched repository.

Raises:

exceptions.PlatformError – If something goes wrong in communicating with the platform, in particular if the repo or team does not exist.

get_repo_issues(repo)

Get all issues related to a repo.

Parameters:: repo (Repo) – The repo to fetch issues from.
Return type:: Iterable[Issue]
Returns:: The issues related to the provided repo.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.

get_repo_urls(assignment_names, org_name=None, team_names=None, insert_auth=False)

Get repo urls for all specified repo names in the organization. As checking if every single repo actually exists takes a long time with a typical REST API, this function does not in general guarantee that the urls returned actually correspond to existing repos.

If the org_name argument is supplied, urls are computed relative to that organization. If it is not supplied, the target organization is used.

If the teams argument is supplied, student repo urls are computed instead of master repo urls.

Parameters:

assignment_names (Iterable[str]) – A list of master repository names.
org_name (Optional[str]) – Organization in which repos are expected. Defaults to the target organization of the API instance.
team_names (Optional[List[str]]) – A list of team names specifying student groups.

Return type:

List[str]

Returns:

a list of urls corresponding to the repo names.

get_repos(repo_urls=None)

Get repositories from the platform.

Parameters:: repo_urls (Optional[List[str]]) – Repository URLs to filter the results by. URLs that do not exist on the platform are ignored. If repo_urls=None, all repos are fetched.
Return type:: Iterable[Repo]
Returns:: Repositories matching the filters.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.

get_team_repos(team)

Get all repos related to a team.

Parameters:: team (Team) – The team to fetch repos from.
Return type:: Iterable[Repo]
Returns:: The repos related to the provided team.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.

get_teams(team_names=None)

Get teams from the platform.

Parameters:: team_names (Optional[Iterable[str]]) – Team names to filter by. Names that do not exist on the platform are ignored. If team_names=None, all teams are fetched.
Return type:: Iterable[Team]
Returns:: Teams matching the filters.
Raises:: exceptions.PlatformError – If something goes wrong in communicating with the platform.

insert_auth(url)

Insert authorization token into the provided URL.

Parameters:: url (str) – A URL to the platform.
Return type:: str
Returns:: The same url, but with authorization credentials inserted.
Raises:: exceptions.InvalidURL – If the provided URL does not point to anything on the platform.

static verify_settings(user, org_name, base_url, token, template_org_name=None)

Verify the following (to the extent that is possible and makes sense for the specific platform):

An internet connection is available
Base url is correct
The token has sufficient access privileges
Target organization (specifiend by org_name) exists
- If template_org_name is supplied, this is also checked to exist.
User is owner in organization (verify by getting
- If template_org_name is supplied, user is also checked to be an owner of it.

organization member list and checking roles)

Should raise an appropriate subclass of PlatformError when a problem is encountered.

Parameters:

user (str) – The username to try to fetch.
org_name (str) – Name of the target organization.
base_url (str) – A base url to a github API.
token (str) – A secure OAUTH2 token.
org_name – Name of the master organization.

Returns:

True if the connection is well formed.

Raises:

PlatformError –

class repobee_plug.platform.Repo(name, description, private, url, implementation)[source]: Wrapper class for a Repo API object.

class repobee_plug.platform.Team(members, name, id, implementation)[source]: Wrapper class for a Team API object.

class repobee_plug.platform.TeamPermission(value)[source]: Enum specifying team permissions on creating teams. On GitHub, for example, this can be e.g. push or pull.

repobee_plug.platform.check_init_params(reference_params, compare_params)[source]: Check that the compare __init__’s parameters are a subset of the reference class’s version.

repobee_plug.platform.check_parameters(reference, compare)[source]

Check if the parameters match, one by one. Stop at the first diff and raise an exception for that parameter.

An exception is made for __init__, for which the compare may be a subset of the reference in no particular order.

repobee_plug.platform.methods(attrdict)[source]: Return all public methods and __init__ for some class.

repobee_plug.platform.parameters(function)[source]: Extract parameter names and default arguments from a function.

localreps

Local representations of API objects.

class repobee_plug.localreps.StudentRepo(name, team, url, _path=None)[source]

Local representation of a student repo.

name: Name of this repository.

team: The team this repository belongs to.

url: URL to the platform repository.

path: Path to the local copy of this repository.

class repobee_plug.localreps.StudentTeam(members, name='')[source]

Local representation of a student team.

members: A list of members of this team.

name: The name of this team.

class repobee_plug.localreps.TemplateRepo(name, url, _path=None)[source]

Local representation of a template repo.

name: Name of this repository.

url: URL to the platform repository.

path: Path to the local copy of this repository.

file_uri: File URI to the local copy of this repository.

config

Helpers related to configuration.

class repobee_plug.config.Config(config_path)[source]

Object representing RepoBee’s config.

This class defines read-only inheritance. This means that when you read a value from the config, for example with get(), it will do a recursive lookup in parent configs.

Writing to a config object, e.g. config[section][option] = value does not respect inheritance, and unconditionally writes to this config, and not any of its parents. Similarly, writing to disk with store() only writes to the most local config, and not to any of the parent configs.

Important

Changes to the config are only persisted if the Config.store() method is called.

Warning

The behavior of this class is currently not stable. Any minor release of RepoBee might bring breaking changes.

create_section(section_name)[source]

Add a section to the config.

Parameters:: section_name (str) – Name of the section.
Return type:: None

get(section_name, key, fallback=None)[source]

Get a value from the given section.

Parameters:

section_name (str) – Name of the section.
key (str) – Key to get the value for.
fallback (Optional[Any]) – An optional fallback value to use if the section or key do not exist.

Return type:

Optional[Any]

Returns:

The value for the section and key, or the fallback value if neither exist.

property parent: Config | None: Returns the parent config if defined, otherwise None.

property path: Path: Path to the config file.

refresh()[source]

Refresh the parser by reading from the config file. Does nothing if the config file does not exist.

Return type:: None

store()[source]

Write the current state of the config to the config file. If the directory does not exist, it is created.

Return type:: None

class repobee_plug.config.ConfigSection(*args, **kwargs)[source]: Protocol defining how a section of the config behaves.

exceptions

Exceptions for repobee_plug.

exception repobee_plug.exceptions.APIImplementationError(*args, **kwargs)[source]: Raise when an API is defined incorrectly.

exception repobee_plug.exceptions.BadCredentials(msg='', status=None)[source]: Raise when credentials are rejected.

exception repobee_plug.exceptions.FileError(*args, **kwargs)[source]: Raise if something goes wrong with reading from or writing to a file.

exception repobee_plug.exceptions.HookNameError(*args, **kwargs)[source]: Raise when a public method in a class that inherits from Plugin does not have a hook name.

exception repobee_plug.exceptions.InternetConnectionUnavailable(msg='could not establish an Internet connection')[source]: Raise when an internet connection cannot be established.

exception repobee_plug.exceptions.InvalidURL(msg='', status=None)[source]: Error to raise if a URL is provided to the platform API, but it is not a valid URL for the platform.

exception repobee_plug.exceptions.NotFoundError(msg='', status=None)[source]: An exception raised when a platform API fails to find a resource.

exception repobee_plug.exceptions.PlatformError(msg='', status=None)[source]: An exception raised when the API responds with an error code.

exception repobee_plug.exceptions.PlugError(*args, **kwargs)[source]: Base class for all repobee_plug exceptions.

exception repobee_plug.exceptions.ServiceNotFoundError(msg='', status=None)[source]: Raise if the base url can’t be located.

exception repobee_plug.exceptions.UnexpectedException(msg='', status=None)[source]: An exception raised when an API request raises an unexpected exception.

fileutils

Utility functions for reading and writing to files.

repobee_plug.fileutils.generate_repo_path(root, team_name, template_repo_name)[source]

Generate a relative path to the student repo.

Parameters:

team_name (str) – Name of the student team.
template_repo_name (str) – Name of the template repo.

Return type:

Path

Returns:

A relative path to the student repo.

repobee_plug.fileutils.hash_path(path)[source]

Hash the path with SHA1.

Important

This is not a security function, it’s just to avoid name collisions in.

Parameters:: path (Union[str, Path]) – A path to hash.
Return type:: str
Returns:: The hexdigest of the SHA1 hash of the path.

repobee_plug.fileutils.parse_students_file(path)[source]

Parse the students file.

Parameters:: path (Path) – Path to the students fil.
Return type:: List[StudentTeam]
Returns:: A list of teams.
Raises:: exceptions.FileError –

log

Logging functions.

repobee_plug.log.debug(msg)[source]

Equivalent to log(msg, level=logging.DEBUG).

Parameters:: msg (str) – A message to log.
Return type:: None

repobee_plug.log.error(msg)[source]

Equivalent to log(msg, level=logging.ERROR).

Parameters:: msg (str) – A message to log.
Return type:: None

repobee_plug.log.exception(msg)[source]

Log an exception.

Parameters:: msg (str) – A message to log.
Return type:: None

repobee_plug.log.info(msg)[source]

Equivalent to log(msg, level=logging.INFO).

Parameters:: msg (str) – A message to log.
Return type:: None

repobee_plug.log.log(msg, level)[source]

Log a message with a specific logging level.

Parameters:

msg (str) – A message to log.
level (int) – The logging level.

Return type:

None

repobee_plug.log.warning(msg)[source]

Equivalent to log(msg, level=logging.WARNING).

Parameters:: msg (str) – A message to log.
Return type:: None

name

Utility functions relating to RepoBee’s naming conventions.

repobee_plug.name.generate_repo_name(team_name, assignment_name)[source]

Construct a repo name for a team.

The behavior of this function can be overridden by implementing the repobee_plug._corehooks.generate_repo_name() hook.

Parameters:

team_name (Union[str, StudentTeam, Team]) – Name of the associated team.
assignment_name (str) – Name of an assignment.

Return type:

str

repobee_plug.name.generate_repo_names(team_names, assignment_names)[source]

Construct all combinations of generate_repo_name(team_name, assignment_name) for the provided team names and master repo names.

Parameters:

team_names (Iterable[Union[str, StudentTeam, Team]]) – One or more names of teams.
assignment_names (Iterable[str]) – One or more names of assignments.

Return type:

Iterable[str]

Returns:

a list of repo names for all combinations of team and master repo.

repobee_plug.name.generate_review_team_name(student, assignment_name)[source]

Generate a review team name.

Parameters:

student (Union[str, StudentTeam, Team]) – A student username.
assignment_name (str) – Name of an assignment.

Return type:

str

Returns:

a review team name for the student repo associated with this master repo and student.

reviews

Containers and helpers for peer review plugins.

class repobee_plug.reviews.Review(repo, done)

Parameters:

repo (Repo) – The reviewed repository.
done (bool) – Whether or not the review is done.

done: Alias for field number 1

repo: Alias for field number 0

class repobee_plug.reviews.ReviewAllocation(review_team, reviewed_team)

Parameters:

review_team (Team) – The team of reviewers.
reviewed_team (Team) – The team that is to be reviewed.

review_team: Alias for field number 0

reviewed_team: Alias for field number 1

deprecation

Module with functions for dealing with deprecation.

class repobee_plug.deprecation.Deprecation(replacement, remove_by_version)

Parameters:

replacement (str) – The functionality that replaces the deprecated functionality.
remove_by_version (str) – A version number on the form MAJOR.MINOR.PATCH by which the deprecated functionality will be removed.

remove_by_version: Alias for field number 1

replacement: Alias for field number 0

repobee_plug.deprecation.deprecate(remove_by_version, replacement=None)[source]

Return a function that can be used to deprecate functions. Currently this is only used for deprecation of hook functions, but it may be expanded to deprecated other things in the future.

Parameters:

remove_by_version (str) – A string that should contain a version number.
replacement (Optional[str]) – An optional string with the name of the replacing function.

Return type:

Callable[[TypeVar(T)], TypeVar(T)]

Returns:

A function

repobee_plug.deprecation.deprecated_hooks()[source]

Return type:: Mapping[str, Deprecation]
Returns:: A mapping of hook names to Deprecation tuples.

serialize

JSON serialization/deserialization functions.

repobee_plug.serialize.json_to_result_mapping(json_string)[source]

Deserialize a JSON string to a mapping repo_name: str -> hook_results: List[Result]

Return type:: Mapping[str, List[Result]]

repobee_plug.serialize.result_mapping_to_json(result_mapping)[source]

Serialize a result mapping repo_name: str -> hook_results: List[Result] to JSON.

Return type:: str

cli

The cli subpackage contains the specific parts to extend RepoBee’s command line interface.

Important

The vast majority of the classes and functions of this package can be accessed from the cli package. Canonical usage of most functionality is like this:

import repobee_plug as plug

class ExtCommand(plug.Plugin, plug.cli.Command):
    is_awesome = plug.cli.flag(help="whether or not everything is awesome")

    def command(self):
        print(f"Everything is awesome = {self.is_awesome}")

args

Command line options for extension commands.

class repobee_plug.cli.args.ConfigurableArguments(config_section_name, argnames)[source]: A container for holding a plugin’s configurable arguments.

repobee_plug.cli.args.flag(short_name=None, long_name=None, help='', const=True, default=None)[source]

Create a command line flag for a Command or a :py:class`CommandExtension`. This is simply a convenience wrapper around option().

A flag is specified on the command line as --flag, and causes a constant to be stored. If the flag is omitted, a default value is used instead. The default behavior is that specifying --flag stores the constant True, and omitting it causes it to default to False. It can also be used to store any other form of constant by specifying the const argument. If so, then omitting the flag will cause it to default to None instead of False. Finally, the default value can also be overridden by specifying the default argument.

Example:

ext.py

import repobee_plug as plug


class Flags(plug.Plugin, plug.cli.Command):
    # a normal flag, which toggles between True and False
    is_great = plug.cli.flag()
    # a "reverse" flag which defaults to True instead of False
    not_great = plug.cli.flag(const=False, default=True)
    # a flag that stores a constant and defaults to None
    meaning = plug.cli.flag(const=42)
    # a flag that stores a constant and defaults to another constant
    approve = plug.cli.flag(const="yes", default="no")

    def command(self):
        print("is_great", self.is_great)
        print("not_great", self.not_great)
        print("meaning", self.meaning)
        print("approve", self.approve)

We can then call this command (for example) like so:

$ repobee -p ext.py flags --meaning --not-great
is_great False
not_great False
meaning 42
approve no

Danger

This function returns an _Option, which is an internal structure. You should not handle this value directly, it should only ever be assigned as an attribute to a command class.

Parameters:

short_name (Optional[str]) – The short name of this option. Must start with -.
long_name (Optional[str]) – The long name of this option. Must start with –.
help (str) – A description of this option that is used in the CLI help section.
const (Any) – The constant to store.
default (Optional[Any]) – The value to default to if the flag is omitted.

Return type:

_Option

Returns:

A CLI argument wrapper used internally by RepoBee to create command line argument.

repobee_plug.cli.args.is_cli_arg(obj)[source]

Determine if an object is a CLI argument.

Parameters:: obj (Any) – An object.
Return type:: bool
Returns:: True if the object is an instance of a CLI argument class.

repobee_plug.cli.args.mutually_exclusive_group(*, __required__=False, **kwargs)[source]

Create a mutually exclusive group of arguments in a command.

Danger

This function returns a _MutuallyExclusiveGroup, which is an internal structure. You should not handle this value directly, it should only ever be assigned as an attribute to a command class.

Parameters:

__required__ – Whether or not this mutex group is required.
kwargs – Keyword arguments on the form name=plug.cli.option().

repobee_plug.cli.args.option(short_name=None, long_name=None, help='', required=False, default=None, configurable=False, converter=None, argparse_kwargs=None)[source]

Create an option for a Command or a CommandExtension.

Example usage:

ext.py

import repobee_plug as plug


class Hello(plug.Plugin, plug.cli.Command):
    name = plug.cli.option(help="Your name.")
    age = plug.cli.option(converter=int, help="Your age.")

    def command(self):
        print(
            f"Hello, my name is {self.name} "
            f"and I am {self.age} years old"
        )

This command can then be called like so:

$ repobee -p ext.py hello --name Alice --age 22
Hello, my name is Alice and I am 22 years old

Danger

This function returns an _Option, which is an internal structure. You should not handle this value directly, it should only ever be assigned as an attribute to a command class.

Parameters:

short_name (Optional[str]) – The short name of this option. Must start with -.
long_name (Optional[str]) – The long name of this option. Must start with –.
help (str) – A description of this option that is used in the CLI help section.
required (bool) – Whether or not this option is required.
default (Optional[Any]) – A default value for this option.
configurable (bool) – Whether or not this option is configurable. If an option is both configurable and required, having a value for the option in the configuration file makes the option non-required.
converter (Optional[Callable[[str], Any]]) – A converter function that takes a string and returns the argument in its proper state. Should also perform input validation and raise an error if the input is malformed.
argparse_kwargs (Optional[Mapping[str, Any]]) – Keyword arguments that are passed directly to argparse.ArgumentParser.add_argument()

Return type:

_Option

Returns:

A CLI argument wrapper used internally by RepoBee to create command line arguments.

repobee_plug.cli.args.positional(help='', converter=None, argparse_kwargs=None)[source]

Create a positional argument for a Command or a CommandExtension.

Example usage:

ext.py

import repobee_plug as plug


class Hello(plug.Plugin, plug.cli.Command):
    name = plug.cli.positional(help="Your name.")
    age = plug.cli.positional(converter=int, help="Your age.")

    def command(self):
        print(
            f"Hello, my name is {self.name} "
            f"and I am {self.age} years old"
        )

This command can then be called like so:

$ repobee -p ext.py hello Alice 22
Hello, my name is Alice and I am 22 years old

Danger

This function returns an _Option, which is an internal structure. You should not handle this value directly, it should only ever be assigned as an attribute to a command class.

Parameters:

help (str) – The help section for the positional argument.
converter (Optional[Callable[[str], Any]]) – A converter function that takes a string and returns the argument in its proper state. Should also perform input validation and raise an error if the input is malformed.
argparse_kwargs (Optional[Mapping[str, Any]]) – Keyword arguments that are passed directly to argparse.ArgumentParser.add_argument()

Return type:

_Option

Returns:

A CLI argument wrapper used internally by RepoBee to create command line argument.

base

Specification for RepoBee’s core CLI categories and actions.

class repobee_plug.cli.base.BaseParser(value)[source]

Enumeration of base parsers that an extension command can request to have added to it.

BASE: Represents the base parser, which includes the --user, --org-name, --base-url and --token arguments.

STUDENTS: Represents the students parser, which includes the --students and –students-file` arguments.

ASSIGNMENTS: Represents the assignments parser, which includes the --assignments argument.

REPO_DISCOVERY: Represents the repo discovery parser, which adds both the --assignments and the --discover-repos arguments.

TEMPLATE_ORG: Represents the master organization parser, which includes the --master-org argument.

categorization

Categorization classes for CLI commands.

class repobee_plug.cli.categorization.Action(name, category)[source]

Class describing a RepoBee CLI action.

name: Name of this action.

category: The category this action belongs to.

as_name_dict()[source]

This is a convenience method for testing that returns a dictionary on the following form:

{"category": self.category.name "action": self.name}

Return type:: Mapping[str, str]
Returns:: A dictionary with the name of this action and its category.

as_name_tuple()[source]

This is a convenience method for testing that returns a tuple on the following form:

(self.category.name, self.name)

Return type:: Tuple[str, str]
Returns:: A dictionary with the name of this action and its category.

asdict()[source]

Same as Action.as_name_dict(), but with the proper Category and Action objects instead of strings.

Return type:: Mapping[str, Union[Category, Action]]
Returns:: A dictionary with the category and action.

astuple()[source]

Same as Action.as_name_tuple(), but with the proper Category and Action objects instead of strings.

Return type:: Tuple[Category, Action]
Returns:: A tuple with the category and action.

class repobee_plug.cli.categorization.Category(name=None, action_names=None, help=None, description=None)[source]

Class describing a command category for RepoBee’s CLI. The purpose of this class is to make it easy to programmatically access the different commands in RepoBee.

A full command in RepoBee typically takes the following form:

$ repobee <category> <action> [options ...]

For example, the command repobee issues list has category issues and action list. Actions are unique only within their category.

repobee_plug.cli.categorization.category(name, action_names, help='', description='')[source]

Create a category for CLI actions.

Parameters:

name (str) – Name of the category.
action_names (List[str]) – The actions of this category.

Return type:

Category

Returns:

A CLI category.

commandmarkers

Mixin classes for marking plugins as CLI commands/extensions.

class repobee_plug.cli.commandmarkers.Command[source]

Mixin class for use with the Plugin class. Explicitly marks a class as a plugin command.

A plugin command must have a command function defined in the class on the following form:

def command(self) -> Optional[plug.Result]:
    pass

Note that the type hints are not required, so the callback can be defined like this instead:

def command(self):
    pass

Example usage:

command.py

import repobee_plug as plug

class Greeting(plug.Plugin, plug.cli.Command):

    name = plug.cli.option(
        short_name="-n", help="your name", required=True
    )
    age = plug.cli.option(
        converter=int, help="your age", default=30
    )

    def command(self):
        print(f"Hello, my name is {self.name} and I am {self.age}")

Note that the file is called command.py. We can run this command with RepoBee like so:

$ repobee -p command.py greeting -n Alice
Hello, my name is Alice and I am 30

If your command requires the platform api, simply add an argument called api to the command function.

Command function that requires the platform API

def command(self, api: plug.PlatformAPI):
    pass

class repobee_plug.cli.commandmarkers.CommandExtension[source]: Mixin class for use with the Plugin class. Marks the extending class as a command extension, that adds options to an existing command.

io

IO functionality for plugins.

repobee_plug.cli.io.echo(msg)[source]

Echo a message to the command line.

Parameters:: msg (Any) – Any kind of object that can be converted into a human-readable string with the str function.
Return type:: None

repobee_plug.cli.io.progress_bar(it, *args, **kwargs)[source]

Create a progress bar for an iterable.

Danger

The API of this function is not stable and may change unexpectedly.

Parameters:

it (Iterable[TypeVar(T)]) – An iterable.
args – Positional arguments passed directly to the underlying implementation (currently tqdm).
kwargs – Keyword arguments passed directly to the underlying implementation (currently tqdm).

Return type:

Iterable[TypeVar(T)]

Returns:

An iterable object that returns elements from it, and also updates a progress bar in the terminal.

settings

Settings for declarative command line extensions.

class repobee_plug.cli.settings.CommandExtensionSettings(actions, config_section_name)

actions: Alias for field number 0

config_section_name: Alias for field number 1

class repobee_plug.cli.settings.CommandSettings(action, category, help, description, base_parsers, config_section_name)

action: Alias for field number 0

base_parsers: Alias for field number 4

category: Alias for field number 1

config_section_name: Alias for field number 5

description: Alias for field number 3

help: Alias for field number 2

repobee_plug.cli.settings.command_extension_settings(actions, config_section_name=None)[source]

Settings for a CommandExtension.

Parameters:

actions (List[Action]) – A list of actions to extend.
config_section_name (Optional[str]) – Name of the configuration section that the command extension will fetch configuration values from. Defaults to the name of the plugin in which the extension is defined.

Return type:

CommandExtensionSettings

Returns:

A wrapper object for settings.

repobee_plug.cli.settings.command_settings(action=None, category=None, help='', description='', base_parsers=None, config_section_name=None)[source]

Create a settings object for a Command.

Example usage:

ext.py

import repobee_plug as plug

class Ext(plug.Plugin, plug.cli.Command):
    __settings__ = plug.cli.command_settings(
        action_name="hello",
        category=plug.cli.CoreCommand.config,
    )

    def command(self):
        print("Hello, world!")

This can then be called with:

$ repobee -p ext.py config hello
Hello, world!

Parameters:

action (Union[str, Action, None]) – The name of this command, or a Action object that defines both category and action for the command. Defaults to the name of the plugin class.
category (Optional[Category]) – The category to place this command in. If not specified, then the command will be top-level (i.e. uncategorized). If action is an Action (as opposed to a str), then this argument is not allowed.
help (str) – A help section for the command. This appears when listing the help section of the command’s category.
description (str) – A help section for the command. This appears when listing the help section for the command itself.
base_parsers (Optional[List[BaseParser]]) – A list of base parsers to add to the command.
config_section_name (Optional[str]) – The name of the configuration section the command should look for configurable options in. Defaults to the name of the plugin the command is defined in.

Return type:

CommandSettings

Returns:

A settings object used internally by RepoBee.

_corehooks

Important

The _corehooks module is part of the module reference only for specification purposes. Plugin developers should never try to import from this module.

Hookspecs for repobee core hooks.

Core hooks provide the basic functionality of repobee. These hooks all have default implementations, but are overridden by any other implementation. All hooks in this module should have the firstresult=True option to the hookspec to allow for this dynamic override.

repobee_plug._corehooks.api_init_requires()[source]

Return which of the arguments to apimeta._APISpec.__init__ that the given API requires. For example, the GitHubAPI requires all, but the GitLabAPI does not require user.

Return type:: Tuple[str]
Returns:: Names of the required arguments.

repobee_plug._corehooks.generate_repo_name(team_name, assignment_name)[source]

This hook allows for overriding the behavior of repobee_plug.name.generate_repo_name().

Danger

The implementations of this hook should never be invoked other than in repobee_plug.name.generate_repo_name().

Parameters:

team_name (Union[str, StudentTeam, Team]) – Name of the associated team.
assignment_name (str) – Name of an assignment.

Return type:

str

repobee_plug._corehooks.generate_review_allocations(teams, num_reviews)[source]

Generate ReviewAllocation tuples from the provided teams, given that this concerns reviews for a single master repo.

The provided teams of students should be treated as units. That is to say, if there are multiple members in a team, they should always be assigned to the same review team. The best way to merge two teams team_a and team_b into one review team is to simply do:

team_c = plug.StudentTeam(members=team_a.members + team_b.members)

This can be scaled to however many teams you would like to merge. As a practical example, if teams team_a and team_b are to review team_c, then the following ReviewAllocation tuple, here called allocation, should be contained in the returned list.

review_team = plug.StudentTeam(
    members=team_a.members + team_b.members
)
allocation = plug.ReviewAllocation(
    review_team=review_team,
    reviewed_team=team_c,
)

Note

Respecting the num_reviews argument is optional: only do it if it makes sense. It’s good practice to issue a warning if num_reviews is ignored, however.

Parameters:

team – A list of student teams.
num_reviews (int) – Amount of reviews each student should perform (and consequently amount of reviewers per repo)

Return type:

List[ReviewAllocation]

Returns:

A list of review allocations tuples.

repobee_plug._corehooks.get_api_class()[source]

Return an API platform class. Must be a subclass of apimeta.API.

Returns:: An apimeta.API subclass.

repobee_plug._corehooks.parse_students_file(students_file)[source]

Parse the students file and return any student teams from it.

This hook is responsible for parsing the students file. The file passed to implementations of this hook is guaranteed to be non-empty, but it is up to implementations to verify that it’s syntactically correct.

Danger

This hook is unstable and may change without notice.

Parameters:: students_file (Path) – Path to a non-empty file.
Return type:: Iterable[StudentTeam]
Returns:: An iterable of student teams parsed from the file.

_exthooks

Important

The _exthooks module is part of the module reference only for specification purposes. Plugin developers should never try to import from this module.

Hookspecs for repobee extension hooks.

Extension hooks add something to the functionality of repobee, but are not necessary for its operation. Currently, all extension hooks are related to cloning repos.

repobee_plug._exthooks.clone_parser_hook(clone_parser)[source]

Do something with the clone repos subparser before it is used used to parse CLI options. The typical task is to add options to it.

Danger

This hook no longer has any effect, it is only kept for testing purposes.

Parameters:: clone_parser (ArgumentParser) – The clone subparser.
Return type:: None

repobee_plug._exthooks.config_hook(config_parser)[source]

Hook into the config file parsing.

Deprecated since version 3.6.0: Use handle_config() instead.

Parameters:: config_parser (ConfigParser) – The config parser after config has been read.
Return type:: None

repobee_plug._exthooks.get_configurable_args()[source]

Get the configurable arguments for a plugin.

Danger

This is not a public hook, don’t implement this manually!

Return type:: ConfigurableArguments
Returns:: The configurable arguments of a plugin.

repobee_plug._exthooks.handle_config(config)[source]

Handle the config.

This hook is allowed both to read the config, and to modify it before it’s passed to the core RepoBee application.

Warning

The Config class is currently not stable and its behavior may change.

Parameters:: config (Config) – RepoBee’s config.
Return type:: None

repobee_plug._exthooks.handle_parsed_args(args)[source]

Handle the parsed args from the parser, before any processing is applied.

Parameters:: args (Namespace) – The full namespace returned by argparse.ArgumentParser.parse_args()
Return type:: None

repobee_plug._exthooks.handle_processed_args(args)[source]

Handle the parsed command line arguments after RepoBee has applied processing.

Parameters:: args (Namespace) – A processed version of the parsed CLI arguments.
Return type:: None

repobee_plug._exthooks.post_clone(repo, api)[source]

Operate on a student repository after it has been cloned.

Parameters:

repo (StudentRepo) – A local representation of a student repo. The path attribute is always set to a valid directory containing the repo.
api (PlatformAPI) – An instance of the platform API.

Return type:

Optional[Result]

Returns:

Optionally returns a Result for reporting the outcome of the hook. May also return None, in which case no reporting will be performed for the hook.

repobee_plug._exthooks.post_setup(repo, api, newly_created)[source]

Operate on a student repo after the setup command has executed.

Parameters:

repo (StudentRepo) – A student repository.
api (PlatformAPI) – An instance of the platform API.
newly_created (bool) – False if the student repo already existed.

Return type:

Optional[Result]

Returns:

Optionally returns a Result for reporting the outcome of the hook. May also return None, in which case no reporting will be performed for the hook.

repobee_plug._exthooks.pre_setup(repo, api)[source]

Operate on a template repository before it is distributed to students.

Note

Changes to the template repo can be persisted by comitting them, making on-the-fly preprocessing possible. An example of this would be squashing the commits of the template repo before pushing it to students. Note that making any commit makes it impossible to later update student repos with the repos update command, as on-the-fly commits are unique by timestamp.

Parameters:

repo (TemplateRepo) – Representation of a local template repo.
api (PlatformAPI) – An instance of the platform API.

Return type:

Optional[Result]

Returns:

Optionally returns a Result for reporting the outcome of the hook. May also return None, in which case no reporting will be performed for the hook.

repobee_plug Module Reference

platform

localreps

config

exceptions

fileutils

log

name

reviews

deprecation

serialize

cli

args

base

categorization

commandmarkers

io

settings

_corehooks

_exthooks

`repobee_plug` Module Reference