Skip to main content

Automatically import APIStar sub apps

Project description

API Star AutoApp

Easily manage and compose API Star projects

CircleCI Test Status PyPI version


Automatically orchestrates API Star projects with sub modules using an app based pattern.


Features

  • Automatically build URLs based on your project's structure.
    • Autoapp Includes routes from apps in your project creating the appropriate URL based on the filesystem path from the projects root app.py file.
  • Automatically collect event_hooks and component lists from apps and consolidate them together to build the App/ASyncApp with.
  • Easily add external packages that support the app.py layout.
    ex: AutoApp(apps=['apistar_websocket'])
  • Allow an ordered priority list of apps by their path string to control the order of items in the event_hooks and component lists as well as control import order.

Quickstart

Just use AutoApp or AutoASyncApp in place of App and ASyncApp respectively

from apistar-autoapp import AutoApp

async def welcome() -> dict:
    return {'msg': 'hello'}


routes = [
    Route('/', 'GET', handler=welcome, name='welcome'),
]

app = AutoApp(
    routes=routes,
)


if __name__ == '__main__':
    app.serve('127.0.0.1', 8000, debug=True)

An ASync application that uses the apistar-websocket package. To use the external library simply list it in the apps parameter.
NOTE: packages listed in apps must support the app.py layout.

from apistar-autoapp import AutoASyncApp

async def welcome() -> dict:
    return {'msg': 'hello'}


routes = [
    Route('/', 'GET', handler=welcome, name='welcome'),
]

app = AutoASyncApp(
    apps=['apistar_websocket'],
    routes=routes,
)


if __name__ == '__main__':
    app.serve('127.0.0.1', 8000, debug=True)

Install

pip install apistar-autoapp

or for Pipenv users

pipenv install apistar-autoapp

Anatomy

For a package to be considered an 'app' it must contain a file named app.py in it's top directory. The app.py file can be empty. It's in the app.py file where you expose what your app provides to the API Star configuration. Autoapp will look for three attributes on the app.py module and if they're found add them to the API Star configuration at startup.

The attributes must be lists and named:

routes
components
event_hooks

For example, a simple app that only exposes it's routes could be:

app.py:

from .handlers import routes

Or an app that exposes it's routes, event_hooks and components:

app.py:

from .handlers import routes
from .components import components
from .event_hooks import event_hooks

And of course if you have a simple app you can have all of your code in the app.py and then have module variables defined by your application code.

A simple app:

from apistar import App, Route


def homepage() -> str:
    return '<html><body><h1>Homepage</h1></body></html>'


routes = [
    Route('/', method='GET', handler=homepage),
]

Example project structure


project/
  app.py
  v1/
    app.py
    ...
    endpointOne/
      app.py
      ...
    endpointTwo/
      app.py
      ...

If the v1/app.py file is empty and each of the endpoint* apps exposes a single root URL, /, route the route URLs created for the project, via Includes would be:

/v1/endpointOne
/v1/endpointTwo

And if endpointOne had another route for the URL /users, you'd then have:

/v1/endpointOne
/v1/endpointOne/users
/v1/endpointTwo

Docs

AutoApp

AutoApp(project_dir: str = None,
        priority_apps: list = None,
        print_results: bool = False,
        **kwargs) -> App

Parameters:

(Optional)
apps: A list of packages to add to your App. Use this for packages outside or your App/project.
Packages listed in the apps list must be on your PYTHON_PATH.

(Optional)
project_dir: The directory from which apistar-autoapp will look for a project root.
    This is autodetected if not used and you normally won't use this parameter.

(Optional)
priority_apps: A list of apps, by their import path, that will be imported before all
  other apps found by apistar-autoapp and imported in the order they are given.

(Optional)
print_results: Print the results of the configuration created by apistar-autoapp to
  the console.

kwargs: These are the arguments you'd normally pass to App or ASyncApp. If you pass
  any of the arguments: routes, components or event_hooks, they will be given precedence
  and listed before any of the corresponding values created by autoapp.

AutoASyncApp

The same as AutoApp but creates a project using ASyncApp

AutoASyncApp(project_dir: str = None,
             priority_apps: list = None,
             print_results: bool = False,
             **kwargs) -> ASyncApp

app_args

app_args(project_dir: str = None,
         priority_apps: list = None,
         print_results: bool = False,
         **kwargs) -> dict:

app_args is the same as AutoApp and AutoASyncApp except it returns a dictionary of arguments that are intended for use by App or ASyncApp.

In fact AutoApp is just:

def AutoApp(**kwargs) -> App:
    return App(**app_args(**kwargs))

So if you want to do something with the data from autoapp before creating your App it's easy:

kwargs = app_args(...)
# Do something with kwargs
# ...
app = App(**kwargs)

Print helper

There are some printing helpers for internal use by apistar-autoapp but are exposed for use by other modules. There is a Printer class the uses print by default but can use any function that accepts a string in it's place.

from apistar_autoapp.printer import Printer

pr = Printer()

# Or if you want to your own print function, like a logger:
pr = Printer(printer=logger.info)

...

# to print out a list of routes:
pr.routes(routes)

include

Prints an Include instance to the console as well as all of it's Routes in the form:

Include: <url> <name>
    <Routes>

ex:

Include: /v2/welcome v2:welcome Route: GET /, welcome app.welcome() -> dict:

route

Prints a Route instance to the console in the form:

Route: <method> <url>, <name>
       <handler>

ex:

Route: GET /, welcome
       app.welcome() -> dict:

routes

Prints a list of Routes and Includes using print_route and print_include in the form:

Routes:
    [
        <print_route> or <print_include>,
        ...
    ]

ex:

Routes:
    Route: GET /, welcome
           app.welcome() -> dict:
    Include: /v2/home v2:home
      Route: GET /v2/home/, list
             v2.home.handlers.list_homes() -> list:
    ...

components

Prints a list of components in the form:

Components:
        <ComponentClass>
                resolve(<signature>) -> <returns>:

ex:

Components:
        WebSocketComponent
                resolve(self, scope: ASGIScope, send: ASGISend, receive: ASGIReceive, app: App) -> WebSocket:

TODO

  • Allow any package with an app.py file that is importable to be used with Autoapp
  • Add the ability to have a list of excluded apps that will not be imported by Autoapp
  • Add printer for event_hooks

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apistar-autoapp-0.6.1.tar.gz (8.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page