Metadata-Version: 2.4
Name: tamilPY
Version: 0.1.7
Summary: TamilPY Framework — schema-driven Python web framework
Author: Selvaganapathi Arumugam
License: MIT
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer
Requires-Dist: jinja2
Requires-Dist: rich
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: sqlalchemy
Requires-Dist: pydantic
Requires-Dist: pymongo
Requires-Dist: psycopg2-binary
Requires-Dist: pymysql
Requires-Dist: PyJWT
Requires-Dist: passlib[bcrypt]
Requires-Dist: bcrypt<4.1

# TamilPY

[![PyPI version](https://img.shields.io/pypi/v/tamilPY.svg)](https://pypi.org/project/tamilPY/)
[![Python versions](https://img.shields.io/pypi/pyversions/tamilPY.svg)](https://pypi.org/project/tamilPY/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

Built by [Selvaganapathi Arumugam](https://github.com/selvaganapathiarumugam).

[Documentation](https://selvaganapathiarumugam.github.io/tamilPY/) · [PyPI](https://pypi.org/project/tamilPY/) · 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](#features)
- [How it compares](#how-it-compares)
- [Installation](#installation)
- [Quick start](#quick-start)
- [CLI reference](#cli-reference)
- [Schema language](#schema-language)
- [Admin dashboard](#admin-dashboard)
- [Documentation](#documentation)
- [License](#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

```bash
pip install tamilPY
```

Verify the install:

```bash
tpy version
```

---

## Quick start

```bash
tpy new myapp
cd myapp
```

Edit `schema.tpy`, then:

```bash
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):

```bash
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)

```bash
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

| 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

```tpy
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

```tpy
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`.

```bash
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](https://selvaganapathiarumugam.github.io/tamilPY/)

---

## License

MIT © Selvaganapathi Arumugam
