Update docs for new flat_transaction function

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 See also: [Github Release Page](https://github.com/enpaul/peewee-plus/releases).
 
+## Version 1.1.0
+
+View this release on: [Github](https://github.com/enpaul/peewee-plus/releases/tag/1.1.0),
+[PyPI](https://pypi.org/project/peewee-plus/1.1.0/)
+
+- Add decorator function for wrapping callables in a flat database transaction
+
 ## Version 1.0.0
 
 View this release on: [Github](https://github.com/enpaul/peewee-plus/releases/tag/1.0.0),

README.md

@@ -55,25 +55,29 @@ when using SQLite
 
 ### Functions
 
-[`calc_batch_size`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L68) -
+[`calc_batch_size`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L71) -
 Helper function for determining how to batch a create/update query with SQLite
 
+[`flat_transaction`](https://github.com/enpaul/peewee-plus/blob/devel/peewee_plus.py#L137)
+\- Decorator function for wrapping callables in a database transaction without creating
+nested transactions
+
 ### Classes
 
-[`PathField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#134) - A
+[`PathField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#179) - A
 Peewee database field for storing
 [Pathlib](https://docs.python.org/3/library/pathlib.html) objects, optionally relative to
 a runtime value.
 
-[`PrecisionFloatField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L192)
+[`PrecisionFloatField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L237)
 \- A Peewee database field for storing floats while specifying the
 [MySQL precision parameters](https://dev.mysql.com/doc/refman/8.0/en/floating-point-types.html)
 `M` and `D`
 
-[`JSONField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L222) - A
+[`JSONField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L267) - A
 Peewee database field for storing arbitrary JSON-serializable data
 
-[`EnumField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L277) - A
+[`EnumField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L322) - A
 Peewee database field for storing Enums by name
 
 ## For Developers

peewee_plus.py

@@ -12,7 +12,9 @@
 
 .. _`Peewee documentation`: http://docs.peewee-orm.com/en/latest/peewee/database.html#recommended-settings
 """
+import contextlib
 import enum
+import functools
 import json
 from pathlib import Path
 from typing import Any
@@ -26,7 +28,7 @@ import peewee
 
 
 __title__ = "peewee-plus"
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __license__ = "MIT"
 __summary__ = "Various extensions, helpers, and utilities for Peewee"
 __url__ = "https://github.com/enpaul/peewee-plus/"
@@ -42,6 +44,7 @@ __all__ = [
     "__authors__",
     "calc_batch_size",
     "EnumField",
+    "flat_transaction",
     "JSONField",
     "PathField",
     "PrecisionFloatField",
@@ -131,6 +134,48 @@ def calc_batch_size(
     return len(models)
 
 
+def flat_transaction(interface: peewee.Database):
+    """Database transaction wrapper that avoids nested transactions
+
+    A decorator that can be used to decorate functions or methods so that the entire callable
+    is executed in a single transaction context. If a transaction is already open then it will
+    be reused rather than opening a nested transaction.
+
+    Example usage:
+
+    .. code-block:: python
+
+      db = peewee.SqliteDatabase("test.db")
+
+
+      @flat_transaction(db)
+      def subquery():
+          ...
+
+
+      @flat_transaction(db)
+      def my_query():
+          ...
+          subquery()
+
+
+      # This call opens only a single transaction
+      my_query()
+
+    :param interface: Peewee database interface that should be used to open the transaction
+    """
+
+    def outer(func):
+        @functools.wraps(func)
+        def inner(*args, **kwargs):
+            with interface.atomic() if not interface.in_transaction() else contextlib.nullcontext():
+                return func(*args, **kwargs)
+
+        return inner
+
+    return outer
+
+
 class PathField(peewee.CharField):
     """Field class for storing file paths
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "peewee-plus"
-version = "1.0.0"
+version = "1.1.0"
 description = "Various extensions, helpers, and utilities for Peewee"
 authors = ["Ethan Paul <24588726+enpaul@users.noreply.github.com>"]
 repository = "https://github.com/enpaul/peewee-plus/"