Bro-Py

Generate Flask backend code and a browser-based admin dashboard from Peewee models. The tool creates CRUD API routes and services, an admin UI, and optional authentication, role permissions, live Socket.IO updates, audit history, migrations, API docs, and test files.

The project is in active development. Try it with a disposable demo database first, and review generated code and configuration before using it with real data.

Install the CLI

Install the commands in an isolated environment with:

pipx install bro-py

Then run bro-py-admin and bro-py from the user's project folder. The generators run locally and read the models/ folder there. The package includes Python source code; this distribution method makes installation easy, but does not hide the generator implementation.

Maintained by selimbenali.

To try the commands from a development checkout before the PyPI release, install the project into a virtual environment:

python -m venv .venv

Activate .venv, then:

python -m pip install --no-deps .
bro-py-admin --help
bro-py --help

Quick start

You need Python 3.9 or newer. From the repository root, generate the admin pages first:

bro-py-admin --models-dir examples/quickstart/models --output-dir examples/quickstart/generated

Then generate the backend. Choose SQLite for the local demo and answer the optional-feature questions:

bro-py --models-dir examples/quickstart/models --output-dir examples/quickstart/generated

The backend generator detects and registers the frontend blueprint when it runs after the frontend generator.

Install and run the generated app:

python -m venv .venv

Activate the environment, then:

python -m pip install -r examples/quickstart/generated/requirements.txt
cd examples/quickstart/generated
python app.py

Open http://127.0.0.1:5000/admin/. The generated project’s README has the exact platform-specific commands, database notes, and the demo model’s API routes.

To regenerate existing files, pass --force and review the files it will replace first. Use --dry-run to preview changes. Files with the generated custom-code marker preserve the code below the marker.

Features

• Peewee model scanning without importing or connecting to the application database.
• Generated Flask services, API blueprints, configuration, and startup app.
• Admin pages with search, sorting, pagination, CSV import/export, bulk update, and bulk delete.
• SQLite and MySQL setup; MySQL asks for database name, host, port, user, and hidden password.
• Optional JWT authentication, admin login, signup/email verification, and per-operation role checks.
• Optional Socket.IO record updates, dashboard status, notifications, and task progress messages.
• Optional audit history, OpenAPI/Swagger docs, and Peewee migration commands.
• Safe preview, template overrides, and trusted Python plugins.
• Generated README, environment example, dependency files, Dockerfile, and WSGI entry point.

For the complete first-time walkthrough, see FEATURES_GUIDE.md. Review SECURITY_AND_LIMITS.md before using generated projects beyond local development.

CLI overview

bro-py --help
bro-py-admin --help

If you omit setup choices in an interactive terminal, the wizard asks about them. Use explicit positive or negative flags to skip individual questions, such as --socketio or --no-socketio. Use --non-interactive in scripts; omitted options use documented defaults and a starter .env is created for you to edit.

PostgreSQL is not currently supported. Supported database engines are SQLite and MySQL.

Development

The generator checks use Python’s standard test runner. JavaScript syntax validation needs Node.js:

python -m unittest discover -s tests -v
python tools/check_generated_javascript.py

See CONTRIBUTING.md to report a bug or prepare a change.

License

This project is licensed under the MIT License. See LICENSE.