star-openapi 0.9.0__tar.gz → 0.9.2__tar.gz

{star_openapi-0.9.0 → star_openapi-0.9.2}/.github/pull_request_template.md

@@ -3,5 +3,5 @@ Checklist:
 - [ ] Run `pytest tests` and no failed.
 - [ ] Run `ruff check star_openapi tests examples` and no failed.
 - [ ] Run `ruff format star_openapi tests examples` and no failed.
-- [ ] Run `mypy star_openapi` and no failed.
+- [ ] Run `ty check star_openapi` and no failed.
 - [ ] Run `mkdocs serve` and no failed.

{star_openapi-0.9.0 → star_openapi-0.9.2}/.github/workflows/docs.yml

@@ -12,6 +12,8 @@ jobs:
       - uses: actions/checkout@v6
 
       - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: uv sync
@@ -21,5 +23,5 @@ jobs:
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
           git fetch origin gh-pages:gh-pages
-          uv run mike deploy v0.9.x
+          uv run mike deploy v0.x latest --update-aliases
           git push origin gh-pages

{star_openapi-0.9.0 → star_openapi-0.9.2}/.github/workflows/tests.yml

@@ -3,17 +3,15 @@ name: tests
 on:
   push:
     branches: [ main ]
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-      - "*.rst"
+    paths:
+      - "star_openapi/**"
+      - "tests/**"
 
   pull_request:
     branches: [ main ]
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-      - "*.rst"
+    paths:
+      - "star_openapi/**"
+      - "tests/**"
 
 jobs:
   tests:
@@ -40,14 +38,11 @@ jobs:
       - name: Test with pytest
         run: uv run pytest tests
 
-      - name: ruff
+      - name: ruff check
         run: uv run ruff check star_openapi tests examples
 
-      - name: Cache mypy
-        uses: actions/cache@v5
-        with:
-          path: ./.mypy_cache
-          key: mypy|${{ matrix.python-version }}|${{ hashFiles('pyproject.toml') }}
+      - name: ruff format
+        run: uv run ruff format --check star_openapi tests examples
 
-      - name: Run mypy
-        run: uv run mypy star_openapi
+      - name: Run ty
+        run: uv run ty check star_openapi

star_openapi-0.9.2/CHANGELOG.md

@@ -0,0 +1,11 @@
+## v0.9.2 2026-01-26
+
+- Add parameter app to StarGroup by @luolingchun in #4
+
+## v0.9.1 2026-01-12
+
+- Support multi content type in request body and responses by @luolingchun in #2
+
+## v0.9.0 2026-01-04
+
+- first version

{star_openapi-0.9.0 → star_openapi-0.9.2}/CONTRIBUTING.md

@@ -27,15 +27,16 @@ Before submitting pr, you need to complete the following steps:
     ruff check star_openapi tests examples
     ```
 
-4. Running the mypy
+4. Running the ty
 
     ```bash
-    mypy star_openapi
+    ty check star_openapi
     ```
 
 5. Building the docs
 
-   Serve the live docs with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material), and make sure it's correct.
+   Serve the live docs with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material), and make sure it's
+   correct.
 
     ```bash
     mkdocs serve

star_openapi-0.9.2/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: star-openapi
+Version: 0.9.2
+Summary: A simple async API framework based on Starlette.
+Project-URL: Homepage, https://github.com/luolingchun/star-openapi
+Project-URL: Documentation, https://luolingchun.github.io/star-openapi
+Maintainer-email: llc <luolingchun@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: starlette>=0.50.0
+Requires-Dist: uvicorn[standard]>=0.40.0
+Provides-Extra: elements
+Requires-Dist: star-openapi-elements; extra == 'elements'
+Provides-Extra: full
+Requires-Dist: httpx; extra == 'full'
+Requires-Dist: itsdangerous; extra == 'full'
+Requires-Dist: python-multipart; extra == 'full'
+Requires-Dist: pyyaml; extra == 'full'
+Provides-Extra: rapidoc
+Requires-Dist: star-openapi-rapidoc; extra == 'rapidoc'
+Provides-Extra: rapipdf
+Requires-Dist: star-openapi-rapipdf; extra == 'rapipdf'
+Provides-Extra: redoc
+Requires-Dist: star-openapi-redoc; extra == 'redoc'
+Provides-Extra: scalar
+Requires-Dist: star-openapi-scalar; extra == 'scalar'
+Provides-Extra: swagger
+Requires-Dist: star-openapi-swagger; extra == 'swagger'
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <a href="https://luolingchun.github.io/star-openapi/" target="_blank">
+        <img class="off-glb" src="https://raw.githubusercontent.com/luolingchun/star-openapi/main/docs/images/logo-text.svg" 
+             width="60%" height="auto" alt="logo">
+    </a>
+</div>
+<p align="center">
+    <em>A simple async API framework based on Starlette.</em>
+</p>
+<p align="center">
+    <a href="https://github.com/luolingchun/star-openapi/actions/workflows/tests.yml" target="_blank">
+        <img class="off-glb" src="https://img.shields.io/github/actions/workflow/status/luolingchun/star-openapi/tests.yml?branch=main" alt="test">
+    </a>
+    <a href="https://pypi.org/project/star-openapi/" target="_blank">
+        <img class="off-glb" src="https://img.shields.io/pypi/v/star-openapi" alt="pypi">
+    </a>
+    <a href="https://pypistats.org/packages/star-openapi" target="_blank">
+        <img class="off-glb" src="https://img.shields.io/pypi/dm/star-openapi" alt="pypistats">
+    </a>
+    <a href="https://pypi.org/project/star-openapi/" target="_blank">
+        <img class="off-glb" src="https://img.shields.io/pypi/pyversions/star-openapi" alt="pypi versions">
+    </a>
+</p>
+
+**Star OpenAPI** is a web API framework based on **Starlette**. It uses **Pydantic** to verify data and automatic
+generation of interaction documentation.
+
+The key features are:
+
+- **Easy to code:** Easy to use and easy to learn
+
+- **Standard document specification:** Based on [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0)
+
+- **Interactive OpenAPI documentation:**
+  [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc), [RapiDoc](https://github.com/rapi-doc/RapiDoc), [RapiPdf](https://mrin9.github.io/RapiPdf/), [Scalar](https://github.com/scalar/scalar), [Elements](https://github.com/stoplightio/elements)
+
+- **Data validation:** Fast data verification based on [Pydantic](https://github.com/pydantic/pydantic)
+
+- **Websocket**: Support for websocket
+
+## Requirements
+
+Python 3.11+
+
+star-openapi is dependent on the following libraries:
+
+- [Starlette](https://github.com/Kludex/starlette) for the web app.
+- [Pydantic](https://github.com/pydantic/pydantic) for the data validation.
+
+## Installation
+
+```bash
+pip install -U star-openapi[swagger]
+```
+
+<details markdown="block">
+<summary>Optional dependencies</summary>
+
+- [`httpx`](https://github.com/encode/httpx/) - Required if you want to use the `TestClient`.
+- [`python-multipart`](https://github.com//kludex/python-multipart) - Required if you want to support form parsing, with
+  `request.form()`.
+- [`itsdangerous`](https://github.com/pallets/itsdangerous) - Required for `SessionMiddleware` support.
+- [`pyyaml`](https://github.com/yaml/pyyaml) - Required for `SchemaGenerator` support.
+
+You can install all of these with `pip install star-openapi[full]`.
+
+- [star-openapi-plugins](https://github.com/luolingchun/star-openapi-plugins) Provide OpenAPI UI for star-openapi.
+
+You can install all of these with `pip install star-openapi[swagger,redoc,rapidoc,rapipdf,scalar,elements]`.
+
+</details>
+
+## A Simple Example
+
+Here's a simple example, further go to the [Example](https://luolingchun.github.io/star-openapi/v0.x/Example/).
+
+```python
+import uvicorn
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+from star_openapi import OpenAPI
+
+info = {"title": "Star API", "version": "1.0.0"}
+app = OpenAPI(info=info)
+
+book_tag = {"name": "book", "description": "book tag"}
+
+
+class BookModel(BaseModel):
+    name: str
+    age: int
+
+
+@app.post("/book", summary="get books", tags=[book_tag])
+async def create_user(body: BookModel):
+    """
+    get all books
+    """
+    print(body.model_dump_json())
+    return JSONResponse({"message": "Hello World"})
+
+
+if __name__ == "__main__":
+    print(app.routes)
+    uvicorn.run(app)
+```
+
+## API Document
+
+Run the [simple example](https://github.com/luolingchun/star-openapi/blob/main/examples/simple_demo.py), and go
+to http://127.0.0.1:8000/openapi.
+
+> OpenAPI UI plugins are optional dependencies that require manual installation.
+>
+> `pip install -U star-openapi[swagger,redoc,rapidoc,rapipdf,scalar,elements]`
+>
+> More optional ui templates goto the document
+> about [UI_Templates](https://luolingchun.github.io/star-openapi/v0.x/Usage/UI_Templates/).
+
+![openapi](https://raw.githubusercontent.com/luolingchun/star-openapi/main/docs/assets/openapi-all.png)

{star_openapi-0.9.0 → star_openapi-0.9.2}/README.md

@@ -5,7 +5,7 @@
     </a>
 </div>
 <p align="center">
-    <em>A simple API framework based on Starlette.</em>
+    <em>A simple async API framework based on Starlette.</em>
 </p>
 <p align="center">
     <a href="https://github.com/luolingchun/star-openapi/actions/workflows/tests.yml" target="_blank">
@@ -36,6 +36,8 @@ The key features are:
 
 - **Data validation:** Fast data verification based on [Pydantic](https://github.com/pydantic/pydantic)
 
+- **Websocket**: Support for websocket
+
 ## Requirements
 
 Python 3.11+
@@ -85,13 +87,13 @@ app = OpenAPI(info=info)
 book_tag = {"name": "book", "description": "book tag"}
 
 
-class TestModel(BaseModel):
+class BookModel(BaseModel):
     name: str
     age: int
 
 
 @app.post("/book", summary="get books", tags=[book_tag])
-async def create_user(body: TestModel):
+async def create_user(body: BookModel):
     """
     get all books
     """

star_openapi-0.9.2/docs/Example.md

@@ -0,0 +1,290 @@
+## Simple Demo
+
+```python
+import uvicorn
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+from star_openapi import OpenAPI
+
+info = {"title": "Star API", "version": "1.0.0"}
+app = OpenAPI(info=info)
+
+book_tag = {"name": "book", "description": "book tag"}
+
+
+class BookModel(BaseModel):
+    name: str
+    age: int
+
+
+@app.get("/book", summary="get books", tags=[book_tag])
+async def get_book(query: BookModel):
+    """
+    get all books
+    """
+    print(query.model_dump_json())
+    return JSONResponse({"message": "Hello World"})
+
+
+if __name__ == "__main__":
+    print(app.routes)
+    uvicorn.run(app)
+```
+
+## REST Demo
+
+```python
+from http import HTTPStatus
+
+from pydantic import BaseModel, Field
+from starlette.responses import JSONResponse
+
+from star_openapi import Info, OpenAPI, Tag
+
+info = Info(title="book API", version="1.0.0")
+# Basic Authentication Sample
+basic = {"type": "http", "scheme": "basic"}
+# JWT Bearer Sample
+jwt = {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
+# API Key Sample
+api_key = {"type": "apiKey", "name": "api_key", "in": "header"}
+# Implicit OAuth2 Sample
+oauth2 = {
+    "type": "oauth2",
+    "flows": {
+        "implicit": {
+            "authorizationUrl": "https://example.com/api/oauth/dialog",
+            "scopes": {"write:pets": "modify pets in your account", "read:pets": "read your pets"},
+        }
+    },
+}
+security_schemes = {"jwt": jwt, "api_key": api_key, "oauth2": oauth2, "basic": basic}
+
+
+class NotFoundResponse(BaseModel):
+    code: int = Field(-1, description="Status Code")
+    message: str = Field("Resource not found!", description="Exception Information")
+
+
+app = OpenAPI(info=info, security_schemes=security_schemes)
+
+book_tag = Tag(name="book", description="Some Book")
+security = [{"jwt": []}, {"oauth2": ["write:pets", "read:pets"]}]
+
+
+class BookPath(BaseModel):
+    id: int = Field(..., description="book id")
+
+
+class BookQuery(BaseModel):
+    age: int | None = Field(None, description="Age")
+    s_list: list[str] = Field(None, alias="s_list[]", description="some array")
+
+
+class BookBody(BaseModel):
+    age: int | None = Field(..., ge=2, le=4, description="Age")
+    author: str | None = Field(None, min_length=2, max_length=4, description="Author")
+
+
+class BookBodyWithID(BaseModel):
+    id: int = Field(..., description="book id")
+    age: int | None = Field(None, ge=2, le=4, description="Age")
+    author: str = Field(None, min_length=2, max_length=4, description="Author")
+
+
+class BookResponse(BaseModel):
+    code: int = Field(0, description="Status Code")
+    message: str = Field("ok", description="Exception Information")
+    data: BookBodyWithID | None
+
+
+@app.get(
+    "/book/{id}",
+    tags=[book_tag],
+    summary="new summary",
+    description="new description",
+    security=security,
+)
+async def get_book(path: BookPath):
+    """Get a book
+    to get some book by id, like:
+    http://localhost:8000/book/3
+    """
+    if path.id == 4:
+        return NotFoundResponse().model_dump_json(), 404
+    return JSONResponse({"code": 0, "message": "ok", "data": {"id": path.id, "age": 3, "author": "no"}})
+
+
+# set doc_ui False disable openapi UI
+@app.get("/book", doc_ui=True, deprecated=True)
+async def get_books(query: BookQuery):
+    """get books
+    to get all books
+    """
+    print(query)
+    return JSONResponse(
+        {
+            "code": 0,
+            "message": "ok",
+            "data": [{"id": 1, "age": query.age, "author": "a1"}, {"id": 2, "age": query.age, "author": "a2"}],
+        }
+    )
+
+
+@app.post("/book", tags=[book_tag])
+async def create_book(body: BookBody):
+    print(body)
+    return JSONResponse({"code": 0, "message": "ok"})
+
+
+@app.put("/book/{id}", tags=[book_tag])
+async def update_book(path: BookPath, body: BookBody):
+    print(path)
+    print(body)
+    return JSONResponse({"code": 0, "message": "ok"})
+
+
+@app.delete("/book/{id}", tags=[book_tag], doc_ui=False)
+async def delete_book(path: BookPath):
+    print(path)
+    return JSONResponse({"code": 0, "message": "ok"})
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app)
+```
+
+## APIRouter
+
+```python
+import uvicorn
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+from star_openapi import OpenAPI
+from star_openapi.router import APIRouter
+
+app = OpenAPI()
+
+api1 = APIRouter(url_prefix="/api1")
+api2 = APIRouter(url_prefix="/api2")
+
+
+class IdModel(BaseModel):
+    id: int
+
+
+class BookModel(BaseModel):
+    name: str
+    age: int
+
+
+@api1.get("/book")
+async def ge_book():
+    return JSONResponse({"message": "Hello World1"})
+
+
+@api1.post("/book")
+async def create_book(body: BookModel):
+    return JSONResponse(body.model_dump())
+
+
+@api1.put("/book/{id}")
+async def update_book(path: IdModel, body: BookModel):
+    return JSONResponse({"id": path.id, "name": body.name, "age": body.age})
+
+
+@api1.delete("/book/{id}")
+async def delete_book(path: IdModel):
+    return JSONResponse({"id": path.id})
+
+
+@api2.get("/")
+async def get_api2():
+    return JSONResponse({"message": "Hello World2"})
+
+
+api1.register_api(api2)
+
+app.register_api(api1)
+app.register_api(api2)
+
+if __name__ == "__main__":
+    print(app.routes)
+    uvicorn.run(app)
+```
+
+## Upload File Demo
+
+```python
+import uvicorn
+from pydantic import BaseModel, Field
+from starlette.responses import JSONResponse
+
+from star_openapi import OpenAPI, UploadFile
+
+app = OpenAPI()
+
+
+class UploadFileForm(BaseModel):
+    file: UploadFile
+    file_type: str = Field(None, description="File Type")
+
+
+class UploadFilesForm(BaseModel):
+    files: list[UploadFile]
+    file_type: str = Field(None, description="File Type")
+
+
+@app.post("/upload/file")
+async def upload_file(form: UploadFileForm):
+    print(form.file.filename)
+    print(form.file_type)
+
+    content = await form.file.read()
+    with open(form.file.filename, "wb") as f:
+        f.write(content)
+    return JSONResponse({"code": 0, "message": "ok"})
+
+
+@app.post("/upload/files")
+async def upload_files(form: UploadFilesForm):
+    print(form.files)
+    print(form.file_type)
+    return JSONResponse({"code": 0, "message": "ok"})
+
+
+if __name__ == "__main__":
+    print(app.routes)
+    uvicorn.run(app)
+```
+
+## Websocket Demo
+
+```python
+import uvicorn
+from starlette.websockets import WebSocket
+
+from star_openapi import OpenAPI
+
+app = OpenAPI()
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(data)
+
+
+if __name__ == "__main__":
+    uvicorn.run("websocket:app", reload=True)
+```
+
+## A complete project
+
+see [star-api-demo](https://github.com/luolingchun/star-api-demo)