codingame_tools.client.common.protocol.codingamer¶
JSON-serializable dataclasses for the CodinGamer service's findCodingamePointsStatsByHandle, findCodinGamerPublicInformations, findFollowers, and findFollowing Codingame API methods.
dataclass
¶
CgCodingamer(user_id, public_handle, extra_data=dict(), pseudo=None, country_id=None, form_values=None, school_id=None, rank=None, avatar=None, cover=None, tagline=None, company=None, city=None, level=None, xp=None, category=None, biography=None, _online_since=Alias('onlineSince', default=None))
Bases: JSONWizardX
A codingamer's profile, as embedded in the response to findCodingamePointsStatsByHandle, and returned directly by findCodinGamerPublicInformations.
pseudo/country_id are Optional--confirmed live (a fresh/minimal "dev" test account,
level 1, no display name set, returned {"userId": ..., "countryId": "US",
"publicHandle": ..., "formValues": {}, "level": 1} with no pseudo key at all). Matches
the same already-documented behavior on the sibling class CgCodingamerFollower (used by
findFollowers/findFollowing), which independently discovered pseudo/country_id missing
for "apparently never-configured accounts"--country_id hasn't been directly observed
missing here yet, but is made Optional pre-emptively given that precedent, rather than
waiting to hit the same failure a second time for a different field.
instance-attribute
¶
public_handle
The codingamer's opaque public handle string, as passed to findCodingamePointsStatsByHandle.
class-attribute
instance-attribute
¶
pseudo = None
The codingamer's display name. Not always present; see class docstring.
class-attribute
instance-attribute
¶
country_id = None
ISO country code, e.g. "US", "GB". Not always present; see class docstring.
class-attribute
instance-attribute
¶
form_values = None
Freeform profile fields the codingamer has filled in, e.g. {"city": "Seattle", "school": "University of Arizona"}. Keys observed vary per codingamer.
class-attribute
instance-attribute
¶
school_id = None
Internal ID of the school selected in the codingamer's profile, if any.
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
¶
company = None
Freeform current employer, as entered in the codingamer's profile.
class-attribute
instance-attribute
¶
city = None
Freeform city, as entered in the codingamer's profile. Observed duplicating form_values["city"].
class-attribute
instance-attribute
¶
level = None
The codingamer's current level, derived from xp (see CgCodingamePointsStats.xp_thresholds).
class-attribute
instance-attribute
¶
biography = None
Freeform biography text, as entered in the codingamer's profile.
dataclass
¶
CgRankHistoryEntry(rank, total, points, contest_points, optim_points, codegolf_points, multi_training_points, clash_points, _date=Alias('date'), extra_data=dict())
Bases: JSONWizardX
A single dated snapshot in a codingamer's points-ranking history
(CgCodingamePointsRankingDto.rank_history). All fields have been consistently present
across every observed entry.
instance-attribute
¶
points
The codingamer's total points as of this snapshot's date (sum of the category points below).
instance-attribute
¶
contest_points
Points earned from contests, as of this snapshot's date.
instance-attribute
¶
optim_points
Points earned from optimization puzzles, as of this snapshot's date.
instance-attribute
¶
codegolf_points
Points earned from code golf puzzles, as of this snapshot's date.
instance-attribute
¶
multi_training_points
Points earned from multiplayer training games, as of this snapshot's date.
instance-attribute
¶
clash_points
Points earned from Clash of Code, as of this snapshot's date.
dataclass
¶
CgCodingamePointsRankingDto(codingame_points_total, codingame_points_rank, codingame_points_contests, codingame_points_achievements, codingame_points_xp, codingame_points_optim, codingame_points_codegolf, codingame_points_multi_training, codingame_points_clash, number_codingamers, number_codingamers_global, extra_data=dict(), rank_history=list())
Bases: JSONWizardX
Points-ranking summary and history for a codingamer.
Per CodinGame's own ranking rework documentation (https://www.codingame.com/help/rank,
https://www.codingame.com/blog/ranking-rework-competition/): rewards are split into XP
(contributes to Level, i.e. platform activity) and CodinPoints/"CP" (contributes to rank,
i.e. multiplayer performance), and CP is tracked as five separate per-category
leaderboards (contests, bot programming, Clash of Code, optimization, code golf), each
computed per-game via (BASE * min(N/500, 1)) ^ ((N-C+1)/N) with a category-specific
BASE--i.e. the per-category fields below are NOT simple counts of "points earned" on a
shared scale, and are NOT meant to be summed. Confirmed live (2026-08-01): summing all
seven codingame_points_* fields below does not reproduce codingame_points_total
(off by more than an order of magnitude)--whatever codingame_points_total/
codingame_points_rank are actually derived from isn't fully understood; treat the
per-category fields as informational only, not as a breakdown of the total/rank.
instance-attribute
¶
codingame_points_total
The codingamer's current total points, used for codingame_points_rank. NOT confirmed to
be a sum of the codingame_points_* category fields below--see the class docstring.
instance-attribute
¶
codingame_points_rank
The codingamer's current global points rank.
instance-attribute
¶
codingame_points_contests
Current CodinPoints in the contests leaderboard category--see the class docstring for why this isn't a simple "points earned" count comparable across categories.
instance-attribute
¶
codingame_points_achievements
Current points attributed to achievements. Per CodinGame's ranking rework, achievement rewards now convert to XP rather than CP--this field's exact current meaning/scale is unconfirmed.
instance-attribute
¶
codingame_points_xp
Observed live to exactly equal CgCodingamer.xp (raw lifetime XP)--i.e. this appears to
just mirror XP for display here, not a CP-scaled value; see the class docstring.
instance-attribute
¶
codingame_points_optim
Current CodinPoints in the optimization-puzzles leaderboard category--see the class docstring.
instance-attribute
¶
codingame_points_codegolf
Current CodinPoints in the code-golf-puzzles leaderboard category--see the class docstring.
instance-attribute
¶
codingame_points_multi_training
Current CodinPoints in the multiplayer-training-games leaderboard category--see the class docstring.
instance-attribute
¶
codingame_points_clash
Current CodinPoints in the Clash of Code leaderboard category--see the class docstring.
instance-attribute
¶
number_codingamers
Total number of codingamers ranked in the codingamer's local ranking scope.
instance-attribute
¶
number_codingamers_global
Total number of codingamers ranked globally.
class-attribute
instance-attribute
¶
rank_history = field(default_factory=list)
Dated snapshots of the codingamer's ranking/points over time.
dataclass
¶
CgXpThreshold(level, xp_threshold, cumulative_xp, extra_data=dict(), reward_languages=None)
Bases: JSONWizardX
One entry in the per-level XP threshold/progression table
(CgCodingamePointsStats.xp_thresholds).
dataclass
¶
CgCodingamePointsStats(achievement_count, codingamer, codingame_points_ranking_dto, extra_data=dict(), codingamer_points=None, xp_thresholds=list())
Bases: JSONWizardX
The complete response to findCodingamePointsStatsByHandle.
codingamer_points is Optional--confirmed live (a fresh/minimal "dev" test account, the
same one that exposed CgCodingamer.pseudo/country_id being Optional): the top-level
codingamerPoints key was entirely absent for that account. Originally documented here as
"duplicating" codingame_points_ranking_dto.codingame_points_total, based on both being 0
for that same degenerate (all-zero) test account--since disproven on a real account
(2026-08-01): codingamer_points was 7150 while codingame_points_total was 2800 at
the same moment--they are two distinct values, not a duplicate pair. See
CgCodingamePointsRankingDto's docstring for more on what is/isn't understood about how
these numbers relate to each other.
instance-attribute
¶
achievement_count
The number of achievements the codingamer has unlocked.
instance-attribute
¶
codingame_points_ranking_dto
The codingamer's points-ranking summary and history.
class-attribute
instance-attribute
¶
codingamer_points = None
The codingamer's current total points--not confirmed equal to codingame_points_ranking_dto.
codingame_points_total (disproven live--see class docstring); exact relationship
unconfirmed. Not always present; see class docstring.
class-attribute
instance-attribute
¶
xp_thresholds = field(default_factory=list)
The per-level XP threshold/progression table, up to (at least) the codingamer's current level.
dataclass
¶
CgCodingamerFollower(user_id, public_handle, is_follower, is_following, level, points, rank, extra_data=dict(), pseudo=None, country_id=None, avatar=None, cover=None, city=None, company_field=None, school_field=None, tagline=None, languages=None)
Bases: JSONWizardX
A single codingamer in a followers/following list, as returned by findFollowers and
findFollowing. Distinct from
CgCodingamer: adds follow-relationship flags (is_follower/is_following) and a few
differently-named/differently-shaped profile fields, and omits fields not returned by
this endpoint (form_values, school_id, xp, category, online_since, biography).
pseudo/country_id are Optional--observed absent for a few apparently never-configured
accounts (rank ~1080871, 0 points).
instance-attribute
¶
is_follower
Whether this codingamer follows the current_codingamer_id passed to findFollowers
(normally the logged-in codingamer).
instance-attribute
¶
is_following
Whether the current_codingamer_id passed to findFollowers (normally the logged-in
codingamer) follows this codingamer.
class-attribute
instance-attribute
¶
pseudo = None
The codingamer's display name. Not always present; see class docstring.
class-attribute
instance-attribute
¶
country_id = None
ISO country code, e.g. "US", "GB". Not always present; see class docstring.
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
¶
city = None
Freeform city, as entered in the codingamer's profile.
class-attribute
instance-attribute
¶
company_field = None
Freeform current employer, as entered in the codingamer's profile. Named differently
from CgCodingamer.company, for reasons unknown.
class-attribute
instance-attribute
¶
school_field = None
Freeform school, as entered in the codingamer's profile. Named differently from
CgCodingamer.school_id (an internal school ID rather than freeform text), for reasons
unknown.
class-attribute
instance-attribute
¶
tagline = None
Short freeform tagline shown on the codingamer's profile.
class-attribute
instance-attribute
¶
languages = None
A JSON-encoded array of programming language names the codingamer uses, e.g. '["JavaScript","Python"]'. Left as a raw (unparsed) string rather than a list: the server has been observed to double-encode this value for some codingamers--e.g. the literal 2-character string '"[]"' (an already-JSON-encoded empty array, itself JSON-encoded as a string a second time).