Handlers and database management

Process Functions

judge.handler.process_contest(contest_name, contest_start, contest_soft_end, contest_hard_end, penalty, is_public, enable_linter_score, enable_poster_score)

Function to process a new Contest.

Parameters

  • contest_name (str) – Name of the contest

  • contest_start (datetime) – A datetime object representing the beginning of the contest

  • contest_soft_end (datetime) – A datetime object representing the soft deadline of the contest

  • contest_hard_end (datetime) – A datetime object representing the hard deadline of the contest

  • penalty (float) – A penalty score for late submissions

  • is_public (bool) – Field to indicate if the contest is public (or private)

  • enable_linter_score (bool) – Field to indicate if linter scoring is enabled in the contest

  • enable_poster_score (bool) – Field to indicate if poster scoring is enabled in the contest

Return type

Tuple[bool, Union[ValidationError, str]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

judge.handler.process_problem(contest_id, **kwargs)

Function to process a new Problem.

Parameters

contest_id (int) – Contest ID to which the problem belongs

**kwargs includes the following keyword arguments, which are directly passed to the construct a Problem object.

Parameters

  • code (str) – Problem code

  • name (str) – Problem name

  • statement (Optional[InMemoryUploadedFile]) – Problem statement

  • input_format – Problem input format

  • output_format – Problem output format

  • difficulty – Problem difficulty

  • time_limit – Problem execution time limit

  • memory_limit – Problem virtual memory limit

  • file_exts – Accepted file format for submissions

  • starting_code – Starting code for the problem

  • max_score – Maximum judge score per test case for the problem

  • compilation_script – Compilation script for the submissions

  • test_script – Test script for the submissions

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

judge.handler.process_submission(problem_id, participant_id, file_type, submission_file, timestamp)

Function to process a new Submission for a problem by a participant.

Parameters

  • problem_id (str) – Problem ID for the problem corresponding to the submission

  • participant_id (str) – Participant ID

  • file_type (str) – Submission file type

  • submission_file (InMemoryUploadedFile) – Submission file

  • timestamp (str) – Time at submission

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

judge.handler.process_testcase(problem_id, test_type, input_file, output_file)

Function to process a new TestCase for a problem.

Warning

This function does not rescore all the submissions and so score will not change in response to the new testcase. Do not call this function once the contest has started, it will lead to erroneous scores.

Parameters

  • problem_id (str) – Problem ID to which the testcase is added.

  • test_type (str) – Type of testcase - one of public, private.

  • input_file (InMemoryUploadedFile) – Input file for the testcase.

  • output_file (InMemoryUploadedFile) – Output file for the testcase.

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

judge.handler.process_person(email, rank=0)

Function to process a new Person.

Parameters

  • email (str) – Email of the person

  • rank (int) – Rank of the person (defaults to 0).

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

judge.handler.process_comment(problem_id, person_id, commenter_id, timestamp, comment)

Function to process a new Comment on the problem.

Parameters

  • problem_id (str) – Problem ID

  • person_id (str) – Person ID

  • commenter_id (str) – Commenter (another person) ID

  • timestamp (datetime) – Date and Time of comment

  • comment (str) – Comment content

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the processing has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful.

Addition Functions

judge.handler.add_person_to_contest(person_id, contest_id, permission)

Function to relate a person to a contest with permissions.

Parameters

  • person_id (str) – Person ID

  • contest_id (int) – Contest ID

  • permission (bool) – If True, then poster, if False, then participant

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the addition has succeeded, and 2nd element providing a ValidationError if addition is unsuccessful.

judge.handler.add_persons_to_contest(persons, contest_id, permission)

Function to relate a list of persons and contest with permissions. This function would create records for all the persons who are not present in the database irrespective of whether anyone has conflict or not.

Parameters

  • persons (List[str]) – List of person IDs

  • contest_id (int) – Contest ID

  • permission (bool) – If True, then poster, if False, then participant

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the relation creation has succeeded, and 2nd element providing a ValidationError if relation creation is unsuccessful.

Update Functions

judge.handler.update_problem(code, name, statement, input_format, output_format, difficulty)

Function to update selected fields in a Problem after creation. The fields that can be modified are name, statement, input_format, output_format and difficulty.

Parameters

  • code (str) – Problem ID

  • name (str) – Modified problem name

  • statement (str) – Modified problem statement

  • input_format (str) – Modified problem input format

  • output_format (str) – Modified problem output format

  • difficulty (str) – Modified problem difficulty

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the update has succeeded, and 2nd element providing a ValidationError if update is unsuccessful.

judge.handler.update_poster_score(submission_id, new_score)

Function to update the poster score for a submission. Leaderboard is updated if the total score for the person-problem pair has changed.

Parameters

  • submission_id (str) – Submission ID of the submission

  • new_score (int) – New score to be assigned

Returns

A 2-tuple - 1st element indicating whether the update has succeeded, and 2nd element providing a ValidationError if update is unsuccessful.

judge.handler.update_leaderboard(contest_id, person_id)

Function to update the leaderboard for a person-contest pair given their IDs.

Note

Only call this function when some submission for some problem of the contest has scored more than its previous submission. Remember to call this function whenever PersonProblemFinalScore is updated.

Parameters

  • contest_id (int) – Contest ID

  • person_id (str) – Person ID

Return type

bool

Returns

If update is successful, then True. If unsuccessful, then False.

Getter Functions

judge.handler.get_personcontest_permission(person_id, contest_id)

Function to give the relation between a Person and a Contest.

Parameters

  • person_id (Optional[str]) – Person ID

  • contest_id (int) – Contest ID

Return type

Optional[bool]

Returns

If participant, then False, if poster, then True, if neither, then None

judge.handler.get_personproblem_permission(person_id, problem_id)

Function to give the relation between a Person and a Contest. This dispatches to get_personcontest_permission() with relevant arguments.

Parameters

  • person_id (Optional[str]) – Person ID

  • problem_id (str) – Problem ID

Return type

Optional[bool]

Returns

If participant, then False, if poster, then True, if neither, then None

judge.handler.get_posters(contest_id)

Function to return the list of the posters for a Contest.

Parameters

contest_id (int) – Contest ID

Return type

Tuple[bool, Union[ValidationError, List[str]]]

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded. If successful, a list of IDs are present in the 2nd element. If unsuccessful, a ValidationError is additionally returned.

judge.handler.get_participants(contest_id)

Function to return the list of the participants for a Contest.

Parameters

contest_id (int) – Contest ID

Return type

Tuple[bool, Union[ValidationError, List[str]]]

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded. If successful, a list of IDs are present in the 2nd element. The list is empty if the contest is public. If unsuccessful, a ValidationError is additionally returned.

judge.handler.get_personcontest_score(person_id, contest_id)

Function to get the final score, which is the sum of individual final scores of all problems in a contest for a particular person.

Parameters

  • person_id (str) – Person ID

  • contest_id (int) – Contest ID

Return type

Tuple[bool, Union[float, ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded. If successful, the final score is present in the 2nd element. If unsuccesful, a ValidationError is additionally returned.

judge.handler.get_submission_status(submission_id)

Function to get the current status of the submission given its submission ID.

Parameters

submission_d – Submission ID

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded. If successful, a tuple consisting of a dictionary and a smaller tuple. The key for the dictionary is the testcase ID, and value is another smaller tuple consisting of the verdict, time taken, memory consumed, flag to indicate if the testcase was public or private and message after checking. The smaller tuple consists of the score given by the judge, poster (if applicable), and linter (if applicable), as well as the final score, timestamp of submission and the file type of submission. If unsuccessful, a ValidationError is additionally returned.

judge.handler.get_submissions(problem_id, person_id)

Function to retrieve all submissions made by everyone or a specific person for this problem.

Parameters

  • problem_id (str) – Problem ID

  • person_id (Optional[str]) – Person ID

Return type

Tuple[bool, Union[Dict[str, List[Any]], ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded. If successful, and person_id is None, then the list of submissions pertaining to each person is placed in a dictionary, and if person_id is provided, then the list of submissions pertaining to the specific person is placed in a dictionary and returned. If unsuccessful, then a ValidationError is additionally returned.

judge.handler.get_leaderboard(contest_id)

Function to returns the current leaderboard for a contest given its contest ID.

Parameters

contest_id (int) – Contest ID

Return type

Tuple[bool, Union[str, List[List[Union[str, float]]]]]

Returns

A 2-tuple - 1st element indicating whether leaderboard has been initialized or not. If initialized, a list of 2-length lists is returned ordered by decreasing scores. The first element is the rank, and the second element is the score. If uninitialized, a suitable message is provided

judge.handler.get_comments(problem_id, person_id)

Function to get the private comments on the problem for the person.

Parameters

  • problem_id (str) – Problem ID

  • person_id (str) – Person ID

Return type

List[Tuple[Any, Any, Any]]

Returns

List of 3-tuple of comments - the person who commented, the timestamp and the comment content, sorted in chronological order.

judge.handler.get_csv(contest_id)

Function to get the CSV (in string form) of the current scores of all participants in a contest given its contest ID.

Parameters

contest_id (int) – Contest ID

Return type

Tuple[bool, Union[ValidationError, StringIO]]

Returns

A 2-tuple - 1st element indicating whether the retrieval has succeeded, and 2nd element providing a ValidationError if processing is unsuccessful or a StringIO object if successful.

Deletion Functions

judge.handler.delete_contest(contest_id)

Function to delete a Contest given its contest ID. This will cascade delete in all the tables that have contest_id as a foreign key. It calls delete_problem() for each problem in the contest.

Parameters

contest_id (int) – the contest ID

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the deletion has succeeded, and 2nd element providing a ValidationError if deletion is unsuccessful.

judge.handler.delete_problem(problem_id)

Function to delete a Problem given its problem ID. This will cascade delete in all the tables that have problem_id as a foreign key. It will also delete all the submissions, testcases and related directories corresponding to the problem.

Parameters

problem_id (str) – the problem ID

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the deletion has succeeded, and 2nd element providing a ValidationError if deletion is unsuccessful.

judge.handler.delete_testcase(testcase_id)

Function to delete a TestCase given its testcase ID. This will cascade delete in all the tables where this testcase appears.

Warning

This function does not rescore all the submissions and so score will not change in response to the deleted testcase. Do not call this function once the contest has started, it will lead to erroneous scores.

Parameters

testcase_id (str) – the testcase ID

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the deletion has succeeded, and 2nd element providing a ValidationError if deletion is unsuccessful.

judge.handler.delete_personcontest(person_id, contest_id)

Function to delete the relation between a person and a contest.

Parameters

  • person_id (str) – Person ID

  • contest_id (int) – Contest ID

Return type

Tuple[bool, Optional[ValidationError]]

Returns

A 2-tuple - 1st element indicating whether the deletion has succeeded, and 2nd element providing an error message if deletion is unsuccessful.