tools: command records, Raw material and uploads group - one line per cause, examples, prohibitions (#142)
Files changed: - CHANGES.md - VERSION - tools/CONTRACT.md - tools/chemenu/commands/raw_cmd.py - tools/chemenu/commands/upload_cmd.py
This commit is contained in:
torben committed
1 parent
be78ad20af
commit
964978a9c6
5 files changed
+305
-103
No files matched your search
@@ -316,42 +316,13 @@ def _replace(
|
||||
cli_contract.Variant(
|
||||
usage='raw accept <file> [<file> ...] --fidelity <v> --authority <v> '
|
||||
'[--page "<Title>"] [--dry-run]',
|
||||
notes="Promote one or more files from `incoming/` into `raw/<YYYY>/<MM>/`, "
|
||||
"computed from the accept date rather than chosen by hand "
|
||||
"(`raw/CONTRACT.md` \"Getting a file in\"): a subdirectory under `incoming/` is "
|
||||
"tolerated and ignored, not inspected - `raw/` no longer addresses by type. One "
|
||||
"file promoted alone lands with no directory of its own; several files in one call "
|
||||
"nest under `raw/<YYYY>/<MM>/<stem>/`, named after the first file's stem. "
|
||||
"`--fidelity`/`--authority` are required here (see `types describe source`; "
|
||||
"`unknown` is refused, backfill-only) - the one moment both are knowable. "
|
||||
'`--page "<Title>"` additionally extends that existing source page\'s '
|
||||
"`raw_files:` in the same call and writes both capture fields onto it (refused if "
|
||||
"it already carries a different value - a capture field is fixed once); if that "
|
||||
"raises the page past one file, its already-promoted file is folded into a bundle "
|
||||
"at *its own* parent directory, not today's shard, so a bundle never mixes an old "
|
||||
"and a new capture date, after checking it has no other owner "
|
||||
"(`provenance.duplicate_raw_file_owners`). The set of names occupied anywhere "
|
||||
"under `raw/` - file stems and bundle directory names alike, old type directories "
|
||||
"and date shards together - must stay unique: a promote whose target name already "
|
||||
"belongs to something this call does not itself own is refused, naming both "
|
||||
"`--replaces` and renaming-in-`incoming/` without recommending either",
|
||||
notes="Promote one or more files from `incoming/` into today's `raw/<YYYY>/<MM>/` "
|
||||
"shard",
|
||||
),
|
||||
cli_contract.Variant(
|
||||
usage='raw accept <file> --replaces <raw-path> [--fidelity <v>] [--authority <v>] '
|
||||
"[--dry-run]",
|
||||
notes="The one sanctioned way past that uniqueness rule, and the one sanctioned "
|
||||
"way to correct an already-set capture field: overwrites `<raw-path>` in place with "
|
||||
"the single incoming file (same filename required; there is no type directory left "
|
||||
"to match), leaving every page's `raw_files:` untouched and writing no `kb/` page - "
|
||||
"the previous edition survives only in `git log --follow <raw-path>`. "
|
||||
"`--fidelity`/`--authority` are optional here, and passing one overwrites the "
|
||||
"owning page's already-set value - the one path fill-once does not block, because "
|
||||
"a corrected capture is a new edition of the source, not an edit of the page "
|
||||
"describing it. Refuses if the target has more than one owning source page; if it "
|
||||
"has none, replaces anyway and says so. Cannot be combined with `--page` or with "
|
||||
"more than one incoming file - a replacement is one file for one file. Prints the "
|
||||
"source page (if any) and its citing pages, so their update lands in the same "
|
||||
"commit as the replacement",
|
||||
notes="Overwrite one existing raw file in place with a new edition",
|
||||
),
|
||||
),
|
||||
properties=cli_contract.Properties(
|
||||
@@ -362,35 +333,108 @@ def _replace(
|
||||
"`--fidelity`/`--authority` was given) one page write",
|
||||
budget=cli_contract.Budget.COUNTED,
|
||||
),
|
||||
notes="See `raw/CONTRACT.md` \"Getting a file in: incoming/\".",
|
||||
notes=(
|
||||
"Promotes files from `incoming/` into `raw/<YYYY>/<MM>/`, computed from the accept "
|
||||
"date rather than chosen by hand. A subdirectory under `incoming/` is tolerated and "
|
||||
"ignored, not inspected - `raw/` does not address by type.",
|
||||
"One file promoted alone lands with no directory of its own; several files in one call "
|
||||
"nest under `raw/<YYYY>/<MM>/<stem>/`, named after the first file's stem.",
|
||||
"`--fidelity`/`--authority` are required on a plain accept (`types describe source` "
|
||||
"lists the values); `unknown` is refused - it is backfill-only.",
|
||||
"`--page \"<Title>\"` additionally extends that existing source page's `raw_files:` in "
|
||||
"the same call and writes both capture fields onto it - refused if it already carries a "
|
||||
"different value, since a capture field is fixed once.",
|
||||
"If `--page` raises the page past one file, its already-promoted file is folded into a "
|
||||
"bundle at *its own* parent directory, not today's shard, so a bundle never mixes an "
|
||||
"old and a new capture date - after checking that file has no other owner.",
|
||||
"Every name occupied anywhere under `raw/` - file stems and bundle directory names "
|
||||
"alike, old type directories and date shards together - stays unique: a promote whose "
|
||||
"target name already belongs to something this call does not itself own is refused, "
|
||||
"naming `--replaces` and renaming in `incoming/` as the two routes, without "
|
||||
"recommending either.",
|
||||
"`--replaces <raw-path>` overwrites that file in place with the single incoming file "
|
||||
"(same filename required), leaves every page's `raw_files:` untouched and writes no "
|
||||
"`kb/` page; the previous edition survives only in `git log --follow <raw-path>`.",
|
||||
"With `--replaces`, `--fidelity`/`--authority` are optional, and passing one overwrites "
|
||||
"the owning page's already-set value - the one path the fixed-once rule does not "
|
||||
"block.",
|
||||
"`--replaces` refuses a target with more than one owning source page; with none, it "
|
||||
"replaces anyway and says so. It cannot be combined with `--page` or with more than one "
|
||||
"incoming file.",
|
||||
"`--replaces` prints the source page (if any) and its citing pages, so their update "
|
||||
"lands in the same commit as the replacement.",
|
||||
"A file already at its computed destination is what \"already exists\" reports, not a "
|
||||
"partial prior run to resume - safe to retry as-is once a cause is fixed.",
|
||||
"`--dry-run` reports the moves without making them.",
|
||||
),
|
||||
failures=(
|
||||
cli_contract.Failure(
|
||||
label="raw accept",
|
||||
cause="A file does not exist, is not under `incoming/`, or is nested more than "
|
||||
"one level below it, two files in one call share a filename, a target path already "
|
||||
"exists, `--fidelity`/`--authority` is missing (unless `--replaces`) or names "
|
||||
"`unknown` or a value outside the schema's enum, the target name is already "
|
||||
"occupied anywhere under `raw/` by something the call does not own, `--page` names "
|
||||
"an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is "
|
||||
"missing on disk, a file to be moved has more than one owning page, or `--page` "
|
||||
"would overwrite an already-set `fidelity`/`authority` with a different value",
|
||||
reaction="Fix the named argument and retry once. Safe to retry as-is once the cause is "
|
||||
"fixed: a file already at its computed destination is what \"already exists\" "
|
||||
"reports, not a partial prior run to resume. A stem-occupied refusal is not fixed "
|
||||
"by retrying at all - it names `--replaces` and renaming in `incoming/` as the two "
|
||||
"routes and neither is the tool's to pick. Never choose the destination by hand "
|
||||
"instead - that is the decision this command exists to take away",
|
||||
cause="A file does not exist, is not under `incoming/`, or is nested more than one "
|
||||
"level below it; two files in one call share a filename; or a target path already "
|
||||
"exists",
|
||||
reaction="Fix the named argument and retry once",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept",
|
||||
cause="`--fidelity`/`--authority` is missing, or names `unknown` or a value outside "
|
||||
"the schema's enum",
|
||||
reaction="Pass both with a valid value, then retry once",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept",
|
||||
cause="The target name is already occupied anywhere under `raw/` by something the "
|
||||
"call does not own",
|
||||
reaction="Not fixed by retrying: the refusal names `--replaces` (same source, new "
|
||||
"edition) and renaming in `incoming/` (a separate source) as the two routes, and "
|
||||
"neither is the tool's to pick. Show the message to the user and wait",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept",
|
||||
cause="`--page` names an unknown page or one with no `raw_files:` yet, an existing "
|
||||
"`raw_files:` entry is missing on disk, a file to be moved has more than one owning "
|
||||
"page, or `--page` would overwrite an already-set `fidelity`/`authority` with a "
|
||||
"different value",
|
||||
reaction="Fix the named argument and retry once; a different capture value on an "
|
||||
"existing page is a new edition - `--replaces`",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept --replaces",
|
||||
cause="More than one incoming file, `--page` also given, the incoming file does "
|
||||
"not exist or is not under `incoming/` (or is nested more than one level below "
|
||||
"it), its filename differs from the target's, the target does not lie under `raw/` "
|
||||
"or does not exist, `--fidelity`/`--authority` names `unknown` or a value outside "
|
||||
"the schema's enum, or the target has more than one owning source page",
|
||||
reaction="Fix the named argument and retry once. Every check runs before the "
|
||||
"filesystem is touched, so a refusal leaves both files exactly as they were",
|
||||
cause="More than one incoming file, or `--page` also given",
|
||||
reaction="A replacement is one file for one file - fix the call and retry once",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept --replaces",
|
||||
cause="The incoming file does not exist or is not under `incoming/` (or is nested "
|
||||
"more than one level below it), its filename differs from the target's, or the "
|
||||
"target does not lie under `raw/` or does not exist",
|
||||
reaction="Fix the named argument and retry once - every check runs before the "
|
||||
"filesystem is touched, so both files are exactly as they were",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
label="raw accept --replaces",
|
||||
cause="`--fidelity`/`--authority` names `unknown` or a value outside the schema's "
|
||||
"enum, or the target has more than one owning source page",
|
||||
reaction="Fix the named argument and retry once; nothing was touched",
|
||||
),
|
||||
),
|
||||
examples=(
|
||||
"tools/wikitool raw accept incoming/docker-cheatsheet.md --fidelity verbatim "
|
||||
"--authority reporting",
|
||||
'tools/wikitool raw accept incoming/part-2.md --fidelity verbatim --authority reporting '
|
||||
'--page "Source - Docker Cheatsheet"',
|
||||
"tools/wikitool raw accept incoming/cluster.md --replaces raw/documents/cluster.md",
|
||||
),
|
||||
never=(
|
||||
"Never choose the destination under `raw/` by hand, and never move a file into `raw/` "
|
||||
"yourself.",
|
||||
"Never pick between `--replaces` and renaming on your own initiative after a "
|
||||
"name-occupied refusal - the user tells the two intents apart.",
|
||||
),
|
||||
see_also=(
|
||||
"`raw/CONTRACT.md` \"Getting a file in: incoming/\" - the rules and why",
|
||||
"`wikitool types describe source` - the capture field values",
|
||||
"`wikitool new source` - the source page for a promoted file",
|
||||
),
|
||||
))
|
||||
@app.command("accept")
|
||||
|
||||
Reference in new issue
Block a user