bantamkit-mcp 0.26.0

package/dist/pyargparse.d.ts

@@ -0,0 +1,141 @@
+/** One `subs.add_parser(name, help=...)` under an `add_subparsers()` action. */
+export interface Subcommand {
+    /** The word the operator types, and the `dest=` of the pseudo-action in the help table. */
+    readonly name: string;
+    /** `help=`, which is what the PARENT prints beside the name. The sub-parser never shows it. */
+    readonly help: string;
+    /** The parser this name dispatches to. Its `prog` is `'<parent prog> <name>'`. */
+    readonly parser: ParserSpec;
+}
+/** One `parser.add_argument(...)`. */
+export interface ActionSpec {
+    /** `-h`, `--help`, … in the order they were given. `option_strings[0]` leads the usage.
+     *  EMPTY for a positional — that emptiness is what argparse itself keys every branch on. */
+    readonly optionStrings: readonly string[];
+    /** argparse's `dest`; the default metavar for an OPTIONAL upper-cases it, a positional does not. */
+    readonly dest: string;
+    /** `metavar=`, when the default is not what the reference prints. */
+    readonly metavar?: string;
+    /**
+     * `store_true` and `help` take no value (`nargs == 0`); `store` and `positional` take one
+     * (`nargs is None`); `subparsers` is `nargs == PARSER`. NOT PORTED: every other `nargs`
+     * (`?`, `*`, `+`, `REMAINDER`, `SUPPRESS`, an integer count) — no parser in this runtime
+     * declares one, and `_get_nargs_pattern` is where they would go.
+     */
+    readonly kind: 'help' | 'storeTrue' | 'store' | 'positional' | 'subparsers';
+    /**
+     * `help=`. THE EMPTY STRING IS argparse's `help=None`, not a blank help line: both are
+     * falsy, and `_format_action` branches on the truth of `action.help` — the header gets a
+     * line to itself and no help text follows. `add_subparsers()` takes no `help=` in the
+     * reference, so the choices row prints bare above its indented children.
+     */
+    readonly help: string;
+    /** `type=`. Throws on a value `int()` would reject; the caller renders the sentence. */
+    readonly convert?: (raw: string) => unknown;
+    /** `__name__` of `type=`, for `invalid %(type)s value: %(value)r`. */
+    readonly typeName?: string;
+    readonly defaultValue: unknown;
+    /** `add_subparsers()`'s parsers, in `add_parser` order. Only ever set on `kind: 'subparsers'`. */
+    readonly subcommands?: readonly Subcommand[];
+}
+export interface ParserSpec {
+    readonly prog: string;
+    /** `description=`. EMPTY means the reference passed none — `add_text(None)` adds nothing. */
+    readonly description: string;
+    readonly actions: readonly ActionSpec[];
+    /**
+     * One entry per `add_mutually_exclusive_group()`, holding indices into `actions`. argparse
+     * only brackets a group whose members are CONTIGUOUS in `actions`; a non-contiguous group
+     * is skipped in the usage line (and still enforced when parsing), which this reproduces.
+     */
+    readonly groups: readonly (readonly number[])[];
+}
+/**
+ * `argparse.ArgumentParser.error`: the usage block, one sentence, stderr, exit 2.
+ *
+ * `spec` is WHOSE usage block, and it is not decoration. A sub-parser reports its own prog
+ * and its own usage (`python -m bantamkit.memory status: error: …`) while an unrecognized
+ * argument that a sub-parser handed back reports the TOP parser's — measured, both.
+ */
+export declare class ArgvError extends Error {
+    readonly spec: ParserSpec | null;
+    constructor(spec: ParserSpec | null, message: string);
+}
+/**
+ * A `-h`/`--help` action fired mid-parse. argparse prints and exits 0 THERE, not after.
+ *
+ * `spec` is whose help: `restore -h` prints the sub-parser's, not the top parser's.
+ */
+export declare class HelpRequested extends Error {
+    readonly spec: ParserSpec | null;
+    constructor(spec?: ParserSpec | null);
+}
+/**
+ * `argparse.ArgumentTypeError`: a `type=` callable's own sentence, printed VERBATIM.
+ *
+ * The distinction is wire-visible and it is the whole reason this class exists:
+ * `--budget 0` is `argument --budget: must be >= 1` (the callable's message) while
+ * `--budget x` is `argument --budget: invalid _positive value: 'x'` (argparse's, because
+ * `int()` raised `ValueError`). One `catch` for both would print the wrong one half the time.
+ */
+export declare class ArgumentTypeError extends Error {
+}
+/**
+ * `int(text)`, which is what `type=int` is — and the first half of `type=_positive`.
+ *
+ * It rejects everything `int()` rejects, and the caller reports that as an ARGUMENT error
+ * (exit 2). It lives here rather than beside one parser because two parsers now need it and
+ * a second hand-written copy of a conversion rule is the defect this module was built from.
+ */
+export declare function pyIntStrict(text: string): number;
+/** What both `_split_lines` and `_fill_text` do before they wrap. */
+export declare const collapseWhitespace: (text: string) => string;
+/** `textwrap.wrap(text, width)`. `text` must already be collapsed. */
+export declare function wrap(text: string, width: number): string[];
+/** `textwrap.fill(text, width)` at indent 0. */
+export declare const fill: (text: string, width: number) => string;
+/**
+ * `shutil.get_terminal_size().columns`, which is what `HelpFormatter` asks for.
+ *
+ * `COLUMNS` wins when it parses to a positive integer; otherwise the size of STDOUT's
+ * terminal; otherwise 80. `spawnSync` hands a child pipes rather than a tty, so 80 is the
+ * width the conformance suite and every MCP host actually see — the DEFAULT help is the
+ * wrapped form, not the wide one.
+ */
+export declare function terminalColumns(): number;
+/** `HelpFormatter.__init__`: `width = shutil.get_terminal_size().columns - 2`. */
+export declare const helpWidth: () => number;
+/** `HelpFormatter._format_usage`, which ends in a BLANK line (`'\n\n'`). */
+export declare function formatUsage(spec: ParserSpec, width: number, prefix?: string): string;
+/** `ArgumentParser.format_usage` — the usage block alone, one trailing newline. */
+export declare const formatUsageBlock: (spec: ParserSpec, width: number) => string;
+/** `ArgumentParser.format_help`. */
+export declare function formatHelp(spec: ParserSpec, width: number): string;
+/**
+ * `ArgumentParser.parse_known_args`: the namespace keyed by `dest`, plus what it could not
+ * place.
+ *
+ * Throws `HelpRequested` where argparse would `parser.exit(0)` mid-parse — which is DURING
+ * the scan, not after it, so `-h --nope` prints help and exits 0 exactly as the reference
+ * does, and `restore -h --nope` prints the SUB-parser's help for the same reason.
+ *
+ * EXTRAS ARE RETURNED RATHER THAN RAISED, and that is the whole reason this function is
+ * separate from `parseArgs`. A subparser hands its leftovers BACK to the parser that
+ * dispatched to it (`_UNRECOGNIZED_ARGS_ATTR`), so `... status extra` reports
+ * `unrecognized arguments: extra` under the TOP parser's prog and usage, not under
+ * `status`'s — measured against the reference, both ways round.
+ *
+ * NOT PORTED: `parse_intermixed_args`, `fromfile_prefix_chars`, `choices` on anything but a
+ * subparsers action, required mutually exclusive groups (`one of the arguments … is
+ * required`), and every `nargs` outside the three `_getNargsPattern` names.
+ */
+export declare function parseKnownArgs(spec: ParserSpec, argv: readonly string[]): {
+    values: Record<string, unknown>;
+    extras: string[];
+};
+/**
+ * `ArgumentParser.parse_args`: `parse_known_args`, and an error for anything left over.
+ *
+ * Returns the namespace as a plain record keyed by `dest`.
+ */
+export declare function parseArgs(spec: ParserSpec, argv: readonly string[]): Record<string, unknown>;