instant-cli 1.0.40 → 1.0.41-branch-python-sdk-v1.26586025551.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> instant-cli@1.0.40 build /home/runner/work/instant/instant/client/packages/cli
+> instant-cli@1.0.41-branch-python-sdk-v1.26586025551.1 build /home/runner/work/instant/instant/client/packages/cli
 > rm -rf dist; tsc -p tsconfig.build.json
 

package/dist/commands/genpy.d.ts

@@ -0,0 +1,39 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect, Schema } from 'effect';
+import { ReadSchemaFileError, SchemaValidationError } from '../lib/pushSchema.ts';
+declare const GenpyWriteError_base: Schema.TaggedErrorClass<GenpyWriteError, "GenpyWriteError", {
+    readonly _tag: Schema.tag<"GenpyWriteError">;
+} & {
+    message: typeof Schema.String;
+}>;
+export declare class GenpyWriteError extends GenpyWriteError_base {
+}
+export declare const genpyCommand: ({ outDir }: {
+    outDir?: string;
+}) => Effect.Effect<undefined, ReadSchemaFileError | SchemaValidationError | GenpyWriteError, FileSystem.FileSystem | Path.Path>;
+type SchemaLike = {
+    entities: Record<string, EntityDefLike>;
+    links: Record<string, LinkDefLike>;
+};
+type EntityDefLike = {
+    attrs: Record<string, DataAttrDefLike>;
+};
+type DataAttrDefLike = {
+    valueType: 'string' | 'number' | 'boolean' | 'date' | 'json';
+    required: boolean;
+};
+type LinkDefLike = {
+    forward: {
+        on: string;
+        label: string;
+        has: 'one' | 'many';
+    };
+    reverse: {
+        on: string;
+        label: string;
+        has: 'one' | 'many';
+    };
+};
+export declare function buildPy(schema: SchemaLike): string;
+export {};
+//# sourceMappingURL=genpy.d.ts.map

package/dist/commands/genpy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"genpy.d.ts","sourceRoot":"","sources":["../../src/commands/genpy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;;;;;;AAE9B,qBAAa,eAAgB,SAAQ,oBAInC;CAAG;AAML,eAAO,MAAM,YAAY,GAAI,YAAY;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,+HAuDxD,CAAC;AAIL,KAAK,UAAU,GAAG;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7D,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5D,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC;CAC7D,CAAC;AAyIF,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAoNlD"}

package/dist/commands/genpy.js

@@ -0,0 +1,537 @@
+import { FileSystem, Path } from '@effect/platform';
+import chalk from 'chalk';
+import { Effect, Schema } from 'effect';
+import { readLocalSchemaFile } from '../old.js';
+import { ReadSchemaFileError, SchemaValidationError, } from "../lib/pushSchema.js";
+export class GenpyWriteError extends Schema.TaggedError('GenpyWriteError')('GenpyWriteError', {
+    message: Schema.String,
+}) {
+}
+const PY_HEADER = `# AUTOGENERATED by \`instant-cli genpy\`. DO NOT EDIT THIS FILE BY HAND.
+# Re-run \`npx instant-cli genpy\` after schema changes.
+`;
+export const genpyCommand = ({ outDir }) => Effect.gen(function* () {
+    const localSchemaFile = yield* Effect.tryPromise({
+        try: readLocalSchemaFile,
+        catch: (e) => e instanceof Error
+            ? ReadSchemaFileError.make({ message: e.message })
+            : ReadSchemaFileError.make({ message: String(e) }),
+    });
+    if (!localSchemaFile || !localSchemaFile.schema) {
+        return yield* ReadSchemaFileError.make({
+            message: `We couldn't find your ${chalk.yellow('`instant.schema.ts`')} file. Make sure it's in the project root or under \`src/\`. (Hint: set INSTANT_SCHEMA_FILE_PATH to override.)`,
+        });
+    }
+    if (localSchemaFile.schema.constructor?.name !== 'InstantSchemaDef') {
+        return yield* SchemaValidationError.make({
+            message: `We couldn't find your schema export.\nIn your ${chalk.yellow('`instant.schema.ts`')} file, make sure you ${chalk.green('`export default schema`')}`,
+        });
+    }
+    const collision = findIdentifierCollisions(localSchemaFile.schema);
+    if (collision) {
+        return yield* SchemaValidationError.make({ message: collision });
+    }
+    const path = yield* Path.Path;
+    const fs = yield* FileSystem.FileSystem;
+    // Default: write alongside the schema; `--out-dir` overrides for
+    // monorepos where Python lives in a sibling directory.
+    const targetDir = outDir
+        ? path.resolve(outDir)
+        : path.dirname(localSchemaFile.path);
+    yield* fs.makeDirectory(targetDir, { recursive: true }).pipe(Effect.mapError((e) => GenpyWriteError.make({
+        message: `Failed to create ${targetDir}: ${e}`,
+    })));
+    const pyPath = path.join(targetDir, 'instant_types.py');
+    const staleStub = path.join(targetDir, 'instant_types.pyi');
+    const pyContent = buildPy(localSchemaFile.schema);
+    yield* fs
+        .writeFileString(pyPath, pyContent)
+        .pipe(Effect.mapError((e) => GenpyWriteError.make({ message: `Failed to write ${pyPath}: ${e}` })));
+    // Earlier versions of genpy emitted a separate `.pyi`; drop it if a
+    // user is upgrading so it doesn't shadow the new `.py`.
+    yield* fs.remove(staleStub).pipe(Effect.ignore);
+    yield* Effect.log(`✅ Wrote ${pyPath}`);
+});
+// In python-land we would do something like keyword.iskeyword(), to generate
+// this list but because our gen-script is in ts-land we use an explicit set
+// based on Python 3 keywords
+// https://docs.python.org/3/reference/lexical_analysis.html#keywords
+const PY_KEYWORDS = new Set([
+    'False',
+    'None',
+    'True',
+    'and',
+    'as',
+    'assert',
+    'async',
+    'await',
+    'break',
+    'class',
+    'continue',
+    'def',
+    'del',
+    'elif',
+    'else',
+    'except',
+    'finally',
+    'for',
+    'from',
+    'global',
+    'if',
+    'import',
+    'in',
+    'is',
+    'lambda',
+    'nonlocal',
+    'not',
+    'or',
+    'pass',
+    'raise',
+    'return',
+    'try',
+    'while',
+    'with',
+    'yield',
+]);
+function isPyIdent(name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name);
+}
+function safePyIdent(name) {
+    if (isPyIdent(name))
+        return name;
+    let safe = name.replace(/[^A-Za-z0-9_]+/g, '_').replace(/_+/g, '_');
+    if (safe === '' || /^[0-9]/.test(safe))
+        safe = '_' + safe;
+    if (PY_KEYWORDS.has(safe))
+        safe += '_';
+    return safe;
+}
+// Python silently keeps the last duplicate class attribute, dropping
+// the first field's alias mapping. Reject up front instead.
+function findIdentifierCollisions(schema) {
+    for (const entName of Object.keys(schema.entities)) {
+        const seen = new Map([['id', 'implicit `id`']]);
+        const check = (rawKey, kind) => {
+            const safe = safePyIdent(rawKey);
+            const existing = seen.get(safe);
+            if (existing !== undefined) {
+                return (`Entity "${entName}": ${existing} and ${kind} "${rawKey}" both ` +
+                    `map to the Python identifier "${safe}". Rename one in your schema.`);
+            }
+            seen.set(safe, `${kind} "${rawKey}"`);
+            return undefined;
+        };
+        for (const attrName of Object.keys(schema.entities[entName].attrs)) {
+            const err = check(attrName, 'attribute');
+            if (err)
+                return err;
+        }
+        for (const link of Object.values(schema.links)) {
+            if (link.forward.on === entName) {
+                const err = check(link.forward.label, 'link');
+                if (err)
+                    return err;
+            }
+            if (link.reverse.on === entName) {
+                const err = check(link.reverse.label, 'link');
+                if (err)
+                    return err;
+            }
+        }
+    }
+    return undefined;
+}
+function className(entName) {
+    // Strip a leading `$` and PascalCase across separators so `my-entity`
+    // or `$users` produce valid Python class names.
+    const stripped = entName.startsWith('$') ? entName.slice(1) : entName;
+    return stripped
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+function mapValueType(vt) {
+    switch (vt) {
+        case 'string':
+            return 'str';
+        case 'number':
+            return 'float';
+        case 'boolean':
+            return 'bool';
+        case 'date':
+            return 'datetime';
+        case 'json':
+            return 'Any';
+        default:
+            // Defensive: if a new valueType ever lands in the schema without a
+            // genpy update, fall back to Any so generated code stays valid Python.
+            return 'Any';
+    }
+}
+function mapWriteValueType(vt) {
+    if (vt === 'date') {
+        return 'datetime | str | int | float';
+    }
+    return mapValueType(vt);
+}
+export function buildPy(schema) {
+    const entityNames = Object.keys(schema.entities).sort();
+    const fieldsByEntity = {};
+    const linkFieldsByEntity = {};
+    let usesDatetime = false;
+    for (const entName of entityNames) {
+        fieldsByEntity[entName] = [{ name: 'id', type: 'str', hasDefault: false }];
+        linkFieldsByEntity[entName] = [];
+        for (const [attrName, attrDef] of Object.entries(schema.entities[entName].attrs)) {
+            const baseType = mapValueType(attrDef.valueType);
+            if (baseType === 'datetime')
+                usesDatetime = true;
+            const type = attrDef.required ? baseType : `${baseType} | None`;
+            const safeName = safePyIdent(attrName);
+            fieldsByEntity[entName].push({
+                name: safeName,
+                type,
+                hasDefault: !attrDef.required,
+                rawKey: safeName === attrName ? undefined : attrName,
+            });
+        }
+    }
+    for (const link of Object.values(schema.links)) {
+        const fwd = link.forward;
+        const rev = link.reverse;
+        if (linkFieldsByEntity[fwd.on]) {
+            const safeName = safePyIdent(fwd.label);
+            linkFieldsByEntity[fwd.on].push({
+                name: safeName,
+                type: fwd.has === 'one'
+                    ? `${className(rev.on)} | None`
+                    : `list[${className(rev.on)}] | None`,
+                hasDefault: true,
+                rawKey: safeName === fwd.label ? undefined : fwd.label,
+            });
+        }
+        if (linkFieldsByEntity[rev.on]) {
+            const safeName = safePyIdent(rev.label);
+            linkFieldsByEntity[rev.on].push({
+                name: safeName,
+                type: rev.has === 'one'
+                    ? `${className(fwd.on)} | None`
+                    : `list[${className(fwd.on)}] | None`,
+                hasDefault: true,
+                rawKey: safeName === rev.label ? undefined : rev.label,
+            });
+        }
+    }
+    // Sort link fields alphabetically for stable output across schema rewrites.
+    for (const entName of entityNames) {
+        linkFieldsByEntity[entName].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    let usesField = false;
+    const classBlocks = entityNames.map((entName) => {
+        const allFields = [
+            ...fieldsByEntity[entName],
+            ...linkFieldsByEntity[entName],
+        ];
+        const hasAlias = allFields.some((f) => f.rawKey !== undefined);
+        const config = hasAlias
+            ? 'ConfigDict(extra="ignore", populate_by_name=True)'
+            : 'ConfigDict(extra="ignore")';
+        const lines = [
+            `class ${className(entName)}(BaseModel):`,
+            `    model_config = ${config}`,
+        ];
+        for (const f of allFields) {
+            let decl;
+            if (f.rawKey !== undefined) {
+                usesField = true;
+                const args = f.hasDefault
+                    ? `default=None, alias=${JSON.stringify(f.rawKey)}`
+                    : `alias=${JSON.stringify(f.rawKey)}`;
+                decl = `    ${f.name}: ${f.type} = Field(${args})`;
+            }
+            else if (f.hasDefault) {
+                decl = `    ${f.name}: ${f.type} = None`;
+            }
+            else {
+                decl = `    ${f.name}: ${f.type}`;
+            }
+            lines.push(decl);
+        }
+        return lines.join('\n');
+    });
+    const rebuilds = entityNames.map((entName) => `${className(entName)}.model_rebuild()`);
+    // Webhook record / handler types live in the same .py so users get one
+    // import point (`from instant_types import ...`) for both query results
+    // and webhook handler type-checking.
+    const webhookSection = buildWebhookSection(schema, entityNames);
+    const typingImports = [
+        'TYPE_CHECKING',
+        'Any',
+        'Callable',
+        'Literal',
+        'TypedDict',
+    ];
+    const stdlibImports = [];
+    if (usesDatetime)
+        stdlibImports.push('from datetime import datetime');
+    stdlibImports.push(`from typing import ${typingImports.join(', ')}`);
+    const pydanticImports = usesField
+        ? 'BaseModel, ConfigDict, Field'
+        : 'BaseModel, ConfigDict';
+    const sdkImports = [
+        'from instantdb import AsyncInstant as _BaseAsyncInstant',
+        'from instantdb import Instant as _BaseInstant',
+        'from instantdb import InstantAPIError, InstantError, id, lookup',
+    ].join('\n');
+    const importBlock = stdlibImports.join('\n') +
+        '\n\n' +
+        `from pydantic import ${pydanticImports}\n\n` +
+        sdkImports;
+    const txTypingBlock = buildTxTypingBlock(schema, entityNames);
+    // Add record-model rebuilds so forward-string annotations to entity
+    // types resolve under `from __future__ import annotations`.
+    const recordRebuilds = [];
+    for (const entName of entityNames) {
+        const cls = className(entName);
+        for (const action of ['Create', 'Update', 'Delete']) {
+            recordRebuilds.push(`${cls}${action}Record.model_rebuild()`);
+        }
+    }
+    const entityMapLines = ['    "entities": {'];
+    for (const entName of entityNames) {
+        entityMapLines.push(`        ${JSON.stringify(entName)}: ${className(entName)},`);
+    }
+    entityMapLines.push('    },');
+    const recordMapLines = ['    "records": {'];
+    for (const entName of entityNames) {
+        const cls = className(entName);
+        for (const action of ['create', 'update', 'delete']) {
+            const capAction = action.charAt(0).toUpperCase() + action.slice(1);
+            recordMapLines.push(`        (${JSON.stringify(entName)}, ${JSON.stringify(action)}): ${cls}${capAction}Record,`);
+        }
+    }
+    recordMapLines.push('    },');
+    const schemaLiteral = [
+        'schema = {',
+        ...entityMapLines,
+        ...recordMapLines,
+        '}',
+    ].join('\n');
+    // `_schema` defaults via setdefault so `_clone()` (used by `as_user`)
+    // can pass an explicit value without a double-pass TypeError.
+    const typedClients = [
+        'class Instant(_BaseInstant):',
+        '    tx: _TxBuilder',
+        '',
+        '    def __init__(self, **kwargs: Any) -> None:',
+        '        kwargs.setdefault("_schema", schema)',
+        '        super().__init__(**kwargs)',
+        '',
+        '',
+        'class AsyncInstant(_BaseAsyncInstant):',
+        '    tx: _TxBuilder',
+        '',
+        '    def __init__(self, **kwargs: Any) -> None:',
+        '        kwargs.setdefault("_schema", schema)',
+        '        super().__init__(**kwargs)',
+    ].join('\n');
+    return [
+        PY_HEADER + '"""Schema-bound Instant clients + Pydantic models."""',
+        '',
+        'from __future__ import annotations',
+        '',
+        importBlock,
+        '',
+        '',
+        txTypingBlock,
+        '',
+        '',
+        classBlocks.join('\n\n\n'),
+        '',
+        '',
+        '# Resolve forward references introduced by `from __future__ import annotations`.',
+        rebuilds.join('\n'),
+        '',
+        '',
+        webhookSection,
+        '',
+        '',
+        '# Rebuild webhook records so `before` / `after` annotations resolve to entity classes.',
+        recordRebuilds.join('\n'),
+        '',
+        '',
+        schemaLiteral,
+        '',
+        '',
+        typedClients,
+        '',
+    ].join('\n');
+}
+// ---------- webhook record / handler codegen ----------
+function buildWebhookSection(schema, entityNames) {
+    // Schemas with zero entities would produce `WebhookRecord = ` (no RHS).
+    if (entityNames.length === 0)
+        return '';
+    const recordClasses = [];
+    const namespaceUnions = [];
+    const namespaceHandlerDicts = [];
+    // `before`/`after` shape varies by action.
+    const RECORD_VARIANTS = [
+        { action: 'create', before: 'None = None', afterTpl: (c) => c },
+        { action: 'update', before: 'CLS', afterTpl: (c) => c },
+        { action: 'delete', before: 'CLS', afterTpl: () => 'None = None' },
+    ];
+    for (const entName of entityNames) {
+        const cls = className(entName);
+        for (const { action, before, afterTpl } of RECORD_VARIANTS) {
+            const cap = action.charAt(0).toUpperCase() + action.slice(1);
+            recordClasses.push([
+                `class ${cls}${cap}Record(BaseModel):`,
+                `    model_config = ConfigDict(extra="ignore")`,
+                `    namespace: Literal[${JSON.stringify(entName)}] = ${JSON.stringify(entName)}`,
+                `    id: str`,
+                `    action: Literal[${JSON.stringify(action)}] = ${JSON.stringify(action)}`,
+                `    before: ${before === 'CLS' ? cls : before}`,
+                `    after: ${afterTpl(cls)}`,
+                `    idempotencyKey: str`,
+            ].join('\n'));
+        }
+        namespaceUnions.push(`${cls}Record = ${cls}CreateRecord | ${cls}UpdateRecord | ${cls}DeleteRecord`);
+        // Per-namespace handler TypedDict. Functional syntax so the `$default`
+        // key is expressible.
+        namespaceHandlerDicts.push([
+            `_${cls}Handlers = TypedDict(`,
+            `    "_${cls}Handlers",`,
+            '    {',
+            `        "create": Callable[[${cls}CreateRecord], Any],`,
+            `        "update": Callable[[${cls}UpdateRecord], Any],`,
+            `        "delete": Callable[[${cls}DeleteRecord], Any],`,
+            `        "$default": Callable[[${cls}Record], Any],`,
+            '    },',
+            '    total=False,',
+            ')',
+        ].join('\n'));
+    }
+    const rootUnionTerms = entityNames.map((n) => `${className(n)}Record`);
+    const rootUnion = `WebhookRecord = ${rootUnionTerms.join(' | ')}`;
+    const handlerDictLines = [
+        'WebhookHandlers = TypedDict(',
+        '    "WebhookHandlers",',
+        '    {',
+    ];
+    for (const entName of entityNames) {
+        handlerDictLines.push(`        ${JSON.stringify(entName)}: _${className(entName)}Handlers,`);
+    }
+    handlerDictLines.push(`        "$default": Callable[[WebhookRecord], Any],`);
+    handlerDictLines.push('    },', '    total=False,', ')');
+    return [
+        '# ---------- webhook record models ----------',
+        '',
+        recordClasses.join('\n\n\n'),
+        '',
+        '',
+        '# ---------- webhook handler types ----------',
+        '',
+        namespaceUnions.join('\n'),
+        '',
+        rootUnion,
+        '',
+        '',
+        namespaceHandlerDicts.join('\n\n\n'),
+        '',
+        '',
+        handlerDictLines.join('\n'),
+    ].join('\n');
+}
+// ---------- tx builder typing (TYPE_CHECKING block) ----------
+function buildTxTypingBlock(schema, entityNames) {
+    const linkFieldsByEntity = {};
+    for (const entName of entityNames)
+        linkFieldsByEntity[entName] = [];
+    for (const link of Object.values(schema.links)) {
+        const fwdArg = link.forward.has === 'one' ? 'str' : 'str | list[str]';
+        const revArg = link.reverse.has === 'one' ? 'str' : 'str | list[str]';
+        if (linkFieldsByEntity[link.forward.on]) {
+            linkFieldsByEntity[link.forward.on].push({
+                label: link.forward.label,
+                type: fwdArg,
+            });
+        }
+        if (linkFieldsByEntity[link.reverse.on]) {
+            linkFieldsByEntity[link.reverse.on].push({
+                label: link.reverse.label,
+                type: revArg,
+            });
+        }
+    }
+    for (const entName of entityNames) {
+        linkFieldsByEntity[entName].sort((a, b) => a.label.localeCompare(b.label));
+    }
+    // Class-syntax TypedDict requires identifier keys; switch to the
+    // functional form when any key on a given dict is irregular.
+    const buildTypedDict = (name, fields) => {
+        const allIdent = fields.every((f) => isPyIdent(f.key));
+        if (allIdent) {
+            const lines = [`    class ${name}(TypedDict, total=False):`];
+            for (const f of fields)
+                lines.push(`        ${f.key}: ${f.type}`);
+            if (fields.length === 0)
+                lines.push('        pass');
+            return lines;
+        }
+        const lines = [
+            `    ${name} = TypedDict(`,
+            `        ${JSON.stringify(name)},`,
+            '        {',
+        ];
+        for (const f of fields) {
+            lines.push(`            ${JSON.stringify(f.key)}: ${f.type},`);
+        }
+        lines.push('        },', '        total=False,', '    )');
+        return lines;
+    };
+    const lines = [
+        'if TYPE_CHECKING:',
+        '    from typing import Generic, TypeVar, overload',
+        '',
+        '    ChunkT = TypeVar("ChunkT")',
+        '',
+        ...buildTypedDict('_TxOpts', [{ key: 'upsert', type: 'bool' }]),
+    ];
+    for (const entName of entityNames) {
+        const cls = className(entName);
+        const argFields = [];
+        for (const [attrName, attrDef] of Object.entries(schema.entities[entName].attrs)) {
+            argFields.push({
+                key: attrName,
+                type: mapWriteValueType(attrDef.valueType),
+            });
+        }
+        lines.push('');
+        lines.push(...buildTypedDict(`${cls}Args`, argFields));
+        lines.push('');
+        lines.push(...buildTypedDict(`${cls}Links`, linkFieldsByEntity[entName].map((l) => ({
+            key: l.label,
+            type: l.type,
+        }))));
+        lines.push('');
+        lines.push(`    class _${cls}Chunk:`, `        def update(self, args: ${cls}Args, opts: _TxOpts | None = None) -> _${cls}Chunk: ...`, `        def create(self, args: ${cls}Args, opts: _TxOpts | None = None) -> _${cls}Chunk: ...`, `        def link(self, args: ${cls}Links) -> _${cls}Chunk: ...`, `        def unlink(self, args: ${cls}Links) -> _${cls}Chunk: ...`, `        def delete(self) -> _${cls}Chunk: ...`, `        def merge(self, args: ${cls}Args, opts: _TxOpts | None = None) -> _${cls}Chunk: ...`, `        def rule_params(self, args: dict[str, Any]) -> _${cls}Chunk: ...`);
+    }
+    lines.push('', '    class _NamespaceBuilder(Generic[ChunkT]):', '        def __getitem__(self, eid: Any) -> ChunkT: ...', '        def lookup(self, attr: str, value: Any) -> ChunkT: ...', '');
+    // Only valid Python identifiers can appear as `_TxBuilder` attrs (for
+    // `db.tx.<name>` autocomplete); irregular names use `db.tx["..."]`.
+    const identifierEntities = entityNames.filter(isPyIdent);
+    lines.push('    class _TxBuilder:');
+    for (const entName of entityNames) {
+        lines.push(`        @overload`, `        def __getitem__(self, etype: Literal[${JSON.stringify(entName)}]) -> _NamespaceBuilder[_${className(entName)}Chunk]: ...`);
+    }
+    lines.push('        @overload');
+    lines.push('        def __getitem__(self, etype: str) -> _NamespaceBuilder[Any]: ...');
+    lines.push('        def __getitem__(self, etype: str) -> _NamespaceBuilder[Any]: ...');
+    for (const entName of identifierEntities) {
+        lines.push(`        ${entName}: _NamespaceBuilder[_${className(entName)}Chunk]`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=genpy.js.map