@voxgig/sdkgen 4.21.0 → 4.22.0

package/project/.sdk/src/cmp/php/utility_php.ts

@@ -67,28 +67,6 @@ function formatPhpValue(val: any, indent: number = 0): string {
 }
 
 
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
 // Keys whose value IS the default the runtime already assumes when the key is

package/project/.sdk/src/cmp/py/Config_py.ts

@@ -34,32 +34,11 @@ import {
 } from './utility_py'
 
 
-// PLUGIN DEFINITION IMPORTS AND THE FEATURE_PLUGINS MAP (mirrors
-// cmp/ts/Config_ts.ts).
-//
-// Upstream sekreto replaced its self-registration registry with
-// voxgig/plugin definitions: a provider kind the caller did not pass in
-// via `plugins: [...]` is unknown to that Sekreto. So config imports each
-// active plugin's exported definition BY NAME (the model's `def.py` map)
-// and hands the list to the feature through FEATURE_PLUGINS.
-//
-// The `def` map is declared in the model rather than derived from
-// filenames because one module may export several definitions (sekreto's
-// aws.py exports awssecrets AND awsparams). A def value is the module's
-// path under tm/py ('pkg/feature/.../aws.py'); Main copies tm/py/pkg INTO
-// the <name>_sdk package, so the import module is the path with `pkg/`
-// swapped for the package name and slashes for dots.
 function pluginImports(feature: any, pkg: string) {
   each(feature, (f: any) => {
-    // path -> [symbol, ...], so one import line serves a two-definition
-    // module.
     const bypath: Record<string, string[]> = {}
 
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object
-      // to arrive filtered: getting it wrong in this direction emits an
-      // import for a module the plugin trim just deleted - an SDK that
-      // does not import, rather than one that merely carries too much.
       if (false === plugin.active || null == plugin.active) return
 
       for (const [sym, one] of Object.entries(plugin.def?.py || {})) {
@@ -76,8 +55,6 @@ function pluginImports(feature: any, pkg: string) {
   })
 }
 
-// The FEATURE_PLUGINS entries: one line per feature that has any active
-// plugin definitions, listing the imported symbols.
 function pluginDefs(feature: any) {
   each(feature, (f: any) => {
     const syms: string[] = []
@@ -99,15 +76,11 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
   const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
   // `in` and `name` travel with the prefix now. They were resolved by
   // apidef all along and dropped here, so an apiKey-in-query API got an
@@ -120,8 +93,6 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see make_options).
   const svars = serverVariables(model)
   const serverBlock = 0 === svars.length ? '' :
     '            "server": {\n' +
@@ -136,12 +107,6 @@ const Config = cmp(async function Config(props: any) {
             },\n`
     : ''
 
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not. Passing the
-  // target name opts in to the main.slug/version/target identity fields -
-  // the literal path below emits them too, keeping the two reps in step.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -193,20 +158,6 @@ def shared_config():
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // A dict literal makes CPython build the whole structure opcode by opcode
-    // at import, and the compiler hold the entire literal in memory to produce
-    // that bytecode. A string constant is one object, and `json.loads` (the C
-    // scanner) builds the dict far faster than the equivalent literal.
-    //
-    // `json.loads` yields exactly what the literal did - str keys, int for
-    // whole numbers, True/False/None - so make_config's result is unchanged.
-    //
-    // JSON.stringify output is a valid Python string literal: every escape it
-    // emits (\\", \\\\, \\n, \\uXXXX) means the same thing in Python, it never emits
-    // \\/ (which Python would not treat as an escape), and Python 3 source is
-    // UTF-8 so non-ASCII needs no escaping.
     if (asData) {
       Content(`# THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
 #
@@ -227,10 +178,6 @@ def make_config():
       return
     }
 
-    // Identity values from configDefinition's def, not re-derived here, so
-    // the literal rep and the data rep cannot disagree on identity (the
-    // slug is CARRIED, never derived from the camel name - station's
-    // descriptor reads all three; see cmp/ts/Config_ts.ts #MainMeta).
     Content(`def make_config():
     """Build a fresh, fully materialised config dict.
 

package/project/.sdk/src/cmp/py/EntityTypes_py.ts

@@ -1,35 +1,5 @@
 
 
-// Typed-model generator (Python target). Port of EntityTypes_ts.ts.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one module, <sdk>_types.py,
-// with a `class <Name>(TypedDict):` per active entity plus a request/match type
-// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
-// real Python types by the shared sdkgen helper `canonToType` (source of truth:
-// @voxgig/apidef VALID_CANON).
-//
-// TYPE CHOICE: `TypedDict`, not `@dataclass`. The generated ops return/accept
-// plain runtime dicts (data_get/match_get return `vs.clone(self._data)`; ops
-// take/return dicts), so a `@dataclass` annotation is only aspirational — a
-// strict checker at a call site would see dict-vs-dataclass. A TypedDict *is* a
-// dict shape, so annotating these dict-returning/-accepting ops with TypedDict
-// makes the TYPES MATCH the runtime. Runtime behaviour is unchanged.
-//
-// OPTIONAL FIELDS: a `req:false` field/param is a key that MAY be absent, which
-// is exactly TypedDict `total=False` (key optionality), not `Optional[T]` (a
-// None value). To express required AND optional keys on py>=3.8 WITHOUT a
-// typing_extensions dependency (no `NotRequired`), a type with both splits into
-// a required base `class <Name>Required(TypedDict): ...` and a `total=False`
-// subclass `class <Name>(<Name>Required, total=False): ...` that carries the
-// public name and adds the optional keys. Degenerate shapes collapse to a
-// single class (all-required, all-optional, or empty). The all-optional
-// collapse also serves the match-mirror types (the Python analogue of TS
-// `Partial<${Name}>`).
-//
-// Keep the SAME type-name scheme as every other language: <Name>,
-// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
-// <Name>RemoveMatch.
 
 import {
   cmp, each, names,
@@ -56,25 +26,11 @@ const PY_KEYWORDS = new Set([
 ])
 
 
-// A name usable as a class-syntax TypedDict key (valid identifier, not a
-// keyword). Non-identifier/keyword field names have no safe class-syntax
-// rendering, so they are skipped (they remain reachable via the runtime dict).
 function pyIdent(name: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name)
 }
 
 
-// Emit a TypedDict named `typeName` from a list of {name, type, optional}
-// items (optionality already decided by the caller — the shared partiality
-// policy for op types, or `req` for the entity data type). Required items
-// become required keys; optional items become not-required keys via a
-// `total=False` extension.
-//
-// Shape selection (see file header for the rationale):
-//   both required + optional -> `<typeName>Required` base + `total=False` sub
-//   only required            -> single `class <typeName>(TypedDict):`
-//   only optional            -> single `class <typeName>(TypedDict, total=False):`
-//   no usable keys           -> single `class <typeName>(TypedDict): pass`
 function emitTypedDict(typeName: string, items: any[], log?: any): void {
   const usable = items.filter((it: any) => it && null != it.name && pyIdent(it.name))
 
@@ -132,10 +88,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const target = props.target || {}
   const ext = target.ext || LANG
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // collection, so inactive entities still get generated entity code that
-  // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
   // Emit for EVERY entity that gets generated entity code: the consumer
   // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
@@ -147,9 +99,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   File({ name: model.const.Name.toLowerCase() + '_types.' + ext }, () => {
@@ -177,7 +126,6 @@ from typing import TypedDict, Any
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.active !== false)
 
-      // Entity data model: one key per field, `req:false` -> optional key.
       Content(`
 
 `)
@@ -185,9 +133,6 @@ from typing import TypedDict, Any
         name: f.name, type: f.type, optional: false === f.req,
       })), log)
 
-      // Per active op: a request/match type. Members and their optionality come
-      // from the shared partiality policy (opRequestShape); this file only
-      // renders them as a TypedDict.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {

package/project/.sdk/src/cmp/py/Entity_py.ts

@@ -19,10 +19,6 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
-  // Collision-free entity CLASS name (see entityClassName): normally
-  // `<Name>Entity`, disambiguated when it would clash with another entity's
-  // data-type name. The DATA type stays `<Name>`. The snake-cased source-file
-  // name is unaffected; only the class identifier changes.
   const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
@@ -32,8 +28,6 @@ const Entity = cmp(function Entity(props: any) {
 
   names(entrep, entity.Name, 'EntityName')
 
-  // Import exactly the typed models this entity references: its data type plus
-  // one request type per ACTIVE op (matches what EntityTypes_py.ts emits).
   const typeNames = [entity.Name]
   const opnamesAll = Object.keys(entity.op || {})
   ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
@@ -41,8 +35,6 @@ const Entity = cmp(function Entity(props: any) {
       typeNames.push(opTypeName(entity.Name, opname))
     }
   })
-  // The generated dataclasses live inside the SDK package alongside
-  // everything else, so the import is package-qualified.
   const typesModule = model.const.Name.toLowerCase() + '_sdk.' +
     model.const.Name.toLowerCase() + '_types'
   const typeImport =
@@ -51,9 +43,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/py/fragment/')
 
-  // Entity files go to <name>_sdk/entity/ — inside the SDK package, not at
-  // the language root. See the note in Main_py.ts: a top-level `entity`
-  // package is shadowable by any entity.py sitting beside the caller.
   Folder({ name: model.const.Name.toLowerCase() + '_sdk' }, () => {
   Folder({ name: 'entity' }, () => {
 
@@ -77,13 +66,8 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.py so the class can be renamed independently.
           EntyClass: cls,
 
-          // Literal-marker slot (jostraca's `#Name` tag pattern is hardcoded to
-          // `//` comments, so Python uses a `# #`-prefixed literal like the op
-          // frag slots) — fills in the typed-model import for this entity.
           '# #TypeImports': typeImport,
 
           // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -42,20 +42,14 @@ const Main = cmp(async function Main(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // Does the secrets feature apply here and is it switched on? Both, since
-  // targetFeatures already dropped it for a target with no sekreto port.
   const secrets = null != (feature as any).secrets
 
-  // The one package directory everything the SDK owns lives in.
   const pkgdir = model.const.Name.toLowerCase() + '_sdk'
 
   Package({ target })
 
   Gitignore({})
 
-  // Root-level statics only (Makefile, LICENSE, test/). The runtime
-  // packages live under tm/py/pkg and are copied INSIDE the SDK package
-  // below.
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, /pkg\//, TEST_CONTROL_EXCLUDE],
@@ -64,35 +58,16 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // Everything the SDK owns lives inside ONE package directory.
-  //
-  // core/, entity/, feature/ and utility/ used to sit at the language root
-  // as top-level importable names. `core`, `entity` and `utility` are all
-  // real PyPI distributions AND common scratch filenames, and Python puts
-  // the working directory first on sys.path — so a single utility.py beside
-  // a notebook shadowed ours and the SDK died on
-  // `No module named 'utility.voxgig_struct'`. Nesting them behind the
-  // model-named package makes that impossible.
-  //
-  // The public import is unchanged: `from <name>_sdk import <Name>SDK`,
-  // because <name>_sdk.py becomes <name>_sdk/__init__.py.
   Folder({ name: pkgdir }, () => {
 
   Copy({
     from: 'tm/' + target.name + '/pkg',
-    // An ACTIVE feature's INACTIVE plugins do not ship. py has no
-    // src/feature layout (srcfeature: false), so this blanket pkg copy is
-    // the one place the generate-time plugin trim can act; the model's
-    // `plugin.<group>.path` entries name their files relative to THIS
-    // copy's root ('feature/secrets/voxgig_sekreto/plugins/<kind>.py').
-    // See helpers/featureSource.pluginExcludes.
     exclude: [...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
-  // Generate main SDK file
   File({ name: '__init__.' + target.ext }, () => {
 
     Fragment(
@@ -101,22 +76,7 @@ const Main = cmp(async function Main(props: any) {
         replace: {
           ...props.ctx$.stdrep,
 
-          // SECRETS. Both slots are emitted only when the secrets feature
-          // applies to this target AND the model activates it - an
-          // unconditional edit would land in every generated SDK, and with
-          // the feature off the marker line is REMOVED, so the inactive
-          // output is byte-identical to pre-migration. `feature` is
-          // already gated by targetFeatures, so a target that does not
-          // provide 'sekreto' never reaches these.
-          //
-          // CUSTOM-REGEX keys, like Entity_py's hook markers: jostraca's
-          // built-in `#Name` tag pattern is hardcoded to `//` comments,
-          // so a bare '#SecretsAccessor' key would silently never match a
-          // python `# #SecretsAccessor` marker line.
-
-          // The LIVE Sekreto, not a clone: sekreto holds provider and
-          // cache state, so a clone would resolve into a copy that
-          // prepare_auth never sees.
+
           '/(?<indent>[ \\t]*)#[ \\t]*#SecretsAccessor[ \\t]*\\n?/':
             ({ indent }: any) => !secrets ? '' :
               `${indent}def secrets(self):\n` +
@@ -148,7 +108,6 @@ self._utility.feature_hook(self._rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -177,7 +136,6 @@ if TYPE_CHECKING:
     }
   })
 
-  // Generate the typed-model module (<sdk>_types.py) next to the main SDK file.
   EntityTypes({ target })
 
   // PEP 561 marker so the inline type hints ship to consumers. Emitted at the
@@ -187,24 +145,13 @@ if TYPE_CHECKING:
     Content(``)
   })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
     Schema({ target })
   })
 
-  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
-  // API, and tm/ can only hold one answer. The blanket tm/py/pkg copy above
-  // no longer brings a prepare_auth.py in - it was deleted, since both
-  // writers would claim the same output path. See PrepareAuth_py.
-  //
-  // Called HERE, inside the <name>_sdk package folder and outside any
-  // other, because that is where the deleted template's own path
-  // (tm/py/pkg/utility/prepare_auth.py) put it: the component opens the one
-  // remaining segment, `utility`, itself.
   PrepareAuth({ target })
 
-  // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`# ${model.const.Name} SDK feature factory
 
@@ -252,11 +199,6 @@ def _has_feature(name):
 `)
   })
 
-  // Generate __init__.py files for sub-packages.
-  // NOTE: deliberately omit __init__.py at the language-root (py/) level —
-  // making py/ a package collides with the third-party `py` module on PyPI
-  // (a single-file `py.py`), which causes pytest to construct test module
-  // paths as `py.test.<file>` and fail with "'py' is not a package".
   Folder({ name: 'core' }, () => {
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
@@ -267,8 +209,6 @@ def _has_feature(name):
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
     })
-    // PEP 561 marker inside the type-bearing package so setuptools package-data
-    // ("*" = ["py.typed"]) bundles it into the wheel.
     File({ name: 'py.typed' }, () => {
       Content(``)
     })

package/project/.sdk/src/cmp/py/Package_py.ts

@@ -22,9 +22,6 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
-  // PyPI distribution name is namespaced to model.origin (e.g. "voxgig-sdk").
-  // PyPI names can't contain "/", so the parts are hyphen-joined. The import
-  // package (the `${model.name}_sdk/` dir) is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const distName = packageName(model, target.name)

package/project/.sdk/src/cmp/py/PrepareAuth_py.ts

@@ -17,51 +17,19 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The py port of cmp/ts/PrepareAuth_ts.ts; see that
-// file for the full account.
-//
-// This was a static file at `tm/py/pkg/utility/prepare_auth.py` that
-// hardcoded a lowercase `authorization` header. apidef has always resolved
-// the scheme's `in` and `name` into `main.kit.info.security` — joplin's
-// says `in: "query", name: "token"` — and generation dropped both, so the
-// SDK sent a header the API does not read and never sent the query
-// parameter it does.
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  // FOLDER NESTING. Main_py already opened the ONE package folder
-  // (`<name>_sdk`) that everything the SDK owns lives in, and the blanket
-  // `Copy({from: 'tm/py/pkg'})` that used to bring this file in runs inside
-  // that same folder — which is why the template's own path,
-  // `tm/py/pkg/utility/prepare_auth.py`, lands at
-  // `<name>_sdk/utility/prepare_auth.py`. So this component opens exactly
-  // ONE segment, `utility`, to reproduce that path. Opening `<name>_sdk`
-  // again would write to `<name>_sdk/<name>_sdk/utility/`, which nothing
-  // imports, while register.py kept importing the stale copy.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({
-        // The generated package name, spelled the way Config_py spells it.
-        // A Copy applies ctx$.stdrep to the file it copies; Content does
-        // not, so the `projectname_sdk` placeholder the template carried
-        // has to be resolved here.
         pkg: model.const.Name.toLowerCase() + '_sdk',
         Name: model.const.Name,
         active: isAuthActive_py(model),
         where: resolveAuthIn(model),
         name: resolveAuthName(model),
         basic: isHttpBasicAuth(model),
-        // Read so the resolution is visible at generation time even though
-        // the emitted code takes the prefix from options at runtime (the
-        // secrets feature rewrites it there).
         prefix: resolveAuthPrefix(model),
       }))
     })
@@ -113,10 +81,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// HEADER. Byte-for-byte the old template when the scheme resolves to the
-// defaults (header / Authorization), so every header-based SDK regenerates
-// unchanged — only the constant's VALUE moves with the model, plus the
-// HTTP Basic block, which is emitted only for a basic scheme.
 function renderHeader(spec: AuthSpec, head: string): string {
   return head + (spec.basic ? `import base64
 ` : '') + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
@@ -211,8 +175,6 @@ function basicBlock(spec: AuthSpec): string {
 }
 
 
-// QUERY. The credential is a query parameter, so it goes in spec.query and
-// the headers are never touched.
 function renderQuery(spec: AuthSpec, head: string): string {
   return head + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
 
@@ -257,9 +219,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// COOKIE. A cookie IS a header, so the credential rides the header bag -
-// but the `cookie` header is SHARED with whatever cookies the caller set,
-// so the pair is spliced in and out rather than the header assigned over.
 function renderCookie(spec: AuthSpec, head: string): string {
   return head + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
 
@@ -339,28 +298,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is
-// false whenever the SPEC declares no security scheme (`main.kit.info.auth:
-// false`) — which is a statement about the DEFINITION, not a ban on ever
-// sending a credential. apidef writes it for every spec with no
-// securitySchemes block, GitHub's official OpenAPI included, and those SDKs
-// are still expected to honour an `apikey` the caller passes; the old
-// template placed the credential unconditionally, so they did.
-//
-// Gating the body on `isAuthActive` therefore does not just trim dead code,
-// it removes working authentication from every such SDK. The generated
-// suite catches it: generatedcompile's `py: auth null beats an explicit
-// apikey` lane generates against a fixture that declares
-// `main: kit: info: { ... auth: false }` and then requires
-// `wire({apikey: 'OPTKEY01'})` to reach the transport as an authorization
-// header. With the wider gate it reports
-//
-//   FAIL: baseline broken: an ordinary apikey was not sent:
-//         {'called': True, 'had': False, 'val': None}
-//
-// So the no-op is emitted only when the PROJECT says so — `config.auth.active:
-// false`, an explicit per-SDK switch nobody sets by accident. A spec that is
-// merely silent keeps the credential path it has always had.
 function isAuthActive_py(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -368,12 +305,6 @@ function isAuthActive_py(model: any): boolean {
 }
 
 
-// HTTP header names are case-insensitive, and the whole py runtime spells
-// them lowercase - the debug feature's redact list, the secrets feature's
-// in-place rewrite of `fetchdef["headers"]["authorization"]`, and the
-// generated tests all match on the lowercase key. Lowercasing here keeps
-// the default byte-identical to the old template AND keeps a custom header
-// name (`X-API-Key`) findable by all of them.
 function headerName(name: string): string {
   return String(name).toLowerCase()
 }

package/project/.sdk/src/cmp/py/ReadmeEntity_py.ts

@@ -7,11 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct, JSON-serialisable Python literal for a field's canonical
-// type. The create example is EXECUTED by the doc test (the body is
-// JSON-serialised), so an Ellipsis (`...`) placeholder would raise
-// "Object of type ellipsis is not JSON serializable" — use a real value.
-// Strings render the quoted placeholder.
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -22,14 +17,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// Operation method spelling differs between Go and other languages — Go
-// uses PascalCase methods with explicit ctrl arg, others use lowercase
-// methods with optional ctrl. The op descriptions are language-agnostic.
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))

package/project/.sdk/src/cmp/py/ReadmeExamplesTest_py.ts

@@ -8,37 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits py/test/test_readme_examples.py — a pytest COMPLETENESS GATE over
-// every ```python fenced block in the repository ROOT README.md, in the
-// per-language py/README.md, AND in the per-language py/REFERENCE.md.
-//
-// The gate GUARANTEES every documented python example is unit-tested. For each
-// of the three docs it:
-//   1. extracts every ```python block (tagged by source doc + index);
-//   2. ast.parse + compile()s EVERY block                 -> SYNTAX gate;
-//   3. EXECUTEs every RUNNABLE block (one that constructs the SDK, or drives a
-//      `client`/`sdk` the narrative built earlier) in a seeded, offline
-//      TEST-mode subprocess. A PROGRAMMING error
-//      (Name/Attribute/Type/Key/Index/Import/Syntax) FAILS; ONLY a
-//      not-found/404 domain error is tolerated. Any other error also FAILS;
-//   4. asserts COMPLETENESS: it partitions every block into exactly one of
-//      {executed, compiled-nonrunnable, illustration} and asserts
-//      total == executed + compiled + illustration. "illustration" is a NARROW
-//      explicit class (a non-runnable block that is only imports / signature
-//      stubs / bare references / literal assignments — a pure signature/table
-//      snippet) and can NEVER absorb a runnable example. A block that looks
-//      runnable (references the SDK/client) but was not executed FAILS the
-//      test; a block that fails to compile FAILS the test. A per-doc summary
-//      (total/executed/compiled/illustration) is printed.
-//
-// If mypy is importable it also type-checks the concatenated ROOT README blocks
-// (the SDK ships py.typed + TypedDicts) — a bonus TYPE gate over the primary
-// EXECUTE gate.
-//
-// The emitted Python is written WITHOUT backticks or backslashes (chr(96) is
-// the fence marker, chr(10) is newline) so this TS template literal stays
-// clean — the only interpolations are the SDK module/class names and the
-// generated entity map.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -8,7 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Python literal for a field's canonical type.
 function pyLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -31,8 +30,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // Sanitise the local variable name — an entity whose lowercased name is a
   // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
   const eVar = exampleVarName(eName.toLowerCase(), 'py')
-  // Model-driven id key: null when the entity has no id-like field, so a
-  // match op takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = ''