z8ter 0.1.0__tar.gz

z8ter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

z8ter-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: z8ter
+Version: 0.1.0
+Summary: SSR-first Python web framework with file-based views, tinyCSR islands, and decorator-driven APIs (Starlette + Jinja2).
+Home-page: https://github.com/ashesh808/Z8ter
+Author: Ashesh Nepal
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: starlette<1.0,>=0.47
+Requires-Dist: Jinja2<4.0,>=3.1
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Z8ter.py
+
+**Z8ter** 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.
+
+---
+
+## ✨ Features (Current)
+
+### 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) Small 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"}
+```
+
+---
+
+## 🛣️ Planned
+
+* **CLI scaffolding**: `z8 new`, `z8 dev`, `z8 create_page <name>`
+* **Auth scaffolding**: login/register/logout + session helpers
+* **Stripe integration**: pricing page, checkout routes, webhooks
+* **DB adapters**: SQLite default, Postgres option
+* **HTMX + Tailwind/DaisyUI** polish out of the box
+
+---
+
+## 🧠 Philosophy
+
+* Conventions over configuration
+* SSR-first with tiny CSR islands
+* Small surface area; sharp, pragmatic tools

z8ter-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Z8ter.py
+
+**Z8ter** 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.
+
+---
+
+## ✨ Features (Current)
+
+### 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) Small 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"}
+```
+
+---
+
+## 🛣️ Planned
+
+* **CLI scaffolding**: `z8 new`, `z8 dev`, `z8 create_page <name>`
+* **Auth scaffolding**: login/register/logout + session helpers
+* **Stripe integration**: pricing page, checkout routes, webhooks
+* **DB adapters**: SQLite default, Postgres option
+* **HTMX + Tailwind/DaisyUI** polish out of the box
+
+---
+
+## 🧠 Philosophy
+
+* Conventions over configuration
+* SSR-first with tiny CSR islands
+* Small surface area; sharp, pragmatic tools

z8ter-0.1.0/api/hello.py

@@ -0,0 +1,13 @@
+from z8ter.api import API
+from starlette.responses import JSONResponse
+from starlette.requests import Request
+
+
+class Hello(API):
+    def __init__(self) -> None:
+        super().__init__()
+
+    @API.endpoint("GET", "/")
+    async def send_hello(self, request: Request) -> JSONResponse:
+        content = {"message": "Hello from the API!"}
+        return JSONResponse(content, 200)

z8ter-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

z8ter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

z8ter-0.1.0/setup.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+from setuptools import setup, find_packages
+
+README = (Path(__file__).parent / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name="z8ter",
+    version="0.1.0",
+    description="SSR-first Python web framework with file-based views, tiny"
+    "CSR islands, and decorator-driven APIs (Starlette + Jinja2).",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    url="https://github.com/ashesh808/Z8ter",
+    author="Ashesh Nepal",
+    license="MIT",
+    packages=find_packages(exclude=(
+        "tests", "tests.*", "examples", "examples.*"
+        )),
+    include_package_data=True,
+    python_requires=">=3.11",
+    install_requires=[
+        "starlette>=0.47,<1.0",
+        "Jinja2>=3.1,<4.0",
+    ],
+    entry_points={"console_scripts": ["z8=z8ter.cli:main"]},
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Framework :: AsyncIO",
+        "Topic :: Internet :: WWW/HTTP",
+    ],
+)

z8ter-0.1.0/views/about.py

@@ -0,0 +1,8 @@
+from z8ter.page import Page
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class About(Page):
+    async def get(self, request: Request) -> Response:
+        return self.render(request, "about.jinja", {})

z8ter-0.1.0/views/index.py

@@ -0,0 +1,9 @@
+from z8ter.page import Page
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class Index(Page):
+    async def get(self, request: Request) -> Response:
+        data = {"title": "Welcome to Z8ter!"}
+        return self.render(request, "index.jinja", data)

z8ter-0.1.0/z8ter/__init__.py

@@ -0,0 +1,14 @@
+__all__ = ["API", "Page"]
+__version__ = "0.1.0"
+from .api import API
+from .page import Page
+from starlette.templating import Jinja2Templates
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+FAVICON_PATH = BASE_DIR / "static" / "favicon" / "favicon.ico"
+TEMPLATES_DIR = BASE_DIR / "templates"
+VIEWS_DIR = BASE_DIR / "views"
+TS_DIR = BASE_DIR / "src" / "ts"
+API_DIR = BASE_DIR / "api"
+templates = Jinja2Templates(directory=str(TEMPLATES_DIR))

z8ter-0.1.0/z8ter/api.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+from starlette.routing import Route, Mount
+
+
+class API():
+    """
+    Class which supports endpoint decorators to provide a list of endpoints
+    for a particular app
+    """
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        mod = cls.__module__
+        if mod.startswith("api."):
+            id = mod.removeprefix("api.")
+        else:
+            id = mod
+        cls._api_id = id.replace('.', '/')
+        cls._endpoints = []
+        cls._endpoints = []
+        for name, obj in cls.__dict__.items():
+            meta = getattr(obj, "_z8_endpoint", None)
+            if meta:
+                http_method, subpath = meta
+                cls._endpoints.append((http_method, subpath, name))
+
+    @classmethod
+    def build_mount(cls) -> Mount:
+        prefix = f"/api/{getattr(cls, "_api_id")}"
+        inst = cls()
+        routes = [
+            Route(subpath, endpoint=getattr(inst, func_name), methods=[method])
+            for (method, subpath, func_name) in getattr(cls, "_endpoints", [])
+        ]
+        return Mount(prefix, routes=routes)
+
+    @staticmethod
+    def endpoint(method: str, path: str):
+        def deco(fn):
+            setattr(fn, "_z8_endpoint", (method.upper(), path))
+            return fn
+        return deco

z8ter-0.1.0/z8ter/cli.py

@@ -0,0 +1,120 @@
+from z8ter import TEMPLATES_DIR, VIEWS_DIR, TS_DIR, API_DIR
+import argparse
+
+'''
+CLI support for the following commands -
+    1. z8ter create_page newpage
+    2. z8ter new project
+    3. z8ter run
+    4. z8ter run dev
+'''
+
+
+def set_page_content(page_name_lower, class_name) -> dict:
+    content = {}
+    content["template_content"] = f"""{{% extends "components/base.jinja" %}}
+{{% block content %}}
+  <h1>{class_name}</h1>
+{{% endblock %}}
+"""
+    content["view_content"] = f"""from z8ter.page import Page
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class {class_name}(Page):
+    async def get(self, request: Request) -> Response:
+        return self.render(request, "{page_name_lower}.jinja", {{}})
+"""
+    content["ts_content"] = (
+        f"export default function init{class_name}(): void {{}}"
+    )
+    return content
+
+
+def create_page(page_name: str):
+    page_name_lower = page_name.lower()
+    class_name = page_name.capitalize()
+    template_path = TEMPLATES_DIR / f"{page_name_lower}.jinja"
+    view_path = VIEWS_DIR / f"{page_name_lower}.py"
+    ts_path = TS_DIR / "pages" /f"{page_name_lower}.ts"
+    TEMPLATES_DIR.mkdir(parents=True, exist_ok=True)
+    VIEWS_DIR.mkdir(parents=True, exist_ok=True)
+    TS_DIR.mkdir(parents=True, exist_ok=True)
+    content = set_page_content(page_name_lower, class_name)
+    if not template_path.exists():
+        template_path.write_text(content["template_content"], encoding="utf-8")
+        print(f"Created template: {template_path}")
+    else:
+        print(f"Template already exists: {template_path}")
+    if not view_path.exists():
+        view_path.write_text(content["view_content"], encoding="utf-8")
+        print(f"Created view: {view_path}")
+    else:
+        print(f"View already exists: {view_path}")
+    if not ts_path.exists():
+        ts_path.write_text(content["ts_content"], encoding="utf-8")
+        print(f"Created script: {ts_path}")
+    else:
+        print(f"Script already exists: {ts_path}")
+
+
+def create_api(api_name: str):
+    api_name_lower = api_name.lower()
+    class_name = api_name.capitalize()
+    api_path = API_DIR / f"{api_name_lower}.py"
+    api_content = f"""from z8ter.api import API
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+
+class {class_name}(Page):
+    @API.endpoint("GET", "/")
+    async def get_{class_name}(self, request: Request) -> JSONResponse:
+        return JSONResponse({{"message": "Hello from {class_name} API!"}}, 200)
+"""
+    if not api_path.exists():
+        api_path.write_text(api_content, encoding="utf-8")
+        print(f"Created template: {api_path}")
+    else:
+        print(f"Template already exists: {api_path}")
+
+
+def new_project(project_name: str):
+    print("This feature has not been implemented yet.")
+    print(f"You can start your project {project_name} by cloning the repo:")
+    print("https://github.com/ashesh808/Z8ter")
+
+
+def run_server(
+        mode: str = "prod", app_path: str = "main:app",
+        host: str = "127.0.0.1", port: int = 8000
+        ):
+    import uvicorn
+    uvicorn.run(app_path, host=host, port=port, reload=(mode == "dev"))
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="z8", description="Z8ter CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_create = sub.add_parser("create_page",
+                              help="Create a new page (template + view)")
+    p_create.add_argument("name",
+                          help="Page name (e.g., 'home' or 'app/home')")
+    p_new = sub.add_parser("new",
+                           help="Create a new Z8ter project")
+    p_new.add_argument("project_name",
+                       help="Folder name for the new project")
+    p_run = sub.add_parser("run", help="Run the app (default: prod)")
+    p_run.add_argument("mode", nargs="?", choices=["dev"],
+                       help="Use 'dev' for autoreload")
+    args = parser.parse_args()
+    if args.cmd == "create_page":
+        create_page(args.name)
+    elif args.cmd == "new":
+        new_project(args.project_name)
+    elif args.cmd == "run":
+        run_server(mode="dev" if args.mode == "dev" else "prod")
+    else:
+        parser.print_help()

z8ter-0.1.0/z8ter/config.py

@@ -0,0 +1,10 @@
+from starlette.config import Config
+from z8ter import BASE_DIR, FAVICON_PATH, VIEWS_DIR
+
+
+def build_config(env_file: str) -> Config:
+    cf = Config(env_file)
+    cf.file_values["ROOT"] = str(BASE_DIR)
+    cf.file_values["FAVICON_PATH"] = str(FAVICON_PATH)
+    cf.file_values["VIEW_PATH"] = str(VIEWS_DIR)
+    return cf

z8ter-0.1.0/z8ter/core.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+from pathlib import Path
+import logging
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.middleware.sessions import SessionMiddleware
+from typing import List
+import uvicorn
+from starlette.staticfiles import StaticFiles
+from z8ter import templates
+from z8ter.router import build_routes_from_pages, build_routes_from_apis
+logger = logging.getLogger("z8ter")
+
+
+class Z8ter:
+    def __init__(
+        self,
+        *,
+        debug: bool | None = None,
+        mode: str | None = None,
+        views_dir: str | Path = "views",
+        routes: list | None = None,
+        sessions: bool = False,
+        session_secret: str | None = None,
+    ) -> None:
+        self._extra_routes: list = list(routes or [])
+        self.mode = (mode or "prod").lower()
+        self.debug = bool(self.mode == "dev") if debug is None else bool(debug)
+        self.views_dir = Path(views_dir).resolve()
+        self.app = Starlette(debug=self.debug, routes=self._assemble_routes())
+        if sessions:
+            if session_secret:
+                secret = session_secret
+            else:
+                raise ValueError(
+                    "Z8ter: session_secret is required when sessions=True."
+                )
+            self.app.add_middleware(SessionMiddleware, secret_key=secret)
+        static_dir = Path("static")
+        if static_dir.exists():
+            self.app.mount("/static", StaticFiles(directory=str(static_dir)),
+                           name="static")
+
+        def _url_for(name: str, filename: str | None = None, **params):
+            if filename is not None:
+                params["path"] = filename
+            return self.app.url_path_for(name, **params)
+
+        templates.env.globals["url_for"] = _url_for
+
+    def _assemble_routes(self) -> List[Route]:
+        routes = []
+        routes += self._extra_routes
+        if self.debug:
+            logger.warning("🚀 Z8ter running in DEV mode")
+        else:
+            logger.info("🚀 Z8ter running in PROD mode")
+        routes += build_routes_from_pages()
+        routes += build_routes_from_apis()
+        return routes
+
+    def _ensure_services_registry(self) -> None:
+        if not hasattr(self.app.state, "services"):
+            self.app.state.services = {}
+
+    def add_service(
+            self, obj: object, *,
+            replace: bool = False
+            ) -> str:
+        """
+        Registers a process-wide service under app.state.
+        Access via: request.app.state.<name> or
+        request.app.state.services[name]
+        """
+        self._ensure_services_registry()
+        key = (obj.__class__.__name__).rstrip("_").lower()
+
+        if key in self.app.state.services and not replace:
+            raise ValueError(
+                f"Service '{key}' already exists." +
+                "Use replace=True to overwrite."
+            )
+        self.app.state.services[key] = obj
+        setattr(self.app.state, key, obj)
+        return key
+
+    async def __call__(self, scope, receive, send):
+        await self.app(scope, receive, send)
+
+    def run(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8080,
+        reload: bool | None = None,
+    ) -> None:
+        reload = self.debug if reload is None else reload
+        uvicorn.run(
+            "main:app" if reload else self,
+            host=host,
+            port=port,
+            reload=reload
+        )

z8ter-0.1.0/z8ter/page.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.endpoints import HTTPEndpoint
+from z8ter import templates
+
+
+class Page(HTTPEndpoint):
+    """HTTPEndpoint + a small render() helper for templates."""
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        mod = cls.__module__
+        if mod.startswith("views."):
+            pid = mod.removeprefix("views.")
+        else:
+            pid = mod
+        cls._page_id = pid
+
+    def __init__(self, scope=None, receive=None, send=None):
+        if scope is not None and receive is not None and send is not None:
+            super().__init__(scope, receive, send)
+
+    def render(self, request: Request, template_name: str,
+               context: dict | None = None) -> Response:
+        page_id = getattr(self.__class__, "_page_id", None)
+        ctx = {"page_id": page_id, "request": request}
+        if context:
+            ctx.update(context)
+        return templates.TemplateResponse(template_name, ctx)

z8ter-0.1.0/z8ter/router.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+from pathlib import Path
+import importlib
+from typing import Iterable, Type
+from starlette.routing import Route, Mount
+from starlette.endpoints import HTTPEndpoint
+from z8ter.api import API
+
+
+def _import_module_for(rel_path: Path, package_root: str) -> object:
+    mod_name = str(rel_path.with_suffix("")).replace(
+        "/", ".").replace("\\", ".")
+    if mod_name.startswith(f"{package_root}."):
+        full_name = mod_name
+    else:
+        full_name = f"{package_root}.{mod_name}"
+    return importlib.import_module(full_name)
+
+
+def _iter_page_classes(mod) -> Iterable[Type[HTTPEndpoint]]:
+    from .page import Page
+    for obj in vars(mod).values():
+        if isinstance(obj, type) and issubclass(obj, Page) and obj is not Page:
+            yield obj
+
+
+def _iter_api_classes(mod) -> Iterable[Type[API]]:
+    from .api import API
+    for obj in vars(mod).values():
+        if isinstance(obj, type) and issubclass(obj, API) and obj is not API:
+            yield obj
+
+
+def _url_from_file(pages_root: Path, file_path: Path) -> str:
+    rel = file_path.relative_to(pages_root).with_suffix("")
+    parts = rel.parts
+    url = "/" + "/".join(parts)
+    if url.endswith("/index"):
+        url = url[:-len("/index")] or "/"
+    return url or "/"
+
+
+def build_routes_from_pages(pages_dir: str = "views") -> list[Route]:
+    routes: list[Route] = []
+    pages_root = Path(pages_dir).resolve()
+    seen_paths: set[str] = set()
+    for file_path in pages_root.rglob("*.py"):
+        if file_path.name == "__init__.py":
+            continue
+        rel_to_cwd = file_path.relative_to(Path().resolve())
+        mod = _import_module_for(rel_to_cwd, pages_dir)
+        classes = list(_iter_page_classes(mod))
+        if not classes:
+            continue
+        base_path = _url_from_file(pages_root, file_path)
+        for cls in classes:
+            path = getattr(cls, "path", None) or base_path
+            if path in seen_paths and getattr(cls, "path", None) is None:
+                path = f"{base_path}/{cls.__name__.lower()}"
+            if path not in seen_paths:
+                routes.append(Route(path, cls))
+                seen_paths.add(path)
+    return routes
+
+
+def build_routes_from_apis(api_dir: str = "api") -> list[Mount]:
+    routes: list[Mount] = []
+    pages_root = Path(api_dir).resolve()
+    for file_path in pages_root.rglob("*.py"):
+        if file_path.name == "__init__.py":
+            continue
+        rel_to_cwd = file_path.relative_to(Path().resolve())
+        mod = _import_module_for(rel_to_cwd, api_dir)
+        classes = list(_iter_api_classes(mod))
+        if not classes:
+            continue
+        for cls in classes:
+            routes.append(cls.build_mount())
+    return routes
+
+
+def build_favicon_route(api_dir: str = "static/favicon") -> list[Mount]:
+    routes: list[Mount] = []
+    pages_root = Path(api_dir).resolve()
+    for file_path in pages_root.rglob("*.py"):
+        if file_path.name == "__init__.py":
+            continue
+        rel_to_cwd = file_path.relative_to(Path().resolve())
+        mod = _import_module_for(rel_to_cwd, api_dir)
+        classes = list(_iter_api_classes(mod))
+        if not classes:
+            continue
+        for cls in classes:
+            routes.append(cls.build_mount())
+    return routes

z8ter-0.1.0/z8ter.egg-info/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: z8ter
+Version: 0.1.0
+Summary: SSR-first Python web framework with file-based views, tinyCSR islands, and decorator-driven APIs (Starlette + Jinja2).
+Home-page: https://github.com/ashesh808/Z8ter
+Author: Ashesh Nepal
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: starlette<1.0,>=0.47
+Requires-Dist: Jinja2<4.0,>=3.1
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Z8ter.py
+
+**Z8ter** 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.
+
+---
+
+## ✨ Features (Current)
+
+### 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) Small 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"}
+```
+
+---
+
+## 🛣️ Planned
+
+* **CLI scaffolding**: `z8 new`, `z8 dev`, `z8 create_page <name>`
+* **Auth scaffolding**: login/register/logout + session helpers
+* **Stripe integration**: pricing page, checkout routes, webhooks
+* **DB adapters**: SQLite default, Postgres option
+* **HTMX + Tailwind/DaisyUI** polish out of the box
+
+---
+
+## 🧠 Philosophy
+
+* Conventions over configuration
+* SSR-first with tiny CSR islands
+* Small surface area; sharp, pragmatic tools

z8ter-0.1.0/z8ter.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+api/__init__.py
+api/hello.py
+views/__init__.py
+views/about.py
+views/index.py
+z8ter/__init__.py
+z8ter/api.py
+z8ter/cli.py
+z8ter/config.py
+z8ter/core.py
+z8ter/page.py
+z8ter/router.py
+z8ter.egg-info/PKG-INFO
+z8ter.egg-info/SOURCES.txt
+z8ter.egg-info/dependency_links.txt
+z8ter.egg-info/entry_points.txt
+z8ter.egg-info/requires.txt
+z8ter.egg-info/top_level.txt

z8ter-0.1.0/z8ter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

z8ter-0.1.0/z8ter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+z8 = z8ter.cli:main

z8ter-0.1.0/z8ter.egg-info/requires.txt

@@ -0,0 +1,2 @@
+starlette<1.0,>=0.47
+Jinja2<4.0,>=3.1

z8ter-0.1.0/z8ter.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+api
+views
+z8ter