codingame_tools.contribution_manager.schema¶
The working-directory root's own manifest (contribution.json) and the per-view content
manifest inside data/ (contribution-data.json):
-
contribution.json(CgContributionIdentity): global identity, and only that--which contribution this directory tracks. Lives only at the working directory's own root (a sibling ofdata/, never inside it, and never itself git-tracked as part ofdata/'s content). Its presence is what identifies a directory as a contribution working directory at all. -
.meta/contribution-meta.json(CgContributionMeta): how the working directory is put together (currently just where its git-dir is)--chosen and maintained by this client rather than describing the contribution, so it is meta state rather than identity. Seecodingame_tools.contribution_manager.manager's module docstring for the--git-dir/--work-treelayout it selects between. -
contribution-data.json(CgContributionView): the actual content manifest, insidedata/(seecodingame_tools.contribution_manager.layout.DATA_SUBDIR_NAME)--part ofdata/'s ordinary git-tracked content, diffed/merged by real git like everything else there. -
.meta/contribution-status.json(CgContributionStatusCache): an offline, non-git-tracked cache of server metadata that isn't tied to any content version (score/votes/comment count/ views/moderator approve-reject tallies/etc.)--see that class's docstring.
module-attribute
¶
CONTRIBUTION_IDENTITY_FILE_NAME = 'contribution.json'
Name of the global-identity manifest file, directly inside the contribution directory root
only (never inside data/)--never propagated to any materialized view.
module-attribute
¶
CONTRIBUTION_DATA_FILE_NAME = 'contribution-data.json'
Name of the per-view materialized-content manifest file, inside every view's data/
subdirectory.
module-attribute
¶
CONTRIBUTION_SCHEMA_VERSION = 1
Current on-disk format version for a contribution working directory, recorded in
CgContributionIdentity.schema_version so a future format change can detect and offer to
migrate an older working directory.
dataclass
¶
CgContributionSelectedTest(ordinal, side, extra_data=dict())
Bases: JSONWizardX
.meta/selected-test.json: which single test case the debugger should run against.
See codingame_tools.puzzle_manager.schema.CgPuzzleSelectedTest for why this lives in
.meta/ rather than as a pickString in launch.json. A contribution needs a side as well
as an ordinal, since the same ordinal can hold both a local and a validator test.
Absent means "no explicit choice", and callers fall back to the first local test--the one an author is normally iterating on. Validators are the hidden, scoring ones; defaulting to a validator would be a surprising thing to land in a debugger.
dataclass
¶
CgContributionIdentity(schema_version, extra_data=dict(), contribution_handle=None)
Bases: JSONWizardX
The contribution.json manifest: global identity for a contribution working directory,
constant for its lifetime (never changes across import_/push/merge/etc.--unlike
everything else in the working directory, this is not tied to any specific commit/version).
Exception: contribution_handle itself transitions exactly once, from None to a real
value, the first time CgContributionManager.push() succeeds against a working directory
created via create() rather than import_()--see push()'s docstring for why.
instance-attribute
¶
schema_version
The on-disk format version this working directory was written in--see
CONTRIBUTION_SCHEMA_VERSION.
class-attribute
instance-attribute
¶
contribution_handle = None
The opaque contribution ID (CgContribution.public_handle) this working directory
tracks--None if it was create()d and has never been successfully push()d yet (there's
no server-side contribution to have a handle for). Also the one fact that decides which of
CgContributionManager.repair()'s two modes applies, and (when set) the one fact that mode
actually needs--everything else about prior git history is either present (git-dir found
where recorded) or, if not, deliberately not reconstructed, just re-fetched fresh.
dataclass
¶
CgContributionMeta(git_repo, extra_data=dict())
Bases: JSONWizardX
.meta/contribution-meta.json: this client's own state about how the working directory is
put together, as opposed to what it is (contribution.json) or what it holds (data/).
Chosen and maintained entirely by the meta infrastructure, so it belongs here rather than in the identity manifest, which describes the contribution itself and is constant for the directory's lifetime.
Not merely a tidiness argument--see manager's "portability contract". contribution.json
and data/ are the exportable state: copy them elsewhere, repair(), and you have a
working directory. So they may hold only facts true of the contribution wherever it is. Where
the git-dir goes is a fact about this checkout on this machine, and two checkouts of one
contribution can legitimately differ--the same content exported from a standalone directory
into a colleague's monorepo must come up external rather than embedded. Recorded in
contribution.json it would travel and be wrong on arrival, which is what 1.0.x did.
Being in .meta/ makes it disposable, like everything else here--so nothing may depend on
it surviving. CgContributionManager.git_dir treats it as a cached answer and falls back to
looking for the repository on disk, which is why deleting .meta/ can never orphan a
data/.git, and why a freshly exported directory with no .meta/ at all still works (see
_resolve_git_dir).
instance-attribute
¶
git_repo
Where this working directory's git-dir is, relative to the working directory root, in POSIX
form--either ".meta/.contribution-git" (external, with data/ as its work tree) or
"data/.git" (embedded, making data/ an ordinary git working directory). Decided once at
create()/import_() time--see manager's module docstring for how, and why it is not
re-derived on every command.
A path rather than a flag because it is read far more often than it is written, and a path is directly usable. It is still only ever one of those two values; anything else is not something the rest of this package knows how to drive.
dataclass
¶
CgContributionSolutionSnapshot(solution_language, code, extra_data=dict())
Bases: JSONWizardX
.meta/solution-snapshot.json: the starter stub this client last generated into
data/solution.src, and the language it was generated for.
Records only generated stubs, never a real reference solution. Its one job is to answer
"is solution.src still just the placeholder we wrote, or does it hold actual work?"--which
is what CgContributionManager.set_language needs, because switching a contribution's
language is destructive in a way switching a puzzle's is not.
A contribution stores exactly one solution server-side, with no per-language history (unlike
a puzzle--see CgTestSessionService.get_previous_code_by_language_id). So there is nothing
to restore when switching, and the previous solution is gone for good once the next
updateContribution lands. "Matches what the server currently has" deliberately does not
count as safe here for that reason.
Deliberately not updated by git-driven writes (merge, discard_local, rebase): after any
of those, solution.src holds real content and no longer matches this snapshot, which is
exactly the answer wanted.
instance-attribute
¶
solution_language
The language the stub was generated for. A snapshot whose language no longer matches
CgContributionData.solution_language describes a previous state and must not be trusted.
instance-attribute
¶
code
The exact stub text written, or None when the language had no stub to offer and
solution.src was removed entirely (see
CgLanguage.build_contribution_create_stub_source).
dataclass
¶
CgContributionView(extra_data=dict(), puzzle_type=None, draft=True, ready_for_moderation=False, data=(lambda: CgContributionData(title=''))())
Bases: JSONWizardX
The contribution-data.json manifest: the content of data/--everything needed to
push() it, or to compare it against main/server at any other commit via git diff.
data is a working version of CgContributionData, with several fields deliberately kept
always-empty by convention (not schema-enforced) because their real content lives in
sibling files/directories instead--overwritten from those sources when a view is
materialized, so a stray hand-edited value here is harmless, just confusing to read:
statement->statement.cgmdinput_description->input_description.cgmdoutput_description->output_description.cgmdconstraints->constraints.cgmdstub_generator->stub_generator.cgstubsolution->solution.src(always this exact name--seecodingame_tools.contribution_manager.layout.SOLUTION_FILE_NAME)test_cases-> built from thetests/subdirectory (seetest_cases_dir)cover_binary_id-> built fromcover.png
All other fields of data (title, difficulty, topics, solution_language) are used
normally--there's no sidecar file for them.
class-attribute
instance-attribute
¶
puzzle_type = None
The contribution type, e.g. "PUZZLE_INOUT". A required top-level parameter to
updateContribution--must be set before push() can succeed.
class-attribute
instance-attribute
¶
draft = True
Whether the version being committed is a private draft. A required top-level parameter to
updateContribution. Defaults to True (the safe default for a working dir that hasn't
explicitly decided to publish yet).
class-attribute
instance-attribute
¶
ready_for_moderation = False
Whether the version being committed is being formally submitted for moderation. A required
top-level parameter to updateContribution.
class-attribute
instance-attribute
¶
data = field(default_factory=lambda: CgContributionData(title=''))
The materialized contribution content--see the class docstring for which fields are real and which are always-empty placeholders backed by sibling files/directories instead.
dataclass
¶
CgContributionStatusCache(version, contribution, moderator_approvals, moderator_denials, _refreshed_at=Alias('refreshedAt'), extra_data=dict())
Bases: JSONWizardX
The .meta/contribution-status.json cache: an offline snapshot of every piece of server
metadata that is NOT tied to any particular content version--status/status_history/
score/up_votes/down_votes/comment_count/views/editable/active_version/
validate_action/the moderation-window timestamps (all live on contribution.last_version
or contribution itself), plus moderator_approvals/moderator_denials (from a wholly
separate endpoint, Contribution/findContributionModerators--not part of CgContribution
at all).
Deliberately NOT git-tracked (see layout.CONTRIBUTION_STATUS_CACHE_FILE_NAME)--unlike
contribution-data.json, none of this is diffable/mergeable content, it's just the most
recent snapshot available, refreshed every time CgContributionManager.fetch()/import_()/
repair() obtain a fresh CgContribution from the server--regardless of whether the
content version changed, since none of these fields are tied to it (a moderator vote or a
new comment doesn't bump the content version).
contribution is stored whole and unredacted here (unlike the version-data git branch's
copy, which redacts draft/ready_for_moderation/contribution_type/last_version.data
to keep those out of diffable git history)--this file isn't git-tracked at all, so nothing
is gained by redacting it, and keeping the full object avoids having to duplicate every
field name into a narrower cache-specific shape.
instance-attribute
¶
version
The content version (contribution.last_version.version) as of this refresh--informational
only; this cache's own fields are current as of refreshed_at regardless of whether the
content version has since moved on.
instance-attribute
¶
contribution
The complete, unredacted CgContribution as returned by findContribution at
refreshed_at.
instance-attribute
¶
moderator_approvals
Moderators who had cast a "validate" (approve) vote as of refreshed_at.
instance-attribute
¶
moderator_denials
Moderators who had cast a "deny" (reject) vote as of refreshed_at.
property
writable
¶
refreshed_at
See the field docstring for _refreshed_at. Always UTC.