google-cloud-spanner 3.55.0__py3-none-any.whl

google/cloud/spanner_v1/types/__init__.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .commit_response import (
+    CommitResponse,
+)
+from .keys import (
+    KeyRange,
+    KeySet,
+)
+from .mutation import (
+    Mutation,
+)
+from .query_plan import (
+    PlanNode,
+    QueryPlan,
+)
+from .result_set import (
+    PartialResultSet,
+    ResultSet,
+    ResultSetMetadata,
+    ResultSetStats,
+)
+from .spanner import (
+    BatchCreateSessionsRequest,
+    BatchCreateSessionsResponse,
+    BatchWriteRequest,
+    BatchWriteResponse,
+    BeginTransactionRequest,
+    CommitRequest,
+    CreateSessionRequest,
+    DeleteSessionRequest,
+    DirectedReadOptions,
+    ExecuteBatchDmlRequest,
+    ExecuteBatchDmlResponse,
+    ExecuteSqlRequest,
+    GetSessionRequest,
+    ListSessionsRequest,
+    ListSessionsResponse,
+    Partition,
+    PartitionOptions,
+    PartitionQueryRequest,
+    PartitionReadRequest,
+    PartitionResponse,
+    ReadRequest,
+    RequestOptions,
+    RollbackRequest,
+    Session,
+)
+from .transaction import (
+    MultiplexedSessionPrecommitToken,
+    Transaction,
+    TransactionOptions,
+    TransactionSelector,
+)
+from .type import (
+    StructType,
+    Type,
+    TypeAnnotationCode,
+    TypeCode,
+)
+
+__all__ = (
+    "CommitResponse",
+    "KeyRange",
+    "KeySet",
+    "Mutation",
+    "PlanNode",
+    "QueryPlan",
+    "PartialResultSet",
+    "ResultSet",
+    "ResultSetMetadata",
+    "ResultSetStats",
+    "BatchCreateSessionsRequest",
+    "BatchCreateSessionsResponse",
+    "BatchWriteRequest",
+    "BatchWriteResponse",
+    "BeginTransactionRequest",
+    "CommitRequest",
+    "CreateSessionRequest",
+    "DeleteSessionRequest",
+    "DirectedReadOptions",
+    "ExecuteBatchDmlRequest",
+    "ExecuteBatchDmlResponse",
+    "ExecuteSqlRequest",
+    "GetSessionRequest",
+    "ListSessionsRequest",
+    "ListSessionsResponse",
+    "Partition",
+    "PartitionOptions",
+    "PartitionQueryRequest",
+    "PartitionReadRequest",
+    "PartitionResponse",
+    "ReadRequest",
+    "RequestOptions",
+    "RollbackRequest",
+    "Session",
+    "MultiplexedSessionPrecommitToken",
+    "Transaction",
+    "TransactionOptions",
+    "TransactionSelector",
+    "StructType",
+    "Type",
+    "TypeAnnotationCode",
+    "TypeCode",
+)

google/cloud/spanner_v1/types/commit_response.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from __future__ import annotations
+
+from typing import MutableMapping, MutableSequence
+
+import proto  # type: ignore
+
+from google.cloud.spanner_v1.types import transaction
+from google.protobuf import timestamp_pb2  # type: ignore
+
+
+__protobuf__ = proto.module(
+    package="google.spanner.v1",
+    manifest={
+        "CommitResponse",
+    },
+)
+
+
+class CommitResponse(proto.Message):
+    r"""The response for [Commit][google.spanner.v1.Spanner.Commit].
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    Attributes:
+        commit_timestamp (google.protobuf.timestamp_pb2.Timestamp):
+            The Cloud Spanner timestamp at which the
+            transaction committed.
+        commit_stats (google.cloud.spanner_v1.types.CommitResponse.CommitStats):
+            The statistics about this Commit. Not returned by default.
+            For more information, see
+            [CommitRequest.return_commit_stats][google.spanner.v1.CommitRequest.return_commit_stats].
+        precommit_token (google.cloud.spanner_v1.types.MultiplexedSessionPrecommitToken):
+            If specified, transaction has not committed
+            yet. Clients must retry the commit with the new
+            precommit token.
+
+            This field is a member of `oneof`_ ``MultiplexedSessionRetry``.
+    """
+
+    class CommitStats(proto.Message):
+        r"""Additional statistics about a commit.
+
+        Attributes:
+            mutation_count (int):
+                The total number of mutations for the transaction. Knowing
+                the ``mutation_count`` value can help you maximize the
+                number of mutations in a transaction and minimize the number
+                of API round trips. You can also monitor this value to
+                prevent transactions from exceeding the system
+                `limit <https://cloud.google.com/spanner/quotas#limits_for_creating_reading_updating_and_deleting_data>`__.
+                If the number of mutations exceeds the limit, the server
+                returns
+                `INVALID_ARGUMENT <https://cloud.google.com/spanner/docs/reference/rest/v1/Code#ENUM_VALUES.INVALID_ARGUMENT>`__.
+        """
+
+        mutation_count: int = proto.Field(
+            proto.INT64,
+            number=1,
+        )
+
+    commit_timestamp: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=1,
+        message=timestamp_pb2.Timestamp,
+    )
+    commit_stats: CommitStats = proto.Field(
+        proto.MESSAGE,
+        number=2,
+        message=CommitStats,
+    )
+    precommit_token: transaction.MultiplexedSessionPrecommitToken = proto.Field(
+        proto.MESSAGE,
+        number=4,
+        oneof="MultiplexedSessionRetry",
+        message=transaction.MultiplexedSessionPrecommitToken,
+    )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/spanner_v1/types/keys.py

@@ -0,0 +1,248 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from __future__ import annotations
+
+from typing import MutableMapping, MutableSequence
+
+import proto  # type: ignore
+
+from google.protobuf import struct_pb2  # type: ignore
+
+
+__protobuf__ = proto.module(
+    package="google.spanner.v1",
+    manifest={
+        "KeyRange",
+        "KeySet",
+    },
+)
+
+
+class KeyRange(proto.Message):
+    r"""KeyRange represents a range of rows in a table or index.
+
+    A range has a start key and an end key. These keys can be open or
+    closed, indicating if the range includes rows with that key.
+
+    Keys are represented by lists, where the ith value in the list
+    corresponds to the ith component of the table or index primary key.
+    Individual values are encoded as described
+    [here][google.spanner.v1.TypeCode].
+
+    For example, consider the following table definition:
+
+    ::
+
+        CREATE TABLE UserEvents (
+          UserName STRING(MAX),
+          EventDate STRING(10)
+        ) PRIMARY KEY(UserName, EventDate);
+
+    The following keys name rows in this table:
+
+    ::
+
+        ["Bob", "2014-09-23"]
+        ["Alfred", "2015-06-12"]
+
+    Since the ``UserEvents`` table's ``PRIMARY KEY`` clause names two
+    columns, each ``UserEvents`` key has two elements; the first is the
+    ``UserName``, and the second is the ``EventDate``.
+
+    Key ranges with multiple components are interpreted
+    lexicographically by component using the table or index key's
+    declared sort order. For example, the following range returns all
+    events for user ``"Bob"`` that occurred in the year 2015:
+
+    ::
+
+        "start_closed": ["Bob", "2015-01-01"]
+        "end_closed": ["Bob", "2015-12-31"]
+
+    Start and end keys can omit trailing key components. This affects
+    the inclusion and exclusion of rows that exactly match the provided
+    key components: if the key is closed, then rows that exactly match
+    the provided components are included; if the key is open, then rows
+    that exactly match are not included.
+
+    For example, the following range includes all events for ``"Bob"``
+    that occurred during and after the year 2000:
+
+    ::
+
+        "start_closed": ["Bob", "2000-01-01"]
+        "end_closed": ["Bob"]
+
+    The next example retrieves all events for ``"Bob"``:
+
+    ::
+
+        "start_closed": ["Bob"]
+        "end_closed": ["Bob"]
+
+    To retrieve events before the year 2000:
+
+    ::
+
+        "start_closed": ["Bob"]
+        "end_open": ["Bob", "2000-01-01"]
+
+    The following range includes all rows in the table:
+
+    ::
+
+        "start_closed": []
+        "end_closed": []
+
+    This range returns all users whose ``UserName`` begins with any
+    character from A to C:
+
+    ::
+
+        "start_closed": ["A"]
+        "end_open": ["D"]
+
+    This range returns all users whose ``UserName`` begins with B:
+
+    ::
+
+        "start_closed": ["B"]
+        "end_open": ["C"]
+
+    Key ranges honor column sort order. For example, suppose a table is
+    defined as follows:
+
+    ::
+
+        CREATE TABLE DescendingSortedTable {
+          Key INT64,
+          ...
+        ) PRIMARY KEY(Key DESC);
+
+    The following range retrieves all rows with key values between 1 and
+    100 inclusive:
+
+    ::
+
+        "start_closed": ["100"]
+        "end_closed": ["1"]
+
+    Note that 100 is passed as the start, and 1 is passed as the end,
+    because ``Key`` is a descending column in the schema.
+
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    Attributes:
+        start_closed (google.protobuf.struct_pb2.ListValue):
+            If the start is closed, then the range includes all rows
+            whose first ``len(start_closed)`` key columns exactly match
+            ``start_closed``.
+
+            This field is a member of `oneof`_ ``start_key_type``.
+        start_open (google.protobuf.struct_pb2.ListValue):
+            If the start is open, then the range excludes rows whose
+            first ``len(start_open)`` key columns exactly match
+            ``start_open``.
+
+            This field is a member of `oneof`_ ``start_key_type``.
+        end_closed (google.protobuf.struct_pb2.ListValue):
+            If the end is closed, then the range includes all rows whose
+            first ``len(end_closed)`` key columns exactly match
+            ``end_closed``.
+
+            This field is a member of `oneof`_ ``end_key_type``.
+        end_open (google.protobuf.struct_pb2.ListValue):
+            If the end is open, then the range excludes rows whose first
+            ``len(end_open)`` key columns exactly match ``end_open``.
+
+            This field is a member of `oneof`_ ``end_key_type``.
+    """
+
+    start_closed: struct_pb2.ListValue = proto.Field(
+        proto.MESSAGE,
+        number=1,
+        oneof="start_key_type",
+        message=struct_pb2.ListValue,
+    )
+    start_open: struct_pb2.ListValue = proto.Field(
+        proto.MESSAGE,
+        number=2,
+        oneof="start_key_type",
+        message=struct_pb2.ListValue,
+    )
+    end_closed: struct_pb2.ListValue = proto.Field(
+        proto.MESSAGE,
+        number=3,
+        oneof="end_key_type",
+        message=struct_pb2.ListValue,
+    )
+    end_open: struct_pb2.ListValue = proto.Field(
+        proto.MESSAGE,
+        number=4,
+        oneof="end_key_type",
+        message=struct_pb2.ListValue,
+    )
+
+
+class KeySet(proto.Message):
+    r"""``KeySet`` defines a collection of Cloud Spanner keys and/or key
+    ranges. All the keys are expected to be in the same table or index.
+    The keys need not be sorted in any particular way.
+
+    If the same key is specified multiple times in the set (for example
+    if two ranges, two keys, or a key and a range overlap), Cloud
+    Spanner behaves as if the key were only specified once.
+
+    Attributes:
+        keys (MutableSequence[google.protobuf.struct_pb2.ListValue]):
+            A list of specific keys. Entries in ``keys`` should have
+            exactly as many elements as there are columns in the primary
+            or index key with which this ``KeySet`` is used. Individual
+            key values are encoded as described
+            [here][google.spanner.v1.TypeCode].
+        ranges (MutableSequence[google.cloud.spanner_v1.types.KeyRange]):
+            A list of key ranges. See
+            [KeyRange][google.spanner.v1.KeyRange] for more information
+            about key range specifications.
+        all_ (bool):
+            For convenience ``all`` can be set to ``true`` to indicate
+            that this ``KeySet`` matches all keys in the table or index.
+            Note that any keys specified in ``keys`` or ``ranges`` are
+            only yielded once.
+    """
+
+    keys: MutableSequence[struct_pb2.ListValue] = proto.RepeatedField(
+        proto.MESSAGE,
+        number=1,
+        message=struct_pb2.ListValue,
+    )
+    ranges: MutableSequence["KeyRange"] = proto.RepeatedField(
+        proto.MESSAGE,
+        number=2,
+        message="KeyRange",
+    )
+    all_: bool = proto.Field(
+        proto.BOOL,
+        number=3,
+    )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/spanner_v1/types/mutation.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from __future__ import annotations
+
+from typing import MutableMapping, MutableSequence
+
+import proto  # type: ignore
+
+from google.cloud.spanner_v1.types import keys
+from google.protobuf import struct_pb2  # type: ignore
+
+
+__protobuf__ = proto.module(
+    package="google.spanner.v1",
+    manifest={
+        "Mutation",
+    },
+)
+
+
+class Mutation(proto.Message):
+    r"""A modification to one or more Cloud Spanner rows. Mutations can be
+    applied to a Cloud Spanner database by sending them in a
+    [Commit][google.spanner.v1.Spanner.Commit] call.
+
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    Attributes:
+        insert (google.cloud.spanner_v1.types.Mutation.Write):
+            Insert new rows in a table. If any of the rows already
+            exist, the write or transaction fails with error
+            ``ALREADY_EXISTS``.
+
+            This field is a member of `oneof`_ ``operation``.
+        update (google.cloud.spanner_v1.types.Mutation.Write):
+            Update existing rows in a table. If any of the rows does not
+            already exist, the transaction fails with error
+            ``NOT_FOUND``.
+
+            This field is a member of `oneof`_ ``operation``.
+        insert_or_update (google.cloud.spanner_v1.types.Mutation.Write):
+            Like [insert][google.spanner.v1.Mutation.insert], except
+            that if the row already exists, then its column values are
+            overwritten with the ones provided. Any column values not
+            explicitly written are preserved.
+
+            When using
+            [insert_or_update][google.spanner.v1.Mutation.insert_or_update],
+            just as when using
+            [insert][google.spanner.v1.Mutation.insert], all
+            ``NOT NULL`` columns in the table must be given a value.
+            This holds true even when the row already exists and will
+            therefore actually be updated.
+
+            This field is a member of `oneof`_ ``operation``.
+        replace (google.cloud.spanner_v1.types.Mutation.Write):
+            Like [insert][google.spanner.v1.Mutation.insert], except
+            that if the row already exists, it is deleted, and the
+            column values provided are inserted instead. Unlike
+            [insert_or_update][google.spanner.v1.Mutation.insert_or_update],
+            this means any values not explicitly written become
+            ``NULL``.
+
+            In an interleaved table, if you create the child table with
+            the ``ON DELETE CASCADE`` annotation, then replacing a
+            parent row also deletes the child rows. Otherwise, you must
+            delete the child rows before you replace the parent row.
+
+            This field is a member of `oneof`_ ``operation``.
+        delete (google.cloud.spanner_v1.types.Mutation.Delete):
+            Delete rows from a table. Succeeds whether or
+            not the named rows were present.
+
+            This field is a member of `oneof`_ ``operation``.
+    """
+
+    class Write(proto.Message):
+        r"""Arguments to [insert][google.spanner.v1.Mutation.insert],
+        [update][google.spanner.v1.Mutation.update],
+        [insert_or_update][google.spanner.v1.Mutation.insert_or_update], and
+        [replace][google.spanner.v1.Mutation.replace] operations.
+
+        Attributes:
+            table (str):
+                Required. The table whose rows will be
+                written.
+            columns (MutableSequence[str]):
+                The names of the columns in
+                [table][google.spanner.v1.Mutation.Write.table] to be
+                written.
+
+                The list of columns must contain enough columns to allow
+                Cloud Spanner to derive values for all primary key columns
+                in the row(s) to be modified.
+            values (MutableSequence[google.protobuf.struct_pb2.ListValue]):
+                The values to be written. ``values`` can contain more than
+                one list of values. If it does, then multiple rows are
+                written, one for each entry in ``values``. Each list in
+                ``values`` must have exactly as many entries as there are
+                entries in
+                [columns][google.spanner.v1.Mutation.Write.columns] above.
+                Sending multiple lists is equivalent to sending multiple
+                ``Mutation``\ s, each containing one ``values`` entry and
+                repeating [table][google.spanner.v1.Mutation.Write.table]
+                and [columns][google.spanner.v1.Mutation.Write.columns].
+                Individual values in each list are encoded as described
+                [here][google.spanner.v1.TypeCode].
+        """
+
+        table: str = proto.Field(
+            proto.STRING,
+            number=1,
+        )
+        columns: MutableSequence[str] = proto.RepeatedField(
+            proto.STRING,
+            number=2,
+        )
+        values: MutableSequence[struct_pb2.ListValue] = proto.RepeatedField(
+            proto.MESSAGE,
+            number=3,
+            message=struct_pb2.ListValue,
+        )
+
+    class Delete(proto.Message):
+        r"""Arguments to [delete][google.spanner.v1.Mutation.delete] operations.
+
+        Attributes:
+            table (str):
+                Required. The table whose rows will be
+                deleted.
+            key_set (google.cloud.spanner_v1.types.KeySet):
+                Required. The primary keys of the rows within
+                [table][google.spanner.v1.Mutation.Delete.table] to delete.
+                The primary keys must be specified in the order in which
+                they appear in the ``PRIMARY KEY()`` clause of the table's
+                equivalent DDL statement (the DDL statement used to create
+                the table). Delete is idempotent. The transaction will
+                succeed even if some or all rows do not exist.
+        """
+
+        table: str = proto.Field(
+            proto.STRING,
+            number=1,
+        )
+        key_set: keys.KeySet = proto.Field(
+            proto.MESSAGE,
+            number=2,
+            message=keys.KeySet,
+        )
+
+    insert: Write = proto.Field(
+        proto.MESSAGE,
+        number=1,
+        oneof="operation",
+        message=Write,
+    )
+    update: Write = proto.Field(
+        proto.MESSAGE,
+        number=2,
+        oneof="operation",
+        message=Write,
+    )
+    insert_or_update: Write = proto.Field(
+        proto.MESSAGE,
+        number=3,
+        oneof="operation",
+        message=Write,
+    )
+    replace: Write = proto.Field(
+        proto.MESSAGE,
+        number=4,
+        oneof="operation",
+        message=Write,
+    )
+    delete: Delete = proto.Field(
+        proto.MESSAGE,
+        number=5,
+        oneof="operation",
+        message=Delete,
+    )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))