Piccolo Admin Documentation

Piccolo Admin is a modern content management system (CMS) and admin interface for Python. It provides a high-quality, responsive UI for managing data, serving as an alternative to Django Admin or WordPress.

Key features include:

• Modern Tech Stack: Vue.js frontend with a powerful REST backend.
• Data Management: Powerful filtering, bulk actions (update/delete), and CSV exports.
• UI/UX: Dark mode support, mobile/desktop responsiveness, and flexible column visibility.
• Extensibility: Easy integration with ASGI apps (FastAPI, Starlette), custom form creation, and custom sidebar links.
• Security & Media: Built-in security, MFA support, and media storage support for local files or S3-compatible services.
• Localization: Multilingual support out of the box.

When calling create_admin, you can pass standard Table classes to register them in the admin interface. However, for more granular control over how a table is displayed and how it behaves (especially for tables with many columns), you should use TableConfig instances. You can mix and match Table classes and TableConfig instances in the list passed to create_admin.

from piccolo_admin.endpoints import create_admin, TableConfig

# Using standard Table classes
create_admin([Director, Movie])

# Using TableConfig for extra control
movie_config = TableConfig(Movie, visible_columns=[Movie.id, Movie.name])
create_admin([Director, movie_config])

Piccolo Admin allows you to add custom forms to the admin interface for tasks like running background jobs or downloading reports. To implement a custom form, you only need two components:

1. A Pydantic model to define the form fields.
2. An endpoint (a sync or async function) to handle the form submission.

Piccolo Admin automatically generates the entire UI based on the Pydantic model, so no frontend code is required.

Piccolo Admin manages media files by storing unique file references (strings) in the database while the actual files reside in block or object storage. To use media storage, you must use a column type that stores strings.

Supported column types:

• Varchar: Recommended for single file references.
• Text: Also suitable for single file references.
• Array: Supported only when the base_column is Varchar or Text. This allows storing multiple file references in a single column.

from piccolo.table import Table
from piccolo.column.column_types import Varchar, Text, Array

class Movie(Table):
    poster = Varchar()  # Single file
    description = Text() # Single file
    screenshots = Array(base_column=Varchar())  # Multiple files

To provide a description for an entire table, pass the help_text argument to the Table class definition. Piccolo Admin will display this text as a tooltip next to the table name on the row listing page.

from piccolo.table import Table
from piccolo.columns import Varchar, Numeric


class Movie(Table, help_text="Movies which were released in the cinema."):
    name = Varchar(length=300)
    box_office = Numeric(
        digits=(5, 1),
        help_text="In millions of US dollars."
    )

To use the recommended AuthenticatorProvider and XChaCha20Provider setup, you must install the authenticator and pynacl extras for piccolo_api.

pip install piccolo_api[authenticator,pynacl]

To run a local demonstration of Piccolo Admin, ensure you are using Python 3.9 or above. You can install the package and launch the demo using the following commands:

1. Install piccolo_admin via pip.
2. Run the admin_demo command.
3. Open localhost:8000 in your web browser.

For an example of the underlying implementation (models, database setup, and REST API), refer to piccolo_admin/example/app.py in the repository.

pip install piccolo_admin
admin_demo

MFA secrets must be stored in a database table. You can set this up in one of two ways:

Option 1: Using Migrations (Recommended)

Add "piccolo_api.mfa.authenticator.piccolo_app" to your AppRegistry in piccolo_conf.py, then run migrations:

piccolo migrations forwards all

Option 2: Manual Table Creation

You can create the table directly using the AuthenticatorSecret table class:

from piccolo_api.mfa.authenticator.tables import AuthenticatorSecret
AuthenticatorSecret.create_table().run_sync()

Install piccolo_admin using pip. It is recommended to perform the installation within a Python virtual environment. Requires Python 3.8 or above.

pip install piccolo_admin

Piccolo Admin provides several requirement files depending on your use case:

• Use requirements.txt for standard installation and running the application.
• Use dev-requirements.txt if you are developing Piccolo Admin itself.
• Use test-requirements.txt to run the project's test suite.
• Use doc-requirements.txt to build and run the documentation.
• Use readthedocs-requirements.txt specifically for ReadTheDocs environments.