tamilPY 0.1.7

TamilPY Framework — schema-driven Python web framework

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

---

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

Criteria	Django	Flask	FastAPI (plain)	tamilPY
Development speed	⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
Learning curve	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Boilerplate code	High	Very high (build it yourself)	Moderate (routes/schemas written by hand)	Very low (schema-generated)
Code generation	❌	❌	❌	✅ Full stack (models → routes → admin)
Database support	PostgreSQL, MySQL, SQLite, Oracle	Any (via extensions, e.g. SQLAlchemy)	Any (via extensions, e.g. SQLAlchemy, Tortoise)	SQLite, PostgreSQL, MySQL, MongoDB
REST API	Requires DRF	Manual	✅ Native	✅ FastAPI native
Async	Limited	❌	✅ Native	✅ Native
Type safety	Optional	Optional	✅ Pydantic	✅ Pydantic-enforced
Admin dashboard	✅ Built-in	❌	❌	✅ Generated (Vite + React)
CRUD development	⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
Time to MVP	Days / weeks	Weeks	Days	Hours to a few days

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

---

Installation

pip install tamilPY

Verify the install:

tpy 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: [e-mail] / 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

Command	Description
tpy new <name>	Create a new project
tpy build	Interactive database setup and code generation
tpy build --skip-db	Generate using an existing .env
tpy build --with-ui	Generate app layers and the React admin dashboard
tpy crud	Regenerate CRUD layers from schema.tpy
tpy admin	Generate a Vite + React admin dashboard
tpy auth	Enable JWT auth (login/register/refresh/logout), AuthRole + User, role seeds
tpy db configure	Re-run the database configuration wizard
tpy migrate	Create the database (if needed) and apply migrations
tpy migrate rollback	Roll back the latest migration
tpy seed	Run seed scripts in database/seeds
tpy serve	Start the FastAPI development server
tpy doctor	Validate project structure
tpy version	Print the installed framework version

---

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

Field constraints

Constraint	Effect
primary	Primary key
required	Required on create
unique	Unique column constraint
nullable	Allows NULL / optional values
index	Secondary index (idx_<table>_<column>)
default <value>	Column default (0, "draft", true / false)
references <Model>	Foreign key (alias: foreign <Model>)

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).

Path	Role
src/data/models.js	Model registry generated from schema.tpy
src/components/	Shared Layout, DataTable, RecordForm
src/pages/	Generic list and form pages

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

---

License

MIT © Selvaganapathi Arumugam