Update documentation

Author: febus982

README.md

@@ -182,13 +182,13 @@ be used for repository operations, **assumed the same bind is used for all the r
 ```python
 class MyRepo(SQLAlchemyRepository):
     _model = MyModel
-class MyOtherRepo(SQLAlchemyRepository):
-    _model = MyOtherModel
 
 bind = sa_manager.get_bind()
-uow = UnitOfWork(bind, (MyRepo, MyOtherRepo))
+uow = UnitOfWork(bind)
+uow.register_repository("repo_a", MyRepo)
+uow.register_repository("repo_b", SQLAlchemyRepository, MyOtherModel)
 
 with uow.transaction():
-    uow.MyRepo.save(some_model)
-    uow.MyOtherRepo.save(some_other_model)
+    uow.repository("repo_a").save(some_model)
+    uow.repository("repo_b").save(some_other_model)
 ```

docs/lifecycle.md

@@ -34,12 +34,16 @@ What you can do is:
 * Save the repositories in global variables and start a thread / asyncio task to handle
   a scoped request (e.g. one thread per HTTP request)
 
-What you cannot do is:
+What you should not do is:
 
 * Get a list of models
 * Save the models using `save()` in parallel threads / tasks (each task will have a different session)
 
-/// tip | The recommendation is of course to try to use a single repository instance, where possible.
+/// warning | Remember: Concurrent writes to the db can cause undesired scenarios like locks and deadlocks!
+
+///
+
+/// tip | The recommendation is to try to use a single repository instance, where possible.
 
 For example a strategy similar to this would be optimal, if possible:
 

docs/repository/uow.md

@@ -10,20 +10,21 @@ be used for repository operations.
 ```python
 class MyRepo(SQLAlchemyRepository):
     _model = MyModel
-class MyOtherRepo(SQLAlchemyRepository):
-    _model = MyOtherModel
 
 bind = sa_manager.get_bind()
-uow = UnitOfWork(bind, (MyRepo, MyOtherRepo))
+uow = UnitOfWork(bind)
+uow.register_repository("repo_a", MyRepo)
+# args and kwargs are forwarded so we can also use directly `SQLAlchemyRepository` class
+uow.register_repository("repo_b", SQLAlchemyRepository, MyOtherModel)
 
 with uow.transaction():
-    uow.MyRepo.save(some_model)
-    uow.MyOtherRepo.save(some_other_model)
+    uow.repository("repo_a").save(some_model)
+    uow.repository("repo_b").save(some_other_model)
 
 # Optionally disable the commit/rollback handling
 with uow.transaction(read_only=True):
-    model1 = uow.MyRepo.get(1)
-    model2 = uow.MyOtherRepo.get(2)
+    model1 = uow.repository("repo_a").get(1)
+    model2 = uow.repository("repo_b").get(2)
 ```
 
 /// admonition | The unit of work implementation is still experimental.