docs: document class members across the core package

Add Google-style `Attributes:` sections (and a few method `Args:`/`Returns:`/
`Yields:` sections) to ~80 previously-undocumented core classes so their
members render in the API docs and are covered by the pydoclint gate.

The protocol contract is the headline: every protocol.py request/response
dataclass (BindRequest, InitRequest, the aggregate/table-buffering/window
messages, catalog create/attach requests, etc.) now documents each wire field,
using a consistent vocabulary for recurring fields (attach_opaque_data,
execution_id, function_name, transaction_opaque_data, output_schema, ...).

Also covered: metadata.ResolvedMetadata, the table_filter_pushdown AST nodes,
table_function/table_in_out_function params, aggregate_function
(AggregateBindParams, AggregateFunction.state_class), worker/client/catalog/
secret/codegen data classes, and table_buffering_function.Meta. Inline `#`
field comments were folded into the docstrings where present.

Because each documented class now has a multi-line docstring, the existing
pydoclint gate enforces its attribute completeness going forward — no config
change or baseline needed. (skip_checking_short_docstrings stays default; the
remaining one-line-docstring classes/methods are intentionally not gated.)

Docstrings only; no runtime behavior changed. mypy clean, gate clean, tests
pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

vgi/aggregate_function.py

@@ -46,7 +46,15 @@
 
 @dataclass(slots=True, frozen=True, kw_only=True)
 class AggregateBindParams:
-    """Parameters passed to `AggregateFunction.on_bind()`."""
+    """Parameters passed to `AggregateFunction.on_bind()`.
+
+    Attributes:
+        args: The bound function [`Arguments`][], or ``None`` if none.
+        input_schema: Arrow schema of the aggregate's input columns, or ``None``.
+        settings: DuckDB session settings relevant to the function.
+        secrets: Accessor for the resolved secrets the function declared.
+        auth_context: The caller's authentication context (anonymous by default).
+    """
 
     args: Arguments | None
     input_schema: pa.Schema | None
@@ -136,6 +144,11 @@ def finalize(
             ) -> Annotated[pa.RecordBatch, Returns(pa.int64())]:
                 ...
 
+    Attributes:
+        state_class: The resolved ``TState`` dataclass used for per-group
+            accumulation state, inferred from the generic parameter; ``None``
+            until resolved by ``__init_subclass__``.
+
     """
 
     state_class: type[TState] | None = None

vgi/arguments.py

@@ -344,6 +344,10 @@ class IdentityFunction(TableFunctionGenerator):
         Unlike [`TableInput`][], [`AnyArrow`][] arguments have actual Arrow values -
         they are just not constrained to a specific Arrow type.
 
+    Attributes:
+        value: The resolved Arrow value of the argument.
+        position: The argument's positional index or name used to resolve it.
+        name: The argument's name.
     """
 
     # Type stubs for static analysis - at runtime, Arg[AnyArrow] returns AnyArrowValue
@@ -1618,6 +1622,12 @@ class SecretLookupEntry(ArrowSerializableDataclass):
     - By type + scope:        SecretLookupEntry(secret_type="s3", scope="s3://bucket/")
     - By type + name:         SecretLookupEntry(secret_type="s3", secret_name="my_cred")
     - By type + scope + name: all three fields set
+
+    Attributes:
+        secret_type: The DuckDB secret type to match (required; C++ enforces
+            type matching).
+        scope: Optional URI prefix the secret must apply to.
+        secret_name: Optional name of the specific secret to resolve.
     """
 
     secret_type: str

vgi/catalog/catalog_interface.py

@@ -445,7 +445,14 @@ class MacroInfo(CatalogSchemaObject, ArrowSerializableDataclass):
 
 
 class FunctionType(Enum):
-    """The type of function in a schema."""
+    """The type of function in a schema.
+
+    Attributes:
+        SCALAR: A scalar function.
+        TABLE: A table function.
+        TABLE_BUFFERING: A table-buffering (table-in-out) function.
+        AGGREGATE: An aggregate function.
+    """
 
     SCALAR = "scalar"
     TABLE = "table"
@@ -454,7 +461,12 @@ class FunctionType(Enum):
 
 
 class MacroType(Enum):
-    """The type of macro in a schema."""
+    """The type of macro in a schema.
+
+    Attributes:
+        SCALAR: A scalar macro.
+        TABLE: A table macro.
+    """
 
     SCALAR = "scalar"
     TABLE = "table"
@@ -463,9 +475,10 @@ class MacroType(Enum):
 class IndexConstraintType(Enum):
     """The constraint type of an index.
 
-    NONE: Regular index (no constraint enforcement).
-    UNIQUE: Index enforces a UNIQUE constraint.
-    PRIMARY: Index enforces a PRIMARY KEY constraint.
+    Attributes:
+        NONE: Regular index (no constraint enforcement).
+        UNIQUE: Index enforces a UNIQUE constraint.
+        PRIMARY: Index enforces a PRIMARY KEY constraint.
     """
 
     NONE = "none"
@@ -499,6 +512,16 @@ class SchemaObjectType(Enum):
     """The type of object that can exist within a schema.
 
     Used to filter results from schema_contents().
+
+    Attributes:
+        TABLE: A table.
+        VIEW: A view.
+        SCALAR_FUNCTION: A scalar function.
+        TABLE_FUNCTION: A table function.
+        AGGREGATE_FUNCTION: An aggregate function.
+        SCALAR_MACRO: A scalar macro.
+        TABLE_MACRO: A table macro.
+        INDEX: An index.
     """
 
     TABLE = "table"
@@ -514,9 +537,10 @@ class SchemaObjectType(Enum):
 class OnConflict(Enum):
     """Behavior when a conflict occurs during creation of an object.
 
-    IGNORE: Do nothing if the object already exists.
-    REPLACE: Replace the existing object if it already exists.
-    ERROR: Raise an error if the object already exists.
+    Attributes:
+        ERROR: Raise an error if the object already exists.
+        IGNORE: Do nothing if the object already exists.
+        REPLACE: Replace the existing object if it already exists.
     """
 
     ERROR = "error"
@@ -2096,6 +2120,47 @@ class ReadOnlyCatalogInterface(CatalogInterface):
     All DDL operations (create, drop, rename, modify) will raise
     [`CatalogReadOnlyError`][].
 
+    Attributes:
+        supports_transactions: Always ``False`` -- read-only catalogs do not
+            support transactions.
+        catalog_version_frozen: Always ``True`` -- the catalog version never
+            changes.
+        catalog_name: Name of the catalog exposed when using the functions-list
+            mode (default ``"functions"``).
+        functions: Function classes to expose in the ``"main"`` schema.
+        settings: DuckDB setting specs the catalog declares.
+        secret_types: Secret type specs the catalog declares.
+        attach_option_specs: Attach option specs accepted at ``ATTACH`` time.
+        catalog: Optional declarative `[`Catalog`][]` object describing the
+            catalog's schemas, tables, and views.
+        catalog_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        catalog_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        catalog_transaction_begin: DDL stub that raises `[`CatalogReadOnlyError`][].
+        catalog_transaction_commit: DDL stub that raises `[`CatalogReadOnlyError`][].
+        catalog_transaction_rollback: DDL stub that raises `[`CatalogReadOnlyError`][].
+        schema_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        schema_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_comment_set: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_comment_set: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_rename: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_add: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_rename: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_default_set: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_default_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_column_type_change: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_not_null_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        table_not_null_set: DDL stub that raises `[`CatalogReadOnlyError`][].
+        view_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        view_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        view_rename: DDL stub that raises `[`CatalogReadOnlyError`][].
+        view_comment_set: DDL stub that raises `[`CatalogReadOnlyError`][].
+        macro_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        macro_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
+        index_create: DDL stub that raises `[`CatalogReadOnlyError`][].
+        index_drop: DDL stub that raises `[`CatalogReadOnlyError`][].
     """
 
     supports_transactions = False

vgi/catalog/descriptors.py

@@ -107,6 +107,19 @@ class ColumnStatisticsInput:
         # Explicit PyArrow scalars
         ColumnStatisticsInput(min=pa.scalar(1, pa.int32()), max=pa.scalar(100, pa.int32()))
 
+    Attributes:
+        min: Minimum value as a Python literal or PyArrow scalar, or ``None`` if
+            unknown.
+        max: Maximum value as a Python literal or PyArrow scalar, or ``None`` if
+            unknown. Must share the column's Arrow type with ``min``.
+        has_null: Whether the column contains any null values.
+        has_not_null: Whether the column contains any non-null values.
+        distinct_count: Approximate count of distinct values, or ``None`` if
+            unknown.
+        contains_unicode: String/binary columns only -- whether values contain
+            non-ASCII characters. ``None`` for non-string columns.
+        max_string_length: String/binary columns only -- maximum byte length of
+            values. ``None`` for non-string columns.
     """
 
     min: StatValue = None

vgi/catalog/storage.py

@@ -139,8 +139,12 @@ class CatalogStorageSqlite:
     - catalog_attachments: Maps attach_opaque_data to catalog name and options
     - catalog_transactions: Tracks active transactions
 
+    Attributes:
+        db_path: Filesystem path to the backing SQLite database file.
     """
 
+    db_path: str
+
     def __init__(self, db_path: str | None = None) -> None:
         """Initialize SQLite catalog storage.
 

vgi/client/catalog_mixin.py

@@ -93,11 +93,12 @@ class CatalogClientMixin:
     ``httpx.Client`` (bearer token, headers). Browsing catalogs over HTTP
     is the canonical non-DuckDB use case this mixin supports.
 
-    Expected attributes from ``Client``:
-        server_path: str — worker shell command (subprocess transport).
-        _transport: Literal["subprocess", "http"].
-        _base_url: str | None — HTTP base URL.
-        _get_or_create_httpx_client(): shared HTTP client factory.
+    Other attributes expected from ``Client``: ``_transport`` (subprocess vs
+    http), ``_base_url`` (HTTP base URL), and ``_get_or_create_httpx_client()``
+    (shared HTTP client factory).
+
+    Attributes:
+        server_path: Worker shell command used for subprocess transport.
     """
 
     # Type hints for attributes expected from Client
@@ -122,6 +123,9 @@ def _catalog_connect(self) -> Iterator[VgiProtocol]:
         connection pooling are consistent.
 
         Worker errors are caught and re-raised as ``CatalogClientError``.
+
+        Yields:
+            A typed `[`VgiProtocol`][]` proxy bound to the active transport.
         """
         try:
             if getattr(self, "_transport", "subprocess") == "http":

vgi/client/client.py

@@ -201,6 +201,13 @@ class WorkerConnection:
 
     Exactly one of {proc+connection, _pool_ctx, _http_ctx} is active per
     connection — transport-specific teardown inspects these fields.
+
+    Attributes:
+        proxy: The typed `[`VgiProtocol`][]` proxy used to invoke the worker.
+        worker_index: Index of this worker within a parallel pool.
+        stream: The active streaming session, if any.
+        proc: The worker subprocess for direct (non-pooled) subprocess transport.
+        connection: The RPC connection for direct subprocess transport.
     """
 
     proxy: VgiProtocol
@@ -242,12 +249,15 @@ class Client(CatalogClientMixin):
         with Client.from_http("http://host:port", bearer_token="...") as c:
             for batch in c.table_function(function_name="sequence", ...):
                 ...
+
+    Attributes:
+        THREAD_JOIN_TIMEOUT: Seconds to wait for a worker thread to join during
+            shutdown.
+        PROCESS_WAIT_TIMEOUT: Seconds to wait for a worker process to exit during
+            shutdown.
     """
 
-    # Timeout for thread join operations (seconds)
     THREAD_JOIN_TIMEOUT: float = 5.0
-
-    # Timeout for worker process wait operations (seconds)
     PROCESS_WAIT_TIMEOUT: float = 5.0
 
     @staticmethod

vgi/codegen/_common.py

@@ -69,11 +69,17 @@ class EmittedSchema:
 
     `name` is the factory/function/const stem (CamelCase, no trailing `Schema`);
     emitters are free to append whatever suffix their output language idiom uses.
+
+    Attributes:
+        name: The factory/function/const stem (CamelCase, no trailing ``Schema``).
+        schema: The Arrow schema to emit.
+        origin: Human-readable source of the schema (e.g. ``"method
+            'catalog_catalogs' result"``), used in generated comments.
     """
 
     name: str
     schema: pa.Schema
-    origin: str  # e.g. "method 'catalog_catalogs' result"
+    origin: str
 
 
 def sanitize_name(name: str) -> str:

vgi/codegen/cpp_constants.py

@@ -40,11 +40,18 @@
 
 
 class _ByteConstant(NamedTuple):
-    """One C++-visible byte constant sourced from the Python vgi_rpc package."""
+    """One C++-visible byte constant sourced from the Python vgi_rpc package.
 
-    cpp_name: str  # emitted as `inline constexpr std::string_view {cpp_name}`
-    python_name: str  # key in vgi_rpc.metadata
-    description: str  # one-liner for the doc comment
+    Attributes:
+        cpp_name: Identifier emitted as ``inline constexpr std::string_view
+            {cpp_name}``.
+        python_name: Key in ``vgi_rpc.metadata`` whose value supplies the bytes.
+        description: One-liner used for the generated doc comment.
+    """
+
+    cpp_name: str
+    python_name: str
+    description: str
 
 
 # Ordered list of constants to emit. Add new entries here, regenerate,

vgi/codegen/ts_client.py

@@ -110,6 +110,17 @@ def _info(name: str) -> type:
 
 @dataclasses.dataclass
 class _Ctx:
+    """Mutable codegen context tracking emitted TypeScript types.
+
+    Attributes:
+        dataclasses_seen: Maps each registered Python dataclass to its emitted
+            TypeScript type name.
+        enums_seen: Maps each registered Python enum to its emitted TypeScript
+            type name.
+        dataclass_order: Dataclasses in the order they should be emitted.
+        enum_order: Enums in the order they should be emitted.
+    """
+
     dataclasses_seen: dict[type, str] = dataclasses.field(default_factory=dict)
     enums_seen: dict[type, str] = dataclasses.field(default_factory=dict)
     dataclass_order: list[type] = dataclasses.field(default_factory=list)