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
• Query Builder & relationships — fluent queries, schema relations { }, eager loading
• Events, queues & scheduler — sync event bus, background jobs, cron-style schedule
• Cache, validation & API envelopes — memory/file/Redis, pipe rules, ApiResponse
• Kernel platform — Application providers/plugins, middleware groups, health & lifecycle
• Logging, config & storage — log channels, config cache, file storage, route cache
• DX tooling — tpy optimize, richer CLI (-V, about), tpy watch
• Admin dashboard — optional Vite + React UI generated from the same schema
• CLI workflow — scaffolding, migrations, seeds, queue/schedule/cache, and local server

Full docs: TamilPY Docs

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[redis]"
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)

Relationships (v0.1.9+)

model Post {
  id: uuid primary
  user_id: uuid references User
  relations {
    belongs_to User as author via user_id
    has_many Comment as comments
    belongs_to_many Tag as tags through PostTag
  }
}

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 & platform guide (GitHub Pages):

TamilPY Docs

In-page sections: Install · Features · Platform API · CLI

Feature cards open study guides with setup, how-it-works, examples, and common mistakes — for example:

• Schema-first generation
• ApiResponse helpers
• Query Builder & relations
• JWT auth
• Optimize · CLI · Watch

Also:

• 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