lightapi 0.1.20__tar.gz → 0.1.22__tar.gz

lightapi-0.1.22/.dockerignore

@@ -0,0 +1,29 @@
+.git
+.github
+.venv
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+.cursor
+.cursorrules
+.specify
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.db
+*.log
+dist
+build
+site
+docs
+examples
+tests
+overrides
+mkdocs.yml
+README.md
+LICENSE
+*.md
+specs

lightapi-0.1.22/.github/workflows/docker-publish.yml

@@ -0,0 +1,92 @@
+name: Publish Docker image
+
+# Builds the ready-to-use LightAPI image and pushes it to Docker Hub.
+#
+# Triggers:
+#   - on push of a `v*` tag (release) → tags the image with that version + `latest`
+#   - on push to `master`             → tags the image with `master`
+#   - manual workflow_dispatch        → tags the image with `manual-<run-number>`
+#
+# Required repository secrets:
+#   - DOCKERHUB_USERNAME  Docker Hub username (e.g. `iklobato`)
+#   - DOCKERHUB_TOKEN     Docker Hub access token (read+write+delete scope)
+
+on:
+  push:
+    tags: ["v*.*.*"]
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build & push iklobato/lightapi
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Read package version
+        id: version
+        shell: bash
+        run: |
+          # Extract version from pyproject.toml (e.g. 0.1.21)
+          VERSION=$(python -c "
+          import tomllib, pathlib
+          data = tomllib.loads(pathlib.Path('pyproject.toml').read_text())
+          print(data['project']['version'])
+          ")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Detected lightapi version: $VERSION"
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Compute image tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: iklobato/lightapi
+          tags: |
+            # On a v*.*.* tag → :0.1.21, :0.1, :latest
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            # On a push to master → :master (rolling head)
+            type=raw,value=master,enable=${{ github.ref == 'refs/heads/master' }}
+            # Manual run → :manual-<run-number>
+            type=raw,value=manual-${{ github.run_number }},enable=${{ github.event_name == 'workflow_dispatch' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            LIGHTAPI_VERSION=${{ steps.version.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Image digest summary
+        run: |
+          echo "### Published image" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Tags:" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          echo "${{ steps.meta.outputs.tags }}" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"

lightapi-0.1.22/Dockerfile

@@ -0,0 +1,65 @@
+# syntax=docker/dockerfile:1.7
+
+# Ready-to-run LightAPI image.
+# Users mount their config at /app/lightapi.yaml and run the container —
+# no Python code or build step required on their side.
+#
+# Build:    docker build -t lightapi:local .
+# Run:      docker run --rm -p 8000:8000 \
+#               -v "$(pwd)/lightapi.yaml:/app/lightapi.yaml:ro" \
+#               -e DATABASE_URL=sqlite:////app/data.db \
+#               lightapi:local
+
+FROM python:3.12-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    LIGHTAPI_CONFIG=/app/lightapi.yaml \
+    LIGHTAPI_HOST=0.0.0.0 \
+    LIGHTAPI_PORT=8000 \
+    LIGHTAPI_LOG_LEVEL=info
+
+WORKDIR /app
+
+# Build dependencies for psycopg2 / asyncpg native code. Keep build-essential
+# in the layer so we can compile, then remove it.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+        build-essential \
+        libpq-dev \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install LightAPI + async + PostgreSQL drivers. We use the published wheel
+# rather than copying the source so the image stays useful even when this
+# Dockerfile is built outside the repo.
+ARG LIGHTAPI_VERSION
+RUN if [ -n "$LIGHTAPI_VERSION" ]; then \
+        pip install "lightapi[async]==$LIGHTAPI_VERSION" psycopg2-binary ; \
+    else \
+        pip install "lightapi[async]" psycopg2-binary ; \
+    fi \
+ && apt-get purge -y --auto-remove build-essential \
+ && rm -rf /root/.cache
+
+# Copy the launcher. Everything user-supplied lives outside /app/entrypoint.py.
+COPY docker/entrypoint.py /app/entrypoint.py
+
+# Non-root runtime user
+RUN groupadd --system --gid 1001 lightapi \
+ && useradd  --system --uid 1001 --gid lightapi --home-dir /app --no-create-home lightapi \
+ && chown -R lightapi:lightapi /app
+USER lightapi
+
+EXPOSE 8000
+
+# Lightweight health check — touches the root path expecting any HTTP response.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request, sys; \
+import os; \
+url='http://127.0.0.1:'+os.environ.get('LIGHTAPI_PORT','8000')+'/'; \
+sys.exit(0 if urllib.request.urlopen(url, timeout=2).status else 1)" \
+    || exit 1
+
+ENTRYPOINT ["python", "/app/entrypoint.py"]

{lightapi-0.1.20 → lightapi-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightapi
-Version: 0.1.20
+Version: 0.1.22
 Summary: A lightweight framework for building API endpoints using Python's native libraries.
 Project-URL: Repository, https://github.com/henriqueblobato/LightApi
 Project-URL: Issues, https://github.com/henriqueblobato/LightApi/issues
@@ -131,6 +131,17 @@ uv add "lightapi[async]"
 
 **Optional Redis caching**: `redis` is included as a core dependency but Redis caching only activates when `Meta.cache = Cache(ttl=N)` is set on an endpoint. A `RuntimeWarning` is emitted at startup if Redis is unreachable.
 
+**Docker (no install required)**: run the API straight from the published image — just mount your config:
+
+```bash
+docker run --rm -p 8000:8000 \
+    -v "$(pwd)/lightapi.yaml:/app/lightapi.yaml:ro" \
+    -e DATABASE_URL=sqlite:////app/data.db \
+    iklobato/lightapi:latest
+```
+
+See [Docker deployment](docs/deployment/docker.md) for the full guide.
+
 ---
 
 ## Quick Start
@@ -337,7 +348,7 @@ Use `Meta.authentication` with a backend and an optional permission class:
 ```python
 import os
 from lightapi import RestEndpoint, Authentication, Field
-from lightapi import JWTAuthentication, IsAuthenticated, IsAdminUser
+from lightapi.authentication import JWTAuthentication, IsAuthenticated, IsAdminUser
 
 os.environ["LIGHTAPI_JWT_SECRET"] = "your-secret-key"
 
@@ -360,6 +371,60 @@ class AdminOnlyEndpoint(RestEndpoint):
 2. Permission class `.has_permission(request)` — checks `request.state.user`
 3. Returns `401` if authentication fails, `403` if permission denied
 
+**Custom authentication:** Subclass `JWTAuthentication` or `BasicAuthentication` and override `validate_credentials()`:
+
+```python
+from lightapi.authentication import JWTAuthentication
+
+class MyAuthBackend(JWTAuthentication):
+    async def validate_credentials(self, username: str, password: str) -> dict | None:
+        # Custom validation logic - query your database, check LDAP, etc.
+        user = await self.get_user_from_db(username)
+        if user and await user.verify_password(password):
+            return {"sub": str(user.id), "is_admin": user.is_admin}
+        return None
+
+class ProtectedEndpoint(RestEndpoint):
+    secret: str = Field(min_length=1)
+    class Meta:
+        authentication = Authentication(backend=MyAuthBackend)
+```
+
+**Login and token endpoints:** When using `JWTAuthentication` or `BasicAuthentication`, pass `login_validator` to obtain automatic `/auth/login` and `/auth/token` endpoints (backward compatible):
+
+```python
+def my_validator(username: str, password: str):
+    # Return user payload dict or None
+    user = db.query(User).filter_by(username=username).first()
+    if user and user.check_password(password):
+        return {"sub": str(user.id), "is_admin": user.is_admin}
+    return None
+
+app = LightApi(engine=engine, login_validator=my_validator)
+app.register({"/secrets": ProtectedEndpoint})
+# POST /auth/login and POST /auth/token now accept {"username":"...","password":"..."}
+# JWT mode: 200 {"token":"...","user":{...}}; Basic-only: 200 {"user":{...}}
+```
+
+**Rate limiting:** Add per-endpoint rate limiting via `Authentication` config or global rate limiter:
+
+```python
+from lightapi import RestEndpoint, Authentication
+from lightapi.authentication import JWTAuthentication
+
+class LimitedEndpoint(RestEndpoint):
+    data: str = Field(min_length=1)
+    class Meta:
+        # Per-endpoint: 5 requests per minute
+        authentication = Authentication(
+            backend=JWTAuthentication,
+            rate_limiter={"requests": 5, "window": 60}
+        )
+
+# Or global rate limiter (applied to all endpoints)
+app = LightApi(engine=engine, rate_limiter={"requests": 100, "window": 60})
+```
+
 **Built-in permission classes:**
 
 | Class | Condition |
@@ -670,7 +735,7 @@ class OrderEndpoint(RestEndpoint):
 
 ### Async Method Overrides
 
-Override individual HTTP verbs with `async def`:
+Override individual HTTP verbs with `async def`. Mode is auto-detected — no explicit `mode="async"` needed:
 
 ```python
 class ProductEndpoint(RestEndpoint):
@@ -688,6 +753,8 @@ class ProductEndpoint(RestEndpoint):
         return await self._list_async(request)
 ```
 
+**Auto-detect mode:** LightAPI automatically detects whether an endpoint method is sync or async by checking if it's a coroutine function. Simply define `async def get()` and the framework will use async execution.
+
 **Built-in async CRUD helpers** available on every `RestEndpoint`:
 
 | Method | Description |
@@ -865,12 +932,14 @@ Override these methods to customise behaviour. Both `def` (sync) and `async def`
 | `update` | `(data, pk, partial)` | `UPDATE WHERE id=pk AND version=N RETURNING` |
 | `destroy` | `(request, pk)` | `DELETE WHERE id=pk` |
 | `queryset` | `(request)` | Returns base `select(cls._model_class)` |
-| `get` | `(request)` | Override GET (collection or detail) |
-| `post` | `(request)` | Override POST |
-| `put` | `(request)` | Override PUT |
-| `patch` | `(request)` | Override PATCH |
+| `get` | `(request)` | Override GET (collection or detail) — can return `dict` |
+| `post` | `(request)` | Override POST — can return `dict` |
+| `put` | `(request)` | Override PUT — can return `dict` |
+| `patch` | `(request)` | Override PATCH — can return `dict` |
 | `delete` | `(request)` | Override DELETE |
 
+**Return dict or Response:** Endpoint override methods can return either a `dict` (auto-wrapped to `JSONResponse`) or a Starlette `Response` object:
+
 **Async CRUD helpers** (available when using an async engine):
 
 | Helper | Description |

{lightapi-0.1.20 → lightapi-0.1.22}/README.md

@@ -75,6 +75,17 @@ uv add "lightapi[async]"
 
 **Optional Redis caching**: `redis` is included as a core dependency but Redis caching only activates when `Meta.cache = Cache(ttl=N)` is set on an endpoint. A `RuntimeWarning` is emitted at startup if Redis is unreachable.
 
+**Docker (no install required)**: run the API straight from the published image — just mount your config:
+
+```bash
+docker run --rm -p 8000:8000 \
+    -v "$(pwd)/lightapi.yaml:/app/lightapi.yaml:ro" \
+    -e DATABASE_URL=sqlite:////app/data.db \
+    iklobato/lightapi:latest
+```
+
+See [Docker deployment](docs/deployment/docker.md) for the full guide.
+
 ---
 
 ## Quick Start
@@ -281,7 +292,7 @@ Use `Meta.authentication` with a backend and an optional permission class:
 ```python
 import os
 from lightapi import RestEndpoint, Authentication, Field
-from lightapi import JWTAuthentication, IsAuthenticated, IsAdminUser
+from lightapi.authentication import JWTAuthentication, IsAuthenticated, IsAdminUser
 
 os.environ["LIGHTAPI_JWT_SECRET"] = "your-secret-key"
 
@@ -304,6 +315,60 @@ class AdminOnlyEndpoint(RestEndpoint):
 2. Permission class `.has_permission(request)` — checks `request.state.user`
 3. Returns `401` if authentication fails, `403` if permission denied
 
+**Custom authentication:** Subclass `JWTAuthentication` or `BasicAuthentication` and override `validate_credentials()`:
+
+```python
+from lightapi.authentication import JWTAuthentication
+
+class MyAuthBackend(JWTAuthentication):
+    async def validate_credentials(self, username: str, password: str) -> dict | None:
+        # Custom validation logic - query your database, check LDAP, etc.
+        user = await self.get_user_from_db(username)
+        if user and await user.verify_password(password):
+            return {"sub": str(user.id), "is_admin": user.is_admin}
+        return None
+
+class ProtectedEndpoint(RestEndpoint):
+    secret: str = Field(min_length=1)
+    class Meta:
+        authentication = Authentication(backend=MyAuthBackend)
+```
+
+**Login and token endpoints:** When using `JWTAuthentication` or `BasicAuthentication`, pass `login_validator` to obtain automatic `/auth/login` and `/auth/token` endpoints (backward compatible):
+
+```python
+def my_validator(username: str, password: str):
+    # Return user payload dict or None
+    user = db.query(User).filter_by(username=username).first()
+    if user and user.check_password(password):
+        return {"sub": str(user.id), "is_admin": user.is_admin}
+    return None
+
+app = LightApi(engine=engine, login_validator=my_validator)
+app.register({"/secrets": ProtectedEndpoint})
+# POST /auth/login and POST /auth/token now accept {"username":"...","password":"..."}
+# JWT mode: 200 {"token":"...","user":{...}}; Basic-only: 200 {"user":{...}}
+```
+
+**Rate limiting:** Add per-endpoint rate limiting via `Authentication` config or global rate limiter:
+
+```python
+from lightapi import RestEndpoint, Authentication
+from lightapi.authentication import JWTAuthentication
+
+class LimitedEndpoint(RestEndpoint):
+    data: str = Field(min_length=1)
+    class Meta:
+        # Per-endpoint: 5 requests per minute
+        authentication = Authentication(
+            backend=JWTAuthentication,
+            rate_limiter={"requests": 5, "window": 60}
+        )
+
+# Or global rate limiter (applied to all endpoints)
+app = LightApi(engine=engine, rate_limiter={"requests": 100, "window": 60})
+```
+
 **Built-in permission classes:**
 
 | Class | Condition |
@@ -614,7 +679,7 @@ class OrderEndpoint(RestEndpoint):
 
 ### Async Method Overrides
 
-Override individual HTTP verbs with `async def`:
+Override individual HTTP verbs with `async def`. Mode is auto-detected — no explicit `mode="async"` needed:
 
 ```python
 class ProductEndpoint(RestEndpoint):
@@ -632,6 +697,8 @@ class ProductEndpoint(RestEndpoint):
         return await self._list_async(request)
 ```
 
+**Auto-detect mode:** LightAPI automatically detects whether an endpoint method is sync or async by checking if it's a coroutine function. Simply define `async def get()` and the framework will use async execution.
+
 **Built-in async CRUD helpers** available on every `RestEndpoint`:
 
 | Method | Description |
@@ -809,12 +876,14 @@ Override these methods to customise behaviour. Both `def` (sync) and `async def`
 | `update` | `(data, pk, partial)` | `UPDATE WHERE id=pk AND version=N RETURNING` |
 | `destroy` | `(request, pk)` | `DELETE WHERE id=pk` |
 | `queryset` | `(request)` | Returns base `select(cls._model_class)` |
-| `get` | `(request)` | Override GET (collection or detail) |
-| `post` | `(request)` | Override POST |
-| `put` | `(request)` | Override PUT |
-| `patch` | `(request)` | Override PATCH |
+| `get` | `(request)` | Override GET (collection or detail) — can return `dict` |
+| `post` | `(request)` | Override POST — can return `dict` |
+| `put` | `(request)` | Override PUT — can return `dict` |
+| `patch` | `(request)` | Override PATCH — can return `dict` |
 | `delete` | `(request)` | Override DELETE |
 
+**Return dict or Response:** Endpoint override methods can return either a `dict` (auto-wrapped to `JSONResponse`) or a Starlette `Response` object:
+
 **Async CRUD helpers** (available when using an async engine):
 
 | Helper | Description |

lightapi-0.1.22/docker/entrypoint.py

@@ -0,0 +1,79 @@
+"""Container entrypoint: load lightapi.yaml and start uvicorn.
+
+Resolved configuration values, in order of precedence:
+
+1. Environment variables:
+   - LIGHTAPI_CONFIG    Path to the YAML config (default /app/lightapi.yaml).
+   - LIGHTAPI_HOST      Host for uvicorn to bind (default 0.0.0.0).
+   - LIGHTAPI_PORT      Port for uvicorn (default 8000).
+   - LIGHTAPI_LOG_LEVEL Uvicorn log level (default info).
+   - DATABASE_URL       Substituted into ${DATABASE_URL} placeholders in the YAML.
+   - LIGHTAPI_JWT_SECRET Required when the config uses JWT authentication.
+2. Defaults baked into this script.
+
+The YAML schema is documented at
+https://iklobato.github.io/lightapi/getting-started/configuration/
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import uvicorn
+
+from lightapi import LightApi
+
+logger = logging.getLogger("lightapi.entrypoint")
+
+
+def _resolve_config_path() -> Path:
+    path = Path(os.environ.get("LIGHTAPI_CONFIG", "/app/lightapi.yaml"))
+    if path.exists():
+        return path
+
+    sys.stderr.write(
+        f"LightAPI config file not found at {path}.\n"
+        "Mount your config into the container, for example:\n"
+        "    docker run -v ./lightapi.yaml:/app/lightapi.yaml lightapi\n"
+        "Or set LIGHTAPI_CONFIG to a different path.\n"
+    )
+    sys.exit(2)
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=os.environ.get("LIGHTAPI_LOG_LEVEL", "info").upper(),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    config_path = _resolve_config_path()
+    logger.info("Loading LightAPI config from %s", config_path)
+
+    try:
+        app = LightApi.from_config(str(config_path))
+    except Exception:
+        logger.exception("Failed to load LightAPI config")
+        sys.exit(3)
+
+    starlette_app = app.build_app()
+
+    host = os.environ.get("LIGHTAPI_HOST", "0.0.0.0")
+    port = int(os.environ.get("LIGHTAPI_PORT", "8000"))
+    log_level = os.environ.get("LIGHTAPI_LOG_LEVEL", "info").lower()
+
+    logger.info("Starting uvicorn on %s:%s", host, port)
+    uvicorn.run(
+        starlette_app,
+        host=host,
+        port=port,
+        log_level=log_level,
+        proxy_headers=True,
+        forwarded_allow_ips="*",
+    )
+
+
+if __name__ == "__main__":
+    main()

lightapi-0.1.22/docker/lightapi.example.yaml

@@ -0,0 +1,32 @@
+# Minimal LightAPI config — mount this into the container at /app/lightapi.yaml.
+#
+#   docker run --rm -p 8000:8000 \
+#       -v "$(pwd)/lightapi.example.yaml:/app/lightapi.yaml:ro" \
+#       -e DATABASE_URL=sqlite:////app/data.db \
+#       iklobato/lightapi:latest
+#
+# See https://iklobato.github.io/lightapi/getting-started/configuration/ for
+# the full YAML schema (auth, filtering, pagination, per-method permissions,
+# YAML reflection, defaults, middleware, etc.).
+
+database:
+  url: "${DATABASE_URL}"        # ${VAR} env-var substitution
+
+endpoints:
+  - route: /books
+    fields:
+      title:  { type: str, min_length: 1, max_length: 200 }
+      author: { type: str, min_length: 1 }
+      year:   { type: int, optional: true }
+    meta:
+      methods: [GET, POST, PUT, PATCH, DELETE]
+      pagination:
+        style: page_number
+        page_size: 25
+
+  - route: /authors
+    fields:
+      name: { type: str, min_length: 1 }
+      bio:  { type: str, optional: true }
+    meta:
+      methods: [GET, POST]

{lightapi-0.1.20 → lightapi-0.1.22}/docs/advanced/async.md

@@ -56,7 +56,7 @@ Define `async def queryset` to scope the base query with async I/O or request-le
 from sqlalchemy import select
 from starlette.requests import Request
 from lightapi import RestEndpoint, Field
-from lightapi.auth import IsAuthenticated
+from lightapi.authentication import IsAuthenticated
 from lightapi.config import Authentication
 
 class OrderEndpoint(RestEndpoint):
@@ -314,7 +314,7 @@ from httpx import ASGITransport, AsyncClient
 from sqlalchemy.ext.asyncio import create_async_engine
 from pydantic import Field
 from lightapi import LightApi, RestEndpoint
-from lightapi.auth import AllowAny
+from lightapi.authentication import AllowAny
 from lightapi.config import Authentication
 
 @pytest_asyncio.fixture

{lightapi-0.1.20 → lightapi-0.1.22}/docs/advanced/authentication.md

@@ -39,7 +39,8 @@ Any request that does not carry a valid `Authorization: Bearer <token>` header n
 ## Authentication class
 
 ```python
-from lightapi import Authentication, JWTAuthentication, IsAuthenticated
+from lightapi import Authentication
+from lightapi.authentication import JWTAuthentication, IsAuthenticated
 
 Authentication(
     backend=JWTAuthentication,   # Authentication backend class
@@ -70,9 +71,44 @@ Authorization: Bearer <jwt-token>
 
 The token payload is stored in `request.state.user` after successful authentication.
 
-### Generating tokens
+### Auto-registered login endpoint
 
-LightAPI does not include a login endpoint — you generate tokens in your own code:
+When any endpoint declares `Authentication(backend=JWTAuthentication)` (or
+`BasicAuthentication`), LightAPI automatically registers `POST /auth/login`
+and `POST /auth/token` (the same handler under both paths). The base path
+defaults to `/auth` and can be changed via `LightApi(auth_path="/api/auth")`.
+
+Pass a `login_validator(username, password) -> dict | None` to `LightApi(...)`
+to validate credentials:
+
+```python
+def login_validator(username: str, password: str):
+    if username == "admin" and password == "secret":
+        return {"sub": "1", "username": "admin", "is_admin": True}
+    return None
+
+app = LightApi(engine=engine, login_validator=login_validator)
+```
+
+The dict returned by the validator is the JWT payload. On JWT-protected apps,
+`POST /auth/login` returns `{"token": "<jwt>", "user": {...}}`; the client
+then sends `Authorization: Bearer <jwt>` on subsequent requests.
+
+```bash
+# 1. Log in to obtain a token
+curl -X POST http://localhost:8000/auth/login \
+     -H 'Content-Type: application/json' \
+     -d '{"username":"admin","password":"secret"}'
+# → 200 {"token": "eyJhbGc...", "user": {"sub": "1", ...}}
+
+# 2. Call a protected endpoint
+curl -H 'Authorization: Bearer eyJhbGc...' http://localhost:8000/posts
+```
+
+### Generating tokens manually
+
+If you do not want to use `login_validator` and the auto-registered endpoint,
+issue tokens directly:
 
 ```python
 import jwt, os, datetime
@@ -104,7 +140,8 @@ Allows access only if `JWTAuthentication.authenticate()` returns `True` (valid t
 Allows access only if the token payload contains `"is_admin": true`.
 
 ```python
-from lightapi import Authentication, JWTAuthentication, IsAdminUser
+from lightapi import Authentication
+from lightapi.authentication import JWTAuthentication, IsAdminUser
 
 class AdminEndpoint(RestEndpoint):
     name: str
@@ -148,7 +185,7 @@ class ArticleEndpoint(RestEndpoint):
 Subclass `BaseAuthentication` to implement your own logic:
 
 ```python
-from lightapi.auth import BaseAuthentication
+from lightapi.authentication import BaseAuthentication
 
 class ApiKeyAuthentication(BaseAuthentication):
     def authenticate(self, request) -> bool:
@@ -171,7 +208,7 @@ class SecureEndpoint(RestEndpoint):
 Subclass `BasePermission` to implement your own access control:
 
 ```python
-from lightapi.auth import BasePermission
+from lightapi.authentication import BasePermission
 
 class IsOwner(BasePermission):
     def has_permission(self, request) -> bool:

{lightapi-0.1.20 → lightapi-0.1.22}/docs/advanced/middleware.md

@@ -217,7 +217,7 @@ import pytest_asyncio
 from httpx import ASGITransport, AsyncClient
 from sqlalchemy.ext.asyncio import create_async_engine
 from lightapi import LightApi, RestEndpoint
-from lightapi.auth import AllowAny
+from lightapi.authentication import AllowAny
 from lightapi.config import Authentication
 from lightapi.core import Middleware
 from pydantic import Field