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 contestcontest_start (
datetime
) – A datetime object representing the beginning of the contestcontest_soft_end (
datetime
) – A datetime object representing the soft deadline of the contestcontest_hard_end (
datetime
) – A datetime object representing the hard deadline of the contestpenalty (
float
) – A penalty score for late submissionsis_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 contestenable_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 aProblem
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 submissionparticipant_id (
str
) – Participant IDfile_type (
str
) – Submission file typesubmission_file (
InMemoryUploadedFile
) – Submission filetimestamp (
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 personrank (
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 IDperson_id (
str
) – Person IDcommenter_id (
str
) – Commenter (another person) IDtimestamp (
datetime
) – Date and Time of commentcomment (
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 IDcontest_id (
int
) – Contest IDpermission (
bool
) – IfTrue
, then poster, ifFalse
, 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 IDscontest_id (
int
) – Contest IDpermission (
bool
) – IfTrue
, then poster, ifFalse
, 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 IDname (
str
) – Modified problem namestatement (
str
) – Modified problem statementinput_format (
str
) – Modified problem input formatoutput_format (
str
) – Modified problem output formatdifficulty (
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 submissionnew_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 IDperson_id (
str
) – Person ID- Return type
bool
- Returns
If update is successful, then
True
. If unsuccessful, thenFalse
.
Getter Functions¶
judge.handler.
get_personcontest_permission
(person_id, contest_id)¶Function to give the relation between a
Person
and aContest
.
- Parameters
person_id (
Optional
[str
]) – Person IDcontest_id (
int
) – Contest ID- Return type
Optional
[bool
]- Returns
If participant, then
False
, if poster, thenTrue
, if neither, thenNone
judge.handler.
get_personproblem_permission
(person_id, problem_id)¶Function to give the relation between a
Person
and aContest
. This dispatches toget_personcontest_permission()
with relevant arguments.
- Parameters
person_id (
Optional
[str
]) – Person IDproblem_id (
str
) – Problem ID- Return type
Optional
[bool
]- Returns
If participant, then
False
, if poster, thenTrue
, if neither, thenNone
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 IDcontest_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 IDperson_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
isNone
, then the list of submissions pertaining to each person is placed in a dictionary, and ifperson_id
is provided, then the list of submissions pertaining to the specific person is placed in a dictionary and returned. If unsuccessful, then aValidationError
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 IDperson_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 aStringIO
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 havecontest_id
as a foreign key. It callsdelete_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 haveproblem_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 IDcontest_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.