cfutils.api package

Submodules

cfutils.api.methods module

class cfutils.api.methods.APIMethod

Bases: ABC

Base class for codeforces API methods. See https://codeforces.com/apiHelp/methods for the full list and information on each parameter.

Each class that inherits from this must also be marked as a dataclass. Use the dataclass parameters to define the API arguments. Allowed argument types:

T ::= int | str | bool | list[T] | Optional[T]

Caveats:

As from is a keyword in python, we instead use From for API parameters. This works as the API keys are case insensitive.

auth_required() → bool

Returns:: True if the method call requires authorization

buildAPICallURL(*, auth: bool = False)

Build the URL to call the CF API

Parameters:: auth – authorized API call, signed using your API key.
Raises:: CFAPIError – when auth=True but API key/secret is not provided.
Returns:: URL string

get(*, auth: bool = False, delay: float = 2.0, output_file: str | None = None, load_from_file: str | None = None)

Execute an API call to codeforces

Parameters:

auth – authorized API call, signed using your API key.
delay (optional) – number of seconds to wait before executing the call. Default is 2s.
output_file (optional) – write raw API response to file.
load_from_file (optional) – If this file exists, load data from it instead of running the API. Useful if you’ve already called the API or called it from a different source and saved the response.

Raises:

CFAPIError – when API call fails.
CFAPIError – when auth=True but API key/secret is not provided.

Returns:

“result” component of the API data returned, parsed appropriately into an object of type self.resultType().

abstract static name() → str: API method name

abstract static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.BlogEntry_Comments(blogEntryId: int)

Bases: APIMethod

Returns a list of comments to the specified blog entry.

blogEntryId: int

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.BlogEntry_View(blogEntryId: int)

Bases: APIMethod

Returns blog entry.

blogEntryId: int

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

exception cfutils.api.methods.CFAPIError: Bases: Exception

class cfutils.api.methods.Contest_Hacks(contestId: int, asManager: bool = False)

Bases: APIMethod

Returns list of hacks in the specified contests. Full information about hacks is available only after some time after the contest end. During the contest user can see only own hacks.

asManager: bool = False

auth_required() → bool

Returns:: True if the method call requires authorization

contestId: int

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.Contest_List(gym: bool = False)

Bases: APIMethod

Returns information about all available contests. If this method is called not anonymously, then all available contests for a calling user will be returned too, including mashups and private gyms.

gym: bool = False

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.Contest_RatingChanges(contestId: int)

Bases: APIMethod

Returns rating changes after the contest.

contestId: int

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.Contest_Standings(contestId: int, From: int, count: int, asManager: bool = False, showUnofficial: bool = False, room: int | None = None)

Bases: APIMethod

Returns the description of the contest and the requested part of the standings.

From: int

class Result(contest: cfutils.api.objects.Contest, problems: list[cfutils.api.objects.Problem], rows: list[cfutils.api.objects.RanklistRow])

Bases: CFObject

contest: Contest

problems: list[Problem]

rows: list[RanklistRow]

asManager: bool = False

contestId: int

count: int

static name(): API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

room: int | None = None

showUnofficial: bool = False

class cfutils.api.methods.Contest_Status(contestId: int, From: int, count: int, asManager: bool = False, handle: str | None = None)

Bases: APIMethod

Returns submissions for specified contest. Optionally can return submissions of specified user.

From: int

asManager: bool = False

auth_required() → bool

Returns:: True if the method call requires authorization

contestId: int

count: int

handle: str | None = None

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.Problemset_Problems(tags: list[str], problemsetName: str | None = None)

Bases: APIMethod

Returns all problems from problemset. Problems can be filtered by tags.

class Result(problems: list[cfutils.api.objects.Problem], problemStatistics: list[cfutils.api.objects.ProblemStatistics])

Bases: JSONSerializable

problemStatistics: list[ProblemStatistics]

problems: list[Problem]

static name() → str: API method name

problemsetName: str | None = None

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

tags: list[str]

class cfutils.api.methods.Problemset_RecentStatus(count: int, problemsetName: str | None = None)

Bases: APIMethod

count: int

static name() → str: API method name

problemsetName: str | None = None

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.RecentActions(maxCount: int)

Bases: APIMethod

maxCount: int: can be up to 100

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_BlogEntries(handle: str)

Bases: APIMethod

handle: str

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_Friends(onlyOnline: bool = False)

Bases: APIMethod

auth_required() → bool

Returns:: True if the method call requires authorization

static name() → str: API method name

onlyOnline: bool = False

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_Info(handles: list[str])

Bases: APIMethod

handles: list[str]

static name(): API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_RatedList(activeOnly: bool = True, includeRetired: bool = False)

Bases: APIMethod

activeOnly: bool = True

includeRetired: bool = False

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_Rating(handle: str)

Bases: APIMethod

Rating history of the specified user.

handle: str

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

class cfutils.api.methods.User_Status(handle: str, From: int, count: int)

Bases: APIMethod

Submissions of specified user.

From: int

count: int

handle: str

static name() → str: API method name

static resultType() → type: Must be dataclass | list[dataclass] | list[str] | list[int]

cfutils.api.objects module

Codeforces API return objects. See https://codeforces.com/apiHelp/objects for a full list and information on each parameter.

class cfutils.api.objects.BlogEntry(id: int, originalLocale: str, creationTimeSeconds: int, authorHandle: str, title: str, locale: str, allowViewHistory: bool, tags: list[str], rating: int, content: str | None = None, modificationTimeSeconds: int | None = None)

Bases: CFObject

allowViewHistory: bool

authorHandle: str

content: str | None = None

creationTimeSeconds: int

id: int

locale: str

modificationTimeSeconds: int | None = None

originalLocale: str

rating: int

tags: list[str]

title: str

class cfutils.api.objects.Comment(id: int, creationTimeSeconds: int, commentatorHandle: str, locale: str, text: str, rating: int, parentCommentId: int | None = None)

Bases: CFObject

commentatorHandle: str

creationTimeSeconds: int

id: int

locale: str

parentCommentId: int | None = None

rating: int

text: str

class cfutils.api.objects.Contest(id: int, name: str, type: cfutils.api.objects.ContestType, phase: cfutils.api.objects.ContestPhase, frozen: bool, durationSeconds: int, startTimeSeconds: int | None = None, relativeTimeSeconds: int | None = None, preparedBy: str | None = None, websiteUrl: str | None = None, description: str | None = None, difficulty: int | None = None, kind: str | None = None, icpcRegion: str | None = None, country: str | None = None, city: str | None = None, season: str | None = None)

Bases: CFObject

city: str | None = None

country: str | None = None

description: str | None = None

difficulty: int | None = None

durationSeconds: int

frozen: bool

icpcRegion: str | None = None

id: int

kind: str | None = None

name: str

phase: ContestPhase

preparedBy: str | None = None

relativeTimeSeconds: int | None = None

season: str | None = None

startTimeSeconds: int | None = None

type: ContestType

websiteUrl: str | None = None

class cfutils.api.objects.ContestPhase(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BEFORE = 'BEFORE'

CODING = 'CODING'

FINISHED = 'FINISHED'

PENDING_SYSTEM_TEST = 'PENDING_SYSTEM_TEST'

SYSTEM_TEST = 'SYSTEM_TEST'

class cfutils.api.objects.ContestType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CF = 'CF'

ICPC = 'ICPC'

IOI = 'IOI'

class cfutils.api.objects.Hack(id: int, creationTimeSeconds: int, hacker: cfutils.api.objects.Party, defender: cfutils.api.objects.Party, problem: cfutils.api.objects.Problem, verdict: cfutils.api.objects.HackVerdict | None = None, test: str | None = None, judgeProtocol: cfutils.api.objects.JudgeProtocol | None = None)

Bases: CFObject

creationTimeSeconds: int

defender: Party

hacker: Party

id: int

judgeProtocol: JudgeProtocol | None = None

problem: Problem

test: str | None = None

verdict: HackVerdict | None = None

class cfutils.api.objects.HackVerdict(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

GENERATOR_CRASHED = 'GENERATOR_CRASHED'

GENERATOR_INCOMPILABLE = 'GENERATOR_INCOMPILABLE'

HACK_SUCCESSFUL = 'HACK_SUCCESSFUL'

HACK_UNSUCCESSFUL = 'HACK_UNSUCCESSFUL'

IGNORED = 'IGNORED'

INVALID_INPUT = 'INVALID_INPUT'

OTHER = 'OTHER'

TESTING = 'TESTING'

class cfutils.api.objects.JudgeProtocol(manual: bool, protocol: str, verdict: str)

Bases: object

manual: bool

protocol: str

verdict: str

class cfutils.api.objects.Member(handle: str, name: str | None = None)

Bases: CFObject

handle: str

name: str | None = None

class cfutils.api.objects.ParticipantType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CONTESTANT = 'CONTESTANT'

MANAGER = 'MANAGER'

OUT_OF_COMPETITION = 'OUT_OF_COMPETITION'

PRACTICE = 'PRACTICE'

VIRTUAL = 'VIRTUAL'

class cfutils.api.objects.Party(members: list[cfutils.api.objects.Member], participantType: cfutils.api.objects.ParticipantType, contestId: int | None = None, teamId: int | None = None, teamName: str | None = None, ghost: bool = False, room: int | None = None, startTimeSeconds: int | None = None)

Bases: CFObject

contestId: int | None = None

ghost: bool = False

members: list[Member]

participantType: ParticipantType

room: int | None = None

startTimeSeconds: int | None = None

teamId: int | None = None

teamName: str | None = None

class cfutils.api.objects.Problem(index: str, name: str, type: cfutils.api.objects.ProblemType, tags: list[str], contestId: int | None = None, problemsetName: str | None = None, points: float | None = None, rating: int | None = None)

Bases: CFObject

contestId: int | None = None

index: str

name: str

points: float | None = None

problemsetName: str | None = None

rating: int | None = None

tags: list[str]

type: ProblemType

class cfutils.api.objects.ProblemResult(points: float, rejectedAttemptCount: int, type: cfutils.api.objects.ProblemResultType, penalty: int | None = None, bestSubmissionTimeSeconds: int | None = None)

Bases: CFObject

bestSubmissionTimeSeconds: int | None = None

penalty: int | None = None

points: float

rejectedAttemptCount: int

type: ProblemResultType

class cfutils.api.objects.ProblemResultType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

FINAL = 'FINAL'

PRELIMINARY = 'PRELIMINARY'

class cfutils.api.objects.ProblemStatistics(index: str, solvedCount: int, contestId: int | None = None)

Bases: CFObject

contestId: int | None = None

index: str

solvedCount: int

class cfutils.api.objects.ProblemType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

PROGRAMMING = 'PROGRAMMING'

QUESTION = 'QUESTION'

class cfutils.api.objects.RanklistRow(party: cfutils.api.objects.Party, rank: int, points: float, penalty: int, successfulHackCount: int, unsuccessfulHackCount: int, problemResults: list[cfutils.api.objects.ProblemResult], lastSubmissionTimeSeconds: int | None = None)

Bases: CFObject

lastSubmissionTimeSeconds: int | None = None

party: Party

penalty: int

points: float

problemResults: list[ProblemResult]

rank: int

successfulHackCount: int

unsuccessfulHackCount: int

class cfutils.api.objects.RatingChange(contestId: int, contestName: str, handle: str, rank: int, ratingUpdateTimeSeconds: int, oldRating: int, newRating: int)

Bases: CFObject

contestId: int

contestName: str

handle: str

newRating: int

oldRating: int

rank: int

ratingUpdateTimeSeconds: int

class cfutils.api.objects.RecentAction(timeSeconds: int, blogEntry: cfutils.api.objects.BlogEntry | None = None, comment: cfutils.api.objects.Comment | None = None)

Bases: CFObject

blogEntry: BlogEntry | None = None

comment: Comment | None = None

timeSeconds: int

class cfutils.api.objects.Submission(id: int, creationTimeSeconds: int, relativeTimeSeconds: int, problem: cfutils.api.objects.Problem, author: cfutils.api.objects.Party, programmingLanguage: str, testset: cfutils.api.objects.Testset, passedTestCount: int, timeConsumedMillis: int, memoryConsumedBytes: int, verdict: cfutils.api.objects.Verdict | None = None, contestId: int | None = None, points: float | None = None)

Bases: CFObject

author: Party

contestId: int | None = None

creationTimeSeconds: int

id: int

memoryConsumedBytes: int

passedTestCount: int

points: float | None = None

problem: Problem

programmingLanguage: str

relativeTimeSeconds: int

testset: Testset

timeConsumedMillis: int

verdict: Verdict | None = None

class cfutils.api.objects.Testset(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CHALLENGES = 'CHALLENGES'

PRETESTS = 'PRETESTS'

SAMPLES = 'SAMPLES'

TESTS = 'TESTS'

TESTS1 = 'TESTS1'

TESTS10 = 'TESTS10'

TESTS2 = 'TESTS2'

TESTS3 = 'TESTS3'

TESTS4 = 'TESTS4'

TESTS5 = 'TESTS5'

TESTS6 = 'TESTS6'

TESTS7 = 'TESTS7'

TESTS8 = 'TESTS8'

TESTS9 = 'TESTS9'

Bases: CFObject

avatar: str | None = None

city: str | None = None

contribution: int | None = None

country: str | None = None

email: str | None = None

firstName: str | None = None

friendOfCount: int | None = None

handle: str

lastName: str | None = None

lastOnlineTimeSeconds: int | None = None

maxRank: str | None = None

maxRating: int | None = None

openId: str | None = None

organization: str | None = None

rank: str | None = None

rating: int | None = None

registrationTimeSeconds: int | None = None

titlePhoto: str | None = None

vkId: str | None = None

class cfutils.api.objects.Verdict(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CHALLENGED = 'CHALLENGED'

COMPILATION_ERROR = 'COMPILATION_ERROR'

CRASHED = 'CRASHED'

FAILED = 'FAILED'

IDLENESS_LIMIT_EXCEEDED = 'IDLENESS_LIMIT_EXCEEDED'

INPUT_PREPARATION_CRASHED = 'INPUT_PREPARATION_CRASHED'

MEMORY_LIMIT_EXCEEDED = 'MEMORY_LIMIT_EXCEEDED'

OK = 'OK'

PARTIAL = 'PARTIAL'

PRESENTATION_ERROR = 'PRESENTATION_ERROR'

REJECTED = 'REJECTED'

RUNTIME_ERROR = 'RUNTIME_ERROR'

SECURITY_VIOLATED = 'SECURITY_VIOLATED'

SKIPPED = 'SKIPPED'

TESTING = 'TESTING'

TIME_LIMIT_EXCEEDED = 'TIME_LIMIT_EXCEEDED'

WRONG_ANSWER = 'WRONG_ANSWER'