codingame_tools.client.common.protocol.puzzle¶
JSON-serializable dataclasses for the Puzzle service's countSolvedPuzzlesByProgrammingLanguage, findPuzzleOfTheWeek, findAllMinimalProgress, and findBestFollowingProgress 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.
dataclass
¶
CgLastActivityPuzzle(id, title, pretty_id, level, details_page_url, forum_link, feedback, topics, community_creation, achievement_count, done_achievement_count, attempt_count, solved_count, rank, validator_score, xp_points, puzzle_type=Alias('type'), _creation_time=Alias('creationTime'), extra_data=dict(), contributor=None, cover_binary_id=None, test_session_handle=None, _last_activity=Alias('lastActivity', default=None), linked_achievements=None, moderators=None, statement=None, title_map=None)
Bases: JSONWizardX
A community puzzle summary, as embedded in a "PUZZLE"-type CgLastActivity entry
(getLastActivities), and also returned directly by Puzzle/findProgressByIds (bare JSON
array) and Puzzle/findProgressByPrettyId (bare JSON object--the richest of the three,
populating linked_achievements/moderators/statement/title_map, which the other
two never include).
instance-attribute
¶
pretty_id
URL-friendly slug for the puzzle, e.g. "logic-gates-detective".
instance-attribute
¶
details_page_url
Relative URL path to the puzzle's details/training page.
instance-attribute
¶
forum_link
Relative URL path (minus domain) to the puzzle's discussion forum thread.
instance-attribute
¶
community_creation
Whether this is a community-created puzzle (as opposed to an official CodinGame puzzle).
instance-attribute
¶
achievement_count
Total number of achievements associated with this puzzle.
instance-attribute
¶
done_achievement_count
Number of this puzzle's achievements the requesting codingamer has unlocked.
instance-attribute
¶
attempt_count
Total number of attempts made on this puzzle across all codingamers.
instance-attribute
¶
solved_count
Total number of codingamers who have solved this puzzle.
instance-attribute
¶
validator_score
Score achieved against the puzzle's validators, e.g. 100 for a fully-solved puzzle.
class-attribute
instance-attribute
¶
puzzle_type = Alias('type')
The puzzle's own type discriminator, e.g. "CODE", "SOLO". Only observed via getLastActivities so far ("CODE"); findProgressByIds additionally returned "SOLO".
class-attribute
instance-attribute
¶
contributor = None
The codingamer who authored this puzzle, or None for a puzzle CodinGame provides itself.
Confirmed live (2026-08-02) absent entirely--not null--for official puzzles, which is what
community_creation: False marks. Only community-created puzzles have an author to name.
class-attribute
instance-attribute
¶
cover_binary_id = None
Binary image ID for the puzzle's cover image, or None for a puzzle that has no cover.
Omitted entirely (not null) rather than defaulted--observed on 7 of 30 puzzles returned by a
single Puzzle/findProgressByIds call (2026-08-03), so this is ordinary, not an edge case.
Defaulted (rather than left required) for the same reason contributor is.
class-attribute
instance-attribute
¶
test_session_handle = None
Opaque handle for a test session against this puzzle. Not always present--absent (along
with last_activity) for puzzles the codingamer has never attempted, observed via
Puzzle/findProgressByIds.
class-attribute
instance-attribute
¶
linked_achievements = None
Achievements linked to this puzzle. Only observed as an empty list so far, so element shape is unknown. Only present via Puzzle/findProgressByPrettyId.
class-attribute
instance-attribute
¶
moderators = None
Codingamers who moderate this puzzle. Only present via Puzzle/findProgressByPrettyId.
class-attribute
instance-attribute
¶
statement = None
Rendered HTML of the puzzle's full problem statement. Only present via Puzzle/findProgressByPrettyId.
class-attribute
instance-attribute
¶
title_map = None
Localized title (locale ID as a string key, e.g. "1"/"2" -> title). Only present via Puzzle/findProgressByPrettyId.
property
writable
¶
creation_time
See the field docstring for _creation_time. Always UTC.
property
writable
¶
last_activity
See the field docstring for _last_activity. Always UTC. None if not applicable.
dataclass
¶
CgPuzzleFeedback(feedback_id, feedbacks, extra_data=dict(), codingamer_feedback=None)
Bases: JSONWizardX
Community feedback/rating summary for a puzzle, as embedded in
CgLastActivityPuzzle.feedback and CgPuzzleMinimalProgress.feedback
(puzzle.py).
instance-attribute
¶
feedbacks
A histogram of community feedback ratings (bucket counts), lowest rating first.
class-attribute
instance-attribute
¶
codingamer_feedback = None
The requesting codingamer's own feedback rating for this puzzle, if given (scale unconfirmed--observed values are 1-5-ish star ratings). Not always present--absent from every example seen via Puzzle/findAllMinimalProgress.
dataclass
¶
CgPuzzleTopicNode(handle, value, extra_data=dict(), children=list(), category=None)
Bases: JSONWizardX
A single node in a puzzle's topic tree (CgLastActivityPuzzle.topics). Topics are
organized hierarchically--e.g. a top-level "Uncategorized"/"Algorithms" node with more
specific child topics like "BFS"/"Pathfinding" underneath.
instance-attribute
¶
handle
Opaque (but human-readable) slug for the topic, e.g. "bfs", "uncategorized".
class-attribute
instance-attribute
¶
children = field(default_factory=list)
Child topics nested under this one. Often empty.
class-attribute
instance-attribute
¶
category = None
The topic's difficulty category, e.g. "FUNDAMENTALS", "INTERMEDIATE", "ADVANCED". Not always present--observed absent for at least one top-level "Uncategorized" node.
dataclass
¶
CgLanguageCertification(can_edit_name, candidate_id, certification_history_id, certification_number, codingamer_id, community_stats, comparative_score, diploma_preview_id, first_name, handle, language_name, last_name, legacy, lower_score_warning, programming_language_id, score, visible, _date=Alias('date'), _last_try_date=Alias('lastTryDate'), certification_type=Alias('type'), extra_data=dict())
Bases: JSONWizardX
A codingamer's language certification (e.g. from a proctored/self-assessed language
skill test), as embedded in a CgSolvedPuzzlesByLanguage entry. Only a single example
has been observed so far, so field optionality beyond what's seen here is unconfirmed.
instance-attribute
¶
can_edit_name
Whether the codingamer can still edit the name shown on the certification/diploma.
instance-attribute
¶
certification_history_id
Numeric ID of this specific certification attempt/history entry.
instance-attribute
¶
certification_number
The certification's displayed certificate number.
instance-attribute
¶
community_stats
A histogram of community scores (bucket counts) used to compute comparative_score.
instance-attribute
¶
comparative_score
The codingamer's score as a percentile relative to the community, from 0.0 to 100.0.
instance-attribute
¶
diploma_preview_id
Binary image ID for a preview image of the certification diploma.
instance-attribute
¶
handle
Opaque handle identifying this certification (e.g. for a public diploma URL).
instance-attribute
¶
language_name
Display name of the certified programming language, e.g. "Python 3".
instance-attribute
¶
lower_score_warning
Whether the UI should warn that the score is on the lower end.
instance-attribute
¶
programming_language_id
The certified programming language's ID, e.g. "Python3".
instance-attribute
¶
visible
Whether the certification is publicly visible on the codingamer's profile.
class-attribute
instance-attribute
¶
certification_type = Alias('type')
The kind of certification, e.g. "LANGUAGE". Only one value observed so far.
property
writable
¶
last_try_date
See the field docstring for _last_try_date. Always UTC.
dataclass
¶
CgSolvedPuzzlesByLanguage(language_name, logo_id, programming_language_id, puzzle_count, extra_data=dict(), certification=None)
Bases: JSONWizardX
A codingamer's solved-puzzle count for a single programming language, as returned (in a bare JSON array) by countSolvedPuzzlesByProgrammingLanguage.
instance-attribute
¶
language_name
Display name of the programming language, e.g. "Python 3".
instance-attribute
¶
programming_language_id
The programming language's ID, e.g. "Python3".
instance-attribute
¶
puzzle_count
Number of puzzles the codingamer has solved using this language.
class-attribute
instance-attribute
¶
certification = None
The codingamer's certification for this language, if any.
dataclass
¶
CgPuzzleOfTheWeek(puzzle_id, picture_binary_id, extra_data=dict())
dataclass
¶
CgPuzzleMinimalProgress(id, level, community_creation, rank, solved_count, submitted, validator_score, _creation_time=Alias('creationTime'), extra_data=dict(), feedback=None, _last_activity=Alias('lastActivity', default=None))
Bases: JSONWizardX
A codingamer's minimal progress summary for a single puzzle, as returned (in a bare JSON
array) by findAllMinimalProgress. Covers every puzzle in some way related to the
codingamer (not just solved/attempted ones--submitted distinguishes the two).
instance-attribute
¶
level
Difficulty level, e.g. "easy", "medium", "hard", "expert", "tutorial", "multi", "optim", or a "codegolf-"-prefixed variant thereof.
instance-attribute
¶
community_creation
Whether this is a community-created puzzle (as opposed to an official CodinGame puzzle).
instance-attribute
¶
solved_count
Total number of codingamers who have solved this puzzle.
instance-attribute
¶
submitted
Whether the codingamer has submitted a solution to this puzzle.
instance-attribute
¶
validator_score
The codingamer's score against the puzzle's validators, e.g. 100 for a fully-solved puzzle. 0 if not submitted.
class-attribute
instance-attribute
¶
feedback = None
Community feedback/rating summary for this puzzle. Not always present.
property
writable
¶
creation_time
See the field docstring for _creation_time. Always UTC.
property
writable
¶
last_activity
See the field docstring for _last_activity. Always UTC. None if not applicable.
dataclass
¶
CgFollowingCodingamer(user_id, pseudo, public_handle, extra_data=dict(), avatar=None, cover=None, level=None, tagline=None, biography=None)
Bases: JSONWizardX
A followed codingamer's profile snippet, as embedded in
CgFollowingPuzzleProgress.codin_gamer. Only a single example has been observed so far,
so optionality of fields beyond the core identity ones is a best guess based on similar
profile snippets elsewhere in this API (e.g. CgCodingamerFollower).
class-attribute
instance-attribute
¶
avatar = None
The binary image ID of the codingamer's avatar image.
class-attribute
instance-attribute
¶
cover = None
The binary image ID of the codingamer's cover image.
class-attribute
instance-attribute
¶
tagline = None
Short freeform tagline shown on the codingamer's profile.
class-attribute
instance-attribute
¶
biography = None
Freeform biography text, as entered in the codingamer's profile.
dataclass
¶
CgFollowingPuzzleProgress(id, level, pretty_id, details_page_url, codin_gamer, topics, achievement_count, done_achievement_count, validator_score, xp_points, _last_activity=Alias('lastActivity'), extra_data=dict())
Bases: JSONWizardX
A followed codingamer's progress on a single puzzle, as returned (in a bare JSON array) by findBestFollowingProgress. Empty if the followed codingamer(s) haven't attempted the given puzzle. Only a single followed codingamer has been observed in this session's test account, so it's unconfirmed whether more than one entry can be returned (e.g. one per followed codingamer who has attempted the puzzle) or how "best" is determined among them.
instance-attribute
¶
details_page_url
Relative URL path to the puzzle's details/training page.
instance-attribute
¶
achievement_count
Total number of achievements associated with this puzzle.
instance-attribute
¶
done_achievement_count
Number of this puzzle's achievements the followed codingamer has unlocked.
instance-attribute
¶
validator_score
The followed codingamer's score against the puzzle's validators, e.g. 100 for a fully-solved puzzle.
property
writable
¶
last_activity
See the field docstring for _last_activity. Always UTC.
dataclass
¶
CgGeneratedPuzzleSession(handle, extra_data=dict(), report_ready=None, direct=None)
Bases: JSONWizardX
The response to Puzzle/generateSessionFromPuzzlePrettyId. Confirmed live (2026-07-30):
not a bare handle string, despite that being all that's actually needed downstream (see
CgPuzzleService.generate_session_from_puzzle_pretty_id, which unwraps this to just
handle for callers).
class-attribute
instance-attribute
¶
report_ready = None
Unclear precise semantics; observed False in the only example so far.
class-attribute
instance-attribute
¶
direct = None
Unclear precise semantics; observed False in the only example so far--possibly related
to CgTestSession.direct.