fastapi-authly 0.1.1__tar.gz → 0.1.2__tar.gz

fastapi_authly-0.1.2/CHANGELOG_SCALAR.md

@@ -0,0 +1,84 @@
+# Scalar 文档功能集成说明
+
+## 改动概述
+
+已将 Scalar API 文档功能集成到 `fastapi-authly` 包中，包含所有必要的静态资源文件。用户只需导入并使用 `setup_scalar_docs` 函数即可启用文档功能，无需手动管理静态文件。
+
+## 新增文件
+
+1. **`src/fastapi_authly/docs.py`**: 文档功能模块
+   - `setup_scalar_docs()`: 主要函数，用于设置 Scalar 文档
+   - `get_static_dir()`: 获取包内静态文件目录路径
+
+2. **`src/fastapi_authly/static/scalar/`**: 静态资源目录
+   - `standalone.js`: Scalar JavaScript 文件
+   - `style.css`: Scalar CSS 样式文件
+
+3. **示例文件**:
+   - `examples/use_scalar_docs.py`: 基本使用示例
+   - `examples/complete_example.py`: 完整使用示例
+   - `docs/SCALAR_DOCS_USAGE.md`: 详细使用文档
+
+## 修改文件
+
+1. **`src/fastapi_authly/__init__.py`**:
+   - 添加 `setup_scalar_docs` 的导入和导出
+
+2. **`README.md` 和 `README.zh.md`**:
+   - 添加 Scalar 文档功能的使用说明
+
+## 使用方法
+
+### 基本使用
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="My API")
+setup_scalar_docs(app)
+```
+
+### 自定义配置
+
+```python
+setup_scalar_docs(
+    app,
+    docs_url="/api-docs",
+    static_url="/assets",
+    title="Custom API Docs",
+    openapi_url="/openapi.json"
+)
+```
+
+## 优势
+
+1. **零配置**: 无需手动复制静态文件
+2. **可移植**: 安装包后即可使用
+3. **简单**: 一行代码启用
+4. **灵活**: 支持自定义 URL 和配置
+
+## 构建和发布
+
+静态文件会自动包含在构建的包中，因为它们在 `src/fastapi_authly/static/` 目录下，属于包的一部分。
+
+构建和发布流程不变：
+
+```bash
+uv build
+uv publish --token your-token
+```
+
+## 测试
+
+安装包后，可以这样测试：
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="Test API")
+setup_scalar_docs(app)
+
+# 运行应用后，访问 http://localhost:8000/docs 即可看到文档
+```

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-authly
-Version: 0.1.1
+Version: 0.1.2
 Summary: A modular authentication system for FastAPI with OAuth2, JWT, and password recovery
 Project-URL: Homepage, https://github.com/yourusername/fastapi-auth-module
 Project-URL: Documentation, https://yourusername.github.io/fastapi-auth-module/
@@ -109,6 +109,10 @@ deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
 
 auth_router = create_auth_router(config=config, dependencies=deps)
 app.include_router(auth_router)
+
+# Optional: Setup Scalar API documentation (static resources included, no manual setup needed)
+from fastapi_authly import setup_scalar_docs
+setup_scalar_docs(app, docs_url="/docs", static_url="/static")
 ```
 
 ### Advanced Usage (custom implementations)
@@ -135,6 +139,30 @@ deps = AuthDependencyConfig(
 auth_router = create_auth_router(config=config, dependencies=deps)
 ```
 
+## 📚 API Documentation
+
+`fastapi-authly` includes built-in Scalar API documentation support with all necessary static resources:
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="My API")
+
+# One line to enable Scalar documentation
+# Automatically mounts static files to /static and creates docs page at /docs
+setup_scalar_docs(app)
+
+# Custom configuration
+setup_scalar_docs(
+    app,
+    docs_url="/api-docs",      # Custom docs URL
+    static_url="/assets",      # Custom static files prefix
+    title="Custom API Docs",   # Custom title
+    openapi_url="/openapi.json" # Custom OpenAPI schema URL
+)
+```
+
 ## 📋 API Endpoints
 
 ### Authentication
@@ -216,26 +244,6 @@ deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
 app.include_router(create_auth_router(config=config, dependencies=deps))
 ```
 
-## 🧪 Testing
-
-```bash
-# Install test dependencies
-uv pip install -e ".[test]"
-
-# Run tests
-uv run pytest
-```
-
-## 📦 Build & Publish
-
-```bash
-# Build
-uv build
-
-# Publish to PyPI (set UV_PUBLISH_TOKEN or pass --token)
-uv publish --token pypi-xxxxx
-```
-
 ## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -261,6 +269,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 If you have any questions or need help:
 
-- 📧 Email: your.email@example.com
 - 💬 GitHub Issues: [Create an issue](https://github.com/yourusername/fastapi-authly/issues)
 - 📖 Documentation: [Read the docs](https://yourusername.github.io/fastapi-authly/)

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/README.md

@@ -57,6 +57,10 @@ deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
 
 auth_router = create_auth_router(config=config, dependencies=deps)
 app.include_router(auth_router)
+
+# Optional: Setup Scalar API documentation (static resources included, no manual setup needed)
+from fastapi_authly import setup_scalar_docs
+setup_scalar_docs(app, docs_url="/docs", static_url="/static")
 ```
 
 ### Advanced Usage (custom implementations)
@@ -83,6 +87,30 @@ deps = AuthDependencyConfig(
 auth_router = create_auth_router(config=config, dependencies=deps)
 ```
 
+## 📚 API Documentation
+
+`fastapi-authly` includes built-in Scalar API documentation support with all necessary static resources:
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="My API")
+
+# One line to enable Scalar documentation
+# Automatically mounts static files to /static and creates docs page at /docs
+setup_scalar_docs(app)
+
+# Custom configuration
+setup_scalar_docs(
+    app,
+    docs_url="/api-docs",      # Custom docs URL
+    static_url="/assets",      # Custom static files prefix
+    title="Custom API Docs",   # Custom title
+    openapi_url="/openapi.json" # Custom OpenAPI schema URL
+)
+```
+
 ## 📋 API Endpoints
 
 ### Authentication
@@ -164,26 +192,6 @@ deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
 app.include_router(create_auth_router(config=config, dependencies=deps))
 ```
 
-## 🧪 Testing
-
-```bash
-# Install test dependencies
-uv pip install -e ".[test]"
-
-# Run tests
-uv run pytest
-```
-
-## 📦 Build & Publish
-
-```bash
-# Build
-uv build
-
-# Publish to PyPI (set UV_PUBLISH_TOKEN or pass --token)
-uv publish --token pypi-xxxxx
-```
-
 ## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -209,6 +217,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 If you have any questions or need help:
 
-- 📧 Email: your.email@example.com
 - 💬 GitHub Issues: [Create an issue](https://github.com/yourusername/fastapi-authly/issues)
 - 📖 Documentation: [Read the docs](https://yourusername.github.io/fastapi-authly/)

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/README.zh.md

@@ -41,6 +41,10 @@ register_tortoise(
 config = AuthConfig(token_url="login")
 deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
 app.include_router(create_auth_router(config=config, dependencies=deps))
+
+# 可选：设置 Scalar API 文档（内置静态资源，无需手动配置）
+from fastapi_authly import setup_scalar_docs
+setup_scalar_docs(app, docs_url="/docs", static_url="/static")
 ```
 
 ## 🔌 自定义实现示例
@@ -65,6 +69,30 @@ deps = AuthDependencyConfig(user_repository=MyRepo(), mailer=MyMailer())
 router = create_auth_router(config=config, dependencies=deps)
 ```
 
+## 📚 API 文档功能
+
+`fastapi-authly` 内置了 Scalar API 文档支持，包含所有必要的静态资源，无需手动配置：
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="My API")
+
+# 一行代码启用 Scalar 文档
+# 自动挂载静态文件到 /static，创建文档页面到 /docs
+setup_scalar_docs(app)
+
+# 自定义配置
+setup_scalar_docs(
+    app,
+    docs_url="/api-docs",      # 自定义文档 URL
+    static_url="/assets",      # 自定义静态文件前缀
+    title="Custom API Docs",   # 自定义标题
+    openapi_url="/openapi.json" # 自定义 OpenAPI schema URL
+)
+```
+
 ## 📋 主要接口
 
 - `POST /auth/login`：登录，返回 access_token（可选 refresh_token）

fastapi_authly-0.1.2/docs/SCALAR_DOCS_USAGE.md

@@ -0,0 +1,121 @@
+# Scalar API 文档功能使用指南
+
+## 概述
+
+`fastapi-authly` 现在内置了 Scalar API 文档支持，包含所有必要的静态资源文件。你无需手动复制静态文件，只需一行代码即可启用美观的 API 文档。
+
+## 快速开始
+
+### 基本使用
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs
+
+app = FastAPI(title="My API")
+
+# 一行代码启用 Scalar 文档
+setup_scalar_docs(app)
+```
+
+这将会：
+- 自动挂载静态文件到 `/static`
+- 创建文档页面到 `/docs`
+- 使用应用的 `title` 和 `openapi_url`
+
+### 完整示例
+
+```python
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs, create_auth_router, AuthConfig, AuthDependencyConfig
+from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository
+from tortoise.contrib.fastapi import register_tortoise
+
+app = FastAPI(
+    title="Complaint API",
+    description="Complaint Data Streaming API",
+    version="2.0.1",
+)
+
+# 初始化数据库
+register_tortoise(
+    app,
+    db_url="postgres://user:password@localhost:5432/mydb",
+    modules={"models": ["fastapi_authly.models.user"]},
+    generate_schemas=True,
+    add_exception_handlers=True,
+)
+
+# 配置认证路由
+config = AuthConfig()
+deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
+auth_router = create_auth_router(config=config, dependencies=deps)
+app.include_router(auth_router)
+
+# 设置 Scalar 文档
+setup_scalar_docs(app, docs_url="/docs", static_url="/static")
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+## 自定义配置
+
+```python
+setup_scalar_docs(
+    app,
+    docs_url="/api-docs",        # 自定义文档 URL
+    static_url="/assets",        # 自定义静态文件前缀
+    title="Custom API Docs",     # 自定义标题
+    openapi_url="/openapi.json"  # 自定义 OpenAPI schema URL
+)
+```
+
+## 参数说明
+
+- `app` (必需): FastAPI 应用实例
+- `docs_url` (可选): 文档页面 URL，默认为 `"/docs"`
+- `static_url` (可选): 静态文件 URL 前缀，默认为 `"/static"`
+- `title` (可选): 文档标题，默认使用 `app.title`
+- `openapi_url` (可选): OpenAPI schema URL，默认使用 `app.openapi_url`
+
+## 注意事项
+
+1. **静态文件位置**: 静态文件已经打包在 `fastapi_authly` 包内，无需手动复制
+2. **URL 冲突**: 确保 `docs_url` 和 `static_url` 不与现有路由冲突
+3. **OpenAPI Schema**: 确保 FastAPI 应用已启用 OpenAPI schema（默认启用）
+
+## 迁移指南
+
+如果你之前手动配置了 Scalar 文档，可以按以下步骤迁移：
+
+### 之前的方式
+
+```python
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+@app.get("/docs", include_in_schema=False)
+async def scalar_html(_app):
+    html_content = f"""
+    <!DOCTYPE html>
+    ...
+    """
+    return HTMLResponse(content=html_content)
+```
+
+### 现在的方式
+
+```python
+from fastapi_authly import setup_scalar_docs
+
+# 一行代码替代上面的所有配置
+setup_scalar_docs(app, docs_url="/docs", static_url="/static")
+```
+
+## 优势
+
+1. **无需手动管理静态文件**: 所有静态资源已打包在包内
+2. **简单易用**: 一行代码即可启用
+3. **可移植**: 其他项目安装包后即可使用，无需额外配置
+4. **可定制**: 支持自定义 URL 和标题

fastapi_authly-0.1.2/docs//345/207/275/346/225/260/345/274/217/347/274/226/347/250/213/344/270/203/346/255/246/345/231/250.md

@@ -0,0 +1,11 @@
+
+## map: 数据转换的瑞士军刀
+
+- 作用: 对可迭代对象中的每个元素应用指定函数，并返回新的迭代器
+- 语法: map(function, iterable)
+- 特点:
+  - 惰性求值: 不立即执行，节省内存
+  - 简洁高效: 一行代码实现批量转换
+- 应用场景:
+  - 数据清洗、格式转换
+  - 特征工程、数据预处理。

fastapi_authly-0.1.2/examples/complete_example.py

@@ -0,0 +1,63 @@
+"""
+完整示例：展示如何像原项目一样使用 fastapi-authly 的文档功能
+"""
+
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs, create_auth_router, AuthConfig, AuthDependencyConfig
+from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository
+from tortoise.contrib.fastapi import register_tortoise, tortoise_exception_handlers
+from contextlib import asynccontextmanager
+
+# 生命周期管理
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # 启动时执行
+    yield
+    # 关闭时执行
+
+# 创建 FastAPI 应用
+app = FastAPI(
+    title="Complaint API",
+    description="Complaint Data Streaming API",
+    version="2.0.1",
+    exception_handlers=tortoise_exception_handlers(),
+    lifespan=lifespan,
+    docs_url="/old_docs",  # 保留旧的 docs，但使用 Scalar
+)
+
+# 初始化数据库
+register_tortoise(
+    app,
+    db_url="postgres://user:password@localhost:5432/mydb",
+    modules={"models": ["fastapi_authly.models.user"]},
+    generate_schemas=True,
+    add_exception_handlers=True,
+)
+
+# 配置认证路由
+config = AuthConfig()
+deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
+auth_router = create_auth_router(config=config, dependencies=deps)
+app.include_router(auth_router)
+
+# 设置 Scalar 文档
+# 这会自动挂载静态文件并创建文档页面
+setup_scalar_docs(
+    app,
+    docs_url="/docs",  # 文档页面 URL
+    static_url="/static",  # 静态文件 URL 前缀（与原来的保持一致）
+)
+
+# 其他 API 路由
+@app.get("/")
+async def root():
+    return {"message": "API is running"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=3040,
+        loop="uvloop",
+    )

fastapi_authly-0.1.2/examples/use_scalar_docs.py

@@ -0,0 +1,53 @@
+"""
+使用示例：如何在项目中使用 fastapi-authly 的 Scalar 文档功能
+"""
+
+from fastapi import FastAPI
+from fastapi_authly import setup_scalar_docs, create_auth_router, AuthConfig, AuthDependencyConfig
+from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository
+from tortoise.contrib.fastapi import register_tortoise
+
+# 创建 FastAPI 应用
+app = FastAPI(
+    title="My API",
+    description="My API with Scalar Documentation",
+    version="1.0.0",
+)
+
+# 配置认证路由（示例）
+config = AuthConfig()
+deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
+auth_router = create_auth_router(config=config, dependencies=deps)
+app.include_router(auth_router)
+
+# 设置 Scalar 文档
+# 这会自动：
+# 1. 挂载静态文件到 /static
+# 2. 创建文档页面到 /docs
+setup_scalar_docs(
+    app,
+    docs_url="/docs",  # 文档页面 URL
+    static_url="/static",  # 静态文件 URL 前缀
+)
+
+# 或者自定义配置
+# setup_scalar_docs(
+#     app,
+#     docs_url="/api-docs",  # 自定义文档 URL
+#     static_url="/assets",  # 自定义静态文件前缀
+#     title="Custom API Docs",  # 自定义标题
+#     openapi_url="/openapi.json",  # 自定义 OpenAPI schema URL
+# )
+
+# 初始化数据库（示例）
+register_tortoise(
+    app,
+    db_url="postgres://user:password@localhost:5432/mydb",
+    modules={"models": ["fastapi_authly.models.user"]},
+    generate_schemas=True,
+    add_exception_handlers=True,
+)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-authly"
-version = "0.1.1"
+version = "0.1.2"
 description = "A modular authentication system for FastAPI with OAuth2, JWT, and password recovery"
 readme = "README.md"
 license = {text = "MIT"}
@@ -75,6 +75,7 @@ path = "src/fastapi_authly/__about__.py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/fastapi_authly"]
+# 静态文件在包目录内，会自动包含，无需额外配置
 
 [tool.hatch.build.targets.sdist]
 exclude = [

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/src/fastapi_authly/__about__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/src/fastapi_authly/__init__.py

@@ -11,6 +11,7 @@ This package provides a complete authentication solution with:
 
 from .auth import AuthModule, create_auth_router
 from .core import AuthConfig, AuthDependencyConfig, BcryptPasswordHasher, JWTTokenService
+from .docs import setup_scalar_docs
 from .interfaces import Mailer, PasswordHasher, TokenService, UserRepository
 from .schemas.user import UserBase, UserCreate, UserUpdate, UserPublic, Token, TokenData
 
@@ -24,6 +25,7 @@ __all__ = [
 
     # Core functions
     "create_auth_router",
+    "setup_scalar_docs",
 
     # Security utilities
     "BcryptPasswordHasher",

{fastapi_authly-0.1.1 → fastapi_authly-0.1.2}/src/fastapi_authly/auth.py

@@ -7,7 +7,7 @@ from fastapi.security import OAuth2PasswordBearer
 from jose import JWTError
 from pydantic import EmailStr
 
-from .core.config import AuthConfig, AuthDependencyConfig
+from .core.config import AuthConfig, AuthDependencyConfig, _config
 from .core.security import BcryptPasswordHasher, JWTTokenService
 from .interfaces import Mailer, PasswordHasher, TokenService, UserRepository
 from .schemas.user import (
@@ -24,11 +24,9 @@ from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository
 
 def _merge_config(config: Optional[AuthConfig]) -> AuthConfig:
     """Environment-driven config, overridden by user-supplied config when provided."""
-    env_config = AuthConfig()
     if config is None:
-        return env_config
-    # user config overrides environment values
-    return env_config.model_copy(update=config.model_dump(exclude_none=True))
+        return _config
+    return _config.model_copy(update=config.model_dump(exclude_none=True))
 
 
 class AuthModule:
@@ -64,9 +62,13 @@ class AuthModule:
         self.router = APIRouter(
             prefix=self.config.router_prefix, tags=self.config.router_tags
         )
-        self.oauth2_scheme = OAuth2PasswordBearer(
-            tokenUrl=f"{self.config.router_prefix.rstrip('/')}/{self.config.token_url}".strip(
-                "/"
+        # token 提取依赖：默认使用 OAuth2PasswordBearer，可通过 AuthDependencyConfig.token_dependency 覆盖
+        self.token_dependency = (
+            self.dependencies.token_dependency
+            or OAuth2PasswordBearer(
+                tokenUrl=f"{self.config.router_prefix.rstrip('/')}/{self.config.token_url}".strip(
+                    "/"
+                )
             )
         )
 
@@ -120,7 +122,7 @@ class AuthModule:
             return Token(access_token=access_token, refresh_token=refresh_token)
 
         @self.router.post("/token/verify")
-        async def verify_token(token: str = Depends(self.oauth2_scheme)) -> Dict[str, Any]:
+        async def verify_token(token: str = Depends(self.token_dependency)) -> Dict[str, Any]:
             try:
                 payload = self.token_service.decode_token(token)
                 token_data = TokenData(**payload)
@@ -142,7 +144,7 @@ class AuthModule:
             return await repo.to_public(created)
 
         @self.router.get("/me", response_model=UserPublic)
-        async def get_current_user(token: str = Depends(self.oauth2_scheme)) -> UserPublic:
+        async def get_current_user(token: str = Depends(self.token_dependency)) -> UserPublic:
             repo = self._ensure_user_repo()
             try:
                 payload = self.token_service.decode_token(token, verify_type="access")