@voxgig/sdkgen 4.34.0 → 4.34.2

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, targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, targetFeatures, opNeedsAction, bodyNote, listMatchArg, entityClassName, entityCollection } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -13,6 +13,7 @@ import {
 // test. Strings render the quoted placeholder.
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -21,37 +22,36 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl=None) -> dict',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: 'load(reqmatch, ctrl=None) -> EntyClass',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, and raises on error.',
   },
   list: {
-    sig: 'list(reqmatch=None, ctrl=None) -> list',
-    returns: 'a list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list and raises on error.',
+    sig: 'list(reqmatch=None, ctrl=None) -> list[EntyClass]',
+    returns: 'a list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl=None) -> dict',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    sig: 'create(reqdata, ctrl=None) -> EntyClass',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
-    sig: 'update(reqdata, ctrl=None) -> dict',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    sig: 'update(reqdata, ctrl=None) -> EntyClass',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl=None) -> EntyClass',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and raises on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl=None) -> dict',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: 'remove(reqmatch, ctrl=None) -> EntyClass',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -216,7 +216,7 @@ ${eVar} = client.${ent.Name}()
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -250,12 +250,16 @@ ${eVar} = client.${ent.Name}()
           const info = OP_SIGNATURES[opname]
           if (!info) return
 
-          Content(`#### \`${info.sig}\`
+          Content(`#### \`${info.sig.replace('EntyClass', entityClassName(ent, entityCollection(model)))}\`
 
 ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           // Show example. Entity ops return the ENTITY and raise on
           // error; direct() is the only method that returns a result dict.
           if ('load' === opname || 'remove' === opname) {
@@ -279,9 +283,9 @@ result = client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`python
-results = client.${ent.Name}().list(${listMatchArg(ent)})
+results = client.${ent.Name}().list(${listMatchArg('py', ent)})
 for ${eVar} in results:
-    print(${eVar})
+    print(${eVar}.data_get())
 \`\`\`
 
 `)
@@ -306,10 +310,10 @@ result = client.${ent.Name}().create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -317,13 +321,21 @@ result = client.${ent.Name}().create({
               `    "${it.name}": ${pyLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`python
-result = client.${ent.Name}().update({
-${updateLines}    # Fields to update
+result = client.${ent.Name}().${opname}({
+${updateLines}    # ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 })
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: '`bytes`, `bytearray`, `memoryview`, a `str` or a file object',
+              once: 'a file object',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 
@@ -400,8 +412,6 @@ client = ${model.const.Name}SDK({
 })
 
 
-
-
 export {
   ReadmeRef
 }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,6 +14,7 @@ import {
 // would break it).
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -22,12 +23,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -68,10 +63,10 @@ client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s (returns a list, raises on error)
-${eVar}s = client.${eName}().list(${listMatchArg(exampleEntity)})
+      Content(`# List all ${eName.toLowerCase()}s (a list of entities, one per record; raises on error)
+${eVar}s = client.${eName}().list(${listMatchArg('py', exampleEntity)})
 for ${eVar} in ${eVar}s:
-    print(${eVar})
+    print(${eVar}.data_get())
 `)
       hasCall = true
     }
@@ -87,9 +82,9 @@ for ${eVar} in ${eVar}s:
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
         : ''
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+# Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
 ${eVar} = client.${eName}().load(${loadArg})
-print(${eVar})
+print(${eVar}.data_get())
 `)
       hasCall = true
     }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Python literal for a field's canonical type.
 function pyLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -37,30 +38,30 @@ client = ${model.const.Name}SDK.test()
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's Match type, so the block also satisfies the mypy doc gate.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `{${items.map((it: any) =>
-          `"${it.name}": ${it.name === idF ? '"test01"' : pyLit(it.type)}`).join(', ')}}`
+          litPair('py', it.name, isMatchOp && it.name === idF ? '"test01"' : pyLit(it.type))).join(', ')}}`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `{${chosen.map((it: any) => `"${it.name}": ${pyLit(it.type)}`).join(', ')}}`
+      arg = `{${chosen.map((it: any) => litPair('py', it.name, pyLit(it.type))).join(', ')}}`
     }
     // A list() result is a list — name the variable accordingly (the root
     // README doc gate concatenates blocks, so reusing the singular name for
     // a different type is a mypy assignment error).
     const eVar = exampleVarName(eName.toLowerCase(), 'py') + ('list' === primaryOp ? 's' : '')
     Content(`${eVar} = client.${eName}().${primaryOp}(${arg})
-print(${eVar})
+print(${'list' === primaryOp ? '[item.data_get() for item in ' + eVar + ']' : eVar + '.data_get()'})
 `)
   }
 

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

@@ -188,7 +188,23 @@ SCENARIOS = [
 ]
 
 
-def _make_sdk(respond, sinks, cleanopts=None, extra=None):
+# Offline, as every generated suite is: the test OPTION resolves a required
+# server variable to test-<name>, and installs no transport.
+def _offline(opts):
+    return dict(opts, test={"active": True})
+
+
+# A client the sweep cannot build leaves nothing swept: a harness error, not a leak.
+def _construct(opts):
+    try:
+        return ${Name}SDK(_offline(opts))
+    except Exception as e:
+        raise RuntimeError(
+            "clean harness: the client could not be constructed, so nothing was swept: "
+            + str(e)) from e
+
+
+def _make_sdk(respond, sinks, cleanopts=None, extra=None, auth=None):
     def capture(name):
         return lambda rec, *a: sinks.extend(_forms(name, rec))
 
@@ -214,7 +230,7 @@ def _make_sdk(respond, sinks, cleanopts=None, extra=None):
     clean = {"values": CANARY["value"]}
     clean.update(cleanopts or {})
 
-    return ${Name}SDK({
+    opts = {
         "apikey": CANARY["apikey"],
         "secret": CANARY["secret"],
         "headers": {"X-Custom-Token": CANARY["header"]},
@@ -222,14 +238,17 @@ def _make_sdk(respond, sinks, cleanopts=None, extra=None):
         "feature": feature,
         "extend": [_CaptureFeature(sinks)] + list(extra or []),
         "utility": {"fetcher": lambda ctx, url, fetchdef: respond(url, fetchdef)},
-    })
+    }
+    if auth is not None:
+        opts["auth"] = auth
+    return _construct(opts)
 
 
 # The first operation that completes against a plain 200: with no
 # arguments, else with every path parameter its points declare filled in.
 def _usable_op():
     def plain():
-        return ${Name}SDK({
+        return _construct({
             "apikey": CANARY["apikey"],
             "utility": {"fetcher": lambda ctx, url, fetchdef: (_response(200, {"id": "i1"}), None)},
         })
@@ -257,7 +276,7 @@ def _usable_op():
     safe = {"list": 0, "load": 1}
     for name in sorted(found):
         accessor, ent = found[name]
-        ops = [op for op in ["list", "load", "create", "update", "remove"]
+        ops = [op for op in ["list", "load", "create", "update", "patch", "remove"]
                if callable(getattr(ent, op, None))]
         ops.sort(key=lambda o: safe.get(o, 2))
         opdefs = (entities.get(name) or {}).get("op") or {}
@@ -338,16 +357,19 @@ class _StreamOkFeature(${Name}BaseFeature):
 def _drive(sdk, target, ctrl, sinks):
     # A caller may keep the record it passed rather than read ctrl["explain"].
     held = ctrl.get("explain")
+    entity = getattr(sdk, target[0])()
     out = None
     err = None
     try:
-        out = getattr(getattr(sdk, target[0])(), target[1])(dict(target[2]), ctrl)
+        out = getattr(entity, target[1])(dict(target[2]), ctrl)
     except Exception as e:
         err = e
     if err is not None:
         sinks.extend(_forms("error", err))
     if out is not None:
         sinks.extend(_forms("result", out))
+    # Raw, as a caller copying the match into another query reads it.
+    sinks.extend(_forms("match", entity.match_get()))
     if ctrl.get("explain") is not None:
         sinks.extend(_forms("explain", ctrl["explain"]))
     if held is not None and held is not ctrl.get("explain"):
@@ -383,11 +405,16 @@ class TestClean:
                 sinks.extend(_forms("sdk", sdk))
                 sinks.append(("sdk:vars", json.dumps(vars(sdk), default=repr)))
 
+        # A name given at run time replaces the declared one: the match
+        # leaves out whichever name prepare_auth placed.
+        _drive(_make_sdk(SCENARIOS[0][1], sinks, auth={"name": "zzcred"}), target, {}, sinks)
+
         # A credential mistyped as a map is rejected by validation, whose
         # message quotes the value it rejected.
         rejected = None
         try:
-            ${Name}SDK({"apikey": {"value": CANARY["apikey"]}, "clean": {"values": CANARY["value"]}})
+            ${Name}SDK(_offline(
+                {"apikey": {"value": CANARY["apikey"]}, "clean": {"values": CANARY["value"]}}))
         except Exception as e:
             rejected = e
         assert rejected is not None, "a credential mistyped as a map should be rejected"
@@ -453,7 +480,7 @@ class TestClean:
         assert cfgclean == {"keys": "zzsens", "values": CANARY["config"]}, cfgclean
 
         # With no clean option at all, the schema defaults still apply.
-        bare = ${Name}SDK({
+        bare = _construct({
             "apikey": CANARY["apikey"],
             "secret": CANARY["secret"],
             "headers": {"X-Custom-Token": CANARY["header"]},
@@ -463,12 +490,14 @@ class TestClean:
 
         # A feature's name is not a field name: only the sensitive names
         # inside its settings register. An entity block, of per-entity
-        # settings or seeded records keyed by entity name and id, is not read.
-        featured = ${Name}SDK({
+        # settings or seeded records keyed by entity name and id, is not read,
+        # and nor are rbac's rules, keyed by entity and operation names.
+        featured = _construct({
             "apikey": CANARY["apikey"],
             "feature": {
                 "zzsecrets": {"active": False, "kind": "PLAINSETTING-q8w2e4r6"},
                 "zzfeat": {"active": False, "apitoken": "FEATTOKEN-z9y8x7w6"},
+                "rbac": {"active": False, "rules": {"zztoken.load": "PLAINRULE-k7j5h3g1"}},
                 "test": {"active": False, "entity": {
                     "zztoken": {"ZZTOKEN01": {"note": "PLAINRECORD-t5r3e1w9"}}}},
             },
@@ -480,6 +509,7 @@ class TestClean:
         ftoken = fclean(froot, "token FEATTOKEN-z9y8x7w6")
         frecord = fclean(froot, "record PLAINRECORD-t5r3e1w9")
         falias = fclean(froot, "alias PLAINALIAS-m2n4b6v8")
+        frule = fclean(froot, "rule PLAINRULE-k7j5h3g1")
 
         leaked = [(name, _leaks(text)) for name, text in sinks]
         leaked = [(name, found) for name, found in leaked if 0 < len(found)]
@@ -513,6 +543,7 @@ class TestClean:
         assert ftoken == "token " + MASK, ftoken
         assert frecord == "record PLAINRECORD-t5r3e1w9", frecord
         assert falias == "alias PLAINALIAS-m2n4b6v8", falias
+        assert frule == "rule PLAINRULE-k7j5h3g1", frule
 
         explained = explains.get("ok/explain") or {}
         assert explained.get("result") is not None, "the explain record should carry the result"