starport 1.0.0__tar.gz

starport-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpine
+
+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.

starport-1.0.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: starport
+Version: 1.0.0
+Summary: Explicit, AI-Ready Web Framework
+Keywords: 
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Dist: starlette>=0.39.0
+Requires-Dist: pyjson5>=2.0.0
+Requires-Dist: python-multipart>=0.0.21
+Requires-Dist: jsonschema>=4 ; extra == 'validate'
+Requires-Dist: openapi-spec-validator>=0.7 ; extra == 'validate'
+Requires-Python: >=3.10
+Provides-Extra: validate
+Description-Content-Type: text/markdown
+
+# Starport
+
+**Explicit, AI-Ready Web Framework**
+
+A minimalist abstraction for Starlette, optimized for the AI era.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+![★Starport](res/logo.svg)
+
+---
+
+## 概要
+
+**Starport** は実装者の意図を明示的にし、AIがその意図を正確に汲み取れる構造を第一に考えて設計された、Starlette ベースの Web フレームワークです。
+
+### 設計思想
+
+1. **シンプルさ** - 不要な抽象化を排除、直感的なAPI
+2. **AI Ready** - サンプル駆動のドキュメント、コードとドキュメントの一体化
+3. **適切な抽象化** - 隠蔽ではなく、必要に応じて Starlette を活用
+
+### 主な特徴
+
+- ✅ **明示的設計 (Explicit)** - 暗黙的な動作を排除、意図が明確なコード
+- ✅ **AI Ready** - JSON5リテラルによるサンプル駆動のドキュメント生成
+- ✅ **軽量** - Pydantic不使用、必要最小限の依存関係
+- ✅ **直感的** - `body.name` のような自然なアクセス、戻り値の型ヒントで動作を制御
+- ✅ **OpenAPI 3.0** - 自動ドキュメント生成と Swagger UI
+- ✅ **Secure by Default** - OpenAPIはデフォルト無効、本番環境での情報露出を防止
+
+---
+
+## クイックスタート
+
+### 基本的な実装
+
+```python
+from starport import Router
+
+
+app = Router(
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+
+@app.get("/helloworld")
+def helloworld() -> str:
+    return "Hello, World!"
+
+
+@app.get("/users")
+def get_users() -> list:
+    return [{"id": "user_001", "name": "海野 彼方"}]
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Swagger UI is available at http://127.0.0.1:8000/docs")
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+### AI Ready のサンプル
+
+```python
+from starport import Router
+from starport.params import JsonBody, Query
+
+app = Router(
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+
+
+@app.get(
+    "/users",
+    spec="""[{
+        id: "user001",           // ユーザーID
+        name: "山田太郎",         // 表示名
+        email: "yamada@example.com",  // メールアドレス
+        "role?": "admin",        // ロール（オプショナル）
+        created_at: "2024-01-01T00:00:00Z"  // 作成日時
+    }]"""
+)
+def list_users(
+    page: int = Query(1, ge=1, description="ページ番号"),
+    limit: int = Query(100, ge=1, le=1000, description="取得件数"),
+    role: str = Query(None, description="ロールでフィルタ")
+) -> list[dict]:
+    """
+    ユーザー一覧を取得（最も基本的なパターン）
+
+    spec: レスポンスの構造を文書化（配列形式）
+    Query: パラメータを個別に定義（バリデーション付き）
+
+    これが最も実用的で、RESTful な API の基本形です。
+    """
+    # 簡易的な実装
+    users = [
+        {
+            "id": "user001",
+            "name": "山田太郎",
+            "email": "yamada@example.com",
+            "role": "admin",
+            "created_at": "2024-01-01T00:00:00Z"
+        },
+        {
+            "id": "user002",
+            "name": "佐藤花子",
+            "email": "sato@example.com",
+            "created_at": "2024-01-02T00:00:00Z"
+        },
+        {
+            "id": "user003",
+            "name": "鈴木一郎",
+            "email": "suzuki@example.com",
+            "role": "user",
+            "created_at": "2024-01-03T00:00:00Z"
+        }
+    ]
+
+    # ロールでフィルタ
+    if role:
+        users = [u for u in users if u.get("role") == role]
+
+    # ページネーション
+    start = (page - 1) * limit
+    end = start + limit
+
+    return users[start:end]
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Swagger UI is available at http://127.0.0.1:8000/docs")
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+### uv を使った実行方法
+
+```bash
+# プロジェクト作成
+uv init hello-starport
+cd hello-starport/
+
+# Starport と Uvicorn のインストール
+uv add git+https://github.com/kinto-dev/starport.git
+uv add uvicorn
+
+# コードを作成
+cat > main.py
+# （上記のサンプルコードをペーストして Ctrl+D）
+
+# サーバー起動
+uv run main.py
+```
+
+Swagger UI: http://127.0.0.1:8000/docs
+
+
+---
+
+## スケールするための設計 (Scalable by Design)
+
+Starport は、小規模なスクリプトから大規模なアプリケーションまで対応可能です。
+App を使って、機能を独立したモジュールとして分割・統合できます。
+
+
+```python
+from starport import App, Route
+
+app = App(
+    routes=[
+        Route("/todos", "myapp.todos:router"),
+        Route("/auth", "myapp.auth:router"),
+    ],
+    lazy=True, 
+    title="My API",
+    version="1.0.0",
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+```
+
+### 疎結合なマルチ・ルーター構成
+
+FastAPI 等で見られる「インポート時に親 App へ登録する」方式ではなく、
+各ルーターを完全に独立した ASGI アプリとして定義し、後から統合する設計を採用しています。
+これにより、循環参照を防止し、各機能を単体でテスト・実行することが容易になります。
+
+### lazy mount
+App は初回リクエスト時にルーターをロード（import）することで、
+大規模アプリケーション（100+ routes）での開発体験を改善します。
+
+- サーバレス環境（AWS Lambda等）の cold start 最適化
+- 開発時の Hot-swap の高速化
+
+
+---
+
+## ドキュメント
+
+### 学習ガイド
+- **[クイックスタート](docs/user/quickstart.md)** - 30分で始める Starport
+- **[開発者ガイド](docs/user/guide.md)** - AI Ready な API 設計と大規模開発
+- **[Spring Boot ユーザー向け入門](docs/user/introduction-for-spring-boot-users.md)** - Spring Boot からの移行ガイド
+
+### リファレンス
+- **[OpenAPI スキーマガイド](docs/user/openapi-schema-guide.md)** - JSON5によるスキーマ定義
+
+### 実装例
+- **[Examples](examples/)** - 実装サンプル集
+
+### 設計資料
+- **[設計原則](docs/dev/design-principles.md)** - Starport の設計思想
+- **[ADR](docs/dev/adr/)** - アーキテクチャ決定記録
+
+---
+
+## 開発
+
+```bash
+# 環境構築
+uv sync
+
+# テスト実行
+uv run pytest
+
+# サンプル実行
+uv run python -m examples.basics.basic
+```
+
+---
+
+## インストール
+
+```bash
+# uv を使用する場合
+uv add git+https://github.com/kinto-dev/starport.git
+
+# pip を使用する場合
+pip install git+https://github.com/kinto-dev/starport.git
+```
+
+**注意**: Starport は現在開発中のため、PyPI での公開は未定です。
+
+---
+
+## 関連プロジェクト
+
+- **[Starlette](https://www.starlette.io/)** - Starport の基盤となる ASGI フレームワーク
+- **[FastAPI](https://fastapi.tiangolo.com/)** - Starport のインスピレーション元

starport-1.0.0/README.md

@@ -0,0 +1,252 @@
+# Starport
+
+**Explicit, AI-Ready Web Framework**
+
+A minimalist abstraction for Starlette, optimized for the AI era.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+![★Starport](res/logo.svg)
+
+---
+
+## 概要
+
+**Starport** は実装者の意図を明示的にし、AIがその意図を正確に汲み取れる構造を第一に考えて設計された、Starlette ベースの Web フレームワークです。
+
+### 設計思想
+
+1. **シンプルさ** - 不要な抽象化を排除、直感的なAPI
+2. **AI Ready** - サンプル駆動のドキュメント、コードとドキュメントの一体化
+3. **適切な抽象化** - 隠蔽ではなく、必要に応じて Starlette を活用
+
+### 主な特徴
+
+- ✅ **明示的設計 (Explicit)** - 暗黙的な動作を排除、意図が明確なコード
+- ✅ **AI Ready** - JSON5リテラルによるサンプル駆動のドキュメント生成
+- ✅ **軽量** - Pydantic不使用、必要最小限の依存関係
+- ✅ **直感的** - `body.name` のような自然なアクセス、戻り値の型ヒントで動作を制御
+- ✅ **OpenAPI 3.0** - 自動ドキュメント生成と Swagger UI
+- ✅ **Secure by Default** - OpenAPIはデフォルト無効、本番環境での情報露出を防止
+
+---
+
+## クイックスタート
+
+### 基本的な実装
+
+```python
+from starport import Router
+
+
+app = Router(
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+
+@app.get("/helloworld")
+def helloworld() -> str:
+    return "Hello, World!"
+
+
+@app.get("/users")
+def get_users() -> list:
+    return [{"id": "user_001", "name": "海野 彼方"}]
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Swagger UI is available at http://127.0.0.1:8000/docs")
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+### AI Ready のサンプル
+
+```python
+from starport import Router
+from starport.params import JsonBody, Query
+
+app = Router(
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+
+
+@app.get(
+    "/users",
+    spec="""[{
+        id: "user001",           // ユーザーID
+        name: "山田太郎",         // 表示名
+        email: "yamada@example.com",  // メールアドレス
+        "role?": "admin",        // ロール（オプショナル）
+        created_at: "2024-01-01T00:00:00Z"  // 作成日時
+    }]"""
+)
+def list_users(
+    page: int = Query(1, ge=1, description="ページ番号"),
+    limit: int = Query(100, ge=1, le=1000, description="取得件数"),
+    role: str = Query(None, description="ロールでフィルタ")
+) -> list[dict]:
+    """
+    ユーザー一覧を取得（最も基本的なパターン）
+
+    spec: レスポンスの構造を文書化（配列形式）
+    Query: パラメータを個別に定義（バリデーション付き）
+
+    これが最も実用的で、RESTful な API の基本形です。
+    """
+    # 簡易的な実装
+    users = [
+        {
+            "id": "user001",
+            "name": "山田太郎",
+            "email": "yamada@example.com",
+            "role": "admin",
+            "created_at": "2024-01-01T00:00:00Z"
+        },
+        {
+            "id": "user002",
+            "name": "佐藤花子",
+            "email": "sato@example.com",
+            "created_at": "2024-01-02T00:00:00Z"
+        },
+        {
+            "id": "user003",
+            "name": "鈴木一郎",
+            "email": "suzuki@example.com",
+            "role": "user",
+            "created_at": "2024-01-03T00:00:00Z"
+        }
+    ]
+
+    # ロールでフィルタ
+    if role:
+        users = [u for u in users if u.get("role") == role]
+
+    # ページネーション
+    start = (page - 1) * limit
+    end = start + limit
+
+    return users[start:end]
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Swagger UI is available at http://127.0.0.1:8000/docs")
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+### uv を使った実行方法
+
+```bash
+# プロジェクト作成
+uv init hello-starport
+cd hello-starport/
+
+# Starport と Uvicorn のインストール
+uv add git+https://github.com/kinto-dev/starport.git
+uv add uvicorn
+
+# コードを作成
+cat > main.py
+# （上記のサンプルコードをペーストして Ctrl+D）
+
+# サーバー起動
+uv run main.py
+```
+
+Swagger UI: http://127.0.0.1:8000/docs
+
+
+---
+
+## スケールするための設計 (Scalable by Design)
+
+Starport は、小規模なスクリプトから大規模なアプリケーションまで対応可能です。
+App を使って、機能を独立したモジュールとして分割・統合できます。
+
+
+```python
+from starport import App, Route
+
+app = App(
+    routes=[
+        Route("/todos", "myapp.todos:router"),
+        Route("/auth", "myapp.auth:router"),
+    ],
+    lazy=True, 
+    title="My API",
+    version="1.0.0",
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+)
+```
+
+### 疎結合なマルチ・ルーター構成
+
+FastAPI 等で見られる「インポート時に親 App へ登録する」方式ではなく、
+各ルーターを完全に独立した ASGI アプリとして定義し、後から統合する設計を採用しています。
+これにより、循環参照を防止し、各機能を単体でテスト・実行することが容易になります。
+
+### lazy mount
+App は初回リクエスト時にルーターをロード（import）することで、
+大規模アプリケーション（100+ routes）での開発体験を改善します。
+
+- サーバレス環境（AWS Lambda等）の cold start 最適化
+- 開発時の Hot-swap の高速化
+
+
+---
+
+## ドキュメント
+
+### 学習ガイド
+- **[クイックスタート](docs/user/quickstart.md)** - 30分で始める Starport
+- **[開発者ガイド](docs/user/guide.md)** - AI Ready な API 設計と大規模開発
+- **[Spring Boot ユーザー向け入門](docs/user/introduction-for-spring-boot-users.md)** - Spring Boot からの移行ガイド
+
+### リファレンス
+- **[OpenAPI スキーマガイド](docs/user/openapi-schema-guide.md)** - JSON5によるスキーマ定義
+
+### 実装例
+- **[Examples](examples/)** - 実装サンプル集
+
+### 設計資料
+- **[設計原則](docs/dev/design-principles.md)** - Starport の設計思想
+- **[ADR](docs/dev/adr/)** - アーキテクチャ決定記録
+
+---
+
+## 開発
+
+```bash
+# 環境構築
+uv sync
+
+# テスト実行
+uv run pytest
+
+# サンプル実行
+uv run python -m examples.basics.basic
+```
+
+---
+
+## インストール
+
+```bash
+# uv を使用する場合
+uv add git+https://github.com/kinto-dev/starport.git
+
+# pip を使用する場合
+pip install git+https://github.com/kinto-dev/starport.git
+```
+
+**注意**: Starport は現在開発中のため、PyPI での公開は未定です。
+
+---
+
+## 関連プロジェクト
+
+- **[Starlette](https://www.starlette.io/)** - Starport の基盤となる ASGI フレームワーク
+- **[FastAPI](https://fastapi.tiangolo.com/)** - Starport のインスピレーション元

starport-1.0.0/pyproject.toml

@@ -0,0 +1,159 @@
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "starport"
+version = "1.0.0"
+description = "Explicit, AI-Ready Web Framework"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "alpine" },
+]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "starlette>=0.39.0",
+    "pyjson5>=2.0.0",
+    "python-multipart>=0.0.21",
+]
+
+[project.optional-dependencies]
+validate = [
+    # STARPORT_VALIDATE_SPEC=1
+    "jsonschema>=4",
+    # STARPORT_VALIDATE_OPENAPI=1
+    "openapi-spec-validator>=0.7", 
+]
+
+[project.scripts]
+#starport = "starport.cli.main:main"
+
+[dependency-groups]
+dev = [
+    # validate
+    "jsonschema",
+    "openapi-spec-validator",
+    # Web server
+    "uvicorn[standard]>=0.38.0",
+    # Linting
+    "ruff",
+    #-- pytest --
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-benchmark>=5.2.3",
+    "httpx>=0.28.1",
+    "fastapi>=0.141.1",
+    #-- dev-docs skill --
+    "pyyaml>=6.0.3",
+    "pytest-env>=1.6.0",
+    "pytest-asyncio>=1.4.0",
+]
+
+
+[tool.uv]
+package = true
+
+
+[tool.ruff]
+# https://docs.astral.sh/ruff/configuration/
+include = ["src/**/*.py", "tests/**/*.py", "scripts/**/*.py"]
+cache-dir = "var/.ruff_cache"
+target-version = "py310"
+preview = true 
+# unsafe-fixes = true
+
+
+[tool.ruff.lint]
+# https://docs.astral.sh/ruff/rules/
+select = [
+    # pycodestyle (E, W)
+    "E2",
+    "E4",
+    "E7",
+    "E9",
+    "W",
+
+    # Pyflakes (F)
+    "F",
+
+    # flake8-no-pep420 (INP)
+    "INP",
+
+    # pep8-naming (N)
+    #"N",
+]
+ignore = [
+    "W293", # Blank line contains whitespace
+]
+
+[tool.ruff.lint.per-file-ignores]
+"docker/*.py" = ["INP"]
+"scripts/*.py" = ["INP"]
+"tests/*.py" = ["INP"]
+"var/*.py" = ["INP"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 130
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "examples"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+cache_dir = "var/.pytest_cache"
+
+log_level = "INFO"
+log_cli = true
+log_cli_level = "INFO"
+log_cli_format = "%(asctime)s.%(msecs)03d [%(levelname)s] %(name)s:%(lineno)d - %(message)s"
+log_file = "var/log/pytest.log"
+log_file_level = "INFO"
+log_file_format = "%(asctime)s [%(levelname)s] <%(threadName)s> %(name)s:%(lineno)d - %(message)s"
+
+# pytest-benchmark
+# - https://pytest-benchmark.readthedocs.io/en/latest/usage.html
+#
+# use --benchmark-only to run them. This overrides –-benchmark-skip.
+# ❯ pytest --benchmark-only [-k <test_name>]
+addopts = "--benchmark-skip"
+
+
+[tool.pytest_env]
+STARPORT_VALIDATE_OPENAPI = 1
+STARPORT_VALIDATE_SPEC = 1
+
+
+[tool.coverage.run]
+source = ["src"]
+data_file = "var/.coverage"
+omit = [
+    "tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]