Clients

Clients#

access module#

class pydomjudge.clients.access.AccessClient(base_url, username, password)#

Bases: _Client

Client for retrieving access information for contests.

get_access_information(contest_id, strict=False)#

Retrieves access information for a specific contest.

Parameters:

contest_id (Union[str, int]) – The contest ID (path parameter).
Example – “1”
strict (bool, optional) – Whether to only include CCS compliant properties in the response (query parameter).
Default – False

Returns:

Access information for the given contest.

Return type:

AccessInformation

Raises:

requests.HTTPError – If the HTTP request to the API fails with status codes 400, 401, 403, or 404.

accounts module#

class pydomjudge.clients.accounts.AccountsClient(base_url, username, password)#

Bases: _Client

Client for retrieving account information for contests.

get_account(contest_id, account_id, strict=False)#

Retrieves the given account for a specific contest.

Sends a GET request to /api/v4/contests/{contest_id}/accounts/{account_id}.

Parameters:

contest_id (Union[str, int]) – The contest ID.
account_id (str) – The account ID.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The User object representing the account.

Return type:

User

Raises:

requests.HTTPError – If the request fails with status codes 400, 401, 403, or 404.

get_all_accounts(contest_id, idlist=None, team_id=None, strict=False)#

Retrieves all accounts for a given contest.

Sends a GET request to /api/v4/contests/{contest_id}/accounts to fetch account information.

Parameters:

contest_id (Union[str, int]) – The contest ID.
idlist (List[str], optional) – List of account IDs to filter the results.
team_id (str, optional) – Only show accounts for the given team.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of User objects representing the accounts for the contest.

Return type:

List[User]

Raises:

requests.HTTPError – If the request fails with status codes 400, 401, 403, or 404.

get_current_account(contest_id, strict=False)#

Retrieves information about the currently logged in account for a specific contest.

Sends a GET request to /api/v4/contests/{contest_id}/account.

Parameters:

contest_id (Union[str, int]) – The contest ID.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The User object representing the currently logged in account.

Return type:

User

Raises:

requests.HTTPError – If the request fails with status codes 400, 401, 403, or 404.

awards module#

class pydomjudge.clients.awards.AwardsClient(base_url, username, password)#

Bases: _Client

Client for retrieving award information for contests.

get_all_awards(contest_id, strict=False)#

Get all the awards standings for a contest.

Parameters:

contest_id (Union[str, int]) – The contest ID.
strict (bool) – Whether to only include CCS compliant properties.

Returns:

List of Award objects.

Return type:

List[Award]

get_award(contest_id, award_id, strict=False)#

Retrieve a specific award for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
award_id (str) – The ID of the award to retrieve.
strict (bool, optional) – Whether to enforce strict validation. Defaults to False.

Returns:

The Award object corresponding to the specified contest and award.

Return type:

Award

Raises:

requests.HTTPError – If the HTTP request returned an unsuccessful status code.
pydantic.ValidationError – If the response data cannot be validated as an Award.

balloons module#

class pydomjudge.clients.balloons.BalloonsClient(base_url, username, password)#

Bases: _Client

Client for retrieving balloon information for contests.

get_all_balloons(contest_id, todo=None)#

Retrieve all balloons for a specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve balloons for.
todo (bool, optional) – If specified, filters balloons based on their ‘todo’ status.

Returns:

A list of Balloon objects for the given contest.

Return type:

List[Balloon]

Raises:

requests.HTTPError – If the HTTP request to the API fails.

mark_balloon_done(contest_id, balloon_id)#

Marks a balloon as delivered (done) for a specific contest.

Sends a POST request to the API to update the status of the specified balloon.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
balloon_id (int) – The ID of the balloon to mark as done.

Raises:

requests.HTTPError – If the API request fails.

Return type:

None

clarifications module#

class pydomjudge.clients.clarifications.ClarificationsClient(base_url, username, password)#

Bases: _Client

Client for retrieving clarification information for contests.

add_clarification(contest_id, clarification)#

Adds a new clarification to the specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to which the clarification will be added.
clarification (ClarificationPost) – The clarification data to be posted.

Returns:

The created clarification object as returned by the API.

Return type:

Clarification

Raises:

requests.HTTPError – If the API request fails.

get_all_clarifications(contest_id, idlist=None, problem=None, strict=False)#

Retrieve all clarifications for a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to fetch clarifications for.
idlist (List[Union[str, int]], optional) – A list of clarification IDs to filter the results. Defaults to None.
problem (Union[str, int], optional) – The problem ID to filter clarifications by a specific problem. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Clarification objects retrieved from the contest.

Return type:

List[Clarification]

Raises:

requests.HTTPError – If the HTTP request to the API fails.

get_clarification(contest_id, clarification_id, strict=False)#

Retrieve a specific clarification for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
clarification_id (Union[str, int]) – The ID of the clarification to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The clarification object corresponding to the provided IDs.

Return type:

Clarification

Raises:

requests.HTTPError – If the HTTP request to the API fails.
pydantic.ValidationError – If the response data cannot be validated as a Clarification.

contests module#

class pydomjudge.clients.contests.ContestsClient(base_url, username, password)#

Bases: _Client

Client for retrieving contest information.

add_contest(contest_data, strict=False)#

Adds a new contest to the system using the provided contest data.

Parameters:

contest_data (dict) – A dictionary containing the contest information to be added.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The response from the server after adding the contest.

Return type:

str

Raises:

requests.HTTPError – If the request to add the contest fails.

change_contest_start_time(contest_id, start_time, force=False, strict=False)#

Change the start time of a contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to update.
start_time (str) – The new start time for the contest in ISO 8601 format.
force (bool, optional) – Whether to force the change even if there are conflicts. Defaults to False.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The response from the server as a JSON string.

Return type:

str

Raises:

requests.HTTPError – If the request to the server fails.

delete_contest_banner(contest_id, strict=False)#

Deletes the banner associated with a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest whose banner is to be deleted.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Raises:

requests.HTTPError – If the HTTP request to delete the banner fails.

Return type:

None

get_all_contests(idlist=None, only_active=False, strict=False)#

Retrieve a list of contests from the API.

Parameters:

idlist (List[str], optional) – A list of contest IDs to filter the results. Defaults to None.
only_active (bool, optional) – If True, only return active contests. Defaults to False.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Contest objects retrieved from the API.

Return type:

List[Contest]

Raises:

requests.HTTPError – If the API request fails.

get_contest(contest_id, strict=False)#

Retrieve contest information by contest ID.

Parameters:

contest_id (Union[str, int]) – The unique identifier of the contest to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

An instance of the Contest model populated with the contest data.

Return type:

Contest

Raises:

requests.HTTPError – If the HTTP request to the contest API fails.
ValidationError – If the response data cannot be validated against the Contest model.

get_contest_banner(contest_id, strict=False)#

Retrieve the banner image for a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve the banner for.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The content of the contest banner image.

Return type:

bytes

Raises:

requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_contest_state(contest_id, strict=False)#

Retrieve the state of a specific contest.

Parameters:

contest_id (Union[str, int]) – The unique identifier of the contest.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

An instance representing the current state of the contest.

Return type:

ContestState

Raises:

requests.HTTPError – If the HTTP request to the API fails.
pydantic.ValidationError – If the response data cannot be validated as a ContestState.

get_contest_status(contest_id, strict=False)#

Retrieves the status of a specific contest.

Parameters:

contest_id (Union[str, int]) – The unique identifier of the contest.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

An object representing the contest’s status.

Return type:

ContestStatus

Raises:

requests.HTTPError – If the HTTP request to the API fails.
pydantic.ValidationError – If the response data cannot be validated into a ContestStatus object.

get_contest_yaml(contest_id, strict=False)#

Retrieve the contest YAML configuration for a specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve the YAML for.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The contest YAML configuration as a string.

Return type:

str

Raises:

requests.HTTPError – If the HTTP request to the server fails.

get_event_feed(contest_id, since_id=None, types=None, stream=True, strict=False)#

Retrieves the event feed for a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve events for.
since_id (str, optional) – If provided, only events after this ID will be returned.
types (List[str], optional) – A list of event types to filter the feed.
stream (bool, optional) – If True, enables streaming of events. Defaults to True.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of validated Event objects from the contest’s event feed.

Return type:

List[Event]

Raises:

requests.HTTPError – If the HTTP request to the event feed fails.

get_samples_zip(contest_id, strict=False)#

Downloads a ZIP file containing sample data for a specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve samples for.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The content of the ZIP file containing the samples.

Return type:

bytes

Raises:

requests.HTTPError – If the HTTP request fails or returns an unsuccessful status code.

set_contest_banner(contest_id, banner, strict=False)#

Uploads and sets a banner image for a specific contest.

Parameters:

contest_id (Union[str, int]) – The unique identifier of the contest.
banner (bytes) – The banner image data to upload.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Raises:

requests.HTTPError – If the HTTP request fails or the server returns an error response.

Return type:

None

executables module#

class pydomjudge.clients.executables.ExecutablesClient(base_url, username, password)#

Bases: _Client

Client for retrieving executable information from the API.

get_executable(executable_id, strict=False)#

Retrieve information about a specific executable by its ID.

Parameters:

executable_id (str) – The unique identifier of the executable to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A dictionary containing the executable’s details as validated by the model.

Return type:

Dict

Raises:

requests.HTTPError – If the HTTP request to the API fails.

general module#

class pydomjudge.clients.general.GeneralClient(base_url, username, password)#

Bases: _Client

Client for retrieving general information from the API.

check_config(strict=False)#

Checks the configuration of the server via the API.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: The JSON response from the server containing the configuration check results.
Return type:: Dict
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_api_info(strict=False)#

Retrieves API information from the server.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: The JSON response containing API information.
Return type:: Dict
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_api_root(strict=False)#

Retrieves the API root information from the server.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: The JSON response from the API root endpoint.
Return type:: Dict
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_api_version(strict=False)#

Retrieves the API version information from the server.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: A dictionary containing the API version details.
Return type:: Dict
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_config(name=None, strict=False)#

Retrieve configuration settings from the API.

Parameters:

name (str, optional) – The name of the configuration setting to retrieve. If None, retrieves all settings.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The configuration data returned by the API.

Return type:

Dict

Raises:

requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_country_flag(country_code, size, strict=False)#

Retrieves the flag image for a specified country.

Parameters:

country_code (str) – The ISO country code for which to retrieve the flag.
size (str) – The desired size of the flag image (e.g., ‘small’, ‘medium’, ‘large’).
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The binary content of the flag image.

Return type:

bytes

Raises:

requests.HTTPError – If the HTTP request fails or returns an error status code.

get_general_status(strict=False)#

Retrieves the general status from the API.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: A list of dictionaries containing the general status information from the API.
Return type:: List[Dict]
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_user_info(strict=False)#

Retrieves information about the current user from the API.

Parameters:

strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

An instance of the User model populated with the user’s information from the API.

Return type:

User

Raises:

requests.HTTPError – If the HTTP request to the API fails.
pydantic.ValidationError – If the response data cannot be validated against the User model.

update_config(config_data, strict=False)#

Updates the configuration on the server with the provided data.

Parameters:

config_data (Dict) – A dictionary containing the configuration data to be updated.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The server’s response as a dictionary after updating the configuration.

Return type:

Dict

Raises:

requests.HTTPError – If the HTTP request returned an unsuccessful status code.

groups module#

class pydomjudge.clients.groups.GroupsClient(base_url, username, password)#

Bases: _Client

Client for retrieving team group information for contests.

add_group(contest_id, group_data, strict=False)#

Adds a new group to a specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to which the group will be added.
group_data (dict) – A dictionary containing the group’s data to be created.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

An instance of TeamCategory representing the newly created group.

Return type:

TeamCategory

Raises:

requests.HTTPError – If the HTTP request to the server fails.

get_all_groups(contest_id, idlist=None, public=None, strict=False)#

Retrieve all team groups for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to fetch groups for.
idlist (List[str], optional) – A list of group IDs to filter the results. Defaults to None.
public (bool, optional) – If set, filters groups by their public status. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of TeamCategory objects representing the groups.

Return type:

List[TeamCategory]

Raises:

requests.HTTPError – If the HTTP request fails.

get_group(contest_id, group_id, strict=False)#

Retrieve a specific group (team category) for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
group_id (str) – The ID of the group (team category) to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The retrieved team category object.

Return type:

TeamCategory

Raises:

requests.HTTPError – If the HTTP request fails.
pydantic.ValidationError – If the response cannot be validated as a TeamCategory.

judgehosts module#

class pydomjudge.clients.judgehosts.JudgehostsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing judgehost information from the API.

add_debug_info(hostname, judgetask_id, debug_info, strict=False)#

Adds debug information to a specific judgehost and judgetask.

Parameters:

hostname (str) – The hostname of the judgehost.
judgetask_id (int) – The ID of the judgetask to associate the debug info with.
debug_info (dict) – A dictionary containing the debug information to be added.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Raises:

requests.HTTPError – If the API request fails.

Return type:

None

add_judgehost(strict=False)#

Adds a new judgehost to the system.

Sends a POST request to the judgehosts API endpoint to add a judgehost.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: A list of Judging objects returned by the API after adding the judgehost.
Return type:: List[Judging]
Raises:: requests.HTTPError – If the API request fails.

add_judging_run(hostname, judgetask_id, judging_run_data, strict=False)#

Adds a judging run to a specified judgehost for a given judgetask.

Sends a POST request to the judgehost API to register a new judging run.

Parameters:

hostname (str) – The hostname of the judgehost to add the judging run to.
judgetask_id (int) – The ID of the judgetask associated with the judging run.
judging_run_data (dict) – The data describing the judging run to be added.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Raises:

requests.HTTPError – If the API request fails or returns an error status code.

Return type:

None

fetch_work_tasks(strict=False)#

Fetches work tasks for judgehosts from the API.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: A list of dictionaries representing the fetched work tasks.
Return type:: List[Dict]
Raises:: requests.HTTPError – If the HTTP request returned an unsuccessful status code.

get_files(file_type, file_id, strict=False)#

Retrieve files of a specified type and ID from the judgehost API.

Parameters:

file_type (str) – The type of file to retrieve (e.g., ‘executable’, ‘source’).
file_id (str) – The unique identifier of the file.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The content of the requested file.

Return type:

bytes

Raises:

requests.HTTPError – If the HTTP request fails or returns an unsuccessful status code.

get_judgehosts(hostname=None, strict=False)#

Retrieve a list of judgehosts from the API.

Parameters:

hostname (str, optional) – Filter judgehosts by hostname. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Judgehost objects retrieved from the API.

Return type:

List[Judgehost]

Raises:

requests.HTTPError – If the API request fails.

report_internal_error(error_data, strict=False)#

Reports an internal error to the judgehosts API.

Parameters:

error_data (dict) – A dictionary containing error details to be reported.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The response from the API after reporting the error.

Return type:

int

Raises:

requests.HTTPError – If the API request fails.

update_judgehost(hostname, judgehost_data, strict=False)#

Updates the information of a specific judgehost.

Parameters:

hostname (str) – The hostname of the judgehost to update.
judgehost_data (dict) – A dictionary containing the updated judgehost data.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Judgehost objects representing the updated judgehost(s).

Return type:

List[Judgehost]

Raises:

requests.HTTPError – If the HTTP request to update the judgehost fails.

update_judging(hostname, judgetask_id, judging_data, strict=False)#

Updates the judging data for a specific judgehost and judgetask.

Parameters:

hostname (str) – The hostname of the judgehost.
judgetask_id (int) – The ID of the judgetask to update.
judging_data (dict) – The data to update for the judging task.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Raises:

requests.HTTPError – If the HTTP request fails.

Return type:

None

judgements module#

class pydomjudge.clients.judgements.JudgementsClient(base_url, username, password)#

Bases: _Client

Client for retrieving judgement information for contests.

get_all_judgements(contest_id, idlist=None, result=None, submission_id=None, strict=False)#

Retrieve all judgements for a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve judgements from.
idlist (List[str], optional) – A list of judgement IDs to filter the results. Defaults to None.
result (str, optional) – Filter judgements by result (e.g., ‘accepted’, ‘rejected’). Defaults to None.
submission_id (str, optional) – Filter judgements by submission ID. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Judging objects representing the retrieved judgements.

Return type:

List[Judging]

Raises:

requests.HTTPError – If the HTTP request fails.

get_judgement(contest_id, judgement_id, strict=False)#

Retrieve a specific judgement for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
judgement_id (str) – The ID of the judgement to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The validated Judging object corresponding to the requested judgement.

Return type:

Judging

Raises:

requests.HTTPError – If the HTTP request returned an unsuccessful status code.
pydantic.ValidationError – If the response data cannot be validated as a Judging object.

judgetypes module#

class pydomjudge.clients.judgetypes.JudgeTypesClient(base_url, username, password)#

Bases: _Client

Client for retrieving judgement type information for contests.

get_all_judgement_types(contest_id, idlist=None, strict=False)#

Retrieve all judgement types for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to retrieve judgement types for.
idlist (List[str], optional) – A list of judgement type IDs to filter the results. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of JudgementType objects representing the judgement types for the contest.

Return type:

List[JudgementType]

Raises:

requests.HTTPError – If the HTTP request to the API fails.

get_judgement_type(contest_id, judgement_type_id, strict=False)#

Retrieve a specific judgement type for a given contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
judgement_type_id (str) – The ID of the judgement type to retrieve.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The retrieved judgement type object.

Return type:

JudgementType

Raises:

requests.HTTPError – If the HTTP request fails.
pydantic.ValidationError – If the response data is invalid for JudgementType.

languages module#

class pydomjudge.clients.languages.LanguagesClient(base_url, username, password)#

Bases: _Client

Client for retrieving language information for contests.

get_all_languages(contest_id, idlist=None, strict=False)#

Retrieve all languages for a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
idlist (List[str], optional) – List of language identifiers to filter. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of language objects.

Return type:

List[Language]

get_language(contest_id, language_id, strict=False)#

Retrieve a specific language for a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
language_id (str) – The language identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The requested language object.

Return type:

Language

metrics module#

class pydomjudge.clients.metrics.MetricsClient(base_url, username, password)#

Bases: _Client

Client for retrieving Prometheus metrics from the API.

get_metrics(strict=False)#

Retrieve Prometheus metrics.

Parameters:: strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.
Returns:: The metrics in Prometheus format.
Return type:: str

organizations module#

class pydomjudge.clients.organizations.OrganizationsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing organization (team affiliation) information for contests.

add_organization(contest_id, organization_data, strict=False)#

Add a new organization (team affiliation) to a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
organization_data (dict) – The organization data to add.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The added organization details.

Return type:

TeamAffiliation

delete_organization_logo(contest_id, organization_id, strict=False)#

Delete the logo of an organization.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
organization_id (str) – The organization identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

get_all_organizations(contest_id, idlist=None, country=None, strict=False)#

Retrieve all organizations (team affiliations) for a given contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
idlist (List[str], optional) – List of organization IDs to filter. Defaults to None.
country (str, optional) – Country code to filter organizations. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of organization details.

Return type:

List[TeamAffiliation]

get_organization(contest_id, organization_id, strict=False)#

Retrieve details of a specific organization (team affiliation) for a given contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
organization_id (str) – The organization identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The organization details.

Return type:

TeamAffiliation

get_organization_logo(contest_id, organization_id, strict=False)#

Get the logo of an organization.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
organization_id (str) – The organization identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The logo image data.

Return type:

bytes

set_organization_logo(contest_id, organization_id, logo, strict=False)#

Set the logo of an organization.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
organization_id (str) – The organization identifier.
logo (bytes) – The logo image data.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

problems module#

class pydomjudge.clients.problems.ProblemsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing problem information for contests.

add_problem(contest_id, problem_data, strict=False)#

Add a single problem to a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problem_data (dict) – The problem data to upload.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The added problem ID.

Return type:

str

add_problems(contest_id, problems_data, strict=False)#

Add multiple problems to a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problems_data (dict) – The problems data to upload.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of added problem IDs.

Return type:

List[str]

get_all_problems(contest_id, idlist=None, strict=False)#

Retrieve all problems from a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
idlist (List[str], optional) – List of problem IDs to filter. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of retrieved problem objects.

Return type:

List[ContestProblem]

get_problem(contest_id, problem_id, strict=False)#

Retrieve a specific problem from a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problem_id (str) – The problem identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The retrieved problem object.

Return type:

ContestProblem

get_problem_statement(contest_id, problem_id, strict=False)#

Retrieve the statement for a specific problem in a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problem_id (str) – The problem identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The problem statement content.

Return type:

bytes

link_problem(contest_id, problem_id, problem_data, strict=False)#

Link a problem to a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problem_id (str) – The problem identifier.
problem_data (dict) – The data to link the problem.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The linked problem object.

Return type:

ContestProblem

unlink_problem(contest_id, problem_id, strict=False)#

Unlink a problem from a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
problem_id (str) – The problem identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

Returns:

None

runs module#

class pydomjudge.clients.runs.RunsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing run (submission) information for contests.

get_all_runs(contest_id, idlist=None, first_id=None, last_id=None, judging_id=None, limit=None, strict=False)#

Retrieve all runs for a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
idlist (List[str], optional) – List of run IDs to filter.
first_id (str, optional) – First run ID for pagination.
last_id (str, optional) – Last run ID for pagination.
judging_id (str, optional) – Judging ID to filter runs.
limit (int, optional) – Maximum number of runs to return.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of JudgingRun objects.

Return type:

List[JudgingRun]

get_run(contest_id, run_id, strict=False)#

Retrieve a specific run for a contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
run_id (str) – The run identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The requested JudgingRun object.

Return type:

JudgingRun

scoreboards module#

class pydomjudge.clients.scoreboards.ScoreboardsClient(base_url, username, password)#

Bases: _Client

Client for retrieving scoreboard information for contests.

get_scoreboard(contest_id, allteams=None, category=None, country=None, affiliation=None, public=None, sortorder=None)#

Retrieve the scoreboard for a specific contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest.
allteams (bool, optional) – If True, include all teams in the scoreboard.
category (Union[str, int], optional) – Filter teams by category ID or name.
country (str, optional) – Filter teams by country code.
affiliation (Union[str, int], optional) – Filter teams by affiliation ID or name.
public (bool, optional) – If True, retrieve the public scoreboard.
sortorder (int, optional) – Specify the sort order for the scoreboard.

Returns:

The validated scoreboard object for the contest.

Return type:

Scoreboard

Raises:

requests.HTTPError – If the HTTP request to the API fails.

submissions module#

class pydomjudge.clients.submissions.SubmissionsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing submission information for contests.

add_submission(contest_id, submission_data, strict=False)#

Add a new submission.

Parameters:

contest_id (Union[str, int]) – The contest ID.
submission_data (dict) – The submission data to send (should include files and metadata).
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The created submission response.

Return type:

str

get_submission(contest_id, submission_id, strict=False)#

Retrieve a specific submission.

Parameters:

contest_id (Union[str, int]) – The contest ID.
submission_id (Union[str, int]) – The submission ID.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The requested Submission object.

Return type:

Submission

get_submission_files(contest_id, submission_id, strict=False)#

Retrieve the archive files for a specific submission.

Parameters:

contest_id (Union[str, int]) – The contest ID.
submission_id (Union[str, int]) – The submission ID.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of ArchiveFile objects for the submission.

Return type:

List[ArchiveFile]

get_submission_source_code(contest_id, submission_id, strict=False)#

Retrieve the source code files for a specific submission.

Parameters:

contest_id (Union[str, int]) – The contest ID.
submission_id (Union[str, int]) – The submission ID.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of SourceCode objects for the submission.

Return type:

List[SourceCode]

get_submissions(contest_id, idlist=None, language_id=None, strict=False)#

Retrieve a list of submissions for a contest.

Parameters:

contest_id (Union[str, int]) – The contest ID.
idlist (List[Union[str, int]], optional) – List of submission IDs to filter. Defaults to None.
language_id (str, optional) – Filter submissions by language ID. Defaults to None.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

A list of Submission objects.

Return type:

List[Submission]

update_submission(contest_id, submission_id, submission_data, strict=False)#

Update a submission.

Parameters:

contest_id (Union[str, int]) – The contest ID.
submission_id (str) – The submission ID.
submission_data (dict) – The data to update the submission with.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The updated submission response.

Return type:

str

teams module#

class pydomjudge.clients.teams.TeamsClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing team information for contests.

add_team(contest_id, team_data, strict=False)#

Adds a new team to a specified contest.

Parameters:

contest_id (Union[str, int]) – The ID of the contest to add the team to.
team_data (dict) – A dictionary containing the team’s data.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The created Team object.

Return type:

Team

Raises:

requests.HTTPError – If the request to the server fails.

delete_team(contest_id, team_id, strict=False)#

Delete a team from a specified contest.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

delete_team_photo(contest_id, team_id, strict=False)#

Delete a team’s photo.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

get_all_teams(contest_id, idlist=None, category=None, affiliation=None, public=None, strict=False)#

Retrieve all teams for a specified contest, with optional filters.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
idlist (List[str], optional) – List of team IDs to filter.
category (str, optional) – Category to filter teams.
affiliation (str, optional) – Affiliation to filter teams.
public (bool, optional) – Filter by public teams.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

List of Team objects.

Return type:

List[Team]

Raises:

requests.HTTPError – If the request to the server fails.

get_team(contest_id, team_id, strict=False)#

Retrieve a team’s information.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The requested team object.

Return type:

Team

Raises:

requests.HTTPError – If the request to the server fails.

get_team_photo(contest_id, team_id, strict=False)#

Get a team’s photo.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The photo file content.

Return type:

bytes

set_team_photo(contest_id, team_id, photo, strict=False)#

Set or update a team’s photo.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
photo (bytes) – The photo file content.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Return type:

None

update_team(contest_id, team_id, team_data, strict=False)#

Update a team’s information.

Parameters:

contest_id (Union[str, int]) – The contest identifier.
team_id (str) – The team identifier.
team_data (dict) – The updated team data.
strict (bool, optional) – Whether to only include CCS compliant properties in the response. Defaults to False.

Returns:

The updated team object.

Return type:

Team

users module#

class pydomjudge.clients.users.UsersClient(base_url, username, password)#

Bases: _Client

Client for retrieving and managing user information from the API.

add_accounts(accounts_data)#

Adds multiple user accounts by sending account data to the API.

Parameters:: accounts_data (dict) – A dictionary containing account information to be uploaded.
Returns:: The JSON response from the API after creating the accounts.
Return type:: dict
Raises:: requests.HTTPError – If the API request fails.

add_groups(groups_data)#

Adds user groups by sending a POST request to the API.

Parameters:: groups_data (dict) – A dictionary containing group data to be added.
Returns:: The JSON response from the API after adding the groups.
Return type:: dict
Raises:: requests.HTTPError – If the API request fails.

add_organizations(organizations_data)#

Adds organizations to a user via the API.

Parameters:: organizations_data (dict) – A dictionary containing organization data to be added.
Returns:: The JSON response from the API after adding the organizations.
Return type:: dict
Raises:: requests.HTTPError – If the API request fails.

add_teams(teams_data)#

Adds multiple teams to the system via the API.

Parameters:: teams_data (dict) – A dictionary containing team data to be uploaded. The structure should match the expected format for the API endpoint.
Returns:: The JSON response from the API after adding the teams.
Return type:: dict
Raises:: requests.HTTPError – If the API request fails or returns an error status code.

add_user(user_data)#

Adds a new user to the system using the provided user data.

Parameters:: user_data (dict) – A dictionary containing the user’s information to be added.
Returns:: An instance of the User model representing the newly created user.
Return type:: User
Raises:: requests.HTTPError – If the request to add the user fails.

delete_user(user_id)#

Deletes a user with the specified user ID from the system.

Parameters:: user_id (str) – The unique identifier of the user to be deleted.
Raises:: requests.HTTPError – If the HTTP request to delete the user fails.
Return type:: None

get_all_users(idlist=None, team_id=None)#

Retrieve a list of users from the API.

Parameters:

idlist (List[str], optional) – A list of user IDs to filter the results. Defaults to None.
team_id (str, optional) – The team ID to filter users by team. Defaults to None.

Returns:

A list of User objects retrieved from the API.

Return type:

List[User]

Raises:

requests.HTTPError – If the API request fails.

get_user(user_id)#

Return type:: User

update_user(user_id, user_data)#

Updates the details of a user with the specified user ID.

Parameters:

user_id (str) – The unique identifier of the user to update.
user_data (dict) – A dictionary containing the user fields to update.

Returns:

An instance of the User model representing the updated user.

Return type:

User

Raises:

requests.HTTPError – If the HTTP request to update the user fails.

Clients

Contents

Clients#

access module#

accounts module#

awards module#

balloons module#

clarifications module#

contests module#

executables module#

general module#

groups module#

judgehosts module#

judgements module#

judgetypes module#

languages module#

metrics module#

organizations module#

problems module#

runs module#

scoreboards module#

submissions module#

teams module#

users module#