PyRails

PyRails is a lightweight, opinionated, batteries-included Python web framework built on top of FastAPI and MongoEngine. It is means to provide helpful, lightweight abstractions to enable standard ways of implementing common patters to prevent the SaaSification of the developer stack.

The goal is to enhance not inhibit.

Features

Built on top of FastAPI and MongoEngine ODM
CLI tool for project management and code generation
Built-in database management (MongoDB)
Support for both local and Docker-based development
Environment-specific configurations
Automatic API documentation

Installation

Install PyRails using pip:

pip install pyrails

Creating a New Project

Create a new PyRails project using the new command:

pyrails new my_project
cd my_project

This will create a new directory myapp with the default project structure:

myapp/
├── app/
│   ├── controllers/
│   ├── models/
│   └── __init__.py
├── config/
│   ├── development.py
│   ├── production.py  
│   └── __init__.py
├── main.py
├── Dockerfile
└── docker-compose.yml

Starting the Development Server

Start the development server using the run command:

pyrails run

This will start the development server on http://localhost:8000.

You can also run the service using Docker:

pyrails run --docker

Scaffolding Resources

PyRails includes a scaffold generator to quickly create models, controllers, and route definitions for a new resource.

To generate a scaffold for a Post resource with title and body fields:

pyrails generate scaffold Post title:str body:str

This will generate:

app/models/post.py with a Post model class
app/controllers/posts_controller.py with CRUD route handlers
Update app/controllers/__init__.py to import the new controller
Update app/models/__init__.py to import the new model

Generating Models and Controllers

You can also generate models and controllers individually.

Generating a Model

To generate a Comment model with post_id, author, and content fields:

pyrails generate model Comment post_id:str author:str content:str

Generating a Controller

To generate a controller for Auth routes:

pyrails generate controller Auth

You can also pass in the routes to generate as arguments:

pyrails generate controller Auth post:login post:register

More field types

Defining Relationships and Field Options

When generating models, you can define relationships between models and specify field options.

One-to-Many Relationship: Use the ref: prefix followed by the related model name.

pyrails generate model Post author:ref:User

This will generate a Post model with an author field referencing the User model.

Many-to-Many Relationship: Use list: and ref: together.

pyrails generate model Student courses:list:ref:Course

This will generate a Student model with a courses field that is a list of references to Course models.

Optional Field: Append _ to the field name to mark it as optional.

pyrails generate model User email_:str

This will generate a User model with an optional email field.

Unique Field: Append ^ to the field name to specify it as unique.

pyrails generate model User username^:str

This will generate a User model with a unique username field.

Specialty Field Types

Hashed Field: Use _hashed: suffix to store the field as a hashed value.

pyrails generate model User name:str password_hashed:str

This will generate a User model with a password field stored as a hashed value.

Encrypted Field: Use _encrypted: suffix to store the field as an encrypted value.

pyrails generate model User name:str email_encrypted:str secret_note_encrypted:str

This will generate a User model with email and secret_note fields stored as encrypted values.

PyRails supports the following field types: str, int, float, bool, datetime, date, dict, list.

Controller Lifecycle Hooks

Lifecycle hooks like before_request and after_request can be defined directly in a controller or inherited from a parent controller. Hooks are useful for tasks such as authentication, logging, or cleanup.

Example: AdminController and AdminUserController

admin_controller.py

from pyrails.controllers import Controller, before_request, after_request
from pyrails.exceptions import UnauthorizedError
from pyrails import Request

class AdminController(Controller):
    @before_request
    async def check_admin(self, request: Request):
        is_admin = False  # Replace with actual logic
        print("Checking admin status... (this will be run before each request)")
        if not is_admin:
            raise UnauthorizedError(detail="Unauthorized access.")

    @after_request
    async def cleanup_stuff(self, request: Request):
        print("Cleaning up... (this will be run after each request)")

admin_user_controller.py

from app.controllers.admin_controller import AdminController

class AdminUserController(AdminController):
    @get('/admin-user/all-users')
    async def all_users(self, request):
        return {"users": []}

Key Points:

Hooks like check_admin and after_request can be defined directly in a controller or inherited from a parent.
In AdminUserController, hooks are inherited from AdminController and run before and after each request handler.