# ![FOCA_logo][foca-logo]  _Develop Flask microservices quickly!_
[![License][badge-license]][badge-url-license]
[![Build_status][badge-build-status]][badge-url-build-status]
[![Docs][badge-docs]][badge-url-docs]
[![Coverage][badge-coverage]][badge-url-coverage]
[![GitHub_tag][badge-github-tag]][badge-url-github-tag]
[![PyPI_release][badge-pypi]][badge-url-pypi]
**FOCA** (**F**lask-**O**penAPI-**C**onnexion-**A**rchetype) is an opinionated
archetype that enables fast development of [OpenAPI][res-openapi]-based HTTP
API microservices in [Flask][res-flask], leveraging the excellent
[Connexion][res-connexion] framework.
FOCA reduces the required boilerplate code to fire up your app to a bare
minimum and allows you to _**focus on your application logic**_. It also avoids
unnecessary code repetition and introduces cross-service consistency when
developing multiple applications. Simply write a configuration file, pass
it to FOCA and you're good to go!
Currently supported features:
* Manage app configuration
* Handle exceptions
* Register OpenAPI 2.x/3.x specifications
* Protect endpoints via [JWT][res-jwt] validation
* Register [MongoDB][res-mongo-db] collections
* Run asynchronous tasks via [RabbitMQ][res-rabbitmq] & [Celery][res-celery]
* [CORS][res-cors] support
Check the [API docs][badge-url-docs] for further details.
## Table of Contents
* [Usage](#usage)
* [Configuration](#configuration)
* [Configuring OpenAPI specifications](#configuring-openapi-specifications)
* [Configuring MongoDB](#configuring-mongodb)
* [Configuring exceptions](#configuring-exceptions)
* [Configuring asynchronous tasks](#configuring-asynchronous-tasks)
* [Configuring logging](#configuring-logging)
* [Configuring security](#configuring-security)
* [Configuring the server](#configuring-the-server)
* [Custom configuration](#custom-configuration)
* [Accessing configuration parameters](#accessing-configuration-parameters)
* [Utilities](#utilities)
* [Database utilities](#database-utilities)
* [Logging utitlies](#logging-utilities)
* [Miscellaneous utilities](#miscellaneous-utilities)
* [Access Control utilities](#access-control-utilities)
* [Contributing](#contributing)
* [Versioning](#versioning)
* [License](#license)
* [Contact](#contact)
## Usage
(1) Install the [FOCA package][badge-url-pypi] with `pip`:
```bash
pip install foca
```
(2) Create a [configuration](#configuration) file.
(3) Import the FOCA class and pass your config file:
```python
from foca import Foca
foca = Foca(config_file="path/to/my/app/config.yaml")
app = foca.create_app() # returns a Connexion app instance
```
(4) Start your [Flask][res-flask] app as usual.
![Hint][img-hint] _**Check out the [Petstore example application][example]
shipped with this repository to see FOCA in action!**_
## Configuration
![Hint][img-hint] _**In order to get you started writing your own app
configuration, you can copy the [**annotated template**][config-template]
shipped with this repository and modify it.**_
In order to use FOCA functionalities, you must create a [YAML][res-yaml]
configuration file that includes keyword sections reserved by FOCA. The
following top-level sections are interpreted by FOCA (exhaustive; links are
provided to the corresponding sections in this documentation, as well as to the
corresponding models in the [API docuementation][badge-url-docs]):
* [`api`](#configuring-openapi-specifications) / [model][docs-models-api]
* [`db`](#configuring-mongodb) / [model][docs-models-db]
* [`exceptions`](#configuring-exceptions) / [model][docs-models-exceptions]
* [`jobs`](#configuring-asynchronous-tasks) / [model][docs-models-jobs]
* [`log`](#configuring-logging) / [model][docs-models-log]
* [`security`](#configuring-security) / [model][docs-models-security]
* [`server`](#configuring-the-server) / [model][docs-models-server]
**_Any values passed to reserved keywords are automatically validated_**, and a
corresponding informative exception will be raised whenever a value does not
adhere to the corresponding model as described in the [API
documentation][docs-models]. If you do _not_ want to make use of a specific
FOCA functionality, simply omit the corresponding section.
### Configuring OpenAPI specifications
The `api` section is used to specify any [OpenAPI][res-openapi] specifications
consumed as part of your application. Essentially, FOCA adds a wrapper around
[Connexion][res-connexion], which validates requests/responses and can serve
the specifications as well as a [Swagger][res-swagger]-based user interface to
explore the API. FOCA supports multiple specification files (versions
Swagger/OpenAPI 2.x, OpenAPI 3.x and mixed) and multiple fragments thereof, and
it adds additional features that allow easy modification of specifications on
the fly. In particular, links to routers and security definitions can be added
to each specified endpoint.
_Example:_
```yaml
api:
specs:
- path:
- path/to/openapi/specs.yaml
- path/to/openapi/additions.yaml
add_operation_fields:
x-openapi-router-controller: myapi.controllers
add_security_fields:
x-bearerInfoFunc: app.validate_token
disable_auth: False
connexion:
strict_validation: True
validate_responses: True
options:
swagger_ui: True
serve_spec: True
- path:
- path/to/openapi/other_specs.yaml
```
> In this example, the configuration file lists two separate specifications.
> The first is a composite one that FOCA will compile from two files,
> `path/to/openapi/specs.yaml` and `path/to/openapi/additions.yaml`. It comes
> with a range of different explicitly specified parameters to further
> customize the specification itself (classes/functions implementing
> controllers and token validation are linked to each endpoint via
> `add_operation_fields`; `x-openapi-router-controller` and `x-bearerInfoFunc`
> can be used to link controller functions/classes and authorization validation
> functions to endpoints, respectively. Furthermore, a flag to disable the need
> for passing authorization tokens and several [Connexion][res-connexion]
> options are explicitly set for this specification. In contrast, only the path
> to a single file is specified for the second specification, implying default
> values for all other options.
>
> Further support for validating authorization can also be added to
> specifications via the `add_security_fields` parameter under `specs` (not
> shown here). Cf. the [API model][docs-models-api] for this and other options,
> as well as further details.
### Configuring MongoDB
FOCA can register one or more [MongoDB][res-mongo-db] databases and/or
collections for you. To use that functionality, simply include the top-level
`db` keyword section in your configuration file and tune its behavior through
the available parameters.
_Example:_
```yaml
db:
host: mongodb
port: 27017
dbs:
myDb:
collections:
myCollection:
indexes:
- keys:
id: 1
options:
'unique': True
mySecondCollection:
indexes:
- keys:
other_id: 1
myOtherDb:
collections:
myThirdCollection:
indexes:
- keys:
third_id: 1
```
> In this example, two databases (`myDb` and `myOtherDb`) are configured, the
> former with two and the latter with one collection (`myCollection`,
> `mySecondCollection` and `myThirdCollection`, respectively). FOCA will
> automatically register and initialize these databases and collections for you
> and add convenient clients to the app instance (accessible as children of
> `current_app.config.foca` in an [application
> context][res-flask-app-context]). The collections would be indexed by keys
> `id`, `other_id` and `third_id`, respectively. Out of these, only `id`
> will be required to be unique.
>
> Cf. the [API model][docs-models-db] for further options and details.
### Configuring exceptions
FOCA provides a convenient, configurable exception handler and a simple way
of adding new exceptions to be used with that handler. To use it, specify a
top-level `exceptions` section in the app configuration file.
_Example:_
```yaml
exceptions:
required_members: [['msg'], ['status']]
status_member: ['status']
exceptions: my_app.exceptions.exceptions
logging: one_line
```
> This example configuration would attach the exceptions defined in the
> `my_app.exceptions.exceptions` dictionary to the exception handler. The
> exception handler ensures that every exception in that dictionary defines
> at least members `msg` and `status`. Out of these, `status` will be used
> to inform the status code for the error response. Exceptions processed via
> FOCA's exception handler will be automatically logged, if requested. In this
> case, the handler is configured to log all errors verbosely (including any
> traceback information, if applicable) on a single line (other rendering
> options are also supported).
>
> You may further configure optional members, a list of `public members` (to be
> included in error responses) and `private members` (only visible in logs).
> Cf. the [API model][docs-models-exceptions] for further options and details.
### Configuring asynchronous tasks
FOCA offers limited support for running asynchronous tasks via the
[RabbitMQ][res-rabbitmq] broker and [Celery][res-celery]. To make use of it,
include the `jobs` top-level section in the app configuration file.
_Example:_
```yaml
jobs:
host: rabbitmq
port: 5672
backend: 'rpc://'
include:
- my_app.tasks.my_task_1
- my_app.tasks.my_task_2
```
> This config attaches the `rabbitmq` broker host running on port `5672` to
> FOCA and registers the tasks found in modules `my_task_1` and `my_task_2`.
>
> Cf. the [API model][docs-models-jobs] for further details.
The `foca.Foca` class provides a method `.create_celery_app()` that you can
use in your Celery worker entry point to crate a Celery app, like so:
```py
from foca import Foca
foca = Foca(config="my_app/config.yaml")
my_celery_app = foca.create_celery_app()
```
### Configuring logging
FOCA allows you to specify a YAML-based logging configuration to control your
application's logging behavior in an effort to provide a single configuration
file for every application. To use it, simply add a `log` top-level section in
your app configuration file.
_Example:_
```yaml
log:
version: 1
disable_existing_loggers: False
formatters:
standard:
class: logging.Formatter
style: "{"
format: "[{asctime}: {levelname:<8}] {message} [{name}]"
handlers:
console:
class: logging.StreamHandler
level: 20
formatter: standard
stream: ext://sys.stderr
root:
level: 10
handlers: [console]
```
> The logging configuration is simply passed on to Python's `logging' package,
> and so it has to conform with that [package's
> requirements][res-python-logging]. See [here][res-python-logging-how-to] for
> more info.
### Configuring security
FOCA offers some convenience functionalities for securing your app.
Specifically, it allows you to configure the validation of [JSON Web
Token (JWT)][res-jwt]-based authorization, a [Casbin][res-casbin]-based access
control model, and the use of [cross-origin resource sharing (CORS)][res-cors].
To make use of them, include the `security` top-level section in your app
configuration, as well as the desired sublevel section(s):
```yaml
security:
auth:
algorithms:
- RS256
allow_expired: False
validation_methods:
- userinfo
- public_key
validation_checks: any
access_control:
api_specs: 'path/to/your/access/control/specs'
api_controllers: 'path/to/your/access/control/spec/controllers'
api_route: '/route/to/access_control_api'
db_name: access_control_db_name
collection_name: access_control_collection_name
model: access_control_model_definition
cors:
enabled: True
```
> In this example, the validation of JWT Bearer tokens would make use of the
> `RS256` algorithm, would not allow expired tokens and would grant access to
> a protected endpoint if `any` of the two listed validation methods (via the
> identity provider's `/userinfo` endpoint or its JSON Web Key (JWK) public
> key. Furthermore, the application created with this config would provide
> an access control model `model`. Corresponding permissions could be accessed
> and altered by a user with admin permissions via the dedicated endpoints
> defined in the `api_specs`, operationalized by the controllers in
> `api_controllers` and hosted at `api_route`. Permissions will be stored in
> collection `collection_name` of a dedicated MongoDB database `db_name`.
> Finally, CORS would be enabled for this application.
>
> Cf. the [API model][docs-models-security] for further options and details.
**Note:** A detailed explaination of the access control implementation can be
found [here][docs-access-control].
### Configuring the server
FOCA allows you to pass certain basic configuration options to your Flask
application. To modify defaults, include the top-level `server` keyword section
in your app configuration file:
```yaml
server:
host: '0.0.0.0'
port: 8080
debug: True
environment: development
use_reloader: False
```
> This config would create an application server hosting a Flask `development`
> environment at `0.0.0.0:8080`, Flask's debugger switched on, and its reloader
> off.
>
> Cf. the [API model][docs-models-server] for further options and details.
### Custom configuration
If you would like FOCA to validate your custom app configuration (e.g.,
parameters required for individual controllers, you can provide a path, in
dot notation, to a [`pydantic`][res-pydantic] `BaseModel`-derived model. FOCA
then tries to instantiate the model class with any custom parameters listed
under keyword section `custom`.
Suppose you have a model like the following defined in module
`my_app.custom_config`:
```py
from pydantic import BaseModel
class CustomConfig(BaseModel):
my_param: int = 5
```
And you have, in your app configuration file `my_app/config.yaml`, the
following section:
```console
custom:
my_param: 10
```
You can then have FOCA validate your custom configuration against the
`CustomConfig` class by including it in the `Foca()` call like so:
```py
from foca import Foca
foca = Foca(
config="my_app/config.yaml",
custom_config_model="my_app.custom_config.CustomConfig",
)
my_app = foca.create_app()
```
We recommend that, when defining your `pydantic` model, that you supply
default values wherever possible. In this way, the custom configuration
parameters will always be available, even if not explicitly listed in the app
configuration (like with the FOCA-specific parameters).
> Note that there is tooling available to automatically generate `pydantic`
> models from different file formats like JSON Schema etc. See here for the
> [datamodel-code-generator][res-datamodel-code-generator] project.
Apart from the reserved keyword sections listed above, you are free to include
any other sections and parameters in your app configuration file. FOCA will
simply attach these to your application instance as described
[above](#configuration) and shown [below](#accessing-configuration-parameters).
Note, however, that any such parameters need to be _manually_ validated. The
same is true if you include a `custom` section but do _not_ provide a
validation model class via the `custom_config_model` parameter when
instantiating `Foca`.
_Example:_
```yaml
my_custom_param: 'some_value'
my_custom_param_section:
another_custom_param: 3
my_custom_list_param:
- 1
- 2
- 3
```
### Accessing configuration parameters
Once the application is created using `foca()`, one can easily access any
configuration parameters from within the [application
context][res-flask-app-context] through `current_app.config.foca like so:
```python
from flask import current_app
app_config = current_app.config.foca
db = app_config.db
api = app_config.api
server = app_config.server
exceptions = app_config.exceptions
security = app_config.security
jobs = app_config.jobs
log = app_config.log
app_specific_param = current_app.config['app_specific_param']
```
_Outside of the application context_, configuration parameters are available
via `app.config.foca` in a similar way.
### More examples
Apart from the [annotated template][config-template], you can also check
out the [configuration file][config-petstore] of the [Petstore app][example]
for another example.
![Hint][img-hint] _**Or why not explore [apps that already use
FOCA][res-using-foca]?**_
## Utilities
FOCA provides some functions that may be useful for several applications.
Simply import them if you want to use them.
### Database utilities
FOCA provides the following general-purpose MongoDB controllers:
* Fetch latest object given the db `collection`:
```python
from foca.utils.db import find_one_latest
latest_object = find_one_latest("your_db_collection_instance")
```
* Fetch latest object identifier (`id`) given the db `collection`:
```python
from foca.utils.db import find_id_latest
latest_object_id = find_id_latest("your_db_collection_instance")
```
### Logging utilities
FOCA provides a decorator that can be used on any route to automatically log
any requests and/or responses passing through that route:
```python
from foca.utils.logging import log_traffic
@log_traffic(log_request=True, log_response=True, log_level=20)
def your_controller():
pass
```
> The above decorater will log both requests and responses with the specified
> logging level (`20`, or `INFO`).
### Miscellaneous utilities
* Generate a random object from a given character set:
```python
import string
from foca.utils.misc import generate_id
obj_id = generate_id(charset=string.digits, length=6)
```
> The above function processes and returns a random `obj_id` of length `6`
> consisting of only digits (`string.digits`).
### Access Control utilities
FOCA provides a decorator that can be used on any route to automatically
validate request on the basis of permission rules.
```python
from foca.security.access_control.register_access_control import (
check_permissions
)
@check_permissions
def your_controller():
pass
```
## Contributing
This project is a community effort and lives off your contributions, be it in
the form of bug reports, feature requests, discussions, or fixes and other code
changes. Please refer to our organization's [contributing
guidelines][res-elixir-cloud-contributing] if you are interested to contribute.
Please mind the [code of conduct][res-elixir-cloud-coc] for all interactions
with the community.
## Versioning
The project adopts [semantic versioning][res-semver]. Currently the service
is in beta stage, so the API may change without further notice.
## License
This project is covered by the [Apache License 2.0][license-apache] also
[shipped with this repository][license].
## Contact
The project is a collaborative effort under the umbrella of [ELIXIR Cloud &
AAI][org-elixir-cloud]. Follow the link to get in touch with us via chat or
email. Please mention the name of this service for any inquiry, proposal,
question etc.
![Logo_banner][img-logo-banner]
[badge-build-status]: <https://github.com/elixir-cloud-aai/foca/actions/workflows/checks.yml/badge.svg>
[badge-coverage]: <https://codecov.io/gh/elixir-cloud-aai/foca/branch/dev/graph/badge.svg?branch=dev>
[badge-docs]: <https://readthedocs.org/projects/foca/badge/>
[badge-github-tag]: <https://img.shields.io/github/v/tag/elixir-cloud-aai/foca?color=C39BD3>
[badge-license]: <https://img.shields.io/badge/license-Apache%202.0-blue.svg>
[badge-pypi]: <https://img.shields.io/pypi/v/foca.svg?style=flat&color=C39BD3>
[badge-url-build-status]: <https://github.com/elixir-cloud-aai/foca/actions/workflows/checks.yml>
[badge-url-coverage]: <https://codecov.io/gh/elixir-cloud-aai/foca?branch=dev>
[badge-url-docs]: <https://foca.readthedocs.io/en/latest/>
[badge-url-github-tag]: <https://github.com/elixir-cloud-aai/foca/releases>
[badge-url-license]: <http://www.apache.org/licenses/LICENSE-2.0>
[badge-url-pypi]: <https://pypi.python.org/pypi/foca>
[config-template]: templates/config.yaml
[config-petstore]: examples/petstore/config.yaml
[docs-access-control]: docs/access_control/README.md
[docs-models]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html>
[docs-models-api]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.APIConfig>
[docs-models-db]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.DBConfig>
[docs-models-exceptions]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.ExceptionConfig>
[docs-models-jobs]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.JobsConfig>
[docs-models-log]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.LogConfig>
[docs-models-security]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.SecurityConfig>
[docs-models-server]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.ServerConfig>
[example]: examples/petstore/README.md
[foca-logo]: images/foca_logo_192px.png
[img-hint]: images/hint.svg
[img-logo-banner]: images/logo-banner.svg
[license]: LICENSE
[license-apache]: <https://www.apache.org/licenses/LICENSE-2.0>
[org-elixir-cloud]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai>
[res-casbin]: <https://casbin.org/>
[res-celery]: <http://docs.celeryproject.org/>
[res-connexion]: <https://github.com/zalando/connexion>
[res-cors]: <https://flask-cors.readthedocs.io/en/latest/>
[res-elixir-cloud-coc]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai/blob/dev/CODE_OF_CONDUCT.md>
[res-elixir-cloud-contributing]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai/blob/dev/CONTRIBUTING.md>
[res-flask]: <http://flask.pocoo.org/>
[res-flask-app-context]: <https://flask.palletsprojects.com/en/1.1.x/appcontext/>
[res-jwt]: <https://jwt.io>
[res-mongo-db]: <https://www.mongodb.com/>
[res-openapi]: <https://www.openapis.org/>
[res-pydantic]: <https://pydantic-docs.helpmanual.io/>
[res-rabbitmq]: <https://www.rabbitmq.com/>
[res-semver]: <https://semver.org/>
[res-swagger]: <https://swagger.io/tools/swagger-ui/>
[res-using-foca]: <https://github.com/elixir-cloud-aai/foca/network/dependents>
[res-yaml]: <https://yaml.org/>
Raw data
{
"_id": null,
"home_page": "https://github.com/elixir-cloud-aai/foca",
"name": "foca",
"maintainer": "Alexander Kanitz",
"docs_url": null,
"requires_python": null,
"maintainer_email": "alexander.kanitz@alumnni.ethz.ch",
"keywords": "rest api app openapi python microservice",
"author": "ELIXIR Cloud & AAI",
"author_email": "alexander.kanitz@alumni.ethz.ch",
"download_url": null,
"platform": null,
"description": "# ![FOCA_logo][foca-logo]  _Develop Flask microservices quickly!_\n\n[![License][badge-license]][badge-url-license]\n[![Build_status][badge-build-status]][badge-url-build-status]\n[![Docs][badge-docs]][badge-url-docs]\n[![Coverage][badge-coverage]][badge-url-coverage]\n[![GitHub_tag][badge-github-tag]][badge-url-github-tag]\n[![PyPI_release][badge-pypi]][badge-url-pypi]\n\n**FOCA** (**F**lask-**O**penAPI-**C**onnexion-**A**rchetype) is an opinionated\narchetype that enables fast development of [OpenAPI][res-openapi]-based HTTP\nAPI microservices in [Flask][res-flask], leveraging the excellent\n[Connexion][res-connexion] framework.\n\nFOCA reduces the required boilerplate code to fire up your app to a bare\nminimum and allows you to _**focus on your application logic**_. It also avoids\nunnecessary code repetition and introduces cross-service consistency when\ndeveloping multiple applications. Simply write a configuration file, pass\nit to FOCA and you're good to go!\n\nCurrently supported features:\n\n* Manage app configuration\n* Handle exceptions\n* Register OpenAPI 2.x/3.x specifications\n* Protect endpoints via [JWT][res-jwt] validation\n* Register [MongoDB][res-mongo-db] collections\n* Run asynchronous tasks via [RabbitMQ][res-rabbitmq] & [Celery][res-celery]\n* [CORS][res-cors] support\n\nCheck the [API docs][badge-url-docs] for further details.\n\n## Table of Contents\n\n* [Usage](#usage)\n* [Configuration](#configuration)\n * [Configuring OpenAPI specifications](#configuring-openapi-specifications)\n * [Configuring MongoDB](#configuring-mongodb)\n * [Configuring exceptions](#configuring-exceptions)\n * [Configuring asynchronous tasks](#configuring-asynchronous-tasks)\n * [Configuring logging](#configuring-logging)\n * [Configuring security](#configuring-security)\n * [Configuring the server](#configuring-the-server)\n * [Custom configuration](#custom-configuration)\n * [Accessing configuration parameters](#accessing-configuration-parameters)\n* [Utilities](#utilities)\n * [Database utilities](#database-utilities)\n * [Logging utitlies](#logging-utilities)\n * [Miscellaneous utilities](#miscellaneous-utilities)\n * [Access Control utilities](#access-control-utilities)\n* [Contributing](#contributing)\n* [Versioning](#versioning)\n* [License](#license)\n* [Contact](#contact)\n\n## Usage\n\n(1) Install the [FOCA package][badge-url-pypi] with `pip`:\n\n```bash\npip install foca\n```\n\n(2) Create a [configuration](#configuration) file.\n\n(3) Import the FOCA class and pass your config file:\n\n```python\nfrom foca import Foca\n\nfoca = Foca(config_file=\"path/to/my/app/config.yaml\")\napp = foca.create_app() # returns a Connexion app instance\n```\n\n(4) Start your [Flask][res-flask] app as usual.\n\n![Hint][img-hint] _**Check out the [Petstore example application][example]\nshipped with this repository to see FOCA in action!**_\n\n## Configuration\n\n![Hint][img-hint] _**In order to get you started writing your own app\nconfiguration, you can copy the [**annotated template**][config-template]\nshipped with this repository and modify it.**_\n\nIn order to use FOCA functionalities, you must create a [YAML][res-yaml]\nconfiguration file that includes keyword sections reserved by FOCA. The\nfollowing top-level sections are interpreted by FOCA (exhaustive; links are\nprovided to the corresponding sections in this documentation, as well as to the\ncorresponding models in the [API docuementation][badge-url-docs]):\n\n* [`api`](#configuring-openapi-specifications) / [model][docs-models-api]\n* [`db`](#configuring-mongodb) / [model][docs-models-db]\n* [`exceptions`](#configuring-exceptions) / [model][docs-models-exceptions]\n* [`jobs`](#configuring-asynchronous-tasks) / [model][docs-models-jobs]\n* [`log`](#configuring-logging) / [model][docs-models-log]\n* [`security`](#configuring-security) / [model][docs-models-security]\n* [`server`](#configuring-the-server) / [model][docs-models-server]\n\n**_Any values passed to reserved keywords are automatically validated_**, and a\ncorresponding informative exception will be raised whenever a value does not\nadhere to the corresponding model as described in the [API\ndocumentation][docs-models]. If you do _not_ want to make use of a specific\nFOCA functionality, simply omit the corresponding section.\n\n### Configuring OpenAPI specifications\n\nThe `api` section is used to specify any [OpenAPI][res-openapi] specifications\nconsumed as part of your application. Essentially, FOCA adds a wrapper around\n[Connexion][res-connexion], which validates requests/responses and can serve\nthe specifications as well as a [Swagger][res-swagger]-based user interface to\nexplore the API. FOCA supports multiple specification files (versions\nSwagger/OpenAPI 2.x, OpenAPI 3.x and mixed) and multiple fragments thereof, and\nit adds additional features that allow easy modification of specifications on\nthe fly. In particular, links to routers and security definitions can be added\nto each specified endpoint.\n\n_Example:_\n\n```yaml\napi:\n specs:\n - path:\n - path/to/openapi/specs.yaml\n - path/to/openapi/additions.yaml\n add_operation_fields:\n x-openapi-router-controller: myapi.controllers\n add_security_fields:\n x-bearerInfoFunc: app.validate_token\n disable_auth: False\n connexion:\n strict_validation: True\n validate_responses: True\n options:\n swagger_ui: True\n serve_spec: True\n - path:\n - path/to/openapi/other_specs.yaml\n```\n\n> In this example, the configuration file lists two separate specifications.\n> The first is a composite one that FOCA will compile from two files,\n> `path/to/openapi/specs.yaml` and `path/to/openapi/additions.yaml`. It comes\n> with a range of different explicitly specified parameters to further\n> customize the specification itself (classes/functions implementing\n> controllers and token validation are linked to each endpoint via\n> `add_operation_fields`; `x-openapi-router-controller` and `x-bearerInfoFunc`\n> can be used to link controller functions/classes and authorization validation\n> functions to endpoints, respectively. Furthermore, a flag to disable the need\n> for passing authorization tokens and several [Connexion][res-connexion]\n> options are explicitly set for this specification. In contrast, only the path\n> to a single file is specified for the second specification, implying default\n> values for all other options. \n> \n> Further support for validating authorization can also be added to\n> specifications via the `add_security_fields` parameter under `specs` (not\n> shown here). Cf. the [API model][docs-models-api] for this and other options,\n> as well as further details.\n\n### Configuring MongoDB\n\nFOCA can register one or more [MongoDB][res-mongo-db] databases and/or\ncollections for you. To use that functionality, simply include the top-level\n`db` keyword section in your configuration file and tune its behavior through\nthe available parameters.\n\n_Example:_\n\n```yaml\ndb:\n host: mongodb\n port: 27017\n dbs:\n myDb:\n collections:\n myCollection:\n indexes:\n - keys:\n id: 1\n options:\n 'unique': True\n mySecondCollection:\n indexes:\n - keys:\n other_id: 1\n myOtherDb:\n collections:\n myThirdCollection:\n indexes:\n - keys:\n third_id: 1\n```\n\n> In this example, two databases (`myDb` and `myOtherDb`) are configured, the\n> former with two and the latter with one collection (`myCollection`,\n> `mySecondCollection` and `myThirdCollection`, respectively). FOCA will\n> automatically register and initialize these databases and collections for you\n> and add convenient clients to the app instance (accessible as children of\n> `current_app.config.foca` in an [application\n> context][res-flask-app-context]). The collections would be indexed by keys\n> `id`, `other_id` and `third_id`, respectively. Out of these, only `id`\n> will be required to be unique. \n> \n> Cf. the [API model][docs-models-db] for further options and details.\n\n### Configuring exceptions\n\nFOCA provides a convenient, configurable exception handler and a simple way\nof adding new exceptions to be used with that handler. To use it, specify a\ntop-level `exceptions` section in the app configuration file.\n\n_Example:_\n\n```yaml\nexceptions:\n required_members: [['msg'], ['status']]\n status_member: ['status']\n exceptions: my_app.exceptions.exceptions\n logging: one_line\n```\n\n> This example configuration would attach the exceptions defined in the\n> `my_app.exceptions.exceptions` dictionary to the exception handler. The\n> exception handler ensures that every exception in that dictionary defines\n> at least members `msg` and `status`. Out of these, `status` will be used\n> to inform the status code for the error response. Exceptions processed via\n> FOCA's exception handler will be automatically logged, if requested. In this\n> case, the handler is configured to log all errors verbosely (including any\n> traceback information, if applicable) on a single line (other rendering\n> options are also supported).\n> \n> You may further configure optional members, a list of `public members` (to be\n> included in error responses) and `private members` (only visible in logs).\n> Cf. the [API model][docs-models-exceptions] for further options and details.\n\n### Configuring asynchronous tasks\n\nFOCA offers limited support for running asynchronous tasks via the\n[RabbitMQ][res-rabbitmq] broker and [Celery][res-celery]. To make use of it,\ninclude the `jobs` top-level section in the app configuration file.\n\n_Example:_\n\n```yaml\njobs:\n host: rabbitmq\n port: 5672\n backend: 'rpc://'\n include:\n - my_app.tasks.my_task_1\n - my_app.tasks.my_task_2\n```\n\n> This config attaches the `rabbitmq` broker host running on port `5672` to\n> FOCA and registers the tasks found in modules `my_task_1` and `my_task_2`. \n> \n> Cf. the [API model][docs-models-jobs] for further details. \n\nThe `foca.Foca` class provides a method `.create_celery_app()` that you can\nuse in your Celery worker entry point to crate a Celery app, like so:\n\n```py\nfrom foca import Foca\n\nfoca = Foca(config=\"my_app/config.yaml\")\nmy_celery_app = foca.create_celery_app()\n```\n\n### Configuring logging\n\nFOCA allows you to specify a YAML-based logging configuration to control your\napplication's logging behavior in an effort to provide a single configuration\nfile for every application. To use it, simply add a `log` top-level section in\nyour app configuration file.\n\n_Example:_\n\n```yaml\nlog:\n version: 1\n disable_existing_loggers: False\n formatters:\n standard:\n class: logging.Formatter\n style: \"{\"\n format: \"[{asctime}: {levelname:<8}] {message} [{name}]\"\n handlers:\n console:\n class: logging.StreamHandler\n level: 20\n formatter: standard\n stream: ext://sys.stderr\n root:\n level: 10\n handlers: [console]\n```\n\n> The logging configuration is simply passed on to Python's `logging' package,\n> and so it has to conform with that [package's\n> requirements][res-python-logging]. See [here][res-python-logging-how-to] for\n> more info.\n\n### Configuring security\n\nFOCA offers some convenience functionalities for securing your app.\nSpecifically, it allows you to configure the validation of [JSON Web\nToken (JWT)][res-jwt]-based authorization, a [Casbin][res-casbin]-based access\ncontrol model, and the use of [cross-origin resource sharing (CORS)][res-cors].\nTo make use of them, include the `security` top-level section in your app\nconfiguration, as well as the desired sublevel section(s):\n\n```yaml\nsecurity:\n auth:\n algorithms:\n - RS256\n allow_expired: False\n validation_methods:\n - userinfo\n - public_key\n validation_checks: any\n access_control:\n api_specs: 'path/to/your/access/control/specs'\n api_controllers: 'path/to/your/access/control/spec/controllers'\n api_route: '/route/to/access_control_api'\n db_name: access_control_db_name\n collection_name: access_control_collection_name\n model: access_control_model_definition\n cors:\n enabled: True\n```\n\n> In this example, the validation of JWT Bearer tokens would make use of the\n> `RS256` algorithm, would not allow expired tokens and would grant access to\n> a protected endpoint if `any` of the two listed validation methods (via the\n> identity provider's `/userinfo` endpoint or its JSON Web Key (JWK) public\n> key. Furthermore, the application created with this config would provide\n> an access control model `model`. Corresponding permissions could be accessed\n> and altered by a user with admin permissions via the dedicated endpoints\n> defined in the `api_specs`, operationalized by the controllers in\n> `api_controllers` and hosted at `api_route`. Permissions will be stored in\n> collection `collection_name` of a dedicated MongoDB database `db_name`.\n> Finally, CORS would be enabled for this application.\n> \n> Cf. the [API model][docs-models-security] for further options and details.\n\n**Note:** A detailed explaination of the access control implementation can be\nfound [here][docs-access-control].\n\n### Configuring the server\n\nFOCA allows you to pass certain basic configuration options to your Flask\napplication. To modify defaults, include the top-level `server` keyword section\nin your app configuration file:\n\n```yaml\nserver:\n host: '0.0.0.0'\n port: 8080\n debug: True\n environment: development\n use_reloader: False\n```\n\n> This config would create an application server hosting a Flask `development`\n> environment at `0.0.0.0:8080`, Flask's debugger switched on, and its reloader\n> off.\n> \n> Cf. the [API model][docs-models-server] for further options and details.\n\n### Custom configuration\n\nIf you would like FOCA to validate your custom app configuration (e.g.,\nparameters required for individual controllers, you can provide a path, in\ndot notation, to a [`pydantic`][res-pydantic] `BaseModel`-derived model. FOCA\nthen tries to instantiate the model class with any custom parameters listed\nunder keyword section `custom`.\n\nSuppose you have a model like the following defined in module\n`my_app.custom_config`:\n\n```py\nfrom pydantic import BaseModel\n\n\nclass CustomConfig(BaseModel):\n my_param: int = 5\n```\n\nAnd you have, in your app configuration file `my_app/config.yaml`, the\nfollowing section:\n\n```console\ncustom:\n my_param: 10\n```\n\nYou can then have FOCA validate your custom configuration against the\n`CustomConfig` class by including it in the `Foca()` call like so:\n\n```py\nfrom foca import Foca\n\nfoca = Foca(\n config=\"my_app/config.yaml\",\n custom_config_model=\"my_app.custom_config.CustomConfig\",\n)\nmy_app = foca.create_app()\n```\n\nWe recommend that, when defining your `pydantic` model, that you supply\ndefault values wherever possible. In this way, the custom configuration\nparameters will always be available, even if not explicitly listed in the app\nconfiguration (like with the FOCA-specific parameters).\n\n> Note that there is tooling available to automatically generate `pydantic`\n> models from different file formats like JSON Schema etc. See here for the\n> [datamodel-code-generator][res-datamodel-code-generator] project.\n\nApart from the reserved keyword sections listed above, you are free to include\nany other sections and parameters in your app configuration file. FOCA will\nsimply attach these to your application instance as described\n[above](#configuration) and shown [below](#accessing-configuration-parameters).\nNote, however, that any such parameters need to be _manually_ validated. The\nsame is true if you include a `custom` section but do _not_ provide a\nvalidation model class via the `custom_config_model` parameter when\ninstantiating `Foca`.\n\n_Example:_\n\n```yaml\nmy_custom_param: 'some_value'\n\nmy_custom_param_section:\n another_custom_param: 3\n my_custom_list_param:\n - 1\n - 2\n - 3\n```\n\n### Accessing configuration parameters\n\nOnce the application is created using `foca()`, one can easily access any\nconfiguration parameters from within the [application\ncontext][res-flask-app-context] through `current_app.config.foca like so:\n\n```python\nfrom flask import current_app\n\napp_config = current_app.config.foca\n\ndb = app_config.db\napi = app_config.api\nserver = app_config.server\nexceptions = app_config.exceptions\nsecurity = app_config.security\njobs = app_config.jobs\nlog = app_config.log\napp_specific_param = current_app.config['app_specific_param']\n```\n\n_Outside of the application context_, configuration parameters are available\nvia `app.config.foca` in a similar way.\n\n### More examples\n\nApart from the [annotated template][config-template], you can also check\nout the [configuration file][config-petstore] of the [Petstore app][example]\nfor another example.\n\n![Hint][img-hint] _**Or why not explore [apps that already use\nFOCA][res-using-foca]?**_\n\n## Utilities\n\nFOCA provides some functions that may be useful for several applications.\nSimply import them if you want to use them.\n\n### Database utilities\n\nFOCA provides the following general-purpose MongoDB controllers:\n\n* Fetch latest object given the db `collection`:\n\n```python\nfrom foca.utils.db import find_one_latest\n\nlatest_object = find_one_latest(\"your_db_collection_instance\")\n```\n\n* Fetch latest object identifier (`id`) given the db `collection`:\n\n```python\nfrom foca.utils.db import find_id_latest\n\nlatest_object_id = find_id_latest(\"your_db_collection_instance\")\n```\n\n### Logging utilities\n\nFOCA provides a decorator that can be used on any route to automatically log\nany requests and/or responses passing through that route:\n\n```python\nfrom foca.utils.logging import log_traffic\n\n@log_traffic(log_request=True, log_response=True, log_level=20)\ndef your_controller():\n pass\n```\n\n> The above decorater will log both requests and responses with the specified\n> logging level (`20`, or `INFO`).\n\n### Miscellaneous utilities\n\n* Generate a random object from a given character set:\n\n```python\nimport string\n\nfrom foca.utils.misc import generate_id\n\nobj_id = generate_id(charset=string.digits, length=6)\n```\n\n> The above function processes and returns a random `obj_id` of length `6`\n> consisting of only digits (`string.digits`).\n\n### Access Control utilities\n\nFOCA provides a decorator that can be used on any route to automatically\nvalidate request on the basis of permission rules.\n\n```python\nfrom foca.security.access_control.register_access_control import (\n check_permissions\n)\n\n@check_permissions\ndef your_controller():\n pass\n```\n\n## Contributing\n\nThis project is a community effort and lives off your contributions, be it in\nthe form of bug reports, feature requests, discussions, or fixes and other code\nchanges. Please refer to our organization's [contributing\nguidelines][res-elixir-cloud-contributing] if you are interested to contribute.\nPlease mind the [code of conduct][res-elixir-cloud-coc] for all interactions\nwith the community.\n\n## Versioning\n\nThe project adopts [semantic versioning][res-semver]. Currently the service\nis in beta stage, so the API may change without further notice.\n\n## License\n\nThis project is covered by the [Apache License 2.0][license-apache] also\n[shipped with this repository][license].\n\n## Contact\n\nThe project is a collaborative effort under the umbrella of [ELIXIR Cloud &\nAAI][org-elixir-cloud]. Follow the link to get in touch with us via chat or\nemail. Please mention the name of this service for any inquiry, proposal,\nquestion etc.\n\n![Logo_banner][img-logo-banner]\n\n[badge-build-status]: <https://github.com/elixir-cloud-aai/foca/actions/workflows/checks.yml/badge.svg>\n[badge-coverage]: <https://codecov.io/gh/elixir-cloud-aai/foca/branch/dev/graph/badge.svg?branch=dev>\n[badge-docs]: <https://readthedocs.org/projects/foca/badge/>\n[badge-github-tag]: <https://img.shields.io/github/v/tag/elixir-cloud-aai/foca?color=C39BD3>\n[badge-license]: <https://img.shields.io/badge/license-Apache%202.0-blue.svg>\n[badge-pypi]: <https://img.shields.io/pypi/v/foca.svg?style=flat&color=C39BD3>\n[badge-url-build-status]: <https://github.com/elixir-cloud-aai/foca/actions/workflows/checks.yml>\n[badge-url-coverage]: <https://codecov.io/gh/elixir-cloud-aai/foca?branch=dev>\n[badge-url-docs]: <https://foca.readthedocs.io/en/latest/>\n[badge-url-github-tag]: <https://github.com/elixir-cloud-aai/foca/releases>\n[badge-url-license]: <http://www.apache.org/licenses/LICENSE-2.0>\n[badge-url-pypi]: <https://pypi.python.org/pypi/foca>\n[config-template]: templates/config.yaml\n[config-petstore]: examples/petstore/config.yaml\n[docs-access-control]: docs/access_control/README.md\n[docs-models]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html>\n[docs-models-api]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.APIConfig>\n[docs-models-db]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.DBConfig>\n[docs-models-exceptions]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.ExceptionConfig>\n[docs-models-jobs]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.JobsConfig>\n[docs-models-log]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.LogConfig>\n[docs-models-security]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.SecurityConfig>\n[docs-models-server]: <https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.ServerConfig>\n[example]: examples/petstore/README.md\n[foca-logo]: images/foca_logo_192px.png\n[img-hint]: images/hint.svg\n[img-logo-banner]: images/logo-banner.svg\n[license]: LICENSE\n[license-apache]: <https://www.apache.org/licenses/LICENSE-2.0>\n[org-elixir-cloud]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai>\n[res-casbin]: <https://casbin.org/>\n[res-celery]: <http://docs.celeryproject.org/>\n[res-connexion]: <https://github.com/zalando/connexion>\n[res-cors]: <https://flask-cors.readthedocs.io/en/latest/>\n[res-elixir-cloud-coc]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai/blob/dev/CODE_OF_CONDUCT.md>\n[res-elixir-cloud-contributing]: <https://github.com/elixir-cloud-aai/elixir-cloud-aai/blob/dev/CONTRIBUTING.md>\n[res-flask]: <http://flask.pocoo.org/>\n[res-flask-app-context]: <https://flask.palletsprojects.com/en/1.1.x/appcontext/>\n[res-jwt]: <https://jwt.io>\n[res-mongo-db]: <https://www.mongodb.com/>\n[res-openapi]: <https://www.openapis.org/>\n[res-pydantic]: <https://pydantic-docs.helpmanual.io/>\n[res-rabbitmq]: <https://www.rabbitmq.com/>\n[res-semver]: <https://semver.org/>\n[res-swagger]: <https://swagger.io/tools/swagger-ui/>\n[res-using-foca]: <https://github.com/elixir-cloud-aai/foca/network/dependents>\n[res-yaml]: <https://yaml.org/>\n",
"bugtrack_url": null,
"license": null,
"summary": "Archetype for OpenAPI microservices based on Flask and Connexion",
"version": "0.13.0",
"project_urls": {
"ELIXIR Cloud & AAI": "https://elixir-europe.github.io/cloud/",
"Homepage": "https://github.com/elixir-cloud-aai/foca",
"Repository": "https://github.com/elixir-cloud-aai/foca",
"Tracker": "https://github.com/elixir-cloud-aai/foca/issues"
},
"split_keywords": [
"rest",
"api",
"app",
"openapi",
"python",
"microservice"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ced6c023fff9e8d30569e9428a5da0824b58301f6b0e5f55cbbd40992e794e4c",
"md5": "ddaec9e21efe3ed97d6b05bcda5ac2c2",
"sha256": "bde43a704c156b23808c4a8e8653c62b0d876be6a69b37e0ed6cc05d7a4fbb2b"
},
"downloads": -1,
"filename": "foca-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddaec9e21efe3ed97d6b05bcda5ac2c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 92785,
"upload_time": "2024-05-20T03:54:25",
"upload_time_iso_8601": "2024-05-20T03:54:25.170045Z",
"url": "https://files.pythonhosted.org/packages/ce/d6/c023fff9e8d30569e9428a5da0824b58301f6b0e5f55cbbd40992e794e4c/foca-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-20 03:54:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elixir-cloud-aai",
"github_project": "foca",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "foca"
}
JSON
