ushka 0.0.2__tar.gz

ushka-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

ushka-0.0.2/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.1
+Name: ushka
+Version: 0.0.2
+Summary: Ushka is a minimal, experimental Python micro-framework for hobbyists and solo developers. Its goal is to enable rapid API development with **zero boilerplate** by using file-based routing.
+Author-Email: kleber-code <kleber.code@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kleber-code/ushka
+Project-URL: Issues, https://github.com/kleber-code/ushka/issues
+Requires-Python: >=3.13
+Requires-Dist: uvicorn>=0.38.0
+Description-Content-Type: text/markdown
+
+# Ushka
+
+Ushka is a minimal, experimental Python ASGI web framework based on file-based routing.
+
+## ⚠️ Alpha Stage: Not Production Ready
+
+This is an **early alpha release**. The project is in active, unstable development. The API may change at any time.
+
+## Core Concept: File-Based Routing
+
+The filesystem is the API. Ushka scans a `routes/` directory and maps the file and directory structure directly to URL paths.
+
+*   A file like `routes/hello.py` becomes the endpoint `/hello`.
+*   A file named `routes/index.py` becomes the root endpoint `/`.
+*   Nested directories become nested paths. `routes/api/v1/status.py` becomes `/api/v1/status`.
+*   Dynamic paths are created using square brackets in the filename. `routes/users/[id].py` becomes the endpoint `/users/[id]`.
+*   The HTTP method is determined by the function name inside the file (e.g., `get()`, `post()`).
+
+---
+
+## Example
+
+This example uses **autodiscovery** to create a simple API.
+
+### Project Structure
+
+```
+examples/
+├── app.py
+└── routes/
+    ├── hello.py
+    ├── index.py
+    └── hello/
+        └── [name].py
+```
+
+### 1. The Route Handlers (`examples/routes/`)
+
+These files contain the functions that will handle requests.
+
+**`examples/routes/index.py`** (handles `GET /`)
+```python
+def get():
+    return "Welcome to the autodiscovered example!"
+```
+
+**`examples/routes/hello.py`** (handles `GET /hello`)
+```python
+def get():
+    return "Hello, World!"
+```
+
+**`examples/routes/hello/[name].py`** (handles `GET /hello/[name]`)
+```python
+def get(name: str):
+    return f"Hello, {name}!"
+```
+
+### 2. The Main Application (`examples/app.py`)
+
+This file creates the Ushka application and tells it to automatically discover the routes.
+
+```python
+from ushka import Ushka
+from pathlib import Path
+
+app = Ushka()
+
+# Autodiscover routes from the 'routes' directory
+routes_path = Path(__file__).parent.joinpath("routes")
+app.router.autodiscover(base_path=routes_path)
+
+if __name__ == "__main__":
+    print("Starting Ushka server on http://127.0.0.1:8000")
+    app.run("127.0.0.1", 8000)
+```
+
+### How to Run the Example
+
+1.  **Navigate to the project root.**
+2.  **Run the application:**
+    ```bash
+    python examples/app.py
+    ```
+3.  **Test the routes in your browser or with `curl`:**
+    *   `curl http://127.0.0.1:8000/`
+    *   `curl http://127.0.0.1:8000/hello`
+    *   `curl http://127.0.0.1:8000/hello/Developer`
+
+---
+
+## Manual Routing
+
+For more complex scenarios, you can add routes manually. This is useful if you prefer not to use file-based routing.
+
+```python
+from ushka import Ushka
+
+app = Ushka()
+
+def my_handler():
+    return "This was added manually."
+
+app.router.add_route("GET", "/manual", my_handler)
+```
+
+## Roadmap
+
+1.  **Stabilize and Enhance the Router:** Improve the routing system and its features.
+2.  **Request/Response Objects:** Implement robust `Request` and `Response` objects.
+3.  **Middleware:** Add support for middleware.
+4.  **CLI:** Create a simple CLI for project scaffolding.
+5.  **Dependency Injection:** Explore a simple DI system.

ushka-0.0.2/README.md

@@ -0,0 +1,113 @@
+# Ushka
+
+Ushka is a minimal, experimental Python ASGI web framework based on file-based routing.
+
+## ⚠️ Alpha Stage: Not Production Ready
+
+This is an **early alpha release**. The project is in active, unstable development. The API may change at any time.
+
+## Core Concept: File-Based Routing
+
+The filesystem is the API. Ushka scans a `routes/` directory and maps the file and directory structure directly to URL paths.
+
+*   A file like `routes/hello.py` becomes the endpoint `/hello`.
+*   A file named `routes/index.py` becomes the root endpoint `/`.
+*   Nested directories become nested paths. `routes/api/v1/status.py` becomes `/api/v1/status`.
+*   Dynamic paths are created using square brackets in the filename. `routes/users/[id].py` becomes the endpoint `/users/[id]`.
+*   The HTTP method is determined by the function name inside the file (e.g., `get()`, `post()`).
+
+---
+
+## Example
+
+This example uses **autodiscovery** to create a simple API.
+
+### Project Structure
+
+```
+examples/
+├── app.py
+└── routes/
+    ├── hello.py
+    ├── index.py
+    └── hello/
+        └── [name].py
+```
+
+### 1. The Route Handlers (`examples/routes/`)
+
+These files contain the functions that will handle requests.
+
+**`examples/routes/index.py`** (handles `GET /`)
+```python
+def get():
+    return "Welcome to the autodiscovered example!"
+```
+
+**`examples/routes/hello.py`** (handles `GET /hello`)
+```python
+def get():
+    return "Hello, World!"
+```
+
+**`examples/routes/hello/[name].py`** (handles `GET /hello/[name]`)
+```python
+def get(name: str):
+    return f"Hello, {name}!"
+```
+
+### 2. The Main Application (`examples/app.py`)
+
+This file creates the Ushka application and tells it to automatically discover the routes.
+
+```python
+from ushka import Ushka
+from pathlib import Path
+
+app = Ushka()
+
+# Autodiscover routes from the 'routes' directory
+routes_path = Path(__file__).parent.joinpath("routes")
+app.router.autodiscover(base_path=routes_path)
+
+if __name__ == "__main__":
+    print("Starting Ushka server on http://127.0.0.1:8000")
+    app.run("127.0.0.1", 8000)
+```
+
+### How to Run the Example
+
+1.  **Navigate to the project root.**
+2.  **Run the application:**
+    ```bash
+    python examples/app.py
+    ```
+3.  **Test the routes in your browser or with `curl`:**
+    *   `curl http://127.0.0.1:8000/`
+    *   `curl http://127.0.0.1:8000/hello`
+    *   `curl http://127.0.0.1:8000/hello/Developer`
+
+---
+
+## Manual Routing
+
+For more complex scenarios, you can add routes manually. This is useful if you prefer not to use file-based routing.
+
+```python
+from ushka import Ushka
+
+app = Ushka()
+
+def my_handler():
+    return "This was added manually."
+
+app.router.add_route("GET", "/manual", my_handler)
+```
+
+## Roadmap
+
+1.  **Stabilize and Enhance the Router:** Improve the routing system and its features.
+2.  **Request/Response Objects:** Implement robust `Request` and `Response` objects.
+3.  **Middleware:** Add support for middleware.
+4.  **CLI:** Create a simple CLI for project scaffolding.
+5.  **Dependency Injection:** Explore a simple DI system.

ushka-0.0.2/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "ushka"
+version = "0.0.2"
+description = "Ushka is a minimal, experimental Python micro-framework for hobbyists and solo developers. Its goal is to enable rapid API development with **zero boilerplate** by using file-based routing."
+authors = [
+    { name = "kleber-code", email = "kleber.code@gmail.com" },
+]
+dependencies = [
+    "uvicorn>=0.38.0",
+]
+requires-python = ">=3.13"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/kleber-code/ushka"
+Issues = "https://github.com/kleber-code/ushka/issues"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14.5",
+    "twine>=6.2.0",
+]

ushka-0.0.2/src/ushka/__init__.py

@@ -0,0 +1,3 @@
+from .application import Ushka
+from .http.request import Request
+from .http.response import Response

ushka-0.0.2/src/ushka/application.py

@@ -0,0 +1,69 @@
+from .http.request import Request
+from .http.response import Response
+from .routing.router import Router
+import uvicorn
+from asyncio import iscoroutinefunction
+import inspect
+
+
+class Ushka:
+    def __init__(self, app_path=None) -> None:
+        # Get the path of the file that instantiated Ushka
+        # stack()[1] refers to the caller's frame
+        # .f_globals['__file__'] gets the __file__ attribute from that frame
+        if app_path is None:
+            app_path = inspect.stack()[1].frame.f_globals["__file__"]
+
+        self.app_path = app_path
+        self.router = Router(app_path)
+        self.router.autodiscover()
+
+    async def handle_http_request(self, scope, receive, send):
+        request = Request(scope, receive)
+
+        func, params = self.router.get_route(request)
+
+        if callable(func):
+            if iscoroutinefunction(func):
+                result = await func(**params)
+            else:
+                result = func(**params)
+
+            # check result type to auto detect media type (example html, text, json)
+
+            if "<html>" in result:
+                response = Response(result, media_type="text/html")
+            else:
+                response = Response(result)
+        else:
+            response = Response("Not Found", 404)
+
+        await response(send)
+
+    async def handle_lifespan(self, receive, send):
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                await send({"type": "lifespan.shutdown.complete"})
+            return
+
+    async def handle_asgi_call(self, scope, receive, send):
+        if scope["type"] == "http":
+            await self.handle_http_request(scope, receive, send)
+
+        elif scope["type"] == "lifespan":
+            await self.handle_lifespan(receive, send)
+
+        else:
+            response = Response("Not Supported", 501)
+
+            await response(send)
+
+    async def __call__(self, scope, receive, send):
+        await self.handle_asgi_call(scope, receive, send)
+
+    def run(self, host="127.0.0.1", port=8000):
+        print(f"Starting Ushka server on http://{host}:{port}")
+        uvicorn.run(self, host=host, port=port)

ushka-0.0.2/src/ushka/http/request.py

@@ -0,0 +1,70 @@
+import json
+from urllib.parse import parse_qs
+
+MAX_BODY = int(2.5 * 1024 * 1024)
+
+
+class Request:
+    def __init__(self, scope, receive):
+        self.scope = scope
+        self.method = str(scope["method"]).upper()
+        self.path = str(scope["path"])
+        self.headers = scope["headers"]
+
+        self._receive = receive
+        self._body = None
+        self._text = None
+        self._json = None
+        self._query = None
+        self._form = None
+
+    async def _load_body(self):
+        chunks = []
+        size = 0
+
+        while True:
+            # TODO Upload Multipart
+            msg = await self._receive()
+            chunk = msg.get("body", b"")
+            size += len(chunk)
+            if size > MAX_BODY:
+                raise ValueError("body too large")
+
+            chunks.append(chunk)
+
+            if not msg.get("more_body", False):
+                break
+
+        self._body = b"".join(chunks)
+        return self._body
+
+    async def body(self) -> bytes:
+        if self._body is None:
+            return await self._load_body()
+        return self._body
+
+    async def text(self) -> str:
+        if self._text is None:
+            self._text = (await self.body()).decode()
+        return self._text
+
+    async def json(self):
+        if self._json is None:
+            self._json = await json.loads(await self.body())
+        return self._json
+
+    async def query(self):
+        if self._query is None:
+            raw = self.scope.get("query_string", b"")
+            parsed = parse_qs(raw.decode())
+
+            self._query = {k: v[0] if len(v) == 1 else v for k, v in parsed.items()}
+        return self._query
+
+    async def form(self):
+        # TODO Multipart form
+        if self._form is None:
+            body = await self.body()
+            parsed = parse_qs(body.decode())
+            self._form = {k: v[0] if len(v) == 1 else v for k, v in parsed.items()}
+        return self._form

ushka-0.0.2/src/ushka/http/response.py

@@ -0,0 +1,18 @@
+class Response:
+    def __init__(self, content, status_code=200, media_type="text/plain") -> None:
+        self.content = content
+
+        self.status_code = status_code
+
+        self.media_type = media_type
+
+    async def __call__(self, send):
+        await send(
+            {
+                "type": "http.response.start",
+                "status": self.status_code,
+                "headers": [[b"content-type", self.media_type.encode()]],
+            }
+        )
+
+        await send({"type": "http.response.body", "body": self.content.encode()})

ushka-0.0.2/src/ushka/routing/router.py

@@ -0,0 +1,96 @@
+import re
+from typing import Dict, Callable, Tuple
+
+from ..http.request import Request
+
+
+def normalize_url_path(path: str) -> str:
+    parts = [p for p in path.split("/") if p and not p == "."]
+    return "/" + "/".join(parts)
+
+
+class Router:
+    def __init__(self, app_path: str):
+        self.app_path = app_path
+        self.static_routes: Dict[str, Dict[str, Callable]] = {}
+        self.dynamic_routes: Dict[
+            str, list[Tuple[re.Pattern, list[str], Callable]]
+        ] = {}
+
+    def add_route(self, method: str, path: str, func: Callable):
+        path = normalize_url_path(path)
+
+        if "[" not in path:
+            self.static_routes.setdefault(method, {})[path] = func
+
+        else:
+            param_names = []
+            regex_pattern = "^"
+            for part in path.strip("/").split("/"):
+                if part.startswith("[") and part.endswith("]"):
+                    param = part[1:-1]
+                    param_names.append(param)
+                    regex_pattern += r"/(?P<%s>[^/]+)" % param
+                else:
+                    regex_pattern += "/" + part
+
+            regex_pattern += "$"
+            compiled = re.compile(regex_pattern)
+            self.dynamic_routes.setdefault(method, []).append(
+                (compiled, param_names, func)
+            )
+
+    def get_route(self, request: Request) -> Tuple[Callable, Dict] | Tuple[None, Dict]:
+        method = request.method
+        path = normalize_url_path(request.path)
+
+        func = self.static_routes.get(method, {}).get(path)
+        if func:
+            return func, {}
+
+        for regex, param_names, dynamic_func in self.dynamic_routes.get(method, []):
+            # TODO: Add Resolve Route to injects depends like func(request)
+            match = regex.match(path)
+            if match:
+                return dynamic_func, match.groupdict()
+
+        return None, {}
+
+    def autodiscover(self, folder="routes"):
+        from pathlib import Path
+        import importlib.util
+        import inspect
+
+        base_path = Path(self.app_path).parent
+        target_path = base_path.joinpath(folder)
+        for file in target_path.rglob("*.py"):
+            if not file.name.startswith("__"):
+                spec = importlib.util.spec_from_file_location("mod", str(file))
+                if spec is None or spec.loader is None:
+                    continue
+
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+
+                for name, obj in inspect.getmembers(mod):
+                    if inspect.isfunction(obj):
+                        # TODO: Add ANY method mode
+                        if name.upper() in [
+                            "GET",
+                            "POST",
+                            "PUT",
+                            "UPDATE",
+                            "DELETE",
+                            "HEAD",
+                        ]:
+                            # FIXME: Race condition caused by /foo/index.py and /foo.py It doesn't pose a danger, but it can cause overwriting and make a "bug" difficult to spot.
+
+                            if file.name.lower() == "index.py":
+                                relative_path = file.parent.relative_to(target_path)
+
+                            else:
+                                relative_path = str(
+                                    file.relative_to(target_path)
+                                ).removesuffix(".py")
+
+                            self.add_route(name.upper(), str(relative_path), obj)