vgi-python 0.37.2__py3-none-any.whl → 0.38.0__py3-none-any.whl

vgi/_test_fixtures/attach_options.py

@@ -123,7 +123,7 @@ class RequiredAttachOptions:
 
     # No class-level assignment: there is no default to fall back on, so the
     # caller has to supply it.
-    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+    api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
     region: Annotated[str, AttachOption(desc="Region")] = "us-east-1"
 
 

vgi/catalog/_descriptor_spec.py

@@ -10,7 +10,7 @@ holds the machinery both share; the two public modules subclass it so their
 names and behaviour are unchanged.
 
 A subclass may widen its wire format with additional columns — `AttachOption`
-adds ``required`` — via :meth:`_SpecBase._extra_row` /
+adds ``required`` and ``secret`` — via :meth:`_SpecBase._extra_row` /
 :meth:`_SpecBase._extra_kwargs` and :meth:`_DescriptorBase.extra_spec_kwargs`.
 Because both directions read by column name, the widening is compatible in both
 directions: a reader ignores columns it doesn't know, and a reader whose peer

vgi/catalog/attach_option.py

@@ -9,6 +9,14 @@ from session-level Settings resent on every call).
 The declaration mirrors ``vgi.catalog.setting.Setting`` — same Arrow IPC spec
 format, same Python type → Arrow mapping, same extractor shape — so both share
 the machinery in ``vgi.catalog._descriptor_spec``.
+
+Credential options (API keys, tokens, passwords) MUST be declared
+``secret=True``. Clients and the DuckDB extension then mask the value, keep it
+out of result-cache keys and logs, and can supply it from a ``vgi_attach``
+DuckDB secret instead of the ``ATTACH`` text::
+
+    CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key '...');
+    ATTACH 'mydb' AS mydb (TYPE vgi, LOCATION 'https://worker.example.com');
 """
 
 from dataclasses import dataclass
@@ -42,18 +50,31 @@ class AttachOptionSpec(_SpecBase):
             rather than surfacing a failure that reads like an empty catalog.
             Mutually exclusive with ``default`` — an option that falls back to
             a value is by definition satisfiable without the caller.
-        ARROW_SCHEMA: The shared four columns plus ``required``.
+        secret: The option carries a credential (an API key, token or
+            password). Clients and the DuckDB extension mask its value, keep it
+            out of result-cache keys and logs, and can supply it from a
+            ``vgi_attach`` DuckDB secret
+            (``CREATE SECRET (TYPE vgi_attach, SCOPE '<worker url>', api_key '...')``)
+            rather than the ``ATTACH`` text. Credential options MUST set this.
+            Compatible with ``required``. Allowed alongside a ``default``, but a
+            secret option should normally have none: a default credential is
+            advertised in plain text to every client at discovery.
+        ARROW_SCHEMA: The shared four columns plus ``required`` and ``secret``.
 
     """
 
     required: bool = False
+    secret: bool = False
 
     ARROW_SCHEMA: ClassVar[pa.Schema] = pa.schema(
         [
             *_SpecBase.ARROW_SCHEMA,
-            # Nullable, and appended last: a peer that predates this column
+            # Nullable, and appended after the shared columns: a peer that predates this column
             # reads the batch by name and simply doesn't see it.
             pa.field("required", pa.bool_(), nullable=True),
+            # Same rules as ``required``: nullable, appended after it, and an
+            # absent column reads as False.
+            pa.field("secret", pa.bool_(), nullable=True),
         ]
     )
 
@@ -67,12 +88,16 @@ class AttachOptionSpec(_SpecBase):
             )
 
     def _extra_row(self) -> dict[str, Any]:
-        return {"required": self.required}
+        return {"required": self.required, "secret": self.secret}
 
     @classmethod
     def _extra_kwargs(cls, row: dict[str, object]) -> dict[str, Any]:
-        # Absent column (older peer) and explicit null both mean "not required".
-        return {"required": bool(row.get("required") or False)}
+        # Absent column (older peer) and explicit null both mean "not required"
+        # / "not secret".
+        return {
+            "required": bool(row.get("required") or False),
+            "secret": bool(row.get("secret") or False),
+        }
 
 
 @dataclass
@@ -90,18 +115,26 @@ class AttachOption(_DescriptorBase):
 
         class AttachOptions:
             region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
-            api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+            api_key: Annotated[str, AttachOption(desc="API key", required=True, secret=True)]
+
+    Credential options (API keys, tokens, passwords) MUST be declared
+    ``secret=True``; see `AttachOptionSpec.secret`.
 
     Attributes:
         required: The caller must supply this option at ``ATTACH`` time.
+        secret: The option carries a credential. Clients and the DuckDB
+            extension mask it, keep it out of cache keys and logs, and can
+            supply it from a ``vgi_attach`` DuckDB secret. Should normally have
+            no default.
 
     """
 
     required: bool = False
+    secret: bool = False
 
     def extra_spec_kwargs(self) -> dict[str, Any]:
-        """Carry ``required`` through to the `AttachOptionSpec`."""
-        return {"required": self.required}
+        """Carry ``required`` and ``secret`` through to the `AttachOptionSpec`."""
+        return {"required": self.required, "secret": self.secret}
 
 
 class MissingAttachOptionsError(ValueError):

vgi/http/landing.html

@@ -544,7 +544,8 @@ async function buildCatalog(info){
       name: s.name, type: typeStr(s.type),
       default: s.default == null ? '' : String(s.default),
       description: s.description || '',
-      required: !!s.required
+      required: !!s.required,
+      secret: !!s.secret
     }));
   } catch (e) { /* keep the card; drop unreadable specs */ }
 
@@ -792,7 +793,8 @@ function attachOptionsHtml(c){
     '<table class="opts"><thead><tr><th>Option</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody>'+
     opts.map(o=>'<tr><td class="o-name">'+esc(o.name)+
       (o.required?'<span class="o-req" title="Must be supplied at ATTACH time">required</span>':'')+
-      '</td><td class="o-type">'+esc(o.type)+'</td><td class="o-def">'+esc(o.default||'—')+'</td><td class="o-desc">'+esc(o.description||'')+'</td></tr>').join('')+
+      (o.secret?'<span class="o-req" title="A credential: supply it from a vgi_attach DuckDB secret rather than the ATTACH text">secret</span>':'')+
+      '</td><td class="o-type">'+esc(o.type)+'</td><td class="o-def">'+esc(o.secret&&o.default?'hidden':(o.default||'—'))+'</td><td class="o-desc">'+esc(o.description||'')+'</td></tr>').join('')+
     '</tbody></table></details>';
 }
 function renderConnect(){

vgi/http/worker_page.py

@@ -584,10 +584,24 @@ def _build_attach_options_table(specs: tuple[AttachOptionSpec, ...]) -> str:
         "<table><tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>",
     ]
     for spec in specs:
-        default_str = _esc(repr(spec.default)) if spec.default is not None else "&mdash;"
+        if spec.default is None:
+            default_str = "&mdash;"
+        elif spec.secret:
+            # A credential's default is never echoed back onto the page.
+            default_str = "<em>hidden</em>"
+        else:
+            default_str = _esc(repr(spec.default))
         desc_str = _esc(spec.desc) if spec.desc else "&mdash;"
+        flags = ""
+        if spec.required:
+            flags += ' <span class="o-flag" title="Must be supplied at ATTACH time">required</span>'
+        if spec.secret:
+            flags += (
+                ' <span class="o-flag" title="A credential: supply it from a vgi_attach DuckDB secret '
+                'rather than the ATTACH text">secret</span>'
+            )
         parts.append(
-            f"<tr><td><code>{_esc(spec.name)}</code></td>"
+            f"<tr><td><code>{_esc(spec.name)}</code>{flags}</td>"
             f"<td><code>{_esc(str(spec.type))}</code></td>"
             f"<td>{default_str}</td>"
             f"<td>{desc_str}</td></tr>"
@@ -1230,6 +1244,9 @@ _PAGE_TEMPLATE = (
         font-weight: 600; border-bottom: 2px solid #e0dcd0; }}
   td {{ padding: 8px 10px; border-bottom: 1px solid #f0ece0; }}
   td code {{ font-size: 0.85em; }}
+  .o-flag {{ font-size: 0.7em; font-weight: 600; text-transform: uppercase; margin-left: 4px;
+             padding: 1px 5px; border-radius: 4px; background: #fdf0e3; color: #8a4b08;
+             border: 1px solid #f0d5b4; }}
   .no-params {{ color: #6b6b5a; font-style: italic; font-size: 0.9em; }}
   .section-label {{ font-size: 0.8em; font-weight: 600; text-transform: uppercase;
                     letter-spacing: 0.05em; color: #6b6b5a; margin-top: 14px;

{vgi_python-0.37.2.dist-info → vgi_python-0.38.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.37.2
+Version: 0.38.0
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python
@@ -158,11 +158,11 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: click
-Requires-Dist: httpx2>=2.9.1
+Requires-Dist: httpx2>=2.12.0
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.47.0
+Requires-Dist: vgi-rpc>=0.47.2
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'
@@ -235,6 +235,11 @@ Description-Content-Type: text/markdown
   <a href="LICENSE"><img src="https://img.shields.io/pypi/l/vgi-python" alt="License"></a>
 </p>
 
+<p align="center">
+  <a href="https://youtu.be/J2E51PTZn6o"><img src="https://raw.githubusercontent.com/Query-farm/vgi-python/main/docs/assets/video-thumbnail.jpg" alt="Watch: VGI explained in 2½ minutes, on YouTube" width="640"></a><br>
+  <sub>▶ <a href="https://youtu.be/J2E51PTZn6o">Watch the 2½-minute overview</a></sub>
+</p>
+
 ---
 
 ## See It in Action

{vgi_python-0.37.2.dist-info → vgi_python-0.38.0.dist-info}/RECORD

@@ -39,7 +39,7 @@ vgi/table_in_out_function.py,sha256=F2QEtsbGEYHDVyQ4Cf9OCW7HlWXeqekAyx607foB-bs,
 vgi/worker.py,sha256=0ez46DE5tc1-78ll29lBP7KRKdDJnkOv89gdr4RjLrE,253453
 vgi/write_results.py,sha256=-OrUcz6E9ahhC_pnKYAwIMR2LpapwQafLC4IOnPTmec,2851
 vgi/_test_fixtures/__init__.py,sha256=xQq-QQLk8USQ6TZHsPiPcZldNNUdcJ2gToXMPGzScLI,444
-vgi/_test_fixtures/attach_options.py,sha256=ZNgNTNF1RymSfnU-uVIDTLvCpc283h6O8tZ1UuEa3Lc,12516
+vgi/_test_fixtures/attach_options.py,sha256=FPsXGmhA9sU0tkgtHAlSO7kUQgqHsaDwtC8jYNXDHko,12529
 vgi/_test_fixtures/bad_enum.py,sha256=b8l-afmXgGR6iqgIUiVeqHu0C0F8Of8ahEmdQGtqd1g,2916
 vgi/_test_fixtures/bad_protocol.py,sha256=fPU7rpXEgBxRtPHfuCa0O2AHNRRbZDllLfydHsAKPEg,2992
 vgi/_test_fixtures/cancellable.py,sha256=hetTRLyT4kkazPNcxAdfzj0pYzEmegMksamJbR0w3Ho,12151
@@ -122,8 +122,8 @@ vgi/_test_fixtures/writable/generic.py,sha256=3UzNUly3DhDPz-Revq7GePi6pxbP3AZ7R0
 vgi/_test_fixtures/writable/table.py,sha256=j4hdzxva7XX_9MG68AJIdpLqC2SY9g-A6jy-eLL6Yzg,5735
 vgi/_test_fixtures/writable/worker.py,sha256=ti-YFqVdYTMPIvDC8iwvaZ_CYUFTIf9xod2gqc1ReBk,42956
 vgi/catalog/__init__.py,sha256=edc2wuvloEgY2WnnJNngV3xP0DN_p49SElYQanGzq4A,2629
-vgi/catalog/_descriptor_spec.py,sha256=fyeWOC3eN04UXDAOnxFeOS1VwGBWoBCMOzZfRYKPFH4,9773
-vgi/catalog/attach_option.py,sha256=4cgJZjTVCnFv8TrLYnfjy-XZLAx5ux4UisJRcBeXkfo,5735
+vgi/catalog/_descriptor_spec.py,sha256=8F7QGHvs5uumkVqpWxgMZi_QuqobqTJwf2_xgyuPZh4,9788
+vgi/catalog/attach_option.py,sha256=-f8a6MPOthTWGf_6cjOgnNwJtVH4rGdxLMOMduGSyxk,7641
 vgi/catalog/catalog_interface.py,sha256=-JdVTfkTOC2RYickktUiESF5UCuLVnPnLCUBQrTaN_4,158452
 vgi/catalog/descriptors.py,sha256=JvI0mqDy6DGmtnhZw-U2Z9ZROMjz4KejxGrw7XmNnGw,49362
 vgi/catalog/duckdb_statistics.py,sha256=Bzw4UGO-zdKrontaCcRV2palO8G3XLCWh-AhZozvQI8,16894
@@ -144,17 +144,17 @@ vgi/client/client.py,sha256=cvBQHzM2Z2lamC-fkBAvZD4HuRxB03aUkEKFVo_E9GU,167312
 vgi/client/errors.py,sha256=cSN65cyQMk3crwZCz1IdPErK3mtlEkTNpu-nuQUDOQE,1633
 vgi/http/__init__.py,sha256=hlOwOVcoZqmEKVGk7ganOdr5ryRSpEhLBF9sRD7BkYc,608
 vgi/http/demo_storage.py,sha256=830s-H61thozC3eEuqdnwCpYFfvoJRq9vjyuXa5OURo,8769
-vgi/http/landing.html,sha256=E3gRtGGYt9DIB1auhNogOOS6W3NdkLNRNxqn_L8OKHY,356356
+vgi/http/landing.html,sha256=v7_5QRwjwVIX_WIKCx-dxZb4FoOF6_XN505__DyOuNw,356562
 vgi/http/landing_page.py,sha256=8dPnRWwao-Zn7SirkJ9KZoGVYFOj9G0kGCTEO0Yo2X4,4149
 vgi/http/vgi-client.js,sha256=dxJEzkpFp-XOAj1_z6inAhZyt2hYsjA9dI2US7k6r8I,560268
-vgi/http/worker_page.py,sha256=ILfIYLZZHS_rOE4y-EsYt14B0ytItiHLO5YtIbRCLUs,54872
+vgi/http/worker_page.py,sha256=hQefuTk_P3O8IfrXY4QzWo8Q_06pjOQLtxjQPxUUCIs,55663
 vgi/transactor/__init__.py,sha256=Y3pHIQc5f6xy771J259oUZlAegklcHlIlTuinL3ENPQ,764
 vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr3vQ,953
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=v59IvrKnuvwOXvn_HEcBAbCzDVcx0akgKN0R1mChXg0,5034
 vgi/transactor/server.py,sha256=nzsZQxJZdgappdYX8okrFIrjFtUbdM_Hhskl1fZ2nDY,32553
-vgi_python-0.37.2.dist-info/METADATA,sha256=fTpswGuWyykmygCUctNzcLQQfYdlu2sJ36Ol6UiS7F4,25617
-vgi_python-0.37.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-vgi_python-0.37.2.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.37.2.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.37.2.dist-info/RECORD,,
+vgi_python-0.38.0.dist-info/METADATA,sha256=BdmzjeWg-CTAbWvVahlskbm-aIC6Ky_-wpf-y9izq3w,25953
+vgi_python-0.38.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vgi_python-0.38.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.38.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.38.0.dist-info/RECORD,,