import inspect
from typing import Type
import click_spinner
import flask_cors
from anytree import Node
from apispec import APISpec
from click import option
from flask import Flask, jsonify
from flask.globals import _app_ctx_stack
from flask_sqlalchemy import SQLAlchemy
from marshmallow import ValidationError
from werkzeug.exceptions import HTTPException, UnprocessableEntity
import ereuse_devicehub.ereuse_utils
from ereuse_devicehub.ereuse_utils import ensure_utf8
from ereuse_devicehub.teal.auth import Auth
from ereuse_devicehub.teal.cli import TealCliRunner
from ereuse_devicehub.teal.client import Client
from ereuse_devicehub.teal.config import Config as ConfigClass
from ereuse_devicehub.teal.db import SchemaSQLAlchemy
from ereuse_devicehub.teal.json_util import TealJSONEncoder
from ereuse_devicehub.teal.request import Request
from ereuse_devicehub.teal.resource import Converters, LowerStrConverter, Resource
class Teal(Flask):
"""
An opinionated REST and JSON first server built on Flask using
MongoDB and Marshmallow.
"""
test_client_class = Client
request_class = Request
json_encoder = TealJSONEncoder
cli_context_settings = {'help_option_names': ('-h', '--help')}
test_cli_runner_class = TealCliRunner
def __init__(
self,
config: ConfigClass,
db: SQLAlchemy,
schema: str = None,
import_name=__name__.split('.')[0],
static_url_path=None,
static_folder='static',
static_host=None,
host_matching=False,
subdomain_matching=False,
template_folder='templates',
instance_path=None,
instance_relative_config=False,
root_path=None,
use_init_db=True,
Auth: Type[Auth] = Auth,
):
"""
:param config:
:param db:
:param schema: A string describing the main PostgreSQL's schema.
``None`` disables this functionality.
If you use a factory of apps (for example by using
:func:`teal.teal.prefixed_database_factory`) and then set this
value differently per each app (as each app has a separate config)
you effectively create a `multi-tenant app <https://
news.ycombinator.com/item?id=4268792>`_.
Your models by default will be created in this ``SCHEMA``,
unless you set something like::
class User(db.Model):
__table_args__ = {'schema': 'users'}
In which case this will be created in the ``users`` schema.
Schemas are interesting over having multiple databases (i.e. using
flask-sqlalchemy's data binding) because you can have relationships
between them.
Note that this only works with PostgreSQL.
:param import_name:
:param static_url_path:
:param static_folder:
:param static_host:
:param host_matching:
:param subdomain_matching:
:param template_folder:
:param instance_path:
:param instance_relative_config:
:param root_path:
:param Auth:
"""
self.schema = schema
ensure_utf8(self.__class__.__name__)
super().__init__(
import_name,
static_url_path,
static_folder,
static_host,
host_matching,
subdomain_matching,
template_folder,
instance_path,
instance_relative_config,
root_path,
)
self.config.from_object(config)
flask_cors.CORS(self)
# Load databases
self.auth = Auth()
self.url_map.converters[Converters.lower.name] = LowerStrConverter
self.load_resources()
self.register_error_handler(HTTPException, self._handle_standard_error)
self.register_error_handler(ValidationError, self._handle_validation_error)
self.db = db
db.init_app(self)
if use_init_db:
self.cli.command('init-db', context_settings=self.cli_context_settings)(
self.init_db
)
self.spec = None # type: APISpec
self.apidocs()
# noinspection PyAttributeOutsideInit
def load_resources(self):
self.resources = {}
"""
The resources definitions loaded on this App, referenced by their
type name.
"""
self.tree = {}
"""
A tree representing the hierarchy of the instances of
ResourceDefinitions. ResourceDefinitions use these nodes to
traverse their hierarchy.
Do not use the normal python class hierarchy as it is global,
thus unreliable if you run different apps with different
schemas (for example, an extension that is only added on the
third app adds a new type of user).
"""
for ResourceDef in self.config['RESOURCE_DEFINITIONS']:
resource_def = ResourceDef(self) # type: Resource
self.register_blueprint(resource_def)
if resource_def.cli_commands:
@self.cli.group(
resource_def.cli_name,
context_settings=self.cli_context_settings,
short_help='{} management.'.format(resource_def.type),
)
def dummy_group():
pass
for (
cli_command,
*args,
) in resource_def.cli_commands: # Register CLI commands
# todo cli commands with multiple arguments end-up reversed
# when teal has been executed multiple times (ex. testing)
# see _param_memo func in click package
dummy_group.command(*args)(cli_command)
# todo should we use resource_def.name instead of type?
# are we going to have collisions? (2 resource_def -> 1 schema)
self.resources[resource_def.type] = resource_def
self.tree[resource_def.type] = Node(resource_def.type)
# Link tree nodes between them
for _type, node in self.tree.items():
resource_def = self.resources[_type]
_, Parent, *superclasses = inspect.getmro(resource_def.__class__)
if Parent is not Resource:
node.parent = self.tree[Parent.type]
@staticmethod
def _handle_standard_error(e: HTTPException):
"""
Handles HTTPExceptions by transforming them to JSON.
"""
try:
response = jsonify(e)
response.status_code = e.code
except (AttributeError, TypeError) as e:
code = getattr(e, 'code', 500)
response = jsonify(
{'message': str(e), 'code': code, 'type': e.__class__.__name__}
)
response.status_code = code
return response
@staticmethod
def _handle_validation_error(e: ValidationError):
data = {
'message': e.messages,
'code': UnprocessableEntity.code,
'type': e.__class__.__name__,
}
response = jsonify(data)
response.status_code = UnprocessableEntity.code
return response
@option(
'--erase/--no-erase',
default=False,
help='Delete all contents from the database (including common schemas)?',
)
@option(
'--exclude-schema',
default=None,
help='Schema to exclude creation (and deletion if --erase is set). '
'Required the SchemaSQLAlchemy.',
)
def init_db(self, erase: bool = False, exclude_schema=None):
"""
Initializes a database from scratch,
creating tables and needed resources.
Note that this does not create the database per se.
If executing this directly, remember to use an app_context.
Resources can hook functions that will be called when this
method executes, by subclassing :meth:`teal.resource.
Resource.load_resource`.
"""
assert _app_ctx_stack.top, 'Use an app context.'
print('Initializing database...'.ljust(30), end='')
with click_spinner.spinner():
if erase:
if exclude_schema: # Using then a schema teal sqlalchemy
assert isinstance(self.db, SchemaSQLAlchemy)
self.db.drop_schema()
else: # using regular flask sqlalchemy
self.db.drop_all()
self._init_db(exclude_schema)
self._init_resources()
self.db.session.commit()
print('done.')
def _init_db(self, exclude_schema=None) -> bool:
"""Where the database is initialized. You can override this.
:return: A flag stating if the database has been created (can
be False in case check is True and the schema already
exists).
"""
if exclude_schema: # Using then a schema teal sqlalchemy
assert isinstance(self.db, SchemaSQLAlchemy)
self.db.create_all(exclude_schema=exclude_schema)
else: # using regular flask sqlalchemy
self.db.create_all()
return True
def _init_resources(self, **kw):
for resource in self.resources.values():
resource.init_db(self.db, **kw)
def apidocs(self):
"""Apidocs configuration and generation."""
self.spec = APISpec(
plugins=(
'apispec.ext.flask',
'apispec.ext.marshmallow',
),
**self.config.get_namespace('API_DOC_CONFIG_'),
)
for name, resource in self.resources.items():
if resource.SCHEMA:
self.spec.definition(
name,
schema=resource.SCHEMA,
extra_fields=self.config.get_namespace('API_DOC_CLASS_'),
)
self.add_url_rule('/apidocs', view_func=self.apidocs_endpoint)
def apidocs_endpoint(self):
"""An endpoint that prints a JSON OpenApi 2.0 specification."""
if not getattr(self, '_apidocs', None):
# We are forced to to this under a request context
for path, view_func in self.view_functions.items():
if path != 'static':
self.spec.add_path(view=view_func)
self._apidocs = self.spec.to_dict()
return jsonify(self._apidocs)
class DumpeableHTTPException(ereuse_devicehub.ereuse_utils.Dumpeable):
"""Exceptions that inherit this class will be able to dump
to dicts and JSONs.
"""
def dump(self):
# todo this is heavily ad-hoc and should be more generic
value = super().dump()
value['type'] = self.__class__.__name__
value['code'] = self.code
value.pop('exc', None)
value.pop('response', None)
if 'data' in value:
value['fields'] = value['data']['messages']
del value['data']
if 'message' not in value:
value['message'] = value.pop('description', str(self))
return value
# Add dump capacity to Werkzeug's HTTPExceptions
HTTPException.__bases__ = HTTPException.__bases__ + (DumpeableHTTPException,)