Merge pull request #31 from febus982/docs_lifecycle

Documentation about components life cycle and concurrency

Author: febus982

docs/lifecycle.md

@@ -0,0 +1,91 @@
+## When should you create each component?
+
+### Bind manager
+
+The `SQLAlchemyBindManager` object holds all the SQLAlchemy Engines, which
+are supposed to be global objects. Therefore it should be created on application
+startup and be globally accessible.
+
+From SQLAlchemy documentation:
+
+> The Engine is intended to normally be a permanent fixture established up-front
+> and maintained throughout the lifespan of an application.
+
+### Repositories
+
+[SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it)
+recommends we create `Session` object at the beginning of a logical operation where
+database access is potentially anticipated.
+
+The repository starts a `Session` for each _operation_, in order to maintain isolation.
+This means you can create a repository object almost whenever you want.
+
+/// details | There two exceptions: creating repositories in global variables or concurrent asyncio tasks
+    type: warning
+The repository creates and maintain the lifecycle of a session object to avoid
+emitting unnecessary queries to refresh the model state on new session.
+
+The session is not thread safe, therefore the repository is not thread safe as well.
+
+Check the [Notes on multithreaded applications](/manager/session/#note-on-multithreaded-applications)
+
+The `AsyncSession` [is not safe on concurrent asyncio tasks](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#is-the-session-thread-safe-is-asyncsession-safe-to-share-in-concurrent-tasks),
+therefore the same repository instance can't be used in multiple asyncio tasks like
+when using `asyncio.gather()`
+///
+
+Even using multiple repository instances will work fine, however as they will have completely
+different sessions, it's likely that the second repository will fire additional SELECT queries
+to get the state of the object prior to saving it.
+
+/// details | Example
+```python
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy_bind_manager import SQLAlchemyBindManager ,SQLAlchemyConfig
+from sqlalchemy_bind_manager.repository import SQLAlchemyRepository
+
+config = SQLAlchemyConfig(
+    engine_url="sqlite:///./sqlite.db",
+    engine_options=dict(connect_args={"check_same_thread": False}, echo=True),
+    session_options=dict(expire_on_commit=False),
+)
+
+sa_manager = SQLAlchemyBindManager(config={})
+
+class MyModel(sa_manager.get_bind().model_declarative_base):
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(30))
+
+def update_my_model():
+    # Create 2 instances of the same repository
+    repo = SQLAlchemyRepository(sa_manager.get_bind(), model_class=MyModel)
+    repo2 = SQLAlchemyRepository(sa_manager.get_bind(), model_class=MyModel)
+    
+    o = repo.get(1)
+    o.name = "John"
+    
+    repo2.save(o)
+
+update_my_model()
+```
+///
+
+The recommendation is of course to use the same repository instance, where possible,
+and structure your code in a way to match the single repository instance approach.
+
+For example a strategy similar to this would be optimal, if possible:
+
+* Create repositories
+* Retrieve all the models you need
+* Do the changes you need, as per business logic
+* Save all the changed models as needed
+
+/// tip | Using multiple repository instances is the only way to safely use concurrent asyncio tasks
+
+///
+
+### Unit of work
+
+The Unit of Work session management follows the **same exact rules as the repository**,
+therefore you should approach the creation af a `UnitOfWork` object in the same way.

docs/repository/repository.md

@@ -94,3 +94,16 @@ using either approach:
 
 Note that `AsyncSession` has [the same limitation on lazy loading](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#asyncio-orm-avoid-lazyloads),
 even when keeping the session opened, so it makes sense that the two Repository implementations behave consistently.
+
+/// details | Lazy loading using `AsyncAttrs`
+
+SQLAlchemy has recently added the `AsyncAttrs` model class mixin to allow lazy loading model attributes 
+with `AsyncSession`, however having to `await` a model property introduce a coupling between the
+application logic and the storage layer.
+
+This would mean the application logic has to know about the storage layer and make a distinction
+between sync and async models. This doesn't feel right, at least for now,
+therefore it's not enabled by default.
+
+If you want to attempt lazy loading refer to [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#synopsis-orm)
+///    

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
   - Repository:
       - Repository usage: repository/repository.md
       - Unit of work: repository/uow.md
+  - Components life cycle: lifecycle.md
 
 markdown_extensions:
   - pymdownx.details

sqlalchemy_bind_manager/_unit_of_work.py …y_bind_manager/_unit_of_work/__init__.pysqlalchemy_bind_manager/_unit_of_work.py renamed to sqlalchemy_bind_manager/_unit_of_work/__init__.py sqlalchemy_bind_manager/_unit_of_work.py renamed to sqlalchemy_bind_manager/_unit_of_work/__init__.py

@@ -58,6 +58,35 @@ async def test_update_model_doesnt_update_other_models_from_same_repo(
     assert updated_model2.name == "SomeoneElse"
 
 
+async def test_update_model_updates_models_retrieved_by_other_repos(
+    repository_class, model_class, sa_manager
+):
+    repo = repository_class(sa_manager.get_bind())
+    repo2 = repository_class(sa_manager.get_bind())
+
+    # Populate a database entry to be used for tests
+    model1 = model_class(
+        name="Someone",
+    )
+    await repo.save(model1)
+    assert model1.model_id is not None
+
+    # Retrieve the models
+    new_model1 = await repo.get(model1.model_id)
+
+    # Update the model with another repository instance
+    new_model1.name = "StillSomeoneElse"
+    await repo2.save(new_model1)
+
+    # Check model1 has been updated
+    updated_model1 = await repo2.get(model1.model_id)
+    assert updated_model1.name == "StillSomeoneElse"
+
+    # Check model1 has been updated
+    updated_model1b = await repo.get(model1.model_id)
+    assert updated_model1b.name == "StillSomeoneElse"
+
+
 @patch.object(AsyncSessionHandler, "commit", return_value=None, new_callable=AsyncMock)
 async def test_commit_triggers_once_per_operation_using_internal_uow(
     mocked_uow_commit: AsyncMock, repository_class, model_class, sa_manager

tests/repository/async_/test_operation_isolation.py

@@ -58,6 +58,35 @@ def test_update_model_doesnt_update_other_models_from_same_repo(
     assert updated_model2.name == "SomeoneElse"
 
 
+def test_update_model_updates_models_retrieved_by_other_repos(
+    repository_class, model_class, sa_manager
+):
+    repo = repository_class(sa_manager.get_bind())
+    repo2 = repository_class(sa_manager.get_bind())
+
+    # Populate a database entry to be used for tests
+    model1 = model_class(
+        name="Someone",
+    )
+    repo.save(model1)
+    assert model1.model_id is not None
+
+    # Retrieve the models
+    new_model1 = repo.get(model1.model_id)
+
+    # Update the model with another repository instance
+    new_model1.name = "StillSomeoneElse"
+    repo2.save(new_model1)
+
+    # Check model1 has been updated
+    updated_model1 = repo2.get(model1.model_id)
+    assert updated_model1.name == "StillSomeoneElse"
+
+    # Check model1 has been updated
+    updated_model1b = repo.get(model1.model_id)
+    assert updated_model1b.name == "StillSomeoneElse"
+
+
 @patch.object(SessionHandler, "commit", return_value=None)
 def test_commit_triggers_once_per_operation(
     mocked_uow_commit: MagicMock, repository_class, model_class, sa_manager