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
• Studio
• Starter templates
• CLI reference
• Schema language
• Admin dashboard
• Documentation
• License
• Contributing

Features

• Schema-first development — one schema.tpy drives models, migrations, repositories, services, controllers, and routes
• Studio — visual local builder (tpy studio) for schema, database, auth, and build/migrate/seed
• Starter templates — crm, institute-admin, inventory, helpdesk, blog-cms via tpy new --template
• Incremental make — tpy make:model / make:controller / make:service without a full rebuild
• 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 — schema validator with line numbers, generated-file markers, tpy optimize, tpy watch
• Admin dashboard — optional Vite + React UI with per-template themes
• 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
# or: tpy new myapp --template crm
cd myapp

Edit schema.tpy (or use Studio), then:

tpy studio         # optional visual builder at http://127.0.0.1:4200
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

Studio

Local visual builder for schema.tpy — no CDN, no separate npm install for end users.

cd myapp
tpy studio                 # http://127.0.0.1:4200
tpy studio --port 5000
tpy studio --no-open
tpy studio --host 0.0.0.0  # opt-in; prints a security warning

Screens: Model Designer, Relations canvas, Database panel, Auth (sidecar .tpy/studio.json), Diff preview before save, Build console (SSE), API Explorer, Templates.

Guide: Studio docs

Starter templates

tpy templates list
tpy new myschool --template institute-admin
tpy templates show crm

Each ships schema.tpy, admin-theme.json, sample seeds, and README notes. Admin themes apply via admin-theme.json or tpy admin --template <name>.

Guide: Templates docs

Incremental make

tpy make:model Invoice --fields "amount:float,status:enum(draft,paid),user_id:uuid references User"
tpy make:controller Invoice
tpy make:service Invoice
# --force required if a generated file was edited by hand

Guide: Make commands

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)
# themed: tpy admin --template crm
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:

• Studio visual builder
• Starter templates
• Make commands
• 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