This repository is a flask starter kit focusing on making robust API.
The api root will contain generated Swagger documentation for endpoints. On a local environment this will usually be http://localhost:5000 if using docker-compose.
Copy the example .env file
cp .env.example .env
Run the Docker container the first time:
docker-compose up -d
After updating the source tree, to refresh the api containers:
docker-compose build
docker-compose up -d --force-recreate
Running migrations:
docker-compose run api alembic upgrade head
Check that the api is running at (http://0.0.0.0:5000/)
You must install the pipenv
utility on your computer to update dependencies.
See the Installation guide
To add a dependency to Pipfile and update Pipfile.lock
# from your project's root directory
pipenv install [package-name]
You can can also
specify the version.
Using ~=
is preferred to ==
so the packages can be updated. Dont specify the patch version.
For example: instead of ==3.9.2
use ~=3.9
.
pipenv install [package-name]~=[version]
If you manually add a package to the Pipfile
pipenv lock
Add the dependencies to your current container
docker-compose exec api pipenv install --deploy --system
Rebuild the image (updates dependencies on the docker image):
docker-compose build api
Update dependencies to your current container
- Add = "*" in packages section of Pipfile and execute below command to update single lib into env.
- Don't forgot to commit updated Pipfile.lock file.
docker-compose exec api pipenv update [library]
docker-compose logs -f
Generating a Migration:
docker-compose run api alembic revision --autogenerat -m "<description of changes>"
Fixes migration permissions:
sudo chown -R ${USER}:${USER} alembic/versions
Running migrations:
docker-compose run api alembic upgrade head
Rolling back
docker-compose run api alembic downgrade -1
Resolve a Schema Conflict with a Merge
- check is schema conflict heads
alembic heads
#output
1e21d19c87f5 (head)
35cc6bc4108f (head)
- Merge conflict heads
alembic merge -m "message" [HEAD-1] [HEAD-2]
#Example
alembic merge -m "merge migrations 11912dfa54c4, 1944c1e7a0f4" 11912dfa54c4 1944c1e7a0f4
- Goto mock_seed/data
cd mock_seed/data
- Create mock data seed xml file
<table name="table_name">
<row
id="value"
column1="value"
column2="value"/>
<row
id="value"
column1="value"
column2="value"/>
</table>
- Open mock_seed/confmock.py and add file name in array of seed_file_order.
seed_file_order = [
'postal_addresses.xml',
'persons.xml',
'users.xml',
]
- Run mock seed script
docker-compose run api python seed_mock_data.py
- All the seeds used in this repository is generated by folowing repository
- Goto tests/seed/data
cd tests/seed/data
- Create test data seed xml file
<table name="table_name">
<row
id="value"
column1="value"
column2="value"/>
<row
id="value"
column1="value"
column2="value"/>
</table>
- Open tests/conftest.py and add file name in array of seed_file_order.
seed_file_order = [
'addresses.xml',
'contacts.xml',
'users.xml',
]
##Testing
Run all tests with docker
docker-compose run api_test
- Create test database
- open .env file and set TEST_DATABASE_URI value
#example
TEST_DATABASE_URI=postgresql://postgres:password@localhost:5432/test_flask_api_kit
#Run all tests
python -m pytest -v
#Run specific test file
python -m pytest [file_path]
#example
python -m pytest tests/resources/test_post.py
python -m pytest tests/resources/test_post.py::TestPostResource::test_get_post_by_id
- Use git flow
Based on the git-flow workflow
git checkout -b release/2.0.0 qa
git commit -a -m "release [2.0.0] - 2019-06-01"
git checkout staging
git pull
git merge --ff-only release/2.0.0
git tag -a 2.0.0 -m "[2.0.0] - 2019-06-01"
git checkout dev
git merge release/2.0.0
- Use PEP 8
- Use mypy typing whenever possible
- Make sure all code changes are linted
- Only break a standard if you have a good reason for doing so
- Disable linting rules on a case by case basis
- Make sure you understand the reason for a linting error before disabling a rule
Always try to have 10/10 code. If you have a good reason to break the standard use
# pylint: diable=
.
Use pylint to lint the code:
pylint api
Don't Repeat Yourself! (DRY)
Always try to abstract out common code in a way that can be used a la carte.
cd docs
sphinx-apidoc -f -o . ../api
cd docs
make html
The marshmallow_with
is based on the
flask_restplus marshal_with() decorator
The docker-compose.yml
defines a network named flask_api_kit
.
Containers are addressible by name within this network. This means that the api project api
container can
resolve the project minio
container.
This is why the api
container uses the minio
of http://minio:9000
Don't Repeat Yourself! (DRY)
Always try to abstract out common code in a way that can be used a la carte.
cd docs
sphinx-apidoc -f -o . ../api
cd docs
make html
clean out all pyc files
find . -name \*.pyc -delete