sqlalchemy-boltons 1.0.0__tar.gz → 1.1.0__tar.gz

{sqlalchemy_boltons-1.0.0 → sqlalchemy_boltons-1.1.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-03-11
+
+### Changed
+
+- `sqlite`: Use an unlimited-size QueuePool by default.
+
+## [1.0.1] - 2025-02-22
+
+### Changed
+
+- Improve the documentation.
+
 ## [1.0.0] - 2025-02-22
 
 ### Added

sqlalchemy_boltons-1.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.1
+Name: sqlalchemy_boltons
+Version: 1.1.0
+Summary: Utilities that should've been inside SQLAlchemy but aren't
+Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
+Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
+License: MIT
+Project-URL: Homepage, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/
+Project-URL: Changelog, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/file?name=CHANGELOG.md&ci=trunk
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+
+# sqlalchemy_boltons
+
+SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
+"bolted on".
+
+(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
+
+## sqlite
+
+SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. This module implements the
+[usual fix](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl)
+for that well-known broken behaviour, and also adds extra features on top of that.
+
+You can [customize](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine.execution_options),
+on a per-engine or per-connection basis:
+
+- `x_sqlite_begin_mode`: The type of transaction to be started, such as "BEGIN" or
+  "[BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html)" (or
+  "[BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md)" someday maybe).
+- `x_sqlite_foreign_keys`: The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be
+  `True`, `False`, or `"defer"`.
+- `x_sqlite_journal_mode`: The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as
+  `"DELETE"` or `"WAL"`.
+
+Here's a minimal example:
+
+```python
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy_boltons.sqlite import create_engine_sqlite
+
+engine = create_engine_sqlite(
+    "file.db",
+    journal_mode="WAL",
+    timeout=0.5,
+    create_engine_args={"echo": True},
+)
+
+# Configure the engine to use a plain "BEGIN" to start transactions and
+# and to use deferred enforcement of foreign keys (recommended!)
+engine = engine.execution_options(
+    x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer"
+)
+
+# Make a separate engine for write transactions using "BEGIN IMMEDIATE"
+# for eager locking.
+engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
+
+# Construct a sessionmaker for each engine.
+Session = sessionmaker(engine)
+SessionW = sessionmaker(engine_w)
+
+# read-only transaction
+with Session() as session:
+    session.execute(select(...))
+
+# lock the database eagerly for writing
+with SessionW() as session:
+    session.execute(update(...))
+```

sqlalchemy_boltons-1.1.0/README.md

@@ -0,0 +1,59 @@
+# sqlalchemy_boltons
+
+SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
+"bolted on".
+
+(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
+
+## sqlite
+
+SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. This module implements the
+[usual fix](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl)
+for that well-known broken behaviour, and also adds extra features on top of that.
+
+You can [customize](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine.execution_options),
+on a per-engine or per-connection basis:
+
+- `x_sqlite_begin_mode`: The type of transaction to be started, such as "BEGIN" or
+  "[BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html)" (or
+  "[BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md)" someday maybe).
+- `x_sqlite_foreign_keys`: The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be
+  `True`, `False`, or `"defer"`.
+- `x_sqlite_journal_mode`: The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as
+  `"DELETE"` or `"WAL"`.
+
+Here's a minimal example:
+
+```python
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy_boltons.sqlite import create_engine_sqlite
+
+engine = create_engine_sqlite(
+    "file.db",
+    journal_mode="WAL",
+    timeout=0.5,
+    create_engine_args={"echo": True},
+)
+
+# Configure the engine to use a plain "BEGIN" to start transactions and
+# and to use deferred enforcement of foreign keys (recommended!)
+engine = engine.execution_options(
+    x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer"
+)
+
+# Make a separate engine for write transactions using "BEGIN IMMEDIATE"
+# for eager locking.
+engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
+
+# Construct a sessionmaker for each engine.
+Session = sessionmaker(engine)
+SessionW = sessionmaker(engine_w)
+
+# read-only transaction
+with Session() as session:
+    session.execute(select(...))
+
+# lock the database eagerly for writing
+with SessionW() as session:
+    session.execute(update(...))
+```

{sqlalchemy_boltons-1.0.0 → sqlalchemy_boltons-1.1.0}/pyproject.toml

@@ -3,7 +3,7 @@ line-length = 120
 
 [project]
 name = "sqlalchemy_boltons"
-version = "1.0.0"
+version = "1.1.0"
 description = "Utilities that should've been inside SQLAlchemy but aren't"
 readme = "README.md"
 license = { text = "MIT" }

{sqlalchemy_boltons-1.0.0 → sqlalchemy_boltons-1.1.0}/src/sqlalchemy_boltons/sqlite.py

@@ -54,6 +54,16 @@ class SQLAlchemySqliteTransactionFix:
     This class exists because sqlalchemy doesn't automatically fix pysqlite's stupid default behaviour. Additionally,
     we implement support for foreign keys.
 
+    The execution options we look for are as follows:
+
+    - `x_sqlite_begin_mode`: The type of transaction to be started, such as "BEGIN" or
+      "[BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html)" (or
+      "[BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md)" someday maybe).
+    - `x_sqlite_foreign_keys`: The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Must be
+      `True`, `False`, or `"defer"`.
+    - `x_sqlite_journal_mode`: The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as
+      `"DELETE"` or `"WAL"`. Optional.
+
     https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl
     """
 
@@ -188,6 +198,9 @@ def create_engine_sqlite(
     # always default to QueuePool
     if (k := "poolclass") not in create_engine_args:
         create_engine_args[k] = sap.QueuePool
+        if (k := "max_overflow") not in create_engine_args:
+            # for SQLite it doesn't make sense to restrict the number of concurrent (read-only) connections
+            create_engine_args["max_overflow"] = -1
 
     if (v := create_engine_args.get(k := "connect_args")) is None:
         create_engine_args[k] = v = {}

sqlalchemy_boltons-1.1.0/src/sqlalchemy_boltons.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.1
+Name: sqlalchemy-boltons
+Version: 1.1.0
+Summary: Utilities that should've been inside SQLAlchemy but aren't
+Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
+Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
+License: MIT
+Project-URL: Homepage, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/
+Project-URL: Changelog, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/file?name=CHANGELOG.md&ci=trunk
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+
+# sqlalchemy_boltons
+
+SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
+"bolted on".
+
+(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
+
+## sqlite
+
+SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. This module implements the
+[usual fix](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl)
+for that well-known broken behaviour, and also adds extra features on top of that.
+
+You can [customize](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine.execution_options),
+on a per-engine or per-connection basis:
+
+- `x_sqlite_begin_mode`: The type of transaction to be started, such as "BEGIN" or
+  "[BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html)" (or
+  "[BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md)" someday maybe).
+- `x_sqlite_foreign_keys`: The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be
+  `True`, `False`, or `"defer"`.
+- `x_sqlite_journal_mode`: The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as
+  `"DELETE"` or `"WAL"`.
+
+Here's a minimal example:
+
+```python
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy_boltons.sqlite import create_engine_sqlite
+
+engine = create_engine_sqlite(
+    "file.db",
+    journal_mode="WAL",
+    timeout=0.5,
+    create_engine_args={"echo": True},
+)
+
+# Configure the engine to use a plain "BEGIN" to start transactions and
+# and to use deferred enforcement of foreign keys (recommended!)
+engine = engine.execution_options(
+    x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer"
+)
+
+# Make a separate engine for write transactions using "BEGIN IMMEDIATE"
+# for eager locking.
+engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
+
+# Construct a sessionmaker for each engine.
+Session = sessionmaker(engine)
+SessionW = sessionmaker(engine_w)
+
+# read-only transaction
+with Session() as session:
+    session.execute(select(...))
+
+# lock the database eagerly for writing
+with SessionW() as session:
+    session.execute(update(...))
+```

{sqlalchemy_boltons-1.0.0 → sqlalchemy_boltons-1.1.0}/tests/test_sqlite.py

@@ -54,7 +54,9 @@ def simple_sqlite_engine(tmp_path, database_type):
     else:
         raise AssertionError
 
-    return _sq.create_engine_sqlite(path, journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True})
+    return _sq.create_engine_sqlite(
+        path, journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True, "pool_timeout": 2}
+    )
 
 
 @pytest.mark.parametrize("database_type", ["file", "memory"])
@@ -117,6 +119,12 @@ def test_transaction(simple_sqlite_engine, database_type):
         assert len(s.execute(sa.select(Example)).all()) == 2
         s.commit()
 
+    with contextlib.ExitStack() as exit_stack:
+        # concurrent connection count
+        for i in range(30):
+            exit_stack.enter_context(s := SessionR())
+            assert len(s.execute(sa.select(Example)).all()) == 2
+
 
 @pytest.mark.parametrize("path_type", ["str", "Path"])
 def test_create_engine_path(tmp_path, path_type):

sqlalchemy_boltons-1.0.0/PKG-INFO

@@ -1,57 +0,0 @@
-Metadata-Version: 2.1
-Name: sqlalchemy_boltons
-Version: 1.0.0
-Summary: Utilities that should've been inside SQLAlchemy but aren't
-Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
-Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
-License: MIT
-Project-URL: Homepage, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/
-Project-URL: Changelog, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/file?name=CHANGELOG.md&ci=trunk
-Classifier: Programming Language :: Python :: 3
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: AUTHORS.md
-
-# sqlalchemy_boltons
-
-SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
-"bolted on".
-
-(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
-
-## sqlite
-
-SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. Instead, it provides a recipe for doing so
-inside the [documentation](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl).
-This module implements a fix for that broken behaviour.
-
-You can customize, on a per-engine or per-connection basis:
-
-- The type of transaction to be started, such as BEGIN or
-  [BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html) (or
-  [BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md) someday maybe).
-- The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be `True`, `False`, or `"defer"`.
-- The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as DELETE or WAL.
-
-```python
-from sqlalchemy.orm import sessionmaker
-from sqlalchemy_boltons.sqlite import create_engine_sqlite
-
-engine = create_engine_sqlite("file.db", journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True})
-
-# use standard "BEGIN" and use deferred enforcement of foreign keys
-engine = engine.execution_options(x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer")
-
-# make a separate engine for write transactions using "BEGIN IMMEDIATE" for eager locking
-engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
-
-Session = sessionmaker(engine)
-SessionW = sessionmaker(engine_w)
-
-with Session() as session:
-    session.execute(select(...))
-
-# this locks the database eagerly
-with SessionW() as session:
-    session.execute(update(...))
-```

sqlalchemy_boltons-1.0.0/README.md

@@ -1,43 +0,0 @@
-# sqlalchemy_boltons
-
-SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
-"bolted on".
-
-(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
-
-## sqlite
-
-SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. Instead, it provides a recipe for doing so
-inside the [documentation](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl).
-This module implements a fix for that broken behaviour.
-
-You can customize, on a per-engine or per-connection basis:
-
-- The type of transaction to be started, such as BEGIN or
-  [BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html) (or
-  [BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md) someday maybe).
-- The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be `True`, `False`, or `"defer"`.
-- The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as DELETE or WAL.
-
-```python
-from sqlalchemy.orm import sessionmaker
-from sqlalchemy_boltons.sqlite import create_engine_sqlite
-
-engine = create_engine_sqlite("file.db", journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True})
-
-# use standard "BEGIN" and use deferred enforcement of foreign keys
-engine = engine.execution_options(x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer")
-
-# make a separate engine for write transactions using "BEGIN IMMEDIATE" for eager locking
-engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
-
-Session = sessionmaker(engine)
-SessionW = sessionmaker(engine_w)
-
-with Session() as session:
-    session.execute(select(...))
-
-# this locks the database eagerly
-with SessionW() as session:
-    session.execute(update(...))
-```

sqlalchemy_boltons-1.0.0/src/sqlalchemy_boltons.egg-info/PKG-INFO

@@ -1,57 +0,0 @@
-Metadata-Version: 2.1
-Name: sqlalchemy-boltons
-Version: 1.0.0
-Summary: Utilities that should've been inside SQLAlchemy but aren't
-Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
-Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
-License: MIT
-Project-URL: Homepage, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/
-Project-URL: Changelog, https://hydra.ecd.space/deaduard/sqlalchemy_boltons/file?name=CHANGELOG.md&ci=trunk
-Classifier: Programming Language :: Python :: 3
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: AUTHORS.md
-
-# sqlalchemy_boltons
-
-SQLAlchemy is great. However, it doesn't have everything built-in. Some important things are missing, and need to be
-"bolted on".
-
-(Name inspired from [boltons](https://pypi.org/project/boltons/). Not affiliated.)
-
-## sqlite
-
-SQLAlchemy doesn't automatically fix pysqlite's broken transaction handling. Instead, it provides a recipe for doing so
-inside the [documentation](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl).
-This module implements a fix for that broken behaviour.
-
-You can customize, on a per-engine or per-connection basis:
-
-- The type of transaction to be started, such as BEGIN or
-  [BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html) (or
-  [BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md) someday maybe).
-- The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Can be `True`, `False`, or `"defer"`.
-- The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as DELETE or WAL.
-
-```python
-from sqlalchemy.orm import sessionmaker
-from sqlalchemy_boltons.sqlite import create_engine_sqlite
-
-engine = create_engine_sqlite("file.db", journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True})
-
-# use standard "BEGIN" and use deferred enforcement of foreign keys
-engine = engine.execution_options(x_sqlite_begin_mode=None, x_sqlite_foreign_keys="defer")
-
-# make a separate engine for write transactions using "BEGIN IMMEDIATE" for eager locking
-engine_w = engine.execution_options(x_sqlite_begin_mode="IMMEDIATE")
-
-Session = sessionmaker(engine)
-SessionW = sessionmaker(engine_w)
-
-with Session() as session:
-    session.execute(select(...))
-
-# this locks the database eagerly
-with SessionW() as session:
-    session.execute(update(...))
-```