docs: add missing argument descriptions

ibis/backends/base/__init__.py

@@ -256,6 +256,8 @@ def to_pyarrow(
         limit
             An integer to effect a specific row limit. A value of `None` means
             "no limit". The default is in `ibis/config.py`.
+        kwargs
+            Keyword arguments
 
         Returns
         -------
@@ -316,6 +318,8 @@ def to_pyarrow_batches(
             Mapping of scalar parameter expressions to value.
         chunk_size
             Number of rows in each returned record batch.
+        kwargs
+            Keyword arguments
 
         Returns
         -------
@@ -761,6 +765,8 @@ def connect(resource: Path | str, **kwargs: Any) -> BaseBackend:
     ----------
     resource
         A URL or path to the resource to be connected to.
+    kwargs
+        Backend specific keyword arguments
 
     Examples
     --------

ibis/backends/base/sql/__init__.py

@@ -182,6 +182,8 @@ def to_pyarrow_batches(
             Mapping of scalar parameter expressions to value.
         chunk_size
             Number of rows in each returned record batch.
+        kwargs
+            Keyword arguments
 
         Returns
         -------

ibis/backends/base/sql/alchemy/datatypes.py

@@ -381,16 +381,19 @@ def sa_struct(dialect, satype, nullable=True):
 
 
 @sch.infer.register((sa.Table, sa.sql.TableClause))
-def schema_from_table(table, schema=None):
+def schema_from_table(table: sa.Table, schema: sch.Schema | None = None) -> sch.Schema:
     """Retrieve an ibis schema from a SQLAlchemy ``Table``.
 
     Parameters
     ----------
-    table : sa.Table
+    table
+        Table whose schema to infer
+    schema
+        Schema to pull types from
 
     Returns
     -------
-    schema : ibis.expr.datatypes.Schema
+    schema
         An ibis schema corresponding to the types of the columns in `table`.
     """
     schema = schema if schema is not None else {}

ibis/backends/base/sql/compiler/query_builder.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from io import StringIO
+from typing import Iterable
 
 import toolz
 
@@ -442,15 +443,18 @@ class Difference(SetOp):
     _keyword = "EXCEPT"
 
 
-def flatten_set_op(op):
+def flatten_set_op(op) -> Iterable[ops.Table | bool]:
     """Extract all union queries from `table`.
 
     Parameters
     ----------
-    table : ops.TableNode
+    op
+        Set operation to flatten
+
     Returns
     -------
-    Iterable[Union[Table, bool]].
+    Iterable[Table | bool]
+        Iterable of tables and `bool`s indicating `distinct`.
     """
 
     if isinstance(op, ops.SetOp):
@@ -470,10 +474,13 @@ def flatten(op: ops.TableNode):
 
     Parameters
     ----------
-    table : Table
+    op
+        Table operation to flatten
+
     Returns
     -------
-    Iterable[Union[Table]].
+    Iterable[Table | bool]
+        Iterable of tables and `bool`s indicating `distinct`.
     """
     return list(toolz.concatv(flatten_set_op(op.left), flatten_set_op(op.right)))
 

ibis/backends/base/sql/registry/window.py

@@ -1,5 +1,6 @@
+from __future__ import annotations
+
 from operator import add, mul, sub
-from typing import Optional
 
 import ibis
 import ibis.common.exceptions as com
@@ -41,18 +42,19 @@
 }
 
 
-def _replace_interval_with_scalar(op: ops.Node):
-    """Good old Depth-First Search to identify the Interval and IntervalValue
-    components of the expression and return a comparable scalar expression.
+def _replace_interval_with_scalar(op: ops.Value) -> float | ir.FloatingScalar:
+    """Replace an interval type or expression with its equivalent numeric scalar.
 
     Parameters
     ----------
-    expr : float or expression of intervals
-        For example, ``ibis.interval(days=1) + ibis.interval(hours=5)``
+    op
+        float or interval expression.
+        For example, `ibis.interval(days=1) + ibis.interval(hours=5)`
 
     Returns
     -------
-    preceding : float or ir.FloatingScalar, depending upon the expr
+    preceding
+        `float` or `ir.FloatingScalar`, depending on the expr.
     """
     if isinstance(op, ops.Literal):
         unit = getattr(op.output_dtype, "unit", "us")
@@ -127,7 +129,7 @@ def format_window(translator, op, window):
 
     p, f = window.preceding, window.following
 
-    def _prec(p: Optional[int]) -> str:
+    def _prec(p: int | None) -> str:
         assert p is None or p >= 0
 
         if p is None:
@@ -138,7 +140,7 @@ def _prec(p: Optional[int]) -> str:
             prefix = str(p)
         return f'{prefix} PRECEDING'
 
-    def _foll(f: Optional[int]) -> str:
+    def _foll(f: int | None) -> str:
         assert f is None or f >= 0
 
         if f is None:

ibis/backends/bigquery/__init__.py

@@ -86,27 +86,28 @@ def connect(
 
         Parameters
         ----------
-        project_id : str
+        project_id
             A BigQuery project id.
-        dataset_id : str
+        dataset_id
             A dataset id that lives inside of the project indicated by
             `project_id`.
-        credentials : google.auth.credentials.Credentials
-        application_name : str
+        credentials
+            Optional credentials.
+        application_name
             A string identifying your application to Google API endpoints.
-        auth_local_webserver : bool
+        auth_local_webserver
             Use a local webserver for the user authentication.  Binds a
             webserver to an open port on localhost between 8080 and 8089,
-            inclusive, to receive authentication token. If not set, defaults
-            to False, which requests a token via the console.
-        auth_external_data : bool
+            inclusive, to receive authentication token. If not set, defaults to
+            False, which requests a token via the console.
+        auth_external_data
             Authenticate using additional scopes required to `query external
             data sources
             <https://cloud.google.com/bigquery/external-data-sources>`_,
             such as Google Sheets, files in Google Cloud Storage, or files in
             Google Drive. If not set, defaults to False, which requests the
             default BigQuery scopes.
-        auth_cache : str
+        auth_cache
             Selects the behavior of the credentials cache.
 
             ``'default'``
@@ -120,13 +121,14 @@ def connect(
                 Authenticates and does **not** cache credentials.
 
             Defaults to ``'default'``.
-        partition_column : str
+        partition_column
             Identifier to use instead of default ``_PARTITIONTIME`` partition
             column. Defaults to ``'PARTITIONTIME'``.
 
         Returns
         -------
         Backend
+            An instance of the BigQuery backend.
         """
         default_project_id = ""
 
@@ -278,20 +280,20 @@ def execute(self, expr, params=None, limit="default", **kwargs):
 
         Parameters
         ----------
-        expr : Expr
-        limit : int, default None
-          For expressions yielding result yets; retrieve at most this number of
-          values/rows. Overrides any limit already set on the expression.
-        params : not yet implemented
-        kwargs : Backends can receive extra params. For example, clickhouse
-            uses this to receive external_tables as dataframes.
+        expr
+            Ibis expression to execute
+        limit
+            Retrieve at most this number of values/rows. Overrides any limit
+            already set on the expression.
+        params
+            Query parameters
+        kwargs
+            Extra arguments specific to the backend
 
         Returns
         -------
-        output : input type dependent
-          Table expressions: pandas.DataFrame
-          Array expressions: pandas.Series
-          Scalar expressions: Python scalar value
+        pd.DataFrame | pd.Series | scalar
+            Output from execution
         """
         # TODO: upstream needs to pass params to raw_sql, I think.
         kwargs.pop("timecontext", None)
@@ -417,27 +419,28 @@ def connect(
 
     Parameters
     ----------
-    project_id : str
+    project_id
         A BigQuery project id.
-    dataset_id : str
+    dataset_id
         A dataset id that lives inside of the project indicated by
         `project_id`.
-    credentials : google.auth.credentials.Credentials
-    application_name : str
+    credentials
+        Optional credentials.
+    application_name
         A string identifying your application to Google API endpoints.
-    auth_local_webserver : bool
+    auth_local_webserver
         Use a local webserver for the user authentication.  Binds a
         webserver to an open port on localhost between 8080 and 8089,
         inclusive, to receive authentication token. If not set, defaults
         to False, which requests a token via the console.
-    auth_external_data : bool
+    auth_external_data
         Authenticate using additional scopes required to `query external
         data sources
         <https://cloud.google.com/bigquery/external-data-sources>`_,
         such as Google Sheets, files in Google Cloud Storage, or files in
         Google Drive. If not set, defaults to False, which requests the
         default BigQuery scopes.
-    auth_cache : str
+    auth_cache
         Selects the behavior of the credentials cache.
 
         ``'default'``
@@ -451,13 +454,14 @@ def connect(
             Authenticates and does **not** cache credentials.
 
         Defaults to ``'default'``.
-    partition_column : str
+    partition_column
         Identifier to use instead of default ``_PARTITIONTIME`` partition
         column. Defaults to ``'PARTITIONTIME'``.
 
     Returns
     -------
     Backend
+        An instance of the BigQuery backend
     """
     backend = Backend()
     return backend.connect(

ibis/backends/bigquery/udf/__init__.py

@@ -4,7 +4,7 @@
 import functools
 import inspect
 import itertools
-from typing import Iterable, Mapping
+from typing import Callable, Iterable, Mapping
 
 import ibis.expr.datatypes as dt
 import ibis.expr.rules as rlz
@@ -39,33 +39,35 @@ def create_udf_node(name, fields):
     return type(external_name, (BigQueryUDFNode,), fields)
 
 
-def udf(input_type, output_type, strict=True, libraries=None):
+def udf(
+    input_type: Iterable[dt.DataType],
+    output_type: dt.DataType,
+    strict: bool = True,
+    libraries: Iterable[str] | None = None,
+) -> Callable:
     '''Define a UDF for BigQuery.
 
+    `INT64` is not supported as an argument type or a return type, as per
+    [the BigQuery documentation](https://cloud.google.com/bigquery/docs/reference/standard-sql/user-defined-functions#sql-type-encodings-in-javascript).
+
     Parameters
     ----------
-    input_type : List[DataType]
-    output_type : DataType
-    strict : bool
+    input_type
+        Iterable of types, one per argument.
+    output_type
+        Return type of the UDF.
+    strict
         Whether or not to put a ``'use strict';`` string at the beginning of
         the UDF. Setting to ``False`` is probably a bad idea.
-    libraries : List[str]
-        A list of Google Cloud Storage URIs containing to JavaScript source
+    libraries
+        An iterable of Google Cloud Storage URIs containing to JavaScript source
         code. Note that any symbols (functions, classes, variables, etc.) that
         are exposed in these JavaScript files will be visible inside the UDF.
 
     Returns
     -------
-    wrapper : Callable
-        The wrapped function
-
-    Notes
-    -----
-    - ``INT64`` is not supported as an argument type or a return type, as per
-      `the BigQuery documentation
-      <https://cloud.google.com/bigquery/docs/reference/standard-sql/user-defined-functions#sql-type-encodings-in-javascript>`_.
-    - `The follow example doctest doesn't work for Python 3.8
-      <https://github.com/ibis-project/ibis/issues/2085>`_.
+    Callable
+        The wrapped user-defined function.
 
     Examples
     --------

ibis/backends/bigquery/udf/core.py

@@ -6,6 +6,7 @@
 import inspect
 import textwrap
 from collections import ChainMap
+from typing import Callable
 
 import ibis.expr.datatypes as dt
 from ibis.backends.bigquery.udf.find import find_names
@@ -49,13 +50,8 @@ def indent(lines, spaces=4):
     return textwrap.indent(text, " " * spaces)
 
 
-def semicolon(f):
-    """Add a semicolon to the result of a visit_* call.
-
-    Parameters
-    ----------
-    f : callable
-    """
+def semicolon(f: Callable) -> Callable:
+    """Add a semicolon to the result of a `visit_*` call."""
 
     @functools.wraps(f)
     def wrapper(*args, **kwargs):

ibis/backends/bigquery/udf/find.py

@@ -36,16 +36,8 @@ def find_Call(self, node):
         return toolz.concat(map(self.find, (getattr(node, field) for field in fields)))
 
 
-def find_names(node):
-    """Return the unique :class:`ast.Name` instances in an AST.
-
-    Parameters
-    ----------
-    node : ast.AST
-
-    Returns
-    -------
-    unique_names : List[ast.Name]
+def find_names(node: ast.AST) -> list[ast.Name]:
+    """Return the unique `ast.Name` instances in an AST.
 
     Examples
     --------