TamilPY

Schema-driven Python web framework — define models in schema.tpy, generate a production-ready FastAPI stack, and ship.

Built by Selvaganapathi Arumugam.

Documentation · PyPI · Requires Python 3.12+

Why "tamilPY"?

The name is a nod to my mother tongue, Tamil — a small personal tribute from the author. The framework itself isn't Tamil-specific in any way; it's a general-purpose, schema-driven Python web framework built for any project, any language, any team.

Table of contents

• Features
• How it compares
• Installation
• Quick start
• CLI reference
• Schema language
• Admin dashboard
• Documentation
• License
• Contributing

Features

• Schema-first development — one schema.tpy drives models, migrations, repositories, services, controllers, and routes
• Multi-database — SQLite, PostgreSQL, MySQL, and MongoDB
• Full CRUD generation — FastAPI layers from a single build step
• Admin dashboard — optional Vite + React UI generated from the same schema
• CLI workflow — project scaffolding, migrations, seeds, and local server in one tool

How it compares

Ratings reflect typical experience for standard CRUD/API-driven projects; results vary by team familiarity and project scope.

Installation

pip install tamilPY

Database drivers are optional extras:

pip install "tamilPY[postgres]"
pip install "tamilPY[mysql]"
pip install "tamilPY[mongodb]"
pip install "tamilPY[all]"

SQLite works with the base install (stdlib).

Verify the install:

python -m tpy.cli version

Quick start

tpy new myapp
cd myapp

Edit schema.tpy, then:

tpy build          # configure database + generate application layers
tpy migrate        # apply migrations
tpy seed           # optional sample data
tpy serve          # start the API at http://127.0.0.1:8000

Generate the admin UI (optional):

tpy admin          # or: tpy build --with-ui
cd admin && npm install && npm run dev

Admin UI: http://127.0.0.1:5173

JWT auth (optional)

tpy auth
pip install -r requirements.txt
tpy migrate
tpy seed
tpy serve
tpy admin   # refresh UI with login page

Default super-admin: admin@example.com / admin123

Roles: super-admin, admin, developer — dashboard allows super-admin and developer only.

API: POST /auth/register, /auth/login, /auth/refresh, /auth/logout, GET /auth/me

CLI reference

Schema language

database postgres

model User {
  id: uuid primary
  email: string unique required
}

model Post {
  id: uuid primary
  title: string required index
  body: string nullable
  user_id: uuid references User
  status: string default "draft"
  published: bool default false
  views: int default 0
}

Types

int · string · float · bool · uuid · datetime · enum(...) / enum Name

Field constraints

Model-level composite unique:

unique(student_id, course_id)

Named / inline enums:

enum Status { draft published }
status: enum Status
kind: enum(a, b)

Foreign keys

user_id: uuid references User
author:  uuid references User.id

Compiles to REFERENCES "user" ("id"). Define referenced models before dependents so migrations run in order.

Defaults and indexes

• Fields with default are optional in the generated create schema
• index adds a secondary index; primary keys are indexed automatically

Database support

SQLite, PostgreSQL, MySQL, and MongoDB are supported for generated CRUD and migrations. SQL providers apply migrations as tables, columns, indexes, and foreign keys. MongoDB applies the same schema as collections and indexes; references are indexed metadata rather than enforced foreign-key constraints.

Admin dashboard

tpy admin generates a Vite + React app under admin/ from schema.tpy.

tpy serve          # terminal 1 — API
tpy admin          # generate UI (once, or after schema changes)
cd admin
npm install
npm run dev        # terminal 2 — UI

The wizard prompts for the API base URL (default: http://127.0.0.1:8000).

Re-running tpy admin refreshes generated files to match the current schema.

Note: The admin package.json uses @rollup/wasm-node so Vite works on Windows hosts where Application Control blocks Rollup's native binary.

Documentation

Full client guide: TamilPY Docs

• Schema grammar (v0.1)
• Versioning & deprecation
• Changelog
• Security policy

Async / sync trade-off

Generated repositories and database providers are synchronous. FastAPI route handlers call sync provider methods directly. That keeps the stack simple and portable across SQLite / Postgres / MySQL / Mongo. For heavy IO under load, run workers behind a process manager or plan for future async providers; do not assume the generated DB layer is async-native today.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT © Selvaganapathi Arumugam