@voxgig/sdkgen 4.20.0 → 4.22.0

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/ReadmeExplanation_py.ts

@@ -20,6 +20,7 @@ Use \`helpers.to_map()\` to safely validate that a value is a dict.
 py/
 ├── ${model.const.Name.toLowerCase()}_sdk.py         -- Main SDK module
 ├── config.py                    -- Configuration
+├── schema.py                    -- Generated option + entity specs
 ├── features.py                  -- Feature factory
 ├── core/                        -- Core types and context
 ├── entity/                      -- Entity implementations

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 = ''

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

@@ -8,11 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// 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))
@@ -26,9 +21,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -39,10 +31,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
-  // Server variables (a templated server URL) are REQUIRED at construction
-  // - the SDK refuses rather than request a URL with a literal
-  // {account_id} in it - so a quickstart that omits them is a quickstart
-  // that fails on its first line.
   const svars = serverVariables(model)
   const pyServerField = 0 === svars.length ? '' :
     `\n    "server": {` +
@@ -117,9 +105,6 @@ except Exception as err:
       const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
       const neVar = exampleVarName(neName.toLowerCase(), 'py')
 
-      // Model-driven match: every REQUIRED load-match key — the same shape
-      // the runtime resolves path params from, so the example always works.
-      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
         .filter((it: any) => !it.optional)
@@ -148,9 +133,6 @@ except Exception as err:
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -176,20 +158,12 @@ except Exception as err:
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Python-typed by
-    // the field's canonical type. ids are rendered separately as the match key
-    // for update/remove; a REQUIRED create id stays (the call is invalid
-    // without it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
@@ -227,8 +201,6 @@ client.${eName}().update({${updatePairs.join(', ')}})
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -21,11 +21,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// 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))
@@ -66,7 +61,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -129,7 +124,6 @@ client = ${model.const.Name}SDK.test()
 `)
 
 
-    // Entity factory methods
     publishedEntities.map((ent: any) => {
       Content(`#### \`${ent.Name}(data=None)\`
 
@@ -171,7 +165,6 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
 `)
 
 
-    // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
@@ -202,7 +195,6 @@ ${eVar} = client.${ent.Name}()
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -249,7 +241,6 @@ ${eVar} = client.${ent.Name}()
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -337,7 +328,6 @@ ${updateLines}    # Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get() -> dict\`
@@ -368,7 +358,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -404,9 +393,6 @@ client = ${model.const.Name}SDK({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

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

@@ -22,11 +22,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// 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))
@@ -42,10 +37,6 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
-  // Server variables (a templated server URL) are REQUIRED at construction
-  // - the SDK refuses rather than request a URL with a literal
-  // {account_id} in it - so a quickstart that omits them is a quickstart
-  // that fails on its first line.
   const svars = serverVariables(model)
   const pyServerField = 0 === svars.length ? '' :
     `\n    "server": {` +
@@ -72,8 +63,6 @@ client = ${ctor}
     // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'py')
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes no match argument.
     const idF = entityIdField(exampleEntity)
 
     let hasCall = false
@@ -88,9 +77,6 @@ for ${eVar} in ${eVar}s:
     }
 
     if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

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

@@ -0,0 +1,53 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`# ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+#
+# Generated from the model: \`main.kit.optspec\` and each feature's
+# \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+_OPTSPEC_DATA = ${JSON.stringify(JSON.stringify(optspec))}
+
+_ENTITYSPEC_DATA = ${JSON.stringify(JSON.stringify(entityspec))}
+
+# Parsed ONCE, at import. The spec is read on every client construction and
+# never mutated, so a per-call parse would be pure waste — and sharing the
+# dict is safe for the same reason: make_options validates AGAINST it and
+# writes into the options, never into the spec.
+OPTSPEC: Dict[str, Any] = json.loads(_OPTSPEC_DATA)
+
+ENTITYSPEC: Dict[str, Any] = json.loads(_ENTITYSPEC_DATA)
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -127,8 +127,6 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const listPath = listPoint ? normalizePathParams(pointParts(listPoint), listPoint?.args?.params || [], listPoint?.rename?.param) : ''
   const listParams = listPoint?.args?.params || []
 
-  // Required query params with spec-provided examples — needed in live mode
-  // to satisfy API contracts (e.g. /v2018/history requires city/start/end).
   const loadQuery = loadPoint?.args?.query || []
   const loadLiveQueryEntries = loadQuery
     .filter((q: any) => q.reqd && undefined !== q.example && null !== q.example)

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

@@ -66,28 +66,6 @@ function formatPyValue(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-data/Main_py-data.ts

@@ -14,26 +14,8 @@ import {
 } from '@voxgig/apidef'
 
 
-// The `py-data` target: a Python package for DATA ANALYSTS working in
-// notebooks (Colab, Jupyter), layered on the sibling `py` SDK generated into
-// the same repo. It is a consumer target in the go-cli / go-mcp mould — every
-// standard generation phase is switched off in model/target/py-data.aon and
-// this component emits the whole package.
-//
-// The deliverable an analyst wants is not "a client", it is TABLES: one line
-// from API to a typed pandas DataFrame, discovered by tab-completion rather
-// than by reading reference docs.
-//
-// Layered, NOT forked from `py`: the dependency arrow points one way
-// (py-data -> py) and `py` must never learn this target exists. A fork would
-// duplicate the entity/feature machinery and drift, which is the known
-// failure mode.
-
-
-// Accessors are generated only for entities exposing these ops. `list` gives
-// a DataFrame; `load` gives a Series. Everything else (create/update/remove)
-// is a write path and deliberately out of scope — see the README's
-// "What this package does not do".
+
+
 const FRAME_OP = 'list'
 const SERIES_OP = 'load'
 
@@ -42,9 +24,6 @@ const Main = cmp(function Main(props: any) {
   const { target, ctx$ } = props
   const { model, log } = ctx$
 
-  // HARD REQUIREMENT: this package imports the sibling py SDK. Generating it
-  // without `py` produces a package whose every import fails at runtime, so
-  // fail at GENERATE time with an actionable message instead.
   const targets = model.main[KIT].target || {}
   if (null == targets.py) {
     throw new SdkGenError(
@@ -54,12 +33,12 @@ const Main = cmp(function Main(props: any) {
       'then regenerate.')
   }
 
-  const name = model.const.Name              // PascalCase, e.g. Univec
-  const lower = String(name).toLowerCase()   // univec
-  const ENV = envName(model)                 // UNIVEC
-  const sdkModule = `${lower}_sdk`           // univec_sdk
-  const sdkClass = `${name}SDK`              // UnivecSDK
-  const dataModule = `${lower}_data`         // univec_data
+  const name = model.const.Name
+  const lower = String(name).toLowerCase()
+  const ENV = envName(model)
+  const sdkModule = `${lower}_sdk`
+  const sdkClass = `${name}SDK`
+  const dataModule = `${lower}_data`
 
   // Multi-tenant APIs (a server URL carrying an unresolved {variable}, e.g.
   // https://{instance}.example.com/api) have no single host, so base_url
@@ -80,25 +59,12 @@ const Main = cmp(function Main(props: any) {
     note: `frames:${frameEnts.length} series:${seriesEnts.length} of ${ents.length}`,
   })
 
-  // Root-level statics: Makefile, LICENSE, the template-side tests.
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, /pkg\//],
     replace: { ...ctx$.stdrep },
   })
 
-  // The runtime modules live INSIDE the package, not at the top level.
-  //
-  // They were originally emitted flat as auth.py / fetch.py / frames.py, which
-  // is actively dangerous here: `auth`, `fetch`, `frames`, `core`, `entity`
-  // and `utility` are all real PyPI distributions AND exactly the names an
-  // analyst leaves lying around next to a notebook. In Colab the working
-  // directory is on sys.path, so one stray auth.py shadowed ours and `data()`
-  // died with `module 'auth' has no attribute 'resolve'`. A package keeps
-  // every internal module behind the distinctive `<name>_data.` prefix.
-  //
-  // The folder name is model-derived, so it comes from the component; the file
-  // contents are the same for every API, so they stay in tm/py-data/pkg.
   Folder({ name: dataModule }, () => {
     Copy({
       from: 'tm/' + target.name + '/pkg',
@@ -436,7 +402,7 @@ function fieldDoc(fields: any[], indent: string): string {
 
 function frameAccessor(ent: any): string {
   const acc = pluralAccessor(ent)
-  const entMethod = ent.Name                 // PascalCase SDK accessor
+  const entMethod = ent.Name
   const fields = entFields(ent)
   const dtypes = pyDict(fields.map((f) => [f.name, f.dtype] as [string, string]), '            ')
   const order = pyList(fields.map((f) => f.name), '            ')