@contractkit/plugin-python 0.9.1

package/src/codegen-models.ts

@@ -0,0 +1,425 @@
+import type { ContractRootNode, ModelNode, FieldNode, ContractTypeNode } from '@contractkit/core';
+import { computeModelsWithInput, topoSortModels, collectExternalRefs, collectExternalInputRefs } from '@contractkit/core';
+
+// ─── Public entry point ────────────────────────────────────────────────────
+
+export interface ModelCodegenOptions {
+    /** Map from model name → output module name (for cross-file imports) */
+    modelModulePaths?: Map<string, string>;
+    /** Current output module name (used to skip self-imports) */
+    currentModule?: string;
+    /** Set of model names that have Input variants (cross-file) */
+    modelsWithInput?: Set<string>;
+}
+
+/**
+ * Generate Pydantic v2 model classes from a ContractRootNode.
+ */
+export function generatePydanticModels(root: ContractRootNode, opts: ModelCodegenOptions = {}): string {
+    const externalRefs = collectExternalRefs(root);
+    const externalModelsWithInput = opts.modelsWithInput ?? new Set<string>();
+    const localModelsWithInput = computeModelsWithInput(root.models, externalModelsWithInput);
+    const allModelsWithInput = new Set([...localModelsWithInput, ...externalModelsWithInput]);
+
+    const externalInputRefs = allModelsWithInput.size > 0 ? collectExternalInputRefs(root, allModelsWithInput) : [];
+    const allExternalRefs = [...new Set([...externalRefs, ...externalInputRefs])].sort();
+
+    // Track needed imports
+    const imports = new ImportTracker();
+    imports.add('pydantic', 'BaseModel');
+
+    // Pre-scan all models to determine what imports will be needed
+    for (const model of root.models) {
+        if (model.type) {
+            scanTypeImports(model.type, imports);
+        } else {
+            for (const f of model.fields) {
+                scanTypeImports(f.type, imports);
+            }
+        }
+    }
+
+    const lines: string[] = [];
+    lines.push('# Auto-generated by contractkit-plugin-python-sdk. Do not edit manually.');
+    lines.push('from __future__ import annotations');
+
+    // Cross-file imports for external model refs
+    const crossFileImports: string[] = [];
+    for (const ref of allExternalRefs) {
+        const modulePath = opts.modelModulePaths?.get(ref);
+        if (modulePath && modulePath !== opts.currentModule) {
+            crossFileImports.push(`from ${modulePath} import ${ref}`);
+        }
+    }
+
+    // We'll prepend stdlib/typing imports after, once we know what's needed
+    // Build model output first
+    const modelLines: string[] = [];
+    for (const model of topoSortModels(root.models)) {
+        modelLines.push('');
+        modelLines.push(...generateModel(model, allModelsWithInput, imports));
+    }
+
+    // Now emit stdlib imports
+    const stdlibLines = imports.render();
+    lines.push(...stdlibLines);
+    if (crossFileImports.length > 0) {
+        lines.push('');
+        lines.push(...crossFileImports);
+    }
+    lines.push(...modelLines);
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+// ─── Import tracking ──────────────────────────────────────────────────────
+
+class ImportTracker {
+    private groups: Map<string, Set<string>> = new Map();
+
+    add(module: string, name: string): void {
+        let s = this.groups.get(module);
+        if (!s) {
+            s = new Set();
+            this.groups.set(module, s);
+        }
+        s.add(name);
+    }
+
+    has(module: string, name: string): boolean {
+        return this.groups.get(module)?.has(name) ?? false;
+    }
+
+    render(): string[] {
+        // Order: stdlib → typing → pydantic
+        const ORDER = ['__future__', 'datetime', 'uuid', 'typing', 'pydantic'];
+        const lines: string[] = [];
+        lines.push('');
+        for (const mod of ORDER) {
+            const names = this.groups.get(mod);
+            if (!names || names.size === 0) continue;
+            const sorted = [...names].sort().join(', ');
+            lines.push(`from ${mod} import ${sorted}`);
+        }
+        // Any remaining
+        for (const [mod, names] of this.groups) {
+            if (ORDER.includes(mod)) continue;
+            const sorted = [...names].sort().join(', ');
+            lines.push(`from ${mod} import ${sorted}`);
+        }
+        return lines;
+    }
+}
+
+function scanTypeImports(type: ContractTypeNode, imports: ImportTracker): void {
+    switch (type.kind) {
+        case 'scalar':
+            switch (type.name) {
+                case 'date':
+                    imports.add('datetime', 'date');
+                    break;
+                case 'time':
+                    imports.add('datetime', 'time');
+                    break;
+                case 'datetime':
+                    imports.add('datetime', 'datetime');
+                    break;
+                case 'duration':
+                    imports.add('datetime', 'timedelta');
+                    break;
+                case 'uuid':
+                    imports.add('uuid', 'UUID');
+                    break;
+                case 'unknown':
+                case 'json':
+                case 'object':
+                    imports.add('typing', 'Any');
+                    break;
+            }
+            break;
+        case 'enum':
+            imports.add('typing', 'Literal');
+            break;
+        case 'union':
+            type.members.forEach(m => scanTypeImports(m, imports));
+            break;
+        case 'discriminatedUnion':
+            imports.add('typing', 'Annotated');
+            imports.add('pydantic', 'Field');
+            type.members.forEach(m => scanTypeImports(m, imports));
+            break;
+        case 'intersection':
+            imports.add('typing', 'Any');
+            break;
+        case 'array':
+            scanTypeImports(type.item, imports);
+            break;
+        case 'tuple':
+            type.items.forEach(t => scanTypeImports(t, imports));
+            break;
+        case 'record':
+            scanTypeImports(type.key, imports);
+            scanTypeImports(type.value, imports);
+            break;
+        case 'lazy':
+            scanTypeImports(type.inner, imports);
+            break;
+        case 'inlineObject':
+            imports.add('typing', 'Any');
+            break;
+    }
+}
+
+// ─── Type rendering ───────────────────────────────────────────────────────
+
+export function renderPyType(type: ContractTypeNode, modelsWithInput?: Set<string>, forInput = false): string {
+    switch (type.kind) {
+        case 'scalar':
+            return renderScalar(type.name);
+        case 'enum':
+            return `Literal[${type.values.map(v => JSON.stringify(v)).join(', ')}]`;
+        case 'literal':
+            return typeof type.value === 'string' ? JSON.stringify(type.value) : String(type.value);
+        case 'array':
+            return `list[${renderPyType(type.item, modelsWithInput, forInput)}]`;
+        case 'tuple':
+            if (type.items.length === 0) return 'tuple[()]';
+            return `tuple[${type.items.map(t => renderPyType(t, modelsWithInput, forInput)).join(', ')}]`;
+        case 'record':
+            return `dict[${renderPyType(type.key, modelsWithInput, forInput)}, ${renderPyType(type.value, modelsWithInput, forInput)}]`;
+        case 'union':
+            return type.members.map(m => renderPyType(m, modelsWithInput, forInput)).join(' | ');
+        case 'discriminatedUnion': {
+            const inner = type.members.map(m => renderPyType(m, modelsWithInput, forInput)).join(' | ');
+            return `Annotated[${inner}, Field(discriminator=${JSON.stringify(type.discriminator)})]`;
+        }
+        case 'intersection':
+            return 'dict[str, Any]';
+        case 'ref': {
+            if (forInput && modelsWithInput?.has(type.name)) {
+                return `${type.name}Input`;
+            }
+            return type.name;
+        }
+        case 'inlineObject':
+            return 'dict[str, Any]';
+        case 'lazy':
+            return renderPyType(type.inner, modelsWithInput, forInput);
+    }
+}
+
+function renderScalar(name: string): string {
+    switch (name) {
+        case 'string':
+        case 'email':
+        case 'url':
+            return 'str';
+        case 'number':
+            return 'float';
+        case 'int':
+            return 'int';
+        case 'bigint':
+            return 'int';
+        case 'boolean':
+            return 'bool';
+        case 'date':
+            return 'date';
+        case 'time':
+            return 'time';
+        case 'datetime':
+            return 'datetime';
+        case 'duration':
+            return 'timedelta';
+        case 'uuid':
+            return 'UUID';
+        case 'null':
+            return 'None';
+        case 'binary':
+            return 'bytes';
+        case 'unknown':
+        case 'json':
+        case 'object':
+            return 'Any';
+        default:
+            return 'Any';
+    }
+}
+
+// ─── Field name conversion ────────────────────────────────────────────────
+
+/** Convert a field name to a valid Python identifier in snake_case. */
+export function toPythonFieldName(name: string): string {
+    // Replace hyphens and non-alphanumeric chars (except underscore) with underscore
+    let result = name.replace(/[^a-zA-Z0-9_]/g, '_');
+    // camelCase → snake_case
+    result = result.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+    // Collapse multiple underscores
+    result = result.replace(/_+/g, '_').replace(/^_|_$/g, '');
+    // Prefix if starts with digit
+    if (/^\d/.test(result)) result = 'f_' + result;
+    return result;
+}
+
+// ─── Model generation ─────────────────────────────────────────────────────
+
+function generateModel(model: ModelNode, allModelsWithInput: Set<string>, imports: ImportTracker): string[] {
+    if (model.type) {
+        return generateTypeAlias(model, allModelsWithInput, imports);
+    }
+
+    const needsInputSplit = model.fields.some(f => f.visibility !== 'normal') || allModelsWithInput.has(model.name);
+
+    if (needsInputSplit) {
+        return generateSplitModel(model, allModelsWithInput, imports);
+    }
+    return generateSimpleModel(model, allModelsWithInput, imports);
+}
+
+function generateTypeAlias(model: ModelNode, allModelsWithInput: Set<string>, _: ImportTracker): string[] {
+    const lines: string[] = [];
+    if (model.description) lines.push(`# ${model.description}`);
+    if (model.deprecated) lines.push('# @deprecated');
+    lines.push(`${model.name} = ${renderPyType(model.type!, allModelsWithInput)}`);
+    if (allModelsWithInput.has(model.name)) {
+        lines.push(`${model.name}Input = ${renderPyType(model.type!, allModelsWithInput, true)}`);
+    }
+    return lines;
+}
+
+function generateSimpleModel(model: ModelNode, allModelsWithInput: Set<string>, imports: ImportTracker): string[] {
+    const lines: string[] = [];
+    if (model.description) lines.push(`# ${model.description}`);
+    if (model.deprecated) lines.push('# @deprecated');
+
+    const baseList = model.bases && model.bases.length > 0 ? model.bases.join(', ') : 'BaseModel';
+    lines.push(`class ${model.name}(${baseList}):`);
+
+    const fieldLines = renderFields(model.fields, allModelsWithInput, imports, false);
+    const needsConfig = model.fields.some(f => toPythonFieldName(f.name) !== f.name);
+    if (needsConfig) {
+        imports.add('pydantic', 'ConfigDict');
+        lines.push(`    model_config = ConfigDict(populate_by_name=True)`);
+        lines.push('');
+    }
+
+    if (fieldLines.length === 0) {
+        lines.push('    pass');
+    } else {
+        lines.push(...fieldLines);
+    }
+
+    return lines;
+}
+
+function generateSplitModel(model: ModelNode, allModelsWithInput: Set<string>, imports: ImportTracker): string[] {
+    const lines: string[] = [];
+
+    // Read model — omit writeonly fields
+    const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
+    if (model.description) lines.push(`# ${model.description}`);
+    if (model.deprecated) lines.push('# @deprecated');
+
+    const readBaseList = model.bases && model.bases.length > 0 ? model.bases.join(', ') : 'BaseModel';
+    lines.push(`class ${model.name}(${readBaseList}):`);
+    const readNeedsConfig = readFields.some(f => toPythonFieldName(f.name) !== f.name);
+    if (readNeedsConfig) {
+        imports.add('pydantic', 'ConfigDict');
+        lines.push(`    model_config = ConfigDict(populate_by_name=True)`);
+        lines.push('');
+    }
+    const readFieldLines = renderFields(readFields, allModelsWithInput, imports, false);
+    if (readFieldLines.length === 0) {
+        lines.push('    pass');
+    } else {
+        lines.push(...readFieldLines);
+    }
+
+    lines.push('');
+
+    // Input model — omit readonly fields
+    const writeFields = model.fields.filter(f => f.visibility !== 'readonly');
+    const inputBaseList =
+        model.bases && model.bases.length > 0 ? model.bases.map(b => (allModelsWithInput.has(b) ? `${b}Input` : b)).join(', ') : 'BaseModel';
+    lines.push(`class ${model.name}Input(${inputBaseList}):`);
+    const writeNeedsConfig = writeFields.some(f => toPythonFieldName(f.name) !== f.name);
+    if (writeNeedsConfig) {
+        imports.add('pydantic', 'ConfigDict');
+        lines.push(`    model_config = ConfigDict(populate_by_name=True)`);
+        lines.push('');
+    }
+    const writeFieldLines = renderFields(writeFields, allModelsWithInput, imports, true);
+    if (writeFieldLines.length === 0) {
+        lines.push('    pass');
+    } else {
+        lines.push(...writeFieldLines);
+    }
+
+    return lines;
+}
+
+function renderFields(fields: FieldNode[], allModelsWithInput: Set<string>, imports: ImportTracker, forInput: boolean): string[] {
+    const lines: string[] = [];
+    for (const f of fields) {
+        lines.push(...renderField(f, allModelsWithInput, imports, forInput));
+    }
+    return lines;
+}
+
+function renderField(field: FieldNode, allModelsWithInput: Set<string>, imports: ImportTracker, forInput: boolean): string[] {
+    const lines: string[] = [];
+    const pyName = toPythonFieldName(field.name);
+    const needsAlias = pyName !== field.name;
+
+    let typeStr = renderPyType(field.type, allModelsWithInput, forInput);
+    if (field.nullable) typeStr = `${typeStr} | None`;
+
+    const isOptional = field.optional || field.default !== undefined;
+
+    const fieldAnnotations: string[] = [];
+    if (needsAlias) {
+        imports.add('pydantic', 'Field');
+        fieldAnnotations.push(`alias=${JSON.stringify(field.name)}`);
+    }
+    if (field.default !== undefined) {
+        const def = typeof field.default === 'string' ? JSON.stringify(field.default) : String(field.default);
+        fieldAnnotations.push(`default=${def}`);
+    }
+
+    if (field.deprecated) lines.push(`    # @deprecated`);
+    if (field.description) lines.push(`    # ${field.description}`);
+
+    let rhs: string;
+    if (fieldAnnotations.length > 0) {
+        imports.add('pydantic', 'Field');
+        rhs = `Field(${fieldAnnotations.join(', ')})`;
+    } else if (isOptional) {
+        rhs = 'None';
+    } else {
+        rhs = '';
+    }
+
+    const optSuffix = isOptional && !field.nullable ? ` | None` : '';
+    const fullType = typeStr + optSuffix;
+
+    if (rhs) {
+        lines.push(`    ${pyName}: ${fullType} = ${rhs}`);
+    } else {
+        lines.push(`    ${pyName}: ${fullType}`);
+    }
+
+    return lines;
+}
+
+// ─── Module name helpers ──────────────────────────────────────────────────
+
+/** Derive a Python module name from a .ck file path, e.g. "ledger.categories.ck" → "_models_ledger_categories" */
+export function deriveModelsModuleName(file: string): string {
+    const base =
+        file
+            .split('/')
+            .pop()
+            ?.replace(/\.(op\.)?ck$/, '') ?? 'models';
+    const clean = base.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+    return `_models_${clean}`;
+}

package/src/index.ts

@@ -0,0 +1,143 @@
+import { resolve, join } from 'node:path';
+import type { ContractKitPlugin } from '@contractkit/core';
+import { generatePydanticModels, deriveModelsModuleName } from './codegen-models.js';
+import {
+    generatePythonClient,
+    deriveClientClassName,
+    deriveClientModuleName,
+    deriveClientPropertyName,
+    hasPublicOperations,
+    BASE_CLIENT_PY,
+} from './codegen-client.js';
+
+export interface PythonSdkPluginConfig {
+    /** Output directory relative to rootDir (default: "python-sdk") */
+    baseDir?: string;
+    /** Python package name used in the aggregator class name (default: "Sdk") */
+    packageName?: string;
+    /**
+     * Whether to emit client methods for operations marked `internal`. Defaults to `false` —
+     * internal ops are omitted so consumers don't pick them up. Set to `true` for an
+     * internal-use SDK that should expose them.
+     */
+    includeInternal?: boolean;
+}
+
+// ─── Default export: loaded via plugins array, reads config from ctx.options ─
+
+const plugin: ContractKitPlugin = {
+    name: 'python-sdk',
+    cacheKey: 'python-sdk',
+    async generateTargets(inputs, ctx) {
+        const config = ctx.options as PythonSdkPluginConfig;
+        return createPythonSdkPlugin(config, ctx.rootDir).generateTargets!(inputs, ctx);
+    },
+};
+
+export default plugin;
+
+// ─── Factory: for programmatic use with explicit config ────────────────────
+
+export function createPythonSdkPlugin(config: PythonSdkPluginConfig, rootDir: string): ContractKitPlugin {
+    return {
+        name: 'python-sdk',
+        cacheKey: `python-sdk:${JSON.stringify(config)}`,
+        async generateTargets({ contractRoots, opRoots, modelsWithInput: _modelsWithInput }, ctx) {
+            const modelsWithInput = _modelsWithInput as Set<string>;
+            const outDir = resolve(rootDir, config.baseDir ?? 'python-sdk');
+
+            // ── Build model module path map ──
+            // model name → importable Python module string, e.g. "._models_payment"
+            const modelModulePaths = new Map<string, string>();
+            const contractEntries: { moduleName: string; outPath: string; root: (typeof contractRoots)[number] }[] = [];
+
+            for (const contractRoot of contractRoots) {
+                const moduleName = deriveModelsModuleName(contractRoot.file);
+                const outPath = join(outDir, `${moduleName}.py`);
+                contractEntries.push({ moduleName, outPath, root: contractRoot });
+
+                for (const model of contractRoot.models) {
+                    modelModulePaths.set(model.name, `.${moduleName}`);
+                    if (modelsWithInput.has(model.name)) {
+                        modelModulePaths.set(`${model.name}Input`, `.${moduleName}`);
+                    }
+                }
+            }
+
+            // ── Emit model files ──
+            for (const { moduleName, outPath, root } of contractEntries) {
+                const content = generatePydanticModels(root, {
+                    modelModulePaths,
+                    currentModule: `.${moduleName}`,
+                    modelsWithInput,
+                });
+                ctx.emitFile(outPath, content);
+            }
+
+            // ── Emit client files ──
+            const clientInfos: { moduleName: string; className: string; propertyName: string }[] = [];
+            for (const opRoot of opRoots) {
+                if (!hasPublicOperations(opRoot, config.includeInternal)) continue;
+                const moduleName = deriveClientModuleName(opRoot.file);
+                const outPath = join(outDir, `${moduleName}.py`);
+                clientInfos.push({
+                    moduleName,
+                    className: deriveClientClassName(opRoot.file),
+                    propertyName: deriveClientPropertyName(opRoot.file),
+                });
+                ctx.emitFile(
+                    outPath,
+                    generatePythonClient(opRoot, {
+                        modelModulePaths,
+                        currentModule: `.${moduleName}`,
+                        modelsWithInput,
+                        includeInternal: config.includeInternal,
+                    }),
+                );
+            }
+
+            // ── Emit shared _base_client.py ──
+            ctx.emitFile(join(outDir, '_base_client.py'), BASE_CLIENT_PY);
+
+            // ── Emit requirements.txt ──
+            ctx.emitFile(join(outDir, 'requirements.txt'), 'httpx\npydantic>=2.0\n');
+
+            // ── Emit __init__.py aggregator ──
+            const sdkClassName = config.packageName
+                ? config.packageName
+                      .split(/[-._\s]+/)
+                      .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+                      .join('') + 'Sdk'
+                : 'Sdk';
+
+            const initLines: string[] = [
+                '# Auto-generated by contractkit-plugin-python-sdk. Do not edit manually.',
+                'from ._base_client import BaseClient, SdkError',
+            ];
+            for (const c of clientInfos) {
+                initLines.push(`from .${c.moduleName} import ${c.className}`);
+            }
+            initLines.push('');
+            initLines.push('');
+            if (clientInfos.length > 0) {
+                initLines.push(`class ${sdkClassName}(BaseClient):`);
+                initLines.push(`    def __init__(self, base_url: str, headers: dict[str, str] | None = None):`);
+                initLines.push(`        super().__init__(base_url, headers)`);
+                for (const c of clientInfos) {
+                    initLines.push(`        self.${c.propertyName} = ${c.className}(base_url, headers)`);
+                }
+                initLines.push('');
+            } else {
+                initLines.push(`class ${sdkClassName}(BaseClient):`);
+                initLines.push(`    pass`);
+                initLines.push('');
+            }
+
+            const allNames = ['BaseClient', 'SdkError', sdkClassName, ...clientInfos.map(c => c.className)];
+            initLines.push(`__all__ = [${allNames.map(n => JSON.stringify(n)).join(', ')}]`);
+            initLines.push('');
+
+            ctx.emitFile(join(outDir, '__init__.py'), initLines.join('\n'));
+        },
+    };
+}