sqlalchemy-spanner 1.6.2__tar.gz → 1.8.0__tar.gz

{sqlalchemy-spanner-1.6.2/sqlalchemy_spanner.egg-info → sqlalchemy_spanner-1.8.0}/PKG-INFO

@@ -1,13 +1,19 @@
 Metadata-Version: 2.1
 Name: sqlalchemy-spanner
-Version: 1.6.2
+Version: 1.8.0
 Summary: SQLAlchemy dialect integrated into Cloud Spanner database
 Home-page: https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy
 Author: Google LLC
 Author-email: cloud-spanner-developers@googlegroups.com
 Classifier: Intended Audience :: Developers
-Provides-Extra: tracing
 License-File: LICENSE
+Requires-Dist: sqlalchemy>=1.1.13
+Requires-Dist: google-cloud-spanner>=3.12.0
+Requires-Dist: alembic
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-api>=1.1.0; extra == "tracing"
+Requires-Dist: opentelemetry-sdk>=1.1.0; extra == "tracing"
+Requires-Dist: opentelemetry-instrumentation>=0.20b0; extra == "tracing"
 
 Spanner dialect for SQLAlchemy
 ==============================
@@ -69,6 +75,13 @@ Next install the package from the package ``setup.py`` file:
 
 During setup the dialect will be registered with entry points.
 
+Samples
+-------------
+
+The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
+contains multiple examples for how to configure and use common Spanner features.
+
+
 A Minimal App
 -------------
 
@@ -84,7 +97,7 @@ on this step in a dialect prefix part:
    # for SQLAlchemy 1.3:
    spanner:///projects/project-id/instances/instance-id/databases/database-id
 
-   # for SQLAlchemy 1.4:
+   # for SQLAlchemy 1.4 and 2.0:
    spanner+spanner:///projects/project-id/instances/instance-id/databases/database-id
 
 To pass your custom client object directly to be be used, create engine as following:
@@ -241,7 +254,7 @@ Unique constraints
 ~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support direct UNIQUE constraints creation. In
-order to achieve column values uniqueness UNIQUE indexes should be used.
+order to achieve column values uniqueness, UNIQUE indexes should be used.
 
 Instead of direct UNIQUE constraint creation:
 
@@ -269,10 +282,16 @@ Autocommit mode
 ~~~~~~~~~~~~~~~
 
 Spanner dialect supports both ``SERIALIZABLE`` and ``AUTOCOMMIT``
-isolation levels. ``SERIALIZABLE`` is the default one, where
-transactions need to be committed manually. ``AUTOCOMMIT`` mode
-corresponds to automatically committing of a query right in its
-execution time.
+isolation levels. ``SERIALIZABLE`` is the default isolation level.
+
+``AUTOCOMMIT`` mode corresponds to automatically committing each
+insert/update/delete statement right after is has been executed.
+Queries that are executed in ``AUTOCOMMIT`` mode use a single-use
+read-only transaction. These do not take any locks and do not need
+to be committed.
+
+Workloads that only read data, should use either ``AUTOCOMMIT`` or
+a read-only transaction.
 
 Isolation level change example:
 
@@ -283,7 +302,7 @@ Isolation level change example:
    eng = create_engine("spanner:///projects/project-id/instances/instance-id/databases/database-id")
    autocommit_engine = eng.execution_options(isolation_level="AUTOCOMMIT")
 
-Automatic transactions retry
+Automatic transaction retry
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In the default ``SERIALIZABLE`` mode transactions may fail with ``Aborted`` exception. This is a transient kind of errors, which mostly happen to prevent data corruption by concurrent modifications. Though the original transaction becomes non operational, a simple retry of the queries solves the issue.
 
@@ -291,8 +310,8 @@ This, however, may require to manually repeat a long list of operations, execute
 
 In ``AUTOCOMMIT`` mode automatic transactions retry mechanism is disabled, as every operation is committed just in time, and there is no way an ``Aborted`` exception can happen.
 
-Autoincremented IDs
-~~~~~~~~~~~~~~~~~~~
+Auto-incremented IDs
+~~~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support autoincremented IDs mechanism due to
 performance reasons (`see for more
@@ -348,8 +367,9 @@ ReadOnly transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
 By default, transactions produced by a Spanner connection are in
-ReadWrite mode. However, some applications require an ability to grant
-ReadOnly access to users/methods; for these cases Spanner dialect
+ReadWrite mode. However, workloads that only read data perform better
+if they use read-only transactions, as Spanner does not need to take
+locks for the data that is read; for these cases, the Spanner dialect
 supports the ``read_only`` execution option, which switches a connection
 into ReadOnly mode:
 
@@ -358,11 +378,13 @@ into ReadOnly mode:
    with engine.connect().execution_options(read_only=True) as connection:
        connection.execute(select(["*"], from_obj=table)).fetchall()
 
-Note that execution options are applied lazily - on the ``execute()``
-method call, right before it.
+See the `Read-only transaction sample
+<https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/read_only_transaction_sample.py>`__
+for a concrete example.
 
 ReadOnly/ReadWrite mode of a connection can't be changed while a
-transaction is in progress - first you must commit or rollback it.
+transaction is in progress - you must commit or rollback the current
+transaction before changing the mode.
 
 Stale reads
 ~~~~~~~~~~~
@@ -519,7 +541,7 @@ run the tests the ``nox`` package commands can be used:
 Running tests on Spanner emulator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The dialect test suite can be runned on `Spanner
+The dialect test suite can be run on `Spanner
 emulator <https://cloud.google.com/spanner/docs/emulator>`__. Several
 tests, relating to ``NULL`` values of data types, are skipped when
 executed on emulator.

sqlalchemy-spanner-1.6.2/PKG-INFO → sqlalchemy_spanner-1.8.0/README.rst

@@ -1,14 +1,3 @@
-Metadata-Version: 2.1
-Name: sqlalchemy-spanner
-Version: 1.6.2
-Summary: SQLAlchemy dialect integrated into Cloud Spanner database
-Home-page: https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy
-Author: Google LLC
-Author-email: cloud-spanner-developers@googlegroups.com
-Classifier: Intended Audience :: Developers
-Provides-Extra: tracing
-License-File: LICENSE
-
 Spanner dialect for SQLAlchemy
 ==============================
 
@@ -69,6 +58,13 @@ Next install the package from the package ``setup.py`` file:
 
 During setup the dialect will be registered with entry points.
 
+Samples
+-------------
+
+The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
+contains multiple examples for how to configure and use common Spanner features.
+
+
 A Minimal App
 -------------
 
@@ -84,7 +80,7 @@ on this step in a dialect prefix part:
    # for SQLAlchemy 1.3:
    spanner:///projects/project-id/instances/instance-id/databases/database-id
 
-   # for SQLAlchemy 1.4:
+   # for SQLAlchemy 1.4 and 2.0:
    spanner+spanner:///projects/project-id/instances/instance-id/databases/database-id
 
 To pass your custom client object directly to be be used, create engine as following:
@@ -241,7 +237,7 @@ Unique constraints
 ~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support direct UNIQUE constraints creation. In
-order to achieve column values uniqueness UNIQUE indexes should be used.
+order to achieve column values uniqueness, UNIQUE indexes should be used.
 
 Instead of direct UNIQUE constraint creation:
 
@@ -269,10 +265,16 @@ Autocommit mode
 ~~~~~~~~~~~~~~~
 
 Spanner dialect supports both ``SERIALIZABLE`` and ``AUTOCOMMIT``
-isolation levels. ``SERIALIZABLE`` is the default one, where
-transactions need to be committed manually. ``AUTOCOMMIT`` mode
-corresponds to automatically committing of a query right in its
-execution time.
+isolation levels. ``SERIALIZABLE`` is the default isolation level.
+
+``AUTOCOMMIT`` mode corresponds to automatically committing each
+insert/update/delete statement right after is has been executed.
+Queries that are executed in ``AUTOCOMMIT`` mode use a single-use
+read-only transaction. These do not take any locks and do not need
+to be committed.
+
+Workloads that only read data, should use either ``AUTOCOMMIT`` or
+a read-only transaction.
 
 Isolation level change example:
 
@@ -283,7 +285,7 @@ Isolation level change example:
    eng = create_engine("spanner:///projects/project-id/instances/instance-id/databases/database-id")
    autocommit_engine = eng.execution_options(isolation_level="AUTOCOMMIT")
 
-Automatic transactions retry
+Automatic transaction retry
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In the default ``SERIALIZABLE`` mode transactions may fail with ``Aborted`` exception. This is a transient kind of errors, which mostly happen to prevent data corruption by concurrent modifications. Though the original transaction becomes non operational, a simple retry of the queries solves the issue.
 
@@ -291,8 +293,8 @@ This, however, may require to manually repeat a long list of operations, execute
 
 In ``AUTOCOMMIT`` mode automatic transactions retry mechanism is disabled, as every operation is committed just in time, and there is no way an ``Aborted`` exception can happen.
 
-Autoincremented IDs
-~~~~~~~~~~~~~~~~~~~
+Auto-incremented IDs
+~~~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support autoincremented IDs mechanism due to
 performance reasons (`see for more
@@ -348,8 +350,9 @@ ReadOnly transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
 By default, transactions produced by a Spanner connection are in
-ReadWrite mode. However, some applications require an ability to grant
-ReadOnly access to users/methods; for these cases Spanner dialect
+ReadWrite mode. However, workloads that only read data perform better
+if they use read-only transactions, as Spanner does not need to take
+locks for the data that is read; for these cases, the Spanner dialect
 supports the ``read_only`` execution option, which switches a connection
 into ReadOnly mode:
 
@@ -358,11 +361,13 @@ into ReadOnly mode:
    with engine.connect().execution_options(read_only=True) as connection:
        connection.execute(select(["*"], from_obj=table)).fetchall()
 
-Note that execution options are applied lazily - on the ``execute()``
-method call, right before it.
+See the `Read-only transaction sample
+<https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/read_only_transaction_sample.py>`__
+for a concrete example.
 
 ReadOnly/ReadWrite mode of a connection can't be changed while a
-transaction is in progress - first you must commit or rollback it.
+transaction is in progress - you must commit or rollback the current
+transaction before changing the mode.
 
 Stale reads
 ~~~~~~~~~~~
@@ -519,7 +524,7 @@ run the tests the ``nox`` package commands can be used:
 Running tests on Spanner emulator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The dialect test suite can be runned on `Spanner
+The dialect test suite can be run on `Spanner
 emulator <https://cloud.google.com/spanner/docs/emulator>`__. Several
 tests, relating to ``NULL`` values of data types, are skipped when
 executed on emulator.

{sqlalchemy-spanner-1.6.2 → sqlalchemy_spanner-1.8.0}/google/cloud/sqlalchemy_spanner/_opentelemetry_tracing.py

@@ -14,6 +14,9 @@
 
 """Manages OpenTelemetry trace creation and handling"""
 
+import collections
+import os
+
 from contextlib import contextmanager
 
 from google.api_core.exceptions import GoogleAPICallError
@@ -46,6 +49,16 @@ def trace_call(name, extra_attributes=None):
     }
 
     if extra_attributes:
+        if os.environ.get("SQLALCHEMY_SPANNER_TRACE_HIDE_QUERY_PARAMETERS"):
+            extra_attributes.pop("db.params", None)
+
+        # Stringify "db.params" sequence values before sending to OpenTelemetry,
+        # otherwise OpenTelemetry may log a Warning if types differ.
+        if isinstance(extra_attributes, dict):
+            for k, v in extra_attributes.items():
+                if k == "db.params" and isinstance(v, collections.abc.Sequence):
+                    extra_attributes[k] = [str(e) for e in v]
+
         attributes.update(extra_attributes)
 
     with tracer.start_as_current_span(

sqlalchemy_spanner-1.8.0/google/cloud/sqlalchemy_spanner/dml.py

@@ -0,0 +1,26 @@
+# Copyright 2024 Google LLC All rights reserved.
+#
+# 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 sqlalchemy import Insert, insert
+from sqlalchemy.sql._typing import _DMLTableArgument
+
+
+def insert_or_update(table: _DMLTableArgument) -> Insert:
+    """Construct a Spanner-specific insert-or-update statement."""
+    return insert(table).prefix_with("OR UPDATE")
+
+
+def insert_or_ignore(table: _DMLTableArgument) -> Insert:
+    """Construct a Spanner-specific insert-or-ignore statement."""
+    return insert(table).prefix_with("OR IGNORE")

{sqlalchemy-spanner-1.6.2 → sqlalchemy_spanner-1.8.0}/google/cloud/sqlalchemy_spanner/requirements.py

@@ -81,7 +81,7 @@ class Requirements(SuiteRequirements):  # pragma: no cover
 
     @property
     def sequences(self):
-        return exclusions.closed()
+        return exclusions.open()
 
     @property
     def temporary_tables(self):