ASGI¶
Since the admin is an ASGI app, you can either run it standalone like in the demo, or integrate it with a larger ASGI app.
Hint
Piccolo can help you create a new ASGI app
using piccolo asgi new
.
For example, using Starlette routes:
import uvicorn
from movies.endpoints import HomeEndpoint
from movies.tables import Director, Movie
from starlette.routing import Mount, Route, Router
from piccolo_admin.endpoints import create_admin
# The `allowed_hosts` argument is required when running under HTTPS. It's
# used for additional CSRF defence.
admin = create_admin([Director, Movie], allowed_hosts=["my_site.com"])
router = Router(
[
Route(path="/", endpoint=HomeEndpoint),
Mount(path="/admin/", app=admin),
]
)
if __name__ == "__main__":
uvicorn.run(router)
FastAPI example¶
Here’s a complete example of a FastAPI app using Piccolo admin.
# app.py
from fastapi import FastAPI
from fastapi.routing import Mount
from movies.tables import Director, Movie
from piccolo.engine import engine_finder
from piccolo_admin.endpoints import create_admin
app = FastAPI(
routes=[
Mount(
path="/admin/",
app=create_admin(
tables=[Director, Movie],
# Specify a different site name in the
# admin UI (default Piccolo Admin):
site_name="My Site Admin",
# Required when running under HTTPS:
# allowed_hosts=["my_site.com"],
),
),
],
)
@app.on_event("startup")
async def open_database_connection_pool():
engine = engine_finder()
await engine.start_connnection_pool()
@app.on_event("shutdown")
async def close_database_connection_pool():
engine = engine_finder()
await engine.close_connnection_pool()
To run app.py
use:
uvicorn app:app --port 8000 --host 0.0.0.0
Now you can go to localhost:8000/admin and log in as an admin user (see Authentication for how to create users).
Source¶
- class piccolo_admin.endpoints.create_admin(tables: Sequence[Union[Type[Table], TableConfig]], forms: List[FormConfig] = [], auth_table: Optional[Type[BaseUser]] = None, session_table: Optional[Type[SessionsBase]] = None, session_expiry: timedelta = timedelta(hours=1), max_session_expiry: timedelta = timedelta(days=7), increase_expiry: Optional[timedelta] = timedelta(minutes=20), page_size: int = 15, read_only: bool = False, rate_limit_provider: Optional[RateLimitProvider] = None, production: bool = False, site_name: str = 'Piccolo Admin', default_language_code: str = 'auto', translations: Optional[List[Translation]] = None, auto_include_related: bool = True, allowed_hosts: Sequence[str] = [], debug: bool = False, sidebar_links: Dict[str, str] = {})[source]¶
- Parameters:
tables – Each of the tables will be added to the admin.
forms – For each
FormConfig
specified, a form will automatically be rendered in the user interface, accessible via the sidebar.auth_table – Either a
BaseUser
, orBaseUser
subclass table, which is used for fetching users. Defaults toBaseUser
if none if specified.session_table – Either a
SessionsBase
, orSessionsBase
subclass table, which is used for storing and querying session tokens. Defaults toSessionsBase
if none if specified.session_expiry – How long a session is valid for.
max_session_expiry – The maximum time a session is valid for, taking into account any refreshes using
increase_expiry
.increase_expiry – If set, the
session_expiry
will be increased by this amount if it’s close to expiry.page_size – The admin API paginates content - this sets the default number of results on each page.
read_only – If
True
, all non auth endpoints only respond to GET requests - the admin can still be viewed, and the data can be filtered. Useful for creating online demos.rate_limit_provider – Rate limiting middleware is used to protect the login endpoint against brute force attack. If not set, an
InMemoryLimitProvider
will be configured with reasonable defaults.production – If
True
, the admin will enforce stronger security - for example, the cookies used will be secure, meaning they are only sent over HTTPS.site_name – Specify a different site name in the admin UI (default
'Piccolo Admin'
).default_language_code – Specify the default language used in the admin UI. The value should be an IETF language tag, for example
'en'
for English. To see available values seepiccolo_admin/translations/data.py
. The UI will be automatically translated into this language. If a value of'auto'
is specified, then we check the user’s browser for the language they prefer, using thenavigator.language
JavaScript API.translations –
Specify which translations are available. By default, we use every translation in
piccolo_admin/translations/data.py
.Here’s an example - if we know our users only speak English or Croatian, we can specify that only those translations are visible in the language selector in the UI:
from piccolo.translations.data import ENGLISH, CROATIAN create_admin( tables=[TableA, TableB], default_language_code='hr', translations=[ENGLISH, CROATIAN] )
You can also use this to provide your own translations, if there’s a language we don’t currently support (though please open a PR to add it!):
from piccolo.translations.models import Translation from piccolo.translations.data import ENGLISH MY_LANGUAGE = Translation( language_code='xx', language_name='My Language', translations={ 'Welcome': 'XXXXX', ... } ) create_admin( tables=[TableA, TableB], default_language_code='xx', translations=[ENGLISH, MY_LANGUAGE] )
auto_include_related – If a table has foreign keys to other tables, those tables will also be included in the admin by default, if not already specified. Otherwise the admin won’t work as expected.
allowed_hosts – This is used by the
CSRFMiddleware
as an additional layer of protection when the admin is run under HTTPS. It must be a sequence of strings, such as['my_site.com']
.debug – If
True
, debug mode is enabled. Any unhandled exceptions will return a stack trace, rather than a generic 500 error. Don’t use this in production!sidebar_links –
Custom links in the navigation sidebar. Example uses cases:
Providing a quick way to get to specific pages with pre-applied filters/sorting.
Linking to relative external websites.
Here’s a full example:
from piccolo_admin.endpoints import create_admin create_admin( tables=[Movie, Director], sidebar_links={ "Top Movies": "/admin/#/movie?__order=-box_office", "Google": "https://google.com" }, )