refactor(project): go-style v2 to pythonic v3 (#11)

* refactor(project): go-style v2 to pythonic v3

* fix: typo

* fix: style

* fix: remove unused

* chore(package): update main and dev and test packages

Makefile

@@ -4,7 +4,7 @@ GIT_ARGS := --name-only --diff-filter=d --cached
 ifneq ($(DIFF_SRC),)
 	GIT_ARGS := --name-only --diff-filter=d $(DIFF_SRC)...HEAD
 endif
-DIFF_FILES = `git diff $(GIT_ARGS) | grep .py$$ | grep -v migrations`
+DIFF_FILES = `git diff $(GIT_ARGS) | grep .py$$`
 
 
 format:

README.md

@@ -2,6 +2,14 @@
 
 This is an example of implementing a Pokémon API based on the Clean Architecture in a Python project, referencing [**go-clean-arch**](https://github.com/bxcodec/go-clean-arch)
 
+## Changelog
+
+- **v1**: checkout to the [v1 branch ](https://github.com/cdddg/py-clean-arch/tree/v1)<br>
+  archived to v1 branch on 2021/04 <br>desc: Initial proposal by me
+- **v2**: checkout to the [v2 branch ](https://github.com/cdddg/py-clean-arch/tree/v2)<br>archived to v1 branch on 2023/07 <br>
+  desc: Improvement from v1, the details can be seen on this PR [#1](https://github.com/cdddg/py-clean-arch/pull/1)
+- **v3**: master branch <br>merged to master on 2023/08. <br>desc: Transitioned from Go-centric design to conventional Python practices. Details available in this PR [#11](https://github.com/cdddg/py-clean-arch/pull/11)
+
 ## Description
 
 Rule of Clean Architecture by Uncle Bob [^1]
@@ -12,23 +20,50 @@ Rule of Clean Architecture by Uncle Bob [^1]
 - Independent of Database. You can swap out Oracle or SQL Server, for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
 - Independent of any external agency. In fact your business rules simply don’t know anything at all about the outside world.
 
-The project, like the original project, has 4 domain layers:
+![clean-arch-01](./docs/clean-arch-01.png)
+
+![clean-arch-02](./docs/clean-arch-02.png)
+
+### Additional Features and Patterns in This Project
+
+Apart from being based on Uncle Bob's Clean Architecture, this project also incorporates the following features and patterns:
 
-- Models Layer
-- Repository Layer
-- Usecase Layer
-- Delivery Layer
+- **Unit of Work Pattern**: Ensures that all work is completed as a single unit for every transactional operation. [^2]
+- **Dependency Injection Pattern**: Helps in reducing direct dependencies between codes, increasing the testability and flexibility of modules. [^3]
+- **Asynchronous SQLalchemy**: By utilizing the asynchronous capabilities of SQLAlchemy 2.0, database operations are optimized for performance and efficiently handle multitasking. [^4]
 
-In addition, Add [Unit of Work Pattern](./src/settings/unit_of_work.py) [^2], [Dependency Injection Pattern](./src/settings/dependency_injection.py) [^3] <br>
-and use Asynchronous SQLalchemy[^4]
+### Project Structure Overview & Clean Architecture Mapping
 
-#### The diagram:
+The directory structure below provides a high-level view of the project. Each directory or module corresponds to a layer in Uncle Bob's Clean Architecture. Please note that only the main directories and key files are listed here. Some specific files or subdirectories might be omitted to highlight the overall architecture and the primary purpose of each layer.
 
-<img src="./docs/clean-arch.png">
+```
+src
+├── app/                                - Directory for business logic.
+│   ├── deliveries/                     - Interface layer for external interactions. 
+│   │                                   ("Frameworks and Drivers" Layer in Clean Architecture)
+│   │
+│   ├── usecases/                       - Application services layer representing business use cases.
+│   │                                   ("Use Cases" Layer in Clean Architecture)
+│   │
+│   ├── repositories/                   - Data storage and interaction module. 
+│   │                                   ("Interface" Adapters Layer in Clean Architecture)
+│   │
+│   └── di/                             - Dependency injection module.
+│       ├── dependency_injection.py
+│       └── unit_of_work.py
+│
+├── models/                             - Domain models representing core business logic.
+│                                       ("Entities" Layer in Clean Architecture)
+│
+├── common/                             - Module containing shared code and utilities. 
+├── settings/                           - Application configurations. 
+├── tests/                              - Testing module for the application. 
+└── main.py                             - Main file to launch the application.
+```
 
-### How To Run This Project
+## How To Run This Project
 
-#### Run the Application
+### Run the Application
 
 ```sh
 $ docker-compose up
@@ -52,7 +87,7 @@ application run on http://localhost:8000
 
 <img src="./docs/fastapi-doc.png" alt="fastapi-doc" style="zoom:40%;" />
 
-#### Run the Testing
+### Run the Testing
 
 To test a single database, set the `SQLALCHEMY_DATABASE_URI` environment variable to the database URI and run:
 
@@ -93,25 +128,17 @@ $ make test
 
 ### Code Coverage
 
-As part of our commitment to maintain high standards, we use `pytest-cov` to ensure extensive test coverage. Currently, our code coverage stands at 95%. [^5]
+As part of our commitment to maintain high standards, we use `pytest-cov` to ensure extensive test coverage. Currently, our code coverage stands at 93%. [^5]
 
 To generate a coverage report:
 
 ```sh
 $ pytest --cov
 ```
 
-## Changelog
-
-- **v1**: checkout to the [v1 branch ](https://github.com/cdddg/py-clean-arch/tree/v1)<br>
-  archived to v1 branch on 2018 <br>
-  Desc: Initial proposal by me
-- **v2**: master branch <br>
-  merged to master on 2023. <br>
-  Desc: Improvement from v1, the details can be seen on this PR [#1](https://github.com/cdddg/py-clean-arch/issues/1)
-
 [^1]: https://github.com/bxcodec/go-clean-arch#description
 [^2]: https://www.cosmicpython.com/book/chapter_06_uow.html
 [^3]: https://en.wikipedia.org/wiki/Dependency_injection
 [^4]:  The asyncio extension as of SQLAlchemy 1.4.3 can now be considered to be **beta level** software. API details are subject to change however at this point it is unlikely for there to be significant backwards-incompatible changes. https://docs.sqlalchemy.org/en/14/orm/extensions/asyncio.html
-[^5]: Test results as of [today's date, e.g., August 12, 2023].
+
+[^5]: Test results as of [today's date, e.g., August 16, 2023].