From 2fdf59c2e3763815de70f4d5c68f22e2a960ba13 Mon Sep 17 00:00:00 2001 From: Matt Wozniski Date: Fri, 19 Aug 2022 19:52:44 -0400 Subject: [PATCH] docs: Fix Sphinx warnings We were using `T` as a stand-in for any valid parameter type, but Sphinx doesn't like that. Let's just use `Any` in the docs - the actual valid types are spelled out in the type stubs, but adding them to the documentation would make things unnecessarily verbose and repetitive. Likewise, we were using `Row` as a stand-in for whatever row type is configured using the `row_factory`, but let's just drop that and leave it implicit. Finally, use code formatting (double backticks) rather than references (single backticks) for some things that were never meant to be references. Signed-off-by: Matt Wozniski --- comdb2/cdb2.py | 2 +- comdb2/dbapi2.py | 18 +++++++++--------- docs/tips.rst | 2 +- docs/types.rst | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/comdb2/cdb2.py b/comdb2/cdb2.py index dc897e1..37a67dd 100644 --- a/comdb2/cdb2.py +++ b/comdb2/cdb2.py @@ -329,7 +329,7 @@ def execute(self, sql, parameters=None): Args: sql (str): The SQL string to execute. - parameters (Mapping[str, T]): An optional mapping from parameter + parameters (Mapping[str, Any]): An optional mapping from parameter names to the values to be bound for them. Returns: diff --git a/comdb2/dbapi2.py b/comdb2/dbapi2.py index 90ba2f2..cacf68c 100644 --- a/comdb2/dbapi2.py +++ b/comdb2/dbapi2.py @@ -225,11 +225,11 @@ Specification v2.0 `_ with a few specific exceptions: -1. DB-API requires `Date` and `DateFromTicks` constructors, which we don't +1. DB-API requires ``Date`` and ``DateFromTicks`` constructors, which we don't provide because Comdb2 has no type for representing a date without a time component. -2. DB-API requires `Time` and `TimeFromTicks` constructors, which we don't +2. DB-API requires ``Time`` and ``TimeFromTicks`` constructors, which we don't provide because Comdb2 has no type for representing a time without a date component. @@ -920,13 +920,13 @@ def callproc(self, procname, parameters): Args: procname (str): The name of the stored procedure to be executed. - parameters (Sequence[T]): A sequence of values to be passed, in + parameters (Sequence[Any]): A sequence of values to be passed, in order, as the parameters to the stored procedure. Each element must be an instance of one of the Python types listed in :doc:`types`. Returns: - List[T]: A copy of the input parameters. + List[Any]: A copy of the input parameters. """ if not _VALID_SP_NAME.match(procname): raise NotSupportedError("Invalid procedure name '%s'" % procname) @@ -952,7 +952,7 @@ def execute(self, sql, parameters=None): Args: sql (str): The SQL string to execute, as a Python format string. - parameters (Mapping[str, T]): An optional mapping from parameter + parameters (Mapping[str, Any]): An optional mapping from parameter names to the values to be bound for them. Returns: @@ -998,7 +998,7 @@ def executemany(self, sql, seq_of_parameters): Args: sql (str): The SQL string to execute, as a Python format string of the format expected by `execute`. - seq_of_parameters (Sequence[Mapping[str, T]]): A sequence of + seq_of_parameters (Sequence[Mapping[str, Any]]): A sequence of mappings from parameter names to the values to be bound for them. The ``sql`` statement will be run once per element in this sequence. @@ -1076,7 +1076,7 @@ def fetchone(self): """Fetch the next row of the current result set. Returns: - Row: If no rows remain in the current result set, ``None`` is + If no rows remain in the current result set, ``None`` is returned, otherwise the next row of the result set is returned. By default the row is returned as a `list`, where the elements in the list correspond to the result row's columns in positional order, @@ -1095,7 +1095,7 @@ def fetchmany(self, n=None): given, `Cursor.arraysize` is used as the maximum. Returns: - List[Row]: Returns a `list` containing the next ``n`` rows of the + list: Returns a `list` containing the next ``n`` rows of the result set. If fewer than ``n`` rows remain, the returned list will contain fewer than ``n`` elements. If no rows remain, the list will be empty. By default each row is @@ -1111,7 +1111,7 @@ def fetchall(self): """Fetch all remaining rows of the current result set. Returns: - List[Row]: Returns a `list` containing all remaining rows of the + list: Returns a `list` containing all remaining rows of the result set. By default each row is returned as a `list`, where the elements in the list correspond to the result row's columns in positional order, but this can be changed with the diff --git a/docs/tips.rst b/docs/tips.rst index ece6f17..e5c9fdf 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -84,7 +84,7 @@ Best Practices, Tips, and Tricks obviously work as well). #. The underlying API doesn't currently allow binding lists. The following snippet - will be useful for a `$var in $list` query with a dynamically generated list:: + will be useful for a ``$var in $list`` query with a dynamically generated list:: from comdb2.dbapi2 import connect diff --git a/docs/types.rst b/docs/types.rst index 3a8d016..0fd1da9 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -61,7 +61,7 @@ both languages. This decision has many important ramifications. #. If you have a variable of type `six.binary_type` (byte string) and you want to pass it to the database as a TEXT value, you need to convert it to a `six.text_type` (Unicode) string using `~bytes.decode`. In Python 2, - unless `unicode_literals` was imported from `__future__`, you will need to + unless ``unicode_literals`` was imported from `__future__`, you will need to do this with every string variable that you want to use as a cstring column. For example::