Skip to content
Permalink
Browse files
docs: fix docstring types and typos (#259)
* docs: fix docstring types

* docs: fix typos

* docs: correctly reference logging.Logger type

* docs: fix pool bind parameter docstring

Co-authored-by: larkee <larkee@users.noreply.github.com>
  • Loading branch information
larkee and larkee committed Mar 17, 2021
1 parent 0d7722b commit 1b0ce1d2986085ce4033cf773eb6c5d3b904473c
@@ -53,19 +53,19 @@ def _merge_query_options(base, merge):
"""Merge higher precedence QueryOptions with current QueryOptions.
:type base:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or :class:`dict` or None
:param base: The current QueryOptions that is intended for use.
:type merge:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or :class:`dict` or None
:param merge:
The QueryOptions that have a higher priority than base. These options
should overwrite the fields in base.
:rtype:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or None
:returns:
QueryOptions object formed by merging the two given QueryOptions.
@@ -167,7 +167,7 @@ def _parse_value_pb(value_pb, field_type):
:type value_pb: :class:`~google.protobuf.struct_pb2.Value`
:param value_pb: protobuf to convert
:type field_type: :class:`~google.cloud.spanner_v1.Type`
:type field_type: :class:`~google.cloud.spanner_v1.types.Type`
:param field_type: type code for the value
:rtype: varies on field_type
@@ -220,7 +220,7 @@ def _parse_list_value_pbs(rows, row_type):
:type rows: list of :class:`~google.protobuf.struct_pb2.ListValue`
:param rows: row data returned from a read/query
:type row_type: :class:`~google.cloud.spanner_v1.StructType`
:type row_type: :class:`~google.cloud.spanner_v1.types.StructType`
:param row_type: row schema specification
:rtype: list of list of cell data
@@ -141,7 +141,7 @@ def size_bytes(self):
def state(self):
"""State of this backup.
:rtype: :class:`~google.cloud.spanner_admin_database_v1.Backup.State`
:rtype: :class:`~google.cloud.spanner_admin_database_v1.types.Backup.State`
:returns: an enum describing the state of the backup
"""
return self._state
@@ -160,7 +160,7 @@ def referencing_databases(self):
def from_pb(cls, backup_pb, instance):
"""Create an instance of this class from a protobuf message.
:type backup_pb: :class:`~google.spanner.admin.database.v1.Backup`
:type backup_pb: :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
:param backup_pb: A backup protobuf object.
:type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
@@ -179,7 +179,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):


def _make_write_pb(table, columns, values):
"""Helper for :meth:`Batch.insert` et aliae.
"""Helper for :meth:`Batch.insert` et al.
:type table: str
:param table: Name of the table to be modified.
@@ -190,7 +190,7 @@ def _make_write_pb(table, columns, values):
:type values: list of lists
:param values: Values to be modified.
:rtype: :class:`google.cloud.spanner_v1.Mutation.Write`
:rtype: :class:`google.cloud.spanner_v1.types.Mutation.Write`
:returns: Write protobuf
"""
return Mutation.Write(
@@ -108,12 +108,12 @@ class Client(ClientWithProject):
on the client. API Endpoint should be set through client_options.
:type query_options:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or :class:`dict`
:param query_options:
(Optional) Query optimizer configuration to use for the given query.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_v1.QueryOptions`
message :class:`~google.cloud.spanner_v1.types.QueryOptions`
:raises: :class:`ValueError <exceptions.ValueError>` if both ``read_only``
and ``admin`` are :data:`True`
@@ -348,7 +348,7 @@ def list_instances(self, filter_="", page_size=None):
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.cloud.spanner_v1.instance.Instance`
Iterator of :class:`~google.cloud.spanner_admin_instance_v1.types.Instance`
resources within the client's project.
"""
metadata = _metadata_with_prefix(self.project_name)
@@ -103,7 +103,7 @@ class Database(object):
passed, the database will construct an instance of
:class:`~google.cloud.spanner_v1.pool.BurstyPool`.
:type logger: `logging.Logger`
:type logger: :class:`logging.Logger`
:param logger: (Optional) a custom logger that is used if `log_commit_stats`
is `True` to log commit statistics. If not passed, a logger
will be created when needed that will log the commit statistics
@@ -138,7 +138,7 @@ def from_pb(cls, database_pb, instance, pool=None):
"""Creates an instance of this class from a protobuf.
:type database_pb:
:class:`~google.cloud.spanner_admin_instance_v1.Instance`
:class:`~google.cloud.spanner_admin_instance_v1.types.Instance`
:param database_pb: A instance protobuf object.
:type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
@@ -199,7 +199,7 @@ def name(self):
def state(self):
"""State of this database.
:rtype: :class:`~google.cloud.spanner_admin_database_v1.Database.State`
:rtype: :class:`~google.cloud.spanner_admin_database_v1.types.Database.State`
:returns: an enum describing the state of the database
"""
return self._state
@@ -218,7 +218,7 @@ def create_time(self):
def restore_info(self):
"""Restore info for this database.
:rtype: :class:`~google.cloud.spanner_v1.database.RestoreInfo`
:rtype: :class:`~google.cloud.spanner_v1.types.RestoreInfo`
:returns: an object representing the restore info for this database
"""
return self._restore_info
@@ -310,7 +310,7 @@ def __ne__(self, other):
def create(self):
"""Create this database within its instance
Inclues any configured schema assigned to :attr:`ddl_statements`.
Includes any configured schema assigned to :attr:`ddl_statements`.
See
https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase
@@ -429,12 +429,12 @@ def execute_partitioned_dml(
required if parameters are passed.
:type query_options:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or :class:`dict`
:param query_options:
(Optional) Query optimizer configuration to use for the given query.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_v1.QueryOptions`
message :class:`~google.cloud.spanner_v1.types.QueryOptions`
:rtype: int
:returns: Count of rows affected by the DML statement.
@@ -568,7 +568,7 @@ def run_in_transaction(self, func, *args, **kw):
:returns: The return value of ``func``.
:raises Exception:
reraises any non-ABORT execptions raised by ``func``.
reraises any non-ABORT exceptions raised by ``func``.
"""
# Sanity check: Is there a transaction already running?
# If there is, then raise a red flag. Otherwise, mark that this one
@@ -895,7 +895,7 @@ def generate_read_batches(
:rtype: iterable of dict
:returns:
mappings of information used peform actual partitioned reads via
mappings of information used perform actual partitioned reads via
:meth:`process_read_batch`.
"""
partitions = self._get_snapshot().partition_read(
@@ -945,7 +945,7 @@ def generate_query_batches(
Uses the ``PartitionQuery`` API request to start a partitioned
query operation. Returns a list of batch information needed to
peform the actual queries.
perform the actual queries.
:type sql: str
:param sql: SQL query statement
@@ -976,16 +976,16 @@ def generate_query_batches(
differ.
:type query_options:
:class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
:class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
or :class:`dict`
:param query_options:
(Optional) Query optimizer configuration to use for the given query.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_v1.QueryOptions`
message :class:`~google.cloud.spanner_v1.types.QueryOptions`
:rtype: iterable of dict
:returns:
mappings of information used peform actual partitioned reads via
mappings of information used perform actual partitioned reads via
:meth:`process_read_batch`.
"""
partitions = self._get_snapshot().partition_query(
@@ -1065,7 +1065,7 @@ def _check_ddl_statements(value):
https://cloud.google.com/spanner/docs/data-definition-language
:type value: list of string
:param value: DDL statements, excluding the 'CREATE DATABSE' statement
:param value: DDL statements, excluding the 'CREATE DATABASE' statement
:rtype: tuple
:returns: tuple of validated DDL statement strings.
@@ -349,7 +349,7 @@ def delete(self):
Soon afterward:
* The instance and all databases within the instance will be deleteed.
* The instance and all databases within the instance will be deleted.
All data in the databases will be permanently deleted.
"""
api = self._client.instance_admin_api
@@ -365,13 +365,13 @@ def database(self, database_id, ddl_statements=(), pool=None, logger=None):
:type ddl_statements: list of string
:param ddl_statements: (Optional) DDL statements, excluding the
'CREATE DATABSE' statement.
'CREATE DATABASE' statement.
:type pool: concrete subclass of
:class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`.
:param pool: (Optional) session pool to be used by database.
:type logger: `logging.Logger`
:type logger: :class:`logging.Logger`
:param logger: (Optional) a custom logger that is used if `log_commit_stats`
is `True` to log commit statistics. If not passed, a logger
will be created when needed that will log the commit statistics
@@ -398,7 +398,7 @@ def list_databases(self, page_size=None):
:rtype: :class:`~google.api._ore.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.cloud.spanner_v1.database.Database`
Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Database`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
@@ -429,6 +429,9 @@ def backup(self, backup_id, database="", expire_time=None, version_time=None):
Optional. The version time that will be used to create the externally
consistent copy of the database. If not present, it is the same as
the `create_time` of the backup.
:rtype: :class:`~google.cloud.spanner_v1.backup.Backup`
:returns: a backup owned by this instance.
"""
try:
return Backup(
@@ -462,7 +465,7 @@ def list_backups(self, filter_="", page_size=None):
:rtype: :class:`~google.api_core.page_iterator.Iterator`
:returns:
Iterator of :class:`~google.cloud.spanner_v1.backup.Backup`
Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
resources within the current instance.
"""
metadata = _metadata_with_prefix(self.name)
@@ -68,7 +68,7 @@ def __init__(
def _to_pb(self):
"""Construct a KeyRange protobuf.
:rtype: :class:`~google.cloud.spanner_v1.KeyRange`
:rtype: :class:`~google.cloud.spanner_v1.types.KeyRange`
:returns: protobuf corresponding to this instance.
"""
kwargs = {}
@@ -88,7 +88,7 @@ def _to_pb(self):
return KeyRangePB(**kwargs)

def _to_dict(self):
"""Return keyrange's state as a dict.
"""Return the state of the keyrange as a dict.
:rtype: dict
:returns: state of this instance.
@@ -139,7 +139,7 @@ def __init__(self, keys=(), ranges=(), all_=False):
def _to_pb(self):
"""Construct a KeySet protobuf.
:rtype: :class:`~google.cloud.spanner_v1.KeySet`
:rtype: :class:`~google.cloud.spanner_v1.types.KeySet`
:returns: protobuf corresponding to this instance.
"""
if self.all_:
@@ -155,7 +155,7 @@ def _to_pb(self):
return KeySetPB(**kwargs)

def _to_dict(self):
"""Return keyset's state as a dict.
"""Return the state of the keyset as a dict.
The result can be used to serialize the instance and reconstitute
it later using :meth:`_from_dict`.
@@ -33,10 +33,10 @@
def Array(element_type): # pylint: disable=invalid-name
"""Construct an array parameter type description protobuf.
:type element_type: :class:`~google.cloud.spanner_v1.Type`
:type element_type: :class:`~google.cloud.spanner_v1.types.Type`
:param element_type: the type of elements of the array
:rtype: :class:`google.cloud.spanner_v1.Type`
:rtype: :class:`google.cloud.spanner_v1.types.Type`
:returns: the appropriate array-type protobuf
"""
return Type(code=TypeCode.ARRAY, array_element_type=element_type)
@@ -48,10 +48,10 @@ def StructField(name, field_type): # pylint: disable=invalid-name
:type name: str
:param name: the name of the field
:type field_type: :class:`google.cloud.spanner_v1.Type`
:type field_type: :class:`google.cloud.spanner_v1.types.Type`
:param field_type: the type of the field
:rtype: :class:`google.cloud.spanner_v1.StructType.Field`
:rtype: :class:`google.cloud.spanner_v1.types.StructType.Field`
:returns: the appropriate struct-field-type protobuf
"""
return StructType.Field(name=name, type_=field_type)
@@ -60,7 +60,7 @@ def StructField(name, field_type): # pylint: disable=invalid-name
def Struct(fields): # pylint: disable=invalid-name
"""Construct a struct parameter type description protobuf.
:type fields: list of :class:`google.cloud.spanner_v1.StructType.Field`
:type fields: list of :class:`google.cloud.spanner_v1.types.StructType.Field`
:param fields: the fields of the struct
:rtype: :class:`type_pb2.Type`
@@ -42,7 +42,7 @@ def __init__(self, labels=None):

@property
def labels(self):
"""User-assigned labels for sesions created by the pool.
"""User-assigned labels for sessions created by the pool.
:rtype: dict (str -> str)
:returns: labels assigned by the user
@@ -53,7 +53,7 @@ def bind(self, database):
"""Associate the pool with a database.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database: database used by the pool: used to create sessions
:param database: database used by the pool to create sessions
when needed.
Concrete implementations of this method may pre-fill the pool
@@ -162,7 +162,7 @@ def bind(self, database):
"""Associate the pool with a database.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database: database used by the pool: used to create sessions
:param database: database used by the pool to used to create sessions
when needed.
"""
self._database = database
@@ -256,7 +256,7 @@ def bind(self, database):
"""Associate the pool with a database.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database: database used by the pool: used to create sessions
:param database: database used by the pool to create sessions
when needed.
"""
self._database = database
@@ -354,7 +354,7 @@ def bind(self, database):
"""Associate the pool with a database.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database: database used by the pool: used to create sessions
:param database: database used by the pool to create sessions
when needed.
"""
self._database = database
@@ -486,7 +486,7 @@ def bind(self, database):
"""Associate the pool with a database.
:type database: :class:`~google.cloud.spanner_v1.database.Database`
:param database: database used by the pool: used to create sessions
:param database: database used by the pool to create sessions
when needed.
"""
super(TransactionPingingPool, self).bind(database)

0 comments on commit 1b0ce1d

Please sign in to comment.