add transactions & db validation sections translate; fix highlighting…

…; minor fixes

docs/benefits.md

@@ -1,4 +1,3 @@
-### Benefits
 An optional section demonstrating the reduction of boilerplate code when using `fastapi_sqlalchemy_toolkit`.
 
 If you need to add filters based on field values in a `FastAPI` endpoint, the code would look something like this:

docs/db_validation.md

@@ -1 +1,27 @@
-# Database validation
+# Database-Level Validation
+
+The `create` and `update` methods perform validation on the passed values at the database level. Specifically:
+
+## Foreign Keys Existence Validation
+
+If `Child.parent_id` is a `ForeignKey` referencing `Parent.id`, and the value of `parent_id` is set via `child_manager.create` or `child_manager.update`, an SQL query will be executed to check the existence of a `Parent` with the provided ID.
+
+If no such object exists, an `fastapi.HTTPException` will be raised.
+
+## Many-to-Many Relationships Existence Validation
+
+If `Post.tags` represents a `ManyToMany` relationship with `Tag.id`, and the `tags` value is set via `post_manager.create` or `post_manager.update` as a list of IDs, an SQL query will be executed to verify the existence of all `Tag` objects with the provided IDs.
+
+If any of the objects do not exist, an `fastapi.HTTPException` will be raised.
+
+## Unique Fields Validation
+
+If `Post.slug` is a field defined with `unique=True`, and the value of `slug` is set via `post_manager.create` or `post_manager.update`, an SQL query will be executed to check that no other `Post` object exists with the same `slug` value.
+
+If the uniqueness constraint is violated, an `fastapi.HTTPException` will be raised.
+
+## Unique Constraints Validation
+
+If the model defines unique constraints using `sqlalchemy.UniqueConstraint`, then when using the `create` or `update` methods, an SQL query will be executed to verify that no other objects with the same combination of field values in the unique constraint exist.
+
+If the unique constraint is violated, an `fastapi.HTTPException` will be raised.

docs/index.md

@@ -12,9 +12,9 @@ To achieve this, `FastAPI SQLAlachemy Toolkit` provides the `fastapi_sqlalchemy_
 
 - Methods for CRUD operations with objects in the database
 
-- Filtering with optional query parameters handling (see the [Filtering](#filtering) section)
+- Filtering with optional query parameters handling (see the [Filtering](./filtering.md) section)
 
-Declarative sorting using `ordering_dep` (see the [Sorting](#sorting) section)
+Declarative sorting using `ordering_dep` (see the [Sorting](./sorting.md) section)
 
 - Validation of foreign key existence
 
@@ -28,14 +28,16 @@ Declarative sorting using `ordering_dep` (see the [Sorting](#sorting) section)
 pip install fastapi-sqlalchemy-toolkit
 ```
 
-## Quick Start
-
-Example of `fastapi-sqlalchemy-toolkit` usage is available in the `examples/app` directory
+## Demonstration
+Example of `fastapi-sqlalchemy-toolkit` usage in FastAPI app:
 
+[https://github.com/e-kondr01/fastapi-sqlalchemy-toolkit/tree/master/examples/app](https://github.com/e-kondr01/fastapi-sqlalchemy-toolkit/tree/master/examples/app)
 
 ## Read More
-- [ModelManager](./usage.md)
+- [Usage](./usage.md)
 - [Filtering](./filtering.md)
 - [Sorting](./sorting.md)
+- [Transactions](./transactions.md)
+- [Database-Level Validation](./db_validation.md)
 - [Extension](./extension.md)
 - [Other utilities](./utils.md)

docs/transactions.md

@@ -1 +1,47 @@
-# Working with transactions
+# Working with transactions
+
+`fastapi-sqlalchemy-toolkit` supports both approaches for working with transactions in `SQLAlchemy`.
+
+## Commit as you go
+
+[Commit as you go SQLAlchemy Documentation](https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#commit-as-you-go)
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from app.managers import my_model_manager
+
+...
+
+    engine = create_async_engine(
+        "...",
+    )
+    async with async_sessionmaker(engine) as session:
+        # Calling this method will perform an SQL COMMIT
+        created_obj = await my_model_manager.create(session, input_data)
+        # Calling this method will perform an SQL COMMIT
+        await my_model_manager.update(session, created_obj, name="updated_name", commit=False)
+    # Only the first call will be saved in the database
+```
+
+## Begin once
+
+[Begin once SQLAlchemy Documentation](https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#begin-once)
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from app.managers import my_model_manager
+
+...
+
+    engine = create_async_engine(
+        "...",
+    )
+    # Transaction begins within the context manager
+    async with async_sessionmaker(engine) as session, session.begin():
+        # This call only performs a flush, without an SQL COMMIT
+        created_obj = await my_model_manager.create(session, input_data)
+        # This call only performs a flush, without an SQL COMMIT
+        await my_model_manager.update(session, created_obj, name="updated_name")
+    # If there were no exceptions in the nested block, a COMMIT is invoked, saving
+    # changes from both calls
+```

mkdocs.yml

@@ -64,16 +64,17 @@ theme:
     - navigation.sections
     - search.suggest
     - content.code.copy
-  markdown_extensions:
-    - pymdownx.details
-    - pymdownx.highlight:
-        anchor_linenums: true
-        line_spans: __span
-        pygments_lang_class: true
-    - pymdownx.inlinehilite
-    - pymdownx.snippets
-    - pymdownx.superfences
-    - toc:
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.details
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
       permalink: true
-    - admonition
-    - tables
+  - admonition
+  - tables