codingame_tools.client.common.protocol.contribution¶
JSON-serializable dataclasses for the findContribution and updateContribution Codingame API methods.
module-attribute
¶
CgSolutionLanguage = str
The programming language used for the reference solution, e.g. "Python3", "Java", "C++", etc.
Code submitted/played (TestSession/play, TestSession/submit, contribution
updateContribution/createContribution) runs server-side in a sandbox with a specific
version and, for some languages, specific bundled libraries--relevant to know when writing a
solution that assumes a particular language feature or library is available. Confirmed:
- Python3: 3.11.5, with NumPy, pandas, and SciPy available.
Other languages' exact versions/bundled libraries aren't catalogued here yet--see https://www.codingame.com/playgrounds/40701/help-center/languages-versions (a client-rendered page; fetching it programmatically only returns the loading shell, not the real content, so this couldn't be filled in automatically--add entries here as they're confirmed for other languages actually in use).
File-extension mapping for a CgSolutionLanguage lives in codingame_tools.language
(get_language(cg_id).extension / get_language_by_extension(ext)), not here--this module is
wire-protocol schema only.
module-attribute
¶
CgMarkdown = str
A simplified markdown format used by Codingame for problem statements, input/output descriptions, and constraints. It allowsa highlighting of certain text, as:
<Monospace Renders as a monospace code block. Forces line breaks.
block style mono
See https://www.codingame.com/playgrounds/40701/help-center/statement for more details.
module-attribute
¶
CgPuzzleType = str
The type of contribution, e.g. "PUZZLE_INOUT" for a standard noninteractive solo puzzle.
module-attribute
¶
CgHtml = str
Rendered HTML for display of the problem statement, input/output descriptions, and constraints. This is derived from the CgMarkdown content. It is rendered by the server and returned in the API response.
module-attribute
¶
CgStubGenerator = str
A script in CodingGame's stub generation language that can generate a stub solution for the puzzle in any supported programming language. See https://www.codingame.com/playgrounds/40701/help-center/stub-generator
module-attribute
¶
CgContributionId = str
A Contribution ID is a long, opaque string that uniquely identifies a contribution on the Codingame service. It is used in the findContribution and updateContribution API methods to retrieve or update a contribution and is not intended to be human-readable. It is returned in the response from findContribution.
module-attribute
¶
CgModerationAction = str
One of the two moderator decisions on a PENDING contribution: "validate" (approve) or
"deny" (reject)--the argument to Contribution/findContributionModerators. This is the gate
that actually publishes/rejects a contribution (confirmed live by the user: "2/3 to approve,
0/3 to reject" on the site matched findContributionModerators(id, "validate") returning 2
moderators and findContributionModerators(id, "deny") returning 0)--distinct from, and not
derivable from, the ungated community up/down vote (CgContribution.up_votes/down_votes,
Vote/findVotableValuesById). The required vote count to tip the gate (3 either way, per the
user) is not itself returned by this API--only the current list of moderators on each side.
dataclass
¶
CgTopic(label_map, extra_data=dict(), id=None, handle=None, category=None, puzzle_count=None, parent_topic_id=None, page_title=None, content_details_id=None)
Bases: JSONWizardX
A topic associated with a contribution, e.g. "Parsing", "Sorting", etc. Most of the fields are fetched from the server in a search for topics.
Only label_map is guaranteed. A topic can arrive carrying nothing but its localized
label, with every identifying/statistical field omitted outright (not null)--seen on
author-typed free-form topics that don't correspond to an entry in CodinGame's own topic
catalogue, e.g. {"labelMap": {"2": "Logic Gates"}}. Surveying the 80 topic objects across
the pending community-review queue (2026-08-03): labelMap appeared 80/80, every other field
70/80, and pageTitle/contentDetailsId 38/80. So the catalogue fields are optional, and
code that reads them must handle None rather than assuming a topic is always a real
catalogue entry.
instance-attribute
¶
label_map
Localized display label for the topic (language code -> label), e.g. {"1": "Parsing", "2": "Parsing"}. The only field always present--see the class docstring.
class-attribute
instance-attribute
¶
id = None
The topic's unique identifier, or None for a topic that isn't a catalogue entry.
class-attribute
instance-attribute
¶
handle = None
Opaque short identifier for the topic, e.g. "parsing". None for a non-catalogue topic.
class-attribute
instance-attribute
¶
category = None
e.g. "FUNDAMENTALS", "ADVANCED", "INTERMEDIATE". None for a non-catalogue topic.
class-attribute
instance-attribute
¶
puzzle_count = None
The number of puzzles tagged with this topic. None for a non-catalogue topic.
class-attribute
instance-attribute
¶
parent_topic_id = None
The ID of this topic's parent topic in the topic hierarchy. None for a non-catalogue topic.
class-attribute
instance-attribute
¶
page_title = None
Title of the topic's help-center page, if it has one.
class-attribute
instance-attribute
¶
content_details_id = None
ID of the topic's help-center content, if it has one.
dataclass
¶
CgTestCase(title, test_in, test_out, is_test, is_validator, need_validation, extra_data=dict())
Bases: JSONWizardX
A single test case for the contribution, including the input and expected output for the test. May represent either a local test case or a server-sideq validator test case. Tests are numbers in the order given, separately for local tests and validator tests. The server-side validator test cases are not shared with the puzzler, and used to validate the solution and score the submission.
See the note on CgTestSessionTestCase (test_session.py) re: a possible future
shared "puzzle test case" model--that class represents the same underlying concept from
the solve/IDE side (TestSession/startTestSession), with binary-ID references instead of
this class's inline text content.
instance-attribute
¶
is_test
True if a local test shown to player during development prior to submission
instance-attribute
¶
is_validator
True if a server-side validator test case, hidden from player; used for validation / scoring
instance-attribute
¶
need_validation
Unclear what this field means; it is always true in current protocol tests.
dataclass
¶
CgContributionData(title, extra_data=dict(), statement=None, input_description=None, output_description=None, constraints=None, difficulty=None, stub_generator=None, topics=list(), test_cases=list(), solution_language=None, solution=None, cover_binary_id=None)
Bases: JSONWizardX
The actual contribution content, including the problem statement, input/output descriptions, constraints, difficulty, solution language, stub generator, topics, and test cases.
instance-attribute
¶
title
The title of the puzzle, e.g. "Grid Pathfinding" or "Sorting Challenge".
class-attribute
instance-attribute
¶
statement = None
The problem statement, in simplified Markdown format, including the description of the problem, input/output formats, and examples.
class-attribute
instance-attribute
¶
input_description = None
The description of the provided stdin input format, in simplified Markdown format.
class-attribute
instance-attribute
¶
output_description = None
The description of the expected stdout output format, in simplified Markdown format.
class-attribute
instance-attribute
¶
constraints = None
The constraints for the problem, in simplified Markdown format, e.g. "1 ≤ N ≤ 1000" or "1 ≤ A[i] ≤ 10^9".
class-attribute
instance-attribute
¶
difficulty = None
The difficulty category for the puzzle, e.g. "easy", "medium", or "hard".
class-attribute
instance-attribute
¶
stub_generator = None
The stub generator used for the puzzle.
class-attribute
instance-attribute
¶
topics = field(default_factory=list)
The topics associated with the puzzle. Topic objects include metadata that is retrieved from the server when searching for topics by name.
class-attribute
instance-attribute
¶
test_cases = field(default_factory=list)
The test cases for the puzzle. Both local test cases shown to the player during development and server-side validator test cases are included here. The server-side validator test cases are not shared with the puzzler, and used to validate the solution and score the submission.
When rendered, test cases are numbered in the order given, begining at 1, separately for local tests and validator tests.
The way the input form is set up, the list will always consist of contiguous pairs of tests, with local test first and validator test second.
class-attribute
instance-attribute
¶
solution_language = None
The programming language used for the reference solution, e.g. "Python3", "Java", "C++", etc.
May be missing if the reference solution is not yet provided.
See codingame_tools.language.get_language_by_extension for mapping from file extension
to solution language string.
class-attribute
instance-attribute
¶
solution = None
The reference solution code for the puzzle, in the specified solution language. May be missing if the reference solution is not yet provided. When a submission is made, this solution must pass all test cases for the submission to be accepted.
class-attribute
instance-attribute
¶
cover_binary_id = None
The ID of an uploaded graphical cover image for the puzzle. The image is uploaded separately and the server returns a binary ID for the image, which can be included here to associate the image with the contribution.
dataclass
¶
CgContributionVersion(version, data, extra_data=dict(), _autoclose_time=Alias('autocloseTime', default=None), _freeze_time=Alias('freezeTime', default=None), draft=None, ready_for_moderation=None, statement_html=Alias('statementHTML', default=None))
Bases: JSONWizardX
The wrapper for a specific version of a contribution, including the contribution data and metadata such as version number.
instance-attribute
¶
version
A sequentially incrementing version number for the contribution, starting at 1 for the first version. When submitting an edit, the previous version number must be provided as a parameter to updateContribution; this serves to make the API idempotent and prevent race conditions from concurrent edits.
instance-attribute
¶
data
The actual contribution content, including the problem statement, input/output descriptions, constraints, difficulty, solution language,
class-attribute
instance-attribute
¶
draft = None
Whether this version of the contribution is a draft. Draft versions are private to
the contributor and are not shared for comment/approval. Present in both findContribution
and updateContribution responses (confirmed 2026-07-26 via round-trip test).
class-attribute
instance-attribute
¶
ready_for_moderation = None
Whether this version of the contribution is ready for moderation. Present in both
findContribution and updateContribution responses (confirmed 2026-07-26 via round-trip
test).
class-attribute
instance-attribute
¶
statement_html = Alias('statementHTML', default=None)
Server-rendered HTML of the statement, input/output descriptions, and constraints, used only
for display on the contribution view page. Entirely derivative of data.statement (and the
other CgContributionData text fields it's rendered from)--non-authoritative, and never
needed to reconstruct or resubmit a version. Present in findContribution responses; omitted
from updateContribution responses (confirmed 2026-07-26), presumably because the update
response doesn't wait for/include the server-side re-render. Fetch via findContribution if
the rendered HTML for a just-submitted version is needed.
Explicitly aliased: the server sends "statementHTML" (all-caps acronym), which the automatic
camelCase transform doesn't produce from statement_html (it produces "statementHtml").
property
writable
¶
autoclose_time
The time at which the contribution will be automatically closed for voting and comments, always UTC. None if the contribution does not have an autoclose time set.
property
writable
¶
freeze_time
See the field docstring for _freeze_time. Always UTC. None if not set.
dataclass
¶
CgContributionStatusChange(author, extra_data=dict(), reason=None)
Bases: JSONWizardX
Details of a single status transition, embedded in
CgContributionStatusHistoryEntry.data.
instance-attribute
¶
author
Who/what triggered the transition, e.g. "SYSTEM" (an automatic transition) or "ACTION" (triggered by the contributor's own action, e.g. editing the contribution).
class-attribute
instance-attribute
¶
reason = None
Why the transition happened, e.g. "INACTIVITY" (automatically refused after a period of no activity) or "EDIT" (moved back to pending after the contributor edited it).
Absent for some transitions, so optional. Observed live (2026-08-12): a contribution
moving to "ACCEPTED" carries {"author": "ACTION"} and nothing else, while "REFUSED" and
"PENDING" both carry a reason. Requiring it meant every call touching a contribution's
status history broke the moment that contribution was accepted--including
updateContribution, so an accepted contribution could not be edited at all.
dataclass
¶
CgContributionStatusHistoryEntry(status, data, _date=Alias('date'), extra_data=dict())
Bases: JSONWizardX
A single entry in a contribution's status history (CgContribution.status_history /
CgPendingContribution.status_history).
dataclass
¶
CgValidateAction(action_id, progress, already_done, extra_data=dict())
Bases: JSONWizardX
The status of an asynchronous server-side validation action for a contribution (e.g. triggered by editing/submitting a puzzle). Only a single example has been observed so far, so field optionality is not yet well established--all three fields are currently required.
dataclass
¶
CgDeleteContributionResult(action_id, result, extra_data=dict())
dataclass
¶
CgContribution(id, active_version, score, votable_id, codingamer_id, views, commentable_id, title, status, nickname, public_handle, codingamer_handle, last_version, comment_count, up_votes, down_votes, editable, draft, ready_for_moderation, contribution_type=Alias('type'), extra_data=dict(), avatar=None, status_history=list(), validate_action=None)
Bases: JSONWizardX
The complete response to findContribution. Also the response shape for updateContribution
(see CgContributionService.update_contribution)--but see active_version and
CgContributionVersion.statement_html for two fields confirmed to differ between the two
in practice.
instance-attribute
¶
active_version
The version number of the currently active version of the contribution.
In an updateContribution response, this has been confirmed live (2026-07-28) to lag by one
version behind the version just created--e.g. after submitting what becomes version 63,
active_version is still 62 even though last_version.version in that same response is
already 63. A findContribution call moments later correctly reports 63. Likely the new
version's activation happens slightly asynchronously server-side, similar to why
CgContributionVersion.statement_html isn't rendered yet either. Use last_version.version
(not this field) when a just-submitted version's number is needed.
instance-attribute
¶
votable_id
The unique identifier for the votable entity associated with the contribution.
instance-attribute
¶
codingamer_id
The unique identifier for the codingamer (contributor) who created the contribution.
instance-attribute
¶
commentable_id
The unique identifier for the commentable entity associated with the contribution.
instance-attribute
¶
status
The status of the contribution, e.g. "PENDING", "APPROVED", "REJECTED".
instance-attribute
¶
public_handle
The public handle of the contribution. This is the identifier used for finding the contribution and updating it.
instance-attribute
¶
codingamer_handle
The long, opaque string identifier for the contributor.
instance-attribute
¶
last_version
The most recent version of the contribution, including all content.
instance-attribute
¶
editable
Whether the contribution is currently editable by the contributor.
instance-attribute
¶
ready_for_moderation
Whether the contribution is ready for moderation.
class-attribute
instance-attribute
¶
contribution_type = Alias('type')
The type of the contribution, e.g. "PUZZLE_INOUT" for a standard noninteractive solo puzzle.
class-attribute
instance-attribute
¶
avatar = None
The binary image ID of the contributor's avatar image, or None for a codingamer who has
never set one. Omitted entirely (not null); seen on 3 of the 54 contributions in the pending
community-review queue (2026-08-03). CgPendingContribution already treated it this way--
these two classes describe the same underlying codingamer and had simply drifted.
class-attribute
instance-attribute
¶
status_history = field(default_factory=list)
The history of status changes for the contribution.
class-attribute
instance-attribute
¶
validate_action = None
The status of an in-progress server-side validation action for the contribution, if any.
dataclass
¶
CgPendingContribution(id, votable_id, commentable_id, title, status, user_moderation_status, codingamer_id, codingamer_handle, nickname, public_handle, active_version, draft, editable, ready_for_moderation, score, up_votes, down_votes, comment_count, views, status_history, contribution_type=Alias('type'), _publication_date=Alias('publicationDate'), _autoclose_time=Alias('autocloseTime'), extra_data=dict(), avatar=None, validate_action=None)
Bases: JSONWizardX
A single contribution summary, as returned (in a bare JSON array) by
getAllPendingContributions. A lighter-weight summary than CgContribution--notably,
it has no last_version (full content), but adds publication_date/autoclose_time
and user_moderation_status not present on CgContribution.
instance-attribute
¶
votable_id
The unique identifier for the votable entity associated with the contribution.
instance-attribute
¶
commentable_id
The unique identifier for the commentable entity associated with the contribution.
instance-attribute
¶
status
The status of the contribution. Always "PENDING" when listed by
getAllPendingContributions; other values (e.g. "REFUSED") observed only in
status_history.
instance-attribute
¶
user_moderation_status
The requesting codingamer's moderation standing for this contribution, e.g. "PENDING" (can moderate) or "FORBIDDEN" (cannot, e.g. having already voted/commented).
instance-attribute
¶
codingamer_id
The unique identifier for the codingamer (contributor) who created the contribution.
instance-attribute
¶
codingamer_handle
The long, opaque string identifier for the contributor.
instance-attribute
¶
active_version
The version number of the currently active version of the contribution.
instance-attribute
¶
editable
Whether the contribution is currently editable by the contributor.
instance-attribute
¶
ready_for_moderation
Whether the contribution is ready for moderation.
instance-attribute
¶
status_history
The history of status changes for the contribution.
class-attribute
instance-attribute
¶
contribution_type = Alias('type')
The type of the contribution, e.g. "PUZZLE_INOUT", "CLASHOFCODE".
class-attribute
instance-attribute
¶
avatar = None
The binary image ID of the contributor's avatar image. Not always present--observed absent for a few contributors.
class-attribute
instance-attribute
¶
validate_action = None
The status of an in-progress server-side validation action for the contribution, if any.
property
writable
¶
publication_date
See the field docstring for _publication_date. Always UTC.
property
writable
¶
autoclose_time
See the field docstring for _autoclose_time. Always UTC.
dataclass
¶
CgPersonalContribution(id, votable_id, commentable_id, codingamer_id, codingamer_handle, nickname, public_handle, title, status, active_version, draft, editable, ready_for_moderation, score, up_votes, down_votes, comment_count, views, status_history, contribution_type=Alias('type'), extra_data=dict(), avatar=None, validate_action=None, _autoclose_time=Alias('autocloseTime', default=None))
Bases: JSONWizardX
A single contribution summary, as returned (in a bare JSON array) by
Contribution/getPersonalContributions--every contribution (any status, not just PENDING)
authored by the queried codingamer, e.g. for a "my contributions" listing page. Another
lighter-weight summary than CgContribution (no last_version), and not quite the same
shape as CgPendingContribution either--no user_moderation_status/publication_date
here, but adds avatar/validate_action, and autoclose_time is optional (absent for
draft/never-submitted-for-moderation contributions) rather than always present.
instance-attribute
¶
votable_id
The unique identifier for the votable entity associated with the contribution.
instance-attribute
¶
commentable_id
The unique identifier for the commentable entity associated with the contribution.
instance-attribute
¶
codingamer_id
The unique identifier for the codingamer (contributor) who created the contribution.
instance-attribute
¶
codingamer_handle
The long, opaque string identifier for the contributor.
instance-attribute
¶
status
The status of the contribution, e.g. "PENDING", "APPROVED", "REFUSED".
instance-attribute
¶
active_version
The version number of the currently active version of the contribution.
instance-attribute
¶
editable
Whether the contribution is currently editable by the contributor.
instance-attribute
¶
ready_for_moderation
Whether the contribution is ready for moderation.
instance-attribute
¶
status_history
The history of status changes for the contribution.
class-attribute
instance-attribute
¶
contribution_type = Alias('type')
The type of the contribution, e.g. "PUZZLE_INOUT", "CLASHOFCODE".
class-attribute
instance-attribute
¶
avatar = None
The binary image ID of the contributor's avatar image, or None for a codingamer who has
never set one. Optional for the same reason as CgContribution.avatar--see there.
class-attribute
instance-attribute
¶
validate_action = None
The status of an in-progress server-side validation action for the contribution, if any.
property
writable
¶
autoclose_time
See the field docstring for _autoclose_time. Always UTC. None if not set.
dataclass
¶
CgContributionModerator(user_id, pseudo, public_handle, avatar, cover, extra_data=dict())
Bases: JSONWizardX
A single moderator who has cast a "validate"/"deny" vote on a contribution, as
returned (in a bare JSON array) by Contribution/findContributionModerators.