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.

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

  2. 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):

  1. An internet connection is available

  2. Base url is correct

  3. The token has sufficient access privileges

  4. Target organization (specifiend by org_name) exists
    • If template_org_name is supplied, this is also checked to exist.

  5. 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.

Type

str

team

The team this repository belongs to.

Type

repobee_plug.localreps.StudentTeam

url

URL to the platform repository.

Type

str

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.

Type

List[str]

name

The name of this team.

Type

str

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

Local representation of a template repo.

name

Name of this repository.

Type

str

url

URL to the platform repository.

Type

str

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: Optional[Config]

Returns the parent config if defined, otherwise None.

Return type

Optional[Config]

property path: Path

Path to the config file.

Return type

Path

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
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
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
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
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.

Type

str

category

The category this action belongs to.

Type

repobee_plug.cli.categorization.Category

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
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.