| Name | z8ter JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Minimal Starlette-powered app framework with pages, APIs, and a DX-first CLI. |
| upload_time | 2025-09-07 18:41:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Ashesh Nepal
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
starlette
asgi
framework
uvicorn
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Z8ter
**8ter** is a lightweight, Laravel-inspired full-stack Python web framework built on [Starlette], designed for rapid development with tight integration between backend logic and frontend templates plus small client-side “islands” where they make sense.
```mermaid
flowchart LR
%% --------- Style (GitHub-friendly) ---------
classDef box fill:#1113,stroke:#888,rx:6,ry:6,color:#eee
classDef key fill:#2563eb,stroke:#1e40af,color:#fff,rx:6,ry:6
classDef accent fill:#059669,stroke:#047857,color:#fff,rx:6,ry:6
classDef warn fill:#dc2626,stroke:#991b1b,color:#fff,rx:6,ry:6
linkStyle default stroke:#94a3b8,color:#94a3b8
%% --------- Browser ---------
subgraph B[🌐 Browser]
Bhtml["HTML (Jinja)"]:::box
Bisland["JS Island (if page_id)"]:::box
Bcookie["Cookie z8_sid"]:::key
end
%% --------- Z8ter App ---------
subgraph Z[⚡ Z8ter App]
direction TB
MW1["Session Middleware"]:::box
MW2["Auth Middleware\n→ sets request.state.user"]:::accent
Router["File-based Router\nviews/, api/"]:::box
subgraph SSR[Views]
Tmpl["Jinja2 Engine"]:::box
end
subgraph API[APIs]
Deco["Decorator-driven Endpoints"]:::box
end
subgraph Auth[Auth Backends]
URepo["UserRepo (pluggable)"]:::box
SRepo["SessionRepo (pluggable)"]:::box
end
Err["Global Exception Handlers"]:::warn
end
%% --------- Assets (optional) ---------
A["Vite / Static Assets"]:::box
%% --------- Request path ---------
B -->|"HTTP Request"| MW1 --> MW2 --> Router
Router -->|SSR| Tmpl -->|"HTML"| Bhtml
Router -->|API| Deco -->|"JSON"| Bhtml
B -- "Hydrate" --> Bisland
%% --------- Cookies & Identity ---------
MW2 <-->|read/write SID| Bcookie
MW2 -->|lookup| SRepo
MW2 -->|load user| URepo
%% --------- Errors ---------
Router --> Err -->|"JSON error"| Bhtml
Tmpl --> Err
Deco --> Err
%% --------- Assets ---------
Bhtml -->|"links/scripts"| A
```
---
## Features
### 1) File-Based Views (SSR)
- Files under `views/` become routes automatically.
- Each view pairs Python logic with a Jinja template in `templates/`.
- A stable `page_id` (derived from `views/` path) is injected into templates and used by the frontend loader to hydrate per-page JS.
### 2) Jinja2 Templating
- Template inheritance with `{% extends %}` / `{% block %}`.
- Templates live in `templates/` (default extension: `.jinja`).
### 3) CSR “Islands”
- A tiny client router lazy-loads `/static/js/pages/<page_id>.js` and runs its default export.
- Great for interactive bits (theme toggles, pings, clipboard, etc.) without going full SPA.
### 4) Decorator-Driven APIs
- Classes under `api/` subclass `API` and register endpoints with a decorator.
- Each class mounts under `/api/<id>` (derived from module path).
> Example shape (conceptual):
> ```
> api/hello.py → /api/hello
> views/about.py → /about
> templates/about.jinja + static/js/pages/about.js (island)
> ```
---
## Getting Started
### Prerequisites
- Python 3.11+ and `pip`
- Node 18+ and `npm`
### Install & Run (dev)
```bash
# 1) Python deps (in a venv)
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt # or: pip install -e .
# 2) Frontend deps
npm install
# 3) Dev server(s)
npm run dev
````
> `npm run dev` runs the dev workflow (backend + assets). Check the terminal for the local URL.
---
## Project Structure
```
.
├─ api/ # API classes (@API.endpoint)
│ └─ hello.py
├─ views/ # File-based pages (SSR)
│ └─ index.py
├─ templates/ # Jinja templates
│ ├─ base.jinja
│ └─ index.jinja
├─ static/
│ └─ js/
│ └─ pages/ # Per-page islands: about.js, app/home.js, ...
│ └─ common.js
├─ z8ter/ # Framework core (Page, API, router)
└─ main.py # App entrypoint
```
---
## Usage Examples
### View + Template (SSR)
```jinja
{# templates/index.jinja #}
{% extends "base.jinja" %}
{% block content %}
<h1>{{ title }}</h1>
<div id="api-response"></div>
{% endblock %}
```
### Client Island (runs when `page_id` matches)
```ts
// static/js/pages/common.ts (or a specific page module)
export default async function init() {
// hydrate interactive bits, fetch data, etc.
}
```
### Minimal API Class
```python
# api/hello.py
from z8ter.api import API
class Hello(API):
@API.endpoint("GET", "/hello")
async def hello(self, request):
return {"ok": True, "message": "Hello from Z8ter"}
```
### Main Application (bootstrapping 8ter)
Your app entrypoint defines the pipeline of features by chaining builder steps.
This example shows a minimal project with templating, Vite, and authentication wired in.
```python
# main.py
from z8ter.builders.app_builder import AppBuilder
from app.identity.data.session_repo import InMemorySessionRepo
from app.identity.data.user_repo import InMemoryUserRepo
app_builder = AppBuilder()
app_builder.use_config(".env") # load environment config
app_builder.use_templating() # enable Jinja2 templates
app_builder.use_vite() # dev/prod asset handling
app_builder.use_auth_repos( # provide your own repos
session_repo=InMemorySessionRepo(),
user_repo=InMemoryUserRepo()
)
app_builder.use_authentication() # auth middleware + request.state.user
app_builder.use_errors() # global JSON error handlers
if __name__ == "__main__":
app = app_builder.build()
```
### Authentication (Sessions + Users)
8ter ships with a minimal but flexible authentication layer.
You provide two repos — `SessionRepo` and `UserRepo` — and 8ter wires them into middleware that sets `request.state.user`.
#### Setup in AppBuilder
```python
from z8ter.auth.inmemory_repos import InMemorySessionRepo, InMemoryUserRepo
builder.use_sessions() # enables secure cookie handling
builder.use_auth_repos(
session_repo=InMemorySessionRepo(),
user_repo=InMemoryUserRepo()
)
builder.use_authentication() # middleware populates request.state.user
```
---
## Planned
* **Stripe integration**: pricing page, checkout routes, webhooks
* **DB adapters**: SQLite default, Postgres option
---
## Philosophy
* Conventions over configuration
* SSR with CSR islands
* Small surface area; sharp, pragmatic tools
Raw data
{
"_id": null,
"home_page": null,
"name": "z8ter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "starlette, asgi, framework, uvicorn",
"author": null,
"author_email": "Ashesh Nepal <nepalashesh8@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/6b/03b95ac79f43736ccc1d76c8448237227ef947e7668fdbb60ca36b27da9f/z8ter-0.2.1.tar.gz",
"platform": null,
"description": "# Z8ter\n**8ter** is a lightweight, Laravel-inspired full-stack Python web framework built on [Starlette], designed for rapid development with tight integration between backend logic and frontend templates plus small client-side \u201cislands\u201d where they make sense.\n\n```mermaid\nflowchart LR\n %% --------- Style (GitHub-friendly) ---------\n classDef box fill:#1113,stroke:#888,rx:6,ry:6,color:#eee\n classDef key fill:#2563eb,stroke:#1e40af,color:#fff,rx:6,ry:6\n classDef accent fill:#059669,stroke:#047857,color:#fff,rx:6,ry:6\n classDef warn fill:#dc2626,stroke:#991b1b,color:#fff,rx:6,ry:6\n linkStyle default stroke:#94a3b8,color:#94a3b8\n\n %% --------- Browser ---------\n subgraph B[\ud83c\udf10 Browser]\n Bhtml[\"HTML (Jinja)\"]:::box\n Bisland[\"JS Island (if page_id)\"]:::box\n Bcookie[\"Cookie z8_sid\"]:::key\n end\n\n %% --------- Z8ter App ---------\n subgraph Z[\u26a1 Z8ter App]\n direction TB\n MW1[\"Session Middleware\"]:::box\n MW2[\"Auth Middleware\\n\u2192 sets request.state.user\"]:::accent\n Router[\"File-based Router\\nviews/, api/\"]:::box\n\n subgraph SSR[Views]\n Tmpl[\"Jinja2 Engine\"]:::box\n end\n\n subgraph API[APIs]\n Deco[\"Decorator-driven Endpoints\"]:::box\n end\n\n subgraph Auth[Auth Backends]\n URepo[\"UserRepo (pluggable)\"]:::box\n SRepo[\"SessionRepo (pluggable)\"]:::box\n end\n\n Err[\"Global Exception Handlers\"]:::warn\n end\n\n %% --------- Assets (optional) ---------\n A[\"Vite / Static Assets\"]:::box\n\n %% --------- Request path ---------\n B -->|\"HTTP Request\"| MW1 --> MW2 --> Router\n Router -->|SSR| Tmpl -->|\"HTML\"| Bhtml\n Router -->|API| Deco -->|\"JSON\"| Bhtml\n B -- \"Hydrate\" --> Bisland\n\n %% --------- Cookies & Identity ---------\n MW2 <-->|read/write SID| Bcookie\n MW2 -->|lookup| SRepo\n MW2 -->|load user| URepo\n\n %% --------- Errors ---------\n Router --> Err -->|\"JSON error\"| Bhtml\n Tmpl --> Err\n Deco --> Err\n\n %% --------- Assets ---------\n Bhtml -->|\"links/scripts\"| A\n\n```\n---\n\n## Features\n\n### 1) File-Based Views (SSR)\n- Files under `views/` become routes automatically.\n- Each view pairs Python logic with a Jinja template in `templates/`.\n- A stable `page_id` (derived from `views/` path) is injected into templates and used by the frontend loader to hydrate per-page JS.\n\n### 2) Jinja2 Templating\n- Template inheritance with `{% extends %}` / `{% block %}`.\n- Templates live in `templates/` (default extension: `.jinja`).\n\n### 3) CSR \u201cIslands\u201d\n- A tiny client router lazy-loads `/static/js/pages/<page_id>.js` and runs its default export.\n- Great for interactive bits (theme toggles, pings, clipboard, etc.) without going full SPA.\n\n### 4) Decorator-Driven APIs\n- Classes under `api/` subclass `API` and register endpoints with a decorator.\n- Each class mounts under `/api/<id>` (derived from module path).\n\n> Example shape (conceptual):\n> ```\n> api/hello.py \u2192 /api/hello\n> views/about.py \u2192 /about\n> templates/about.jinja + static/js/pages/about.js (island)\n> ```\n\n---\n\n## Getting Started\n\n### Prerequisites\n- Python 3.11+ and `pip`\n- Node 18+ and `npm`\n\n### Install & Run (dev)\n```bash\n# 1) Python deps (in a venv)\npython -m venv .venv\nsource .venv/bin/activate # Windows: .\\.venv\\Scripts\\Activate.ps1\npip install -r requirements.txt # or: pip install -e .\n\n# 2) Frontend deps\nnpm install\n\n# 3) Dev server(s)\nnpm run dev\n````\n\n> `npm run dev` runs the dev workflow (backend + assets). Check the terminal for the local URL.\n\n---\n\n## Project Structure\n\n```\n.\n\u251c\u2500 api/ # API classes (@API.endpoint)\n\u2502 \u2514\u2500 hello.py\n\u251c\u2500 views/ # File-based pages (SSR)\n\u2502 \u2514\u2500 index.py\n\u251c\u2500 templates/ # Jinja templates\n\u2502 \u251c\u2500 base.jinja\n\u2502 \u2514\u2500 index.jinja\n\u251c\u2500 static/\n\u2502 \u2514\u2500 js/\n\u2502 \u2514\u2500 pages/ # Per-page islands: about.js, app/home.js, ...\n\u2502 \u2514\u2500 common.js\n\u251c\u2500 z8ter/ # Framework core (Page, API, router)\n\u2514\u2500 main.py # App entrypoint\n```\n\n---\n\n## Usage Examples\n\n### View + Template (SSR)\n\n```jinja\n{# templates/index.jinja #}\n{% extends \"base.jinja\" %}\n{% block content %}\n <h1>{{ title }}</h1>\n <div id=\"api-response\"></div>\n{% endblock %}\n```\n\n### Client Island (runs when `page_id` matches)\n\n```ts\n// static/js/pages/common.ts (or a specific page module)\nexport default async function init() {\n // hydrate interactive bits, fetch data, etc.\n}\n```\n\n### Minimal API Class\n\n```python\n# api/hello.py\nfrom z8ter.api import API\n\nclass Hello(API):\n @API.endpoint(\"GET\", \"/hello\")\n async def hello(self, request):\n return {\"ok\": True, \"message\": \"Hello from Z8ter\"}\n```\n\n### Main Application (bootstrapping 8ter)\n\nYour app entrypoint defines the pipeline of features by chaining builder steps.\nThis example shows a minimal project with templating, Vite, and authentication wired in.\n\n```python\n# main.py\nfrom z8ter.builders.app_builder import AppBuilder\nfrom app.identity.data.session_repo import InMemorySessionRepo\nfrom app.identity.data.user_repo import InMemoryUserRepo\n\napp_builder = AppBuilder()\napp_builder.use_config(\".env\") # load environment config\napp_builder.use_templating() # enable Jinja2 templates\napp_builder.use_vite() # dev/prod asset handling\napp_builder.use_auth_repos( # provide your own repos\n session_repo=InMemorySessionRepo(),\n user_repo=InMemoryUserRepo()\n)\napp_builder.use_authentication() # auth middleware + request.state.user\napp_builder.use_errors() # global JSON error handlers\n\nif __name__ == \"__main__\":\n app = app_builder.build()\n```\n\n### Authentication (Sessions + Users)\n\n8ter ships with a minimal but flexible authentication layer.\nYou provide two repos \u2014 `SessionRepo` and `UserRepo` \u2014 and 8ter wires them into middleware that sets `request.state.user`.\n\n#### Setup in AppBuilder\n\n```python\nfrom z8ter.auth.inmemory_repos import InMemorySessionRepo, InMemoryUserRepo\n\nbuilder.use_sessions() # enables secure cookie handling\n\nbuilder.use_auth_repos(\n session_repo=InMemorySessionRepo(),\n user_repo=InMemoryUserRepo()\n)\n\nbuilder.use_authentication() # middleware populates request.state.user\n```\n\n---\n\n## Planned\n* **Stripe integration**: pricing page, checkout routes, webhooks\n* **DB adapters**: SQLite default, Postgres option\n\n---\n\n## Philosophy\n\n* Conventions over configuration\n* SSR with CSR islands\n* Small surface area; sharp, pragmatic tools\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Ashesh Nepal\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Minimal Starlette-powered app framework with pages, APIs, and a DX-first CLI.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/ashesh808/Z8ter",
"Issues": "https://github.com/ashesh808/Z8ter/issues"
},
"split_keywords": [
"starlette",
" asgi",
" framework",
" uvicorn"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7dc35429d7d41e0ea264ddb437eb952e9618dc03d051d6de32b286828ead18bc",
"md5": "7eff2ec317d0dc2205d2327bd718c072",
"sha256": "42431f0cf5b4a6d75fac39fb474a2272b8bdef179b43eafd16029468faa707b5"
},
"downloads": -1,
"filename": "z8ter-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7eff2ec317d0dc2205d2327bd718c072",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28383,
"upload_time": "2025-09-07T18:41:34",
"upload_time_iso_8601": "2025-09-07T18:41:34.470625Z",
"url": "https://files.pythonhosted.org/packages/7d/c3/5429d7d41e0ea264ddb437eb952e9618dc03d051d6de32b286828ead18bc/z8ter-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd6b03b95ac79f43736ccc1d76c8448237227ef947e7668fdbb60ca36b27da9f",
"md5": "249d4c31ed1d8caf7f3d579fb8423c3b",
"sha256": "8d7ffd12f00fa6585175c0c9da10c1451c32bb68f76e61618915332e79ba2fdf"
},
"downloads": -1,
"filename": "z8ter-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "249d4c31ed1d8caf7f3d579fb8423c3b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24546,
"upload_time": "2025-09-07T18:41:35",
"upload_time_iso_8601": "2025-09-07T18:41:35.814813Z",
"url": "https://files.pythonhosted.org/packages/cd/6b/03b95ac79f43736ccc1d76c8448237227ef947e7668fdbb60ca36b27da9f/z8ter-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 18:41:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ashesh808",
"github_project": "Z8ter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "z8ter"
}
