cookiecutter-python-flask-clean-architecture - GitLite

KO | EN

gitlite — search

#hacktoberfest #golang #android #rust #deep-learning #nodejs #java #awesome #cli #awesome-list #security #ios #openai #open-source

cookiecutter-python-flask-clean-architecture

(★ 167)

Cookiecutter Python Flask template for jumpstarting production-ready projects quickly.

파일 탐색기

최종 버전 다운로드 (.zip)

- - maintenance_window_sequence.jpg
- maintenance_window_database_migration_strategy.md
- onion-architecture-article.md
- - run_postgres.sh
- - __init__.py
  - app.py
  - config.py
  - cors.py
  - create_app.py
  - dependency_container.py
  - error_handler.py
  - logging.py
  - management.py
- - __init__.py
- .gitignore
- Dockerfile
- README.md
- requirements-test.txt
- requirements.txt
- wsgi.py
.gitignore
CODE_OF_CONDUCT.md
cookiecutter.json
LICENSE
README.md
SECURITY.md
SUPPORT.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/microsoft/cookiecutter-python-flask-clean-architecture

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd cookiecutter-python-flask-clean-architecture

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -f {{cookiecutter.repo_name}}/Dockerfile -t cookiecutter-python-flask-clean-architecture .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run -p 8080:80 cookiecutter-python-flask-clean-architecture

빌드된 이미지를 실제 컨테이너로 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

python -m unittest discover -s tests

파이썬 스크립트(또는 모듈)를 실행합니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Cookiecutter flask clean architecture
This is a reusable Python Flask template. The project is based on Flask in combination with SQLAlchemy ORM.

Complete list of features the template provides:
* [Onion architecture](#onion-architecture)
* [Maintenance window support](#maintenance-window-support)
* [SQLAlchemy ORM](#sqlalchemy-orm)
* [Alembic Database migrations](#alembic-database-migrations)
* [Local postgres database docker support](#local-postgres-database-docker-support)
* [Tests and test containers integration](#tests-and-test-containers-integration)
* [Service prefix](#service-prefix)
* [Dependency injection](#dependency-injection)
* [Service-repository design pattern](#service-repository-design-pattern)

## Getting started
To start a new project, run the following command:
```bash
cookiecutter https://github.com/microsoft/cookiecutter-python-flask-clean-architecture
```
This will prompt you for some information about your project. The information
you provide will be used to populate the files in the new project directory.

### Running the application locally
To run the application locally, you need to have a Postgres database running.
You can use the `run_postgres.sh` script in the `scripts` directory to run a Postgres container.
```bash
./scripts/run_postgres.sh
```
You can then run the application with flask:
```bash
flask --app src/app run 
```
or with gunicorn:
```bash
gunicorn wsgi:app -b  0.0.0.0:7000 --workers=1 --preload
```

## Onion Architecture 
The application follows the Onion Architecture pattern. An article is written 
about our experience integrating an onion architecture with flask in combination with 
SQL Alchemy ORM that can be found [here](./docs/onion-architecture-article.md).

This architecture is a design pattern that organizes the codebase of a software application into multiple layers, where the innermost layer 
is the domain layer and the outermost layer is the application layer. Each layer depends only on the layers inside of it and not on the layers outside of it, 
creating a separation of concerns, allowing for a more maintainable and scalable codebase.

For this template we suggest using a service-repository design pattern. This template also provides 
a set of abc meta classes that you can use to create your repositories and services.
For example implementations you can have a look at [Service-repository design pattern](#service-repository-design-pattern).

## Maintenance window support
This template provides you with a maintenance window mode. To learn more about 
maintenance windows in your service you can read this article [here](https://devblogs.microsoft.com/cse/2023/02/08/maintenance_window_db_migrations/)

During maintenance mode, clients will receive an http 503 status code.

### Activating maintenance mode
You can activate maintenance mode in the following ways:
```bash
curl -X PATCH http://localhost:7000/<service-prefix>/v1/service-context -d '{"maintenance": true}' -H 'Content-Type: application/json'
```
or via the command line:
```bash
flask activate_maintenance_mode
```

### Deactivating maintenance mode
You can deactivate maintenance mode in the following ways:
```bash
curl -X PATCH http://localhost:7000/<service-prefix>/v1/service-context -d '{"maintenance": false}' -H 'Content-Type: application/json'
```
or via the command line:
```bash
flask deactivate_maintenance_mode
```

## SQLAlchemy ORM
The template uses SQLAlchemy ORM for its database connection and database models
integration. Its is currently setup with postgres, however you can 
change it to any other database that is supported by SQLAlchemy. For other databases 
have a look at the official Flask SQLAlchemy documentation 
that can be found [here](https://flask-sqlalchemy.palletsprojects.com/en/3.0.x/)

This template provides you with a model base class that you can use to create your models.

```python
from src.infrastructure.models.model_extension import ModelExtension

class User(ModelExtension):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    attribute_a = Column(String(50), nullable=False)
    attribute_b = Column(String(50), nullable=False)

def __repr__(self):
        return self.repr(id=self.id, attribute_a=self.attribute_a, attribute_b=self.attribute_b)
```

## Alembic database migrations
> Note: The application uses a postgres database. Make sure you have a postgres
> database running before running the following commands. For local development,
> you can use the run_postgres.sh script to run a postgres container locally.

1) Make sure you have the diesel cli installed. You can install it with the following command:
    ```bash
    sh ./scripts/run_postgres.sh
    ```
2) Create a database migration
    ```bash
    flask db migrate -m <migration-message>
    ```
3) Apply the database migration:
    ```bash
    flask db upgrade
    ```
   
## Local postgres database docker support 
You can run a local postgres docker database by using the following script:
```bash
 sh ./scripts/run_postgres.sh
 ```

This will run a postgres docker container on port 5432. Also it will create a
.env file in the root directory of the project. This file contains the database
connection string. The service will read this connection string from the .env file 
and use it to connect to the database.

## Tests and test containers integration
All tests are can be found under the `tests` folder. When using the template
you can place all you tests in this folder.

The service uses [python unittest](https://docs.python.org/3/library/unittest.html) in combination
with [flask testing]

To run the tests, you can use the following command:
```bash
python -m unittest discover -s tests
```

You can use the test containers library to run your tests against a postgres database.
You do this by ```setup_database()``` in your test class. This will create a postgres container
and run your tests against it. After the tests are done, the container will be destroyed.

If you want to run your tests against a different database, you can change the 
setyp_database method in the test class to use a different database container.

```python
class Test(AppTestBase):

def setUp(self) -> None:
        super(Test, self).setUp()
        self.setup_database()
```

## Service prefix
The application can use a service prefix for the endpoints.
The service prefix is defined in the config.py file. Given a service prefix 
of 'example', endpoints will be prefixed with '/example/v1/service-context'.

```python
# config.py
SERVICE_PREFIX = os.environ.get(SERVICE_PREFIX, '')

# middleware
class PrefixMiddleware(object):
    ROUTE_NOT_FOUND_MESSAGE = "This url does not belong to the app."

def __init__(self, app, prefix=''):
        self.app = app
        self.wsgi_app = app.wsgi_app
        self.prefix = prefix

def __call__(self, environ, start_response):

if environ['PATH_INFO'].startswith(self.prefix):
            environ['PATH_INFO'] = environ['PATH_INFO'][len(self.prefix):]
            environ['SCRIPT_NAME'] = self.prefix
            return self.wsgi_app(environ, start_response)
        else:
            start_response('404', [('Content-Type', 'text/plain')])
            return [self.ROUTE_NOT_FOUND_MESSAGE.encode()]
```

During testing the service prefix is not applied. This allows you
to test the endpoints without having to add the service prefix to the
endpoint.

If the service prefix is not set, the service will not use a service prefix.

## Dependency injection
This template uses the [dependency_injector](https://pypi.org/project/dependency-injector/) library
for dependency injection. The template provides you with a container class that you can use to
register your dependencies. The container class is located in the `src/dependency_container.py` file.

You can add your dependencies to the container and use them 
in your routers, services and repositories.

## Service repository design pattern
This template provides you with a repository-service pattern. There are two base classes
that you can use to create your repositories and services. These base classes are located
in the `src/services/repository_service.py` and `src/infrastructure/repositories/repository.py`.

### Repository example
A repository example can be seen below, this repository is used to query the MyModel model.
For custom query params support override the `_apply_query_params` method.

```python
from infrastructure.repositories import Repository
from infrastructure.models import MyModel

class MyExampleRepository(Repository):
    base_class = MyModel
    DEFAULT_NOT_FOUND_MESSAGE = "MyModel was not found"

def _apply_query_params(self, query, query_params):
        name_query_param = self.get_query_param("name", query_params)
        
        if name_query_param:
           query = query.filter_by(name=name_query_param)
            
        return query
```

### Service example
A Service example can be seen below, this service expect a repository to be injected in its contuctor.

```python
from services.repository_service import RepositoryService

class MyExampleService(RepositoryService):
    # The RepositoryService gives you access to crud repository operations by the inheritance 
    # RepositoryService.
    pass

# Can be instantiate by injecting the repository
my_example_service = MyExampleService(my_example_repository)
```