Metadata-Version: 2.4
Name: flaskteroids
Version: 0.4.0
Summary: Flask on steroids
Author: Juan Sebastian Quintero
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Classifier: Framework :: Flask
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic>=1.20.0
Requires-Dist: Flask>=3.1.3
Requires-Dist: sqlalchemy>=2.1.4
Requires-Dist: celery>=5.6.3
Requires-Dist: cryptography>=50.0.2
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: playwright>=1.63.0
Requires-Dist: pytest>=9.1.1
Requires-Dist: pytest-xdist>=3.8.0
Dynamic: license-file

<h1 align="center">Flaskteroids</h1>

<p align="center">
  A Rails-inspired Python MVC framework built on Flask, SQLAlchemy, and Celery.
</p>

<p align="center">
  <a href="https://github.com/nullco/flaskteroids/actions/workflows/test.yml?query=branch%3Amain++" target="_blank">
    <img src="https://github.com/nullco/flaskteroids/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Build Status">
  </a>
  <a href="https://pypi.org/project/flaskteroids/" target="_blank">
    <img src="https://img.shields.io/pypi/v/flaskteroids.svg?color=28a745" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/flaskteroids/" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/flaskteroids.svg" alt="Python Versions">
  </a>
  <a href="https://github.com/nullco/flaskteroids/blob/main/LICENSE" target="_blank">
    <img src="https://img.shields.io/github/license/nullco/flaskteroids.svg" alt="License">
  </a>
</p>

---

Flaskteroids brings Rails conventions to Python. It uses Rails 8 as the reference for application structure and framework behavior, with Flask handling HTTP requests, SQLAlchemy and Alembic handling the database, and Celery running background jobs.

Models, controllers, and templates live in conventional directories. The framework discovers them without manual registration. Flask APIs and extensions remain available when you need them.

## What's included

- Resource routing with CRUD routes and path helpers.
- Active Record-style models with associations, validations, and lifecycle callbacks.
- Jinja templates, form helpers, and HTML or JSON responses.
- Generators for models, migrations, controllers, scaffolds, mailers, and authentication.
- Background jobs and email delivery.
- Environment settings, `database.yml`, encrypted credentials, and boot-time initializers.
- Pytest-based transactional tests, YAML fixtures, job and mail assertions, and Playwright browser tests.

## Installation

Requires Python 3.12 or newer. Install Flaskteroids in your Python environment:

```sh
pip install flaskteroids
```

## Getting started

Create an application. Git must be installed.

```sh
flaskteroids new my_app
cd my_app
```

The command creates the application files and initializes a Git repository in `my_app`. Start the development server:

```sh
flask run
```

Open `http://127.0.0.1:5000` to see the welcome page.

## Add a posts resource

Stop the server and run these commands inside `my_app`:

```sh
flask generate scaffold Post title:string content:text
flask db:migrate
flask run
```

The scaffold generates a model, migration, controller, views, and routes. Visit
`http://127.0.0.1:5000/posts/` to create, view, edit, and delete posts.

See the [documentation](https://nullco.github.io/flaskteroids/) for configuration,
testing, and the API guides.

## Agent skills

Flaskteroids bundles coding guidance for agents with each release. New applications
include `.agents/skills/using-flaskteroids/SKILL.md`, which points agents to
instructions for the installed framework version. These instructions require
agents to use public Flaskteroids APIs when they cover the task, rather than
calling dependency internals.

In your application's Python environment, locate the installed skills with:

```sh
flaskteroids agent-skills path
```

The command prints the absolute skills directory path. Read
`using-flaskteroids/SKILL.md` inside that directory for version-matched guidance.
No application configuration or initialization is required.

## Releasing

See [the release guide](RELEASING.md) for release PRs and PyPI publishing.

## License

Flaskteroids is released under the [MIT License](LICENSE).
