rcds.project — Projects

class rcds.Project(root: pathlib.Path, docker_client: Optional[docker.client.DockerClient] = None)

An rCDS project; the context that all actions are done within

rcds.project.config - Config loading

Functions for loading project config files

rcds.project.config.check_config(config_file: pathlib.Path) → Tuple[Optional[Dict[str, Any]], Optional[Iterable[rcds.errors.ValidationError]]]

Load and validate a config file, returning any errors encountered.

If the config file is valid, the tuple returned contains the loaded config as the first element, and the second element is None. Otherwise, the second element is an iterable of errors that occurred during validation

This method wraps parse_config().

Parameters

config_file (pathlib.Path) – The challenge config to load

rcds.project.config.load_config(config_file: pathlib.Path) → Dict[str, Any]

Loads a config file, or throw an exception if it is not valid

This method wraps check_config(), and throws the first error returned if there are any errors.

Parameters

config_file (pathlib.Path) – The challenge config to load

Returns

The loaded config

rcds.project.config.parse_config(config_file: pathlib.Path) → Iterable[Union[rcds.errors.ValidationError, Dict[str, Any]]]

Load and validate a config file, returning both the config and any errors encountered.

Parameters

config_file (pathlib.Path) – The challenge config to load

Returns

Iterable containing any errors (all instances of rcds.errors.ValidationError) and the parsed config. The config will always be last.

rcds.project.assets - Asset management

class rcds.project.assets.AssetManager(project: rcds.Project)

Class for managing assets from challenges that are provided to competitors

This class manages all assets under a given project.

create_context(name: str) → rcds.project.assets.AssetManagerContext

Create a subcontext within the AssetManager

Parameters

name (str) – The name of the context (challenge id)

Raises

ValueError – if the context name is not valid

list_context_names() → Iterable[str]

List the names of all subcontexts within this AssetManager

Returns

The contexts’ names. Call create_context() on a name to obtain a AssetManagerContext object

class rcds.project.assets.AssetManagerContext(asset_manager: rcds.project.assets.AssetManager, name: str)

A subcontext within an AssetManager

Represents a namespace within the AssetManager, essentially a subdirectory. The context holds assets for a challenge with the same id

This class is not meant to be constructed directly, use AssetManager.create_context()

clear() → None

Clear all files in this context

exists(name: str) → bool

Queries if an asset exists

Parameters

name (str) – The name of the asset

Returns

Whether or not it exists

get(name: str) → pathlib.Path

Retrieves the asset

Parameters

name (str) – The name of the asset

Returns

The asset

get_mtime(name: str) → float

Retrieves the time an asset was modified

Parameters

name (str) – The name of the asset

Returns

The time the asset was modified (:attr`os.stat_result.st_mtime`)

ls() → Iterable[str]

List all files within this context

Returns

The list of asset names

sync(*, check: bool = True)

Syncs the manifest for this context to disk

Parameters

check (bool) – If true (default), check to make sure all files in the manifest exist, and that there are no extra files

transaction() → rcds.project.assets.AssetManagerTransaction

Create a AssetManagerTransaction.

Only one transaction can be created at a time.

Returns

The transaction

Raises

RuntimeError – when attempting to create a transaction while one already exists

class rcds.project.assets.AssetManagerTransaction(asset_manager_context: rcds.project.assets.AssetManagerContext)

A transaction within an AssetManagerContext

This class manages declarative transactional updates to a context, allowing you to declare the files that should exist in the context, the last time that file was modified, and a callable to run to get the file, should it be out-of-date in the cache. The transaction starts in a blank state; without adding anything by calling add(), commit() will clear the context. No actions are performed until commit() is called.

This classs is not meant to be constructed directly, use AssetManagerContext.transaction()

add(name: str, mtime: float, contents: Union[BinaryIO, pathlib.Path, bytes, Callable[], Union[BinaryIO, pathlib.Path, bytes]]]) → None

Add a file to the context

Parameters

• name (str) – The name of the asset to add

• mtime (float) – The time the asset to add was modified (os.stat_result.st_mtime)

• contents (File or Callable[[], File]) – The contents of the file - this can either be the contents directly as a File, or a thunk function that, when calls, returns the contents

Raises

• RuntimeError – if the transaction has already been committed

• ValueError – if the asset name is not valid

add_file(name: str, file: pathlib.Path)

Add an already-existing file on disk to the context

This wraps add()

Parameters

• name (str) – The name of the asset to add

• file (Path) – The path to the asset on disk

commit() → None

Commit the transaction.

This transaction can no longer be used after commit() is called.

rcds.project.assets.File

Something that the asset manager can interpret as a file (contents only)

Valid types:

• A pathlib.Path object referring to a file that already exists on-disk

• Any typing.BinaryIO object that is seekable

• A typing.ByteString object containing the contents of the file (internally this is converted to a io.BytesIO)

alias of Union[BinaryIO, pathlib.Path, bytes]