Skip to content

Latest commit

 

History

History
155 lines (137 loc) · 10.9 KB

message-codes-options.md

File metadata and controls

155 lines (137 loc) · 10.9 KB
SPDX-FileCopyrightText 2026-present Arthit Suriyawongkul
SPDX-FileType DOCUMENTATION
SPDX-License-Identifier CC0-1.0

Message codes: Options

See also: Message codes (the index of every code) and Messages and codes (the line grammar, what a code guarantees and when to trust one).

Trust a code only when the line is one of the lines below, a value in place of each <name>, after at most one prefix: the index lists the prefixes and the values.

Codes

Code Level Means Since
option-conflict ERROR The command line holds an option the command cannot take in this case (-o/--output with several wheels), or one an existing ID registry contradicts: 'loom id generate --namespace' for a registry made with another namespace, or 'loom id generate' with a --project-dir (the current directory when not given), or 'loom id import' with an explicit one, other than the one the registry was made for. The 'not allowed with' line is reserved for options of a mutually exclusive group; no command has one yet. 0.25.0
option-invalid ERROR The command line holds an option or a value the command does not take: an unknown option, a value of the wrong form or out of range, an unknown subcommand, an option out of order (a creator's type or email before its name), or a 'loom id generate' PATH outside --project-dir (the library: a path outside the project root given to IdRegistry.generate). Or a URL credential fingerprint is not one: an accept-url-credentials in [tool.pitloom] that is no array or has an entry that is no fingerprint (named by its position, from 0), or one given to the library; the line never shows the value, which may be a credential pasted by mistake. Or a url-credentials in [tool.pitloom] (PitloomConfig.url_credentials in the library) is neither warn nor refuse, or CredentialPolicy(refuse=...) is no bool. An option given without its value is option-missing; two options argparse refuses together are option-conflict. 0.25.0
option-missing ERROR The command line lacks an argument or option the command needs (a subcommand, -o/--output for 'loom generate', an ID registry for 'loom id'), or the value of an option given (-o with nothing after it). 0.25.0
option-no-effect WARNING, INFO An option or setting was given that the target or command cannot act on (a build flag without --allow-build, --use-lockfile for a wheel given to 'loom generate', a library parameter a URL target ignores); the line says why. The INFO: line is a [tool.pitloom] setting the build hook or 'embed-wheel' never acts on, named by its flag. The FINGERPRINT= line is a fingerprint accepted (--accept-url-credential, accept-url-credentials in [tool.pitloom]) that no URL value of the SBOM it names (its document id) has: a value since removed, or a fingerprint mistyped. The DIR= line is 'loom id generate' or 'loom id import' given -o and --project-dir, whose project config could not be read (a bare setup(), an invalid setting): its url-credentials is not applied. 0.25.0

option-conflict

  • Level: ERROR. As an ERROR, the command stops for that input and writes nothing for it (exit 1).

  • Means: The command line holds an option the command cannot take in this case (-o/--output with several wheels), or one an existing ID registry contradicts: 'loom id generate --namespace' for a registry made with another namespace, or 'loom id generate' with a --project-dir (the current directory when not given), or 'loom id import' with an explicit one, other than the one the registry was made for. The 'not allowed with' line is reserved for options of a mutually exclusive group; no command has one yet.

  • SBOM effect: not-written: no SBOM is written for the input.

  • Pitloom did: Ran nothing: the command exits 1 (2 for the 'not allowed with' line), the library (IdRegistry) raises ValueError carrying the code, and an ID registry is left as it is.

  • The caller may fix: The caller may drop the option, run the command once per input, or, for an ID registry, pass the namespace or project directory the registry holds (or name another registry file), and run again. Deleting a registry to change them loses every id it pins: that is the user's decision, never the caller's.

  • Lines:

    ERROR: <option> cannot be used <when> [option-conflict]
    ERROR: argument <option>: not allowed with argument <other> [option-conflict]
    ERROR: ID registry: FILE=<file>: namespace <namespace> is not --namespace <given-namespace>; delete it to change the namespace [option-conflict]
    ERROR: ID registry: FILE=<file>: namespace <namespace> is not --namespace <given-namespace> (they differ in masked credentials); delete it to change the namespace [option-conflict]
    ERROR: ID registry: FILE=<file>: project root '<path>' is not '<root>'; delete it to change the project root [option-conflict]
    

option-invalid

  • Level: ERROR. As an ERROR, the command stops for that input and writes nothing for it (exit 1).

  • Means: The command line holds an option or a value the command does not take: an unknown option, a value of the wrong form or out of range, an unknown subcommand, an option out of order (a creator's type or email before its name), or a 'loom id generate' PATH outside --project-dir (the library: a path outside the project root given to IdRegistry.generate). Or a URL credential fingerprint is not one: an accept-url-credentials in [tool.pitloom] that is no array or has an entry that is no fingerprint (named by its position, from 0), or one given to the library; the line never shows the value, which may be a credential pasted by mistake. Or a url-credentials in [tool.pitloom] (PitloomConfig.url_credentials in the library) is neither warn nor refuse, or CredentialPolicy(refuse=...) is no bool. An option given without its value is option-missing; two options argparse refuses together are option-conflict.

  • SBOM effect: not-written: no SBOM is written for the input.

  • Pitloom did: Ran nothing: the command exits 2 (the Action step fails), 1 for a PATH outside --project-dir, a fingerprint or a url-credentials in [tool.pitloom]; the library raises ValueError carrying the code for a build timeout out of range (BuildOptions), a path outside the project root (IdRegistry.generate) and a fingerprint that is none (CredentialPolicy, accept-url-credentials) or a url-credentials that is no mode.

  • The caller may fix: The caller may fix the option or value the line names ('loom --help' lists them) and run again. Tell the user only when the value came from them. For a fingerprint, the user copies it from the credentials-unsafe/written or refused line that offers it; do not show the value they gave, and do not edit their configuration.

  • Lines:

    ERROR: argument <option>: <refusal> [option-invalid]
    ERROR: unrecognized arguments: <error> [option-invalid]
    ERROR: ambiguous option: <error> [option-invalid]
    ERROR: build timeout must be 1-<limit> seconds, got <value> [option-invalid]
    ERROR: PATH '<path>' is outside --project-dir '<root>' [option-invalid]
    ERROR: ID registry: PATH '<path>' is not inside the project root '<root>' [option-invalid]
    ERROR: not a fingerprint (sha256: and 16 to 64 lowercase hex digits) [option-invalid]
    ERROR: <table> <setting> entry <number>: not a fingerprint (sha256: and 16 to 64 lowercase hex digits) [option-invalid]
    ERROR: <table> <setting>: must be an array of fingerprints [option-invalid]
    ERROR: <table> <setting>: must be "warn" or "refuse" [option-invalid]
    ERROR: PitloomConfig url_credentials: must be "warn" or "refuse" [option-invalid]
    ERROR: CredentialPolicy refuse: must be True or False [option-invalid]
    

option-missing

  • Level: ERROR. As an ERROR, the command stops for that input and writes nothing for it (exit 1).

  • Means: The command line lacks an argument or option the command needs (a subcommand, -o/--output for 'loom generate', an ID registry for 'loom id'), or the value of an option given (-o with nothing after it).

  • SBOM effect: not-written: no SBOM is written for the input.

  • Pitloom did: Ran nothing: the command exits 2 (a parse error) or 1.

  • The caller may fix: The caller may add what the line names and run again. Tell the user only when the value must come from them (an output file, a registry location).

  • Lines:

    ERROR: the following arguments are required: <error> [option-missing]
    ERROR: argument <option>: expected <arity> [option-missing]
    ERROR: -o/--output is required: a detected target has no default file name; pass -o FILE, or use 'loom project', 'loom wheel', 'loom model' or 'loom env' for that target's own default [option-missing]
    ERROR: no ID registry declared: pass --id-registry FILE or set id-registry in <table> [option-missing]
    

option-no-effect

  • Level: WARNING, INFO.

  • Means: An option or setting was given that the target or command cannot act on (a build flag without --allow-build, --use-lockfile for a wheel given to 'loom generate', a library parameter a URL target ignores); the line says why. The INFO: line is a [tool.pitloom] setting the build hook or 'embed-wheel' never acts on, named by its flag. The FINGERPRINT= line is a fingerprint accepted (--accept-url-credential, accept-url-credentials in [tool.pitloom]) that no URL value of the SBOM it names (its document id) has: a value since removed, or a fingerprint mistyped. The DIR= line is 'loom id generate' or 'loom id import' given -o and --project-dir, whose project config could not be read (a bare setup(), an invalid setting): its url-credentials is not applied.

  • SBOM effect: none: the SBOM states what the input holds.

  • Pitloom did: Ran as if it were not given; the run goes on.

  • The caller may fix: The caller may drop the option from its command, or pick the target or companion option it needs (the line says which). Nothing to tell the user unless they asked for the option; for the INFO: line, do not edit their configuration. For the FINGERPRINT= line, tell the user the acceptance accepts nothing here; they may drop it. For the DIR= line, tell the user the project's url-credentials was not applied and why; to refuse, the caller adds --refuse-url-credentials.

  • Lines:

    WARNING: Options: <name>: <option> has no effect <when> [option-no-effect]
    INFO: Options: <name>: <option> has no effect <when> [option-no-effect]
    WARNING: Build: <name>: <option> has no effect <when> [option-no-effect]
    WARNING: Options: FINGERPRINT=<fingerprint>: matches no URL of the SBOM <element> [option-no-effect]
    WARNING: Options: DIR=<dir>: url-credentials not read: <failure>; the warn mode applies; add <option> to refuse [option-no-effect]