Development¶

Developer Quick Start Guide¶

Follow the instructions below to get a flask-ligand development environment up and running quickly!

Prerequisites¶

Python 3.10+
Hatch 1.6+
Docker (with Compose V2)

Hatch Scripts¶

Execute the following command to get a full list of available custom Hatch scripts:

$ hatch env show

Setup Python Environment¶

Create a Hatch environment:
```
$ hatch env create
```
Setup git pre-commit hooks:
```
$ hatch run setup-pre-commit
```
Execute the following hatch script to run tests against all supported Python versions:
```
$ hatch run test-tox
```

Configuration Settings¶

The following environment variables are available to configure behavior of services that use this library when utilizing the built-in ‘local’ and ‘dev’ and ‘prod’ Flask environments. (See flask_environments.rst for more details about the available built-in Flask environments)

(Note: this project does support the use of ‘.env’ files for loading environment variables)

**Environment Variable Settings**¶
ENV	Default Value for ‘local’ Flask Environment	Description
`SERVICE_PUBLIC_URL`	`http://localhost:5000`	The public URL for this service. (Also used for generating OpenAPI clients)
`SERVICE_PRIVATE_URL`	`http://localhost:5000`	The private URL for this service. (Also used for generating OpenAPI clients)
`ALLOWED_ROLES`	`user,admin`	A comma separated list of user roles that are allowed for endpoint protection. (e.g. ‘user,admin’)
`OIDC_DISCOVERY_URL`	Not set (must be provided)	The OpenID Connect Provider Configuration Request URL.
`SQLALCHEMY_DATABASE_URI`	`sqlite:///:memory:`	The URI for a PostgreSQL database to use for persistent storage. (See database_configuration.rst for more information)
`OPENAPI_GEN_SERVER_URL`	`http://api.openapi-generator.tech`	The OpenAPI online generator server URL to use for creating clients.

Python Black Support¶

This repo utilizes Python Black for automatic code formatting using the hatch fmt script. However, this is not very convenient to use on a regular basis and instead it is recommended to integrate Python Black into your IDE workflow. Checkout these editor integration guides for integrating Python Black with popular IDEs and text editors.

Integration Testing¶

This repo contains Docker compose scripts and associated Hatch scripts for setting up and executing integration tests against a PostgreSQL + Keycloak environment.

Utilize Docker Environment¶

It can be quite useful to experiment while developing new features by manually exploring with a production like environment. This can be easily accomplished by leveraging the integration testing environment!

Simply execute steps 1-4 from the following section to get an operational integration test environment then execute the Hatch script:

$ hatch run gen-local-env-file

The hatch run gen-local-env-file will create a new .env file that contains the environment variables necessary to access the integration environment.

Once the .env file has been generated you can start a local Flask server by executing the Hatch script:

$ hatch run run-server

Simple navigate to http:://localhost:5000/apidocs to access the local environment via SwaggerUI.

Release Process¶

Automated Process¶

This repo utilizes python-semantic-release in conjunction with GitHub Actions to create releases automatically.

Manually Process¶

ONLY UNDER LIMITED CIRCUMSTANCES SHOULD THIS PROCESS BE USED!

Configuring Environment Variables¶

The following environment variables are necessary for creating a full production release:

**Environment Variables**¶
ENV	Description
`GH_TOKEN`	A personal access token from GitHub. This is used for authenticating when pushing tags, publishing releases etc. See Configuring push to Github for usage. To generate a token go to https://github.com/settings/tokens and click on Personal access token.
`HATCH_INDEX_USER`	Used together with REPOSITORY_PASSWORD when publishing artifact. Note: If you use token authentication with pypi set this to __token__.
`HATCH_INDEX_AUTH`	Used together with REPOSITORY_USERNAME when publishing artifact. Also used for token when using token authentication.

Publish the Release¶

Create a new release and build artifacts:
```
$ hatch run sem-release
```
Publish artifacts to PyPI:
```
$ hatch publish
```