Flask Graphql Boilerplate

This is a boilerplate code for writing backend services using Flask and GraphQL.

Table of Contents

1. Dependencies
2. Getting Started
3. Commands
4. Database
5. Application Structure
6. Development
7. Testing
8. Lint
9. Format

Dependencies

You will need docker and docker-compose.

Getting Started

First, clone the project:

$ git clone https://github.com/codenut/flask-graphl-boilerplate
$ cd flask-graphql-boilerplate

Then install dependencies and check that it works

$ make server.install      # Install the pip dependencies on the docker container
$ make server.start        # Run the container containing your local python server
$ make database.upgrade    # Upgrade the database to the latest migration

If everything works, you should see the GraphQL explorer here. You can send the create user mutation below using the GraphQL Explorer.

mutation {
  createUser(username: "whoami", email: "[email protected]") {
    user {
      username
    }
  }
}

And retrieve a user using the query user below:

{
  user(username: "whoami") {
    username
    email
  }
}

Commands

You can display availables make commands using make.

While developing, you will probably rely mostly on make server.start; however, there are additional scripts at your disposal:

make <script>	Description
help	Display availables make commands
server.install	Install the pip dependencies on the server's container.
server.start	Run your local server in its own docker container.
server.daemon	Run your local server in its own docker container as a daemon.
server.upgrade	Upgrade pip packages interactively.
database.connect	Connect to your docker database.
database.migrate	Generate a database migration file using alembic, based on your model files.
database.upgrade	Run the migrations until your database is up to date.
database.downgrade	Downgrade your database by one migration.
test	Run unit tests with pytest in its own container.
test.coverage	Run test coverage using pytest-cov.
test.lint	Run flake8 on the src and test directories.
test.safety	Run safety to check if your vendors have security issues.
format.black	Format python files using Black.
format.isort	Order python imports using isort.

Database

The database is in PostgreSql.

Locally, you can connect to your database using :

$ make database.connect

This kit contains a built in database versioning using alembic. Once you've changed your models, which should reflect your database's state, you can generate the migration, then upgrade or downgrade your database as you want. See Commands for more information.

The migration will be generated by the container, it may possible that you can only edit it via sudo or by running chown on the generated file.

Application Structure

The application structure presented in this boilerplate is grouped primarily by file type. Please note, however, that this structure is only meant to serve as a guide, it is by no means prescriptive.

.
├── migrations               # Database's migrations settings
│   └── versions             # Database's migrations versions generated by alembic
├── src                      # Application source code
│   ├── models               # Python classes modeling the database
│   │   ├── abc.py           # Abstract base class model
│   │   └── user.py          # Definition of the user model
│   ├── gql                  # The classes for GraphQL schema and resolvers
│   │   └── schema.py        # This where the schemas are defined
│   │   └── user_schema.py   # The GraphQL queries and mutations related to the user
│   ├── config.py            # Project configuration settings
│   ├── manage.py            # Project commands
│   └── server.py            # Server configuration
└── test                     # Unit tests source code

Development

To develop locally, here are your two options:

$ make server.start           # Create the containers containing your python server in your terminal
$ make server.daemon          # Create the containers containing your python server as a daemon

The containers will reload by themselves as your source code is changed. You can check the logs in the ./server.log file.

Testing

To add a unit test, simply create a test_*.py file anywhere in ./test/, prefix your test classes with Test and your testing methods with test_. Unittest will run them automaticaly. You can add objects in your database that will only be used in your tests, see example. You can run your tests in their own container with the command:

$ make test

Lint

To lint your code using flake8, just run in your terminal:

$ make test.lint

It will run the flake8 commands on your project in your server container, and display any lint error you may have in your code.

Format

The code is formatted using Black and Isort. You have the following commands to your disposal:

$ make format.black # Apply Black on every file
$ make format.isort # Apply Isort on every file

Contributing

If you want to contribute to this flask restplus boilerplate, clone the repository and just start making pull requests.

https://github.com/codenut/flask-graphql-boilerplate

Credits

The setup of this boilerplate code is based from antkahn/flask-api-starter-kit