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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-authly
-Version: 0.1.1
+Version: 0.1.3
 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.3}/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.3}/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.3/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.3/examples/correct_usage.py

@@ -0,0 +1,74 @@
+"""
+正确的使用方式示例
+"""
+
+from fastapi import FastAPI
+from tortoise.contrib.fastapi import register_tortoise
+from fastapi_authly import (
+    AuthConfig, 
+    AuthDependencyConfig, 
+    create_auth_router,
+    JwtConfig,
+    setup_scalar_docs
+)
+from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository
+
+app = FastAPI(title="FastAPI Authly 测试应用")
+
+# 初始化 Tortoise + Postgres
+register_tortoise(
+    app,
+    db_url="postgres://user:password@localhost:5432/testdb",
+    modules={"models": ["fastapi_authly.models.user"]},
+    generate_schemas=True,
+    add_exception_handlers=True,
+)
+
+# 方式 1: 使用 JwtConfig 实例（推荐）
+config = AuthConfig(
+    jwt=JwtConfig(
+        secret_key="your-secret-key-change-in-production",
+        algorithm="HS256",
+        access_token_expires_minutes=30,
+        refresh_token_expire_days=7,
+    ),
+    router_prefix="/auth",
+    token_url="login",
+)
+
+# 方式 2: 使用字典更新（也可以）
+# config = AuthConfig(
+#     jwt={
+#         "secret_key": "your-secret-key-change-in-production",
+#         "algorithm": "HS256",
+#         "access_token_expires_minutes": 30,
+#     },
+#     router_prefix="/auth",
+#     token_url="login",
+# )
+
+# 方式 3: 使用默认配置，然后通过环境变量覆盖
+# 设置环境变量: AUTH_JWT__SECRET_KEY=your-secret-key
+# config = AuthConfig(
+#     router_prefix="/auth",
+#     token_url="login",
+# )
+
+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")
+
+@app.get("/")
+async def root():
+    return {"message": "FastAPI Authly 测试应用已启动"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-authly"
-version = "0.1.1"
+version = "0.1.3"
 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.3}/src/fastapi_authly/__about__.py

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

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

@@ -7,23 +7,27 @@ This package provides a complete authentication solution with:
 - Password recovery
 - User management
 - Modular and configurable design
+- Built-in Scalar API documentation
 """
 
 from .auth import AuthModule, create_auth_router
-from .core import AuthConfig, AuthDependencyConfig, BcryptPasswordHasher, JWTTokenService
+from .core import AuthConfig, AuthDependencyConfig, JwtConfig, 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
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     # Main classes
     "AuthModule",
     "AuthConfig",
     "AuthDependencyConfig",
+    "JwtConfig",
 
     # Core functions
     "create_auth_router",
+    "setup_scalar_docs",
 
     # Security utilities
     "BcryptPasswordHasher",

{fastapi_authly-0.1.1 → fastapi_authly-0.1.3}/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")

{fastapi_authly-0.1.1 → fastapi_authly-0.1.3}/src/fastapi_authly/core/__init__.py

@@ -1,11 +1,12 @@
 """Core functionality for fastapi-authly."""
 
-from .config import AuthConfig, AuthDependencyConfig
+from .config import AuthConfig, AuthDependencyConfig, JwtConfig
 from .security import BcryptPasswordHasher, JWTTokenService
 
 __all__ = [
     "AuthConfig",
     "AuthDependencyConfig",
+    "JwtConfig",
     "BcryptPasswordHasher",
     "JWTTokenService",
 ]

fastapi_authly-0.1.3/src/fastapi_authly/core/config.py

@@ -0,0 +1,98 @@
+"""Configuration settings for fastapi-authly."""
+
+from typing import List, Optional, Any
+from datetime import timedelta
+from pydantic import BaseModel, Field, ConfigDict
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class JwtConfig(BaseModel):
+    secret_key: str = "xxx"
+    algorithm: str = "HS256"
+    scheme: str = "JWT"
+    token_expires_time: str = "1200"  # seconds, legacy name
+    access_token_expires_minutes: int | None = None
+    refresh_token_expires_days: int = 7
+
+    @property
+    def access_expires(self) -> timedelta:
+        """Preferred access token expiry."""
+        if self.access_token_expires_minutes is not None:
+            return timedelta(minutes=self.access_token_expires_minutes)
+        # fallback to legacy seconds-based setting
+        return timedelta(seconds=int(self.token_expires_time))
+
+    @property
+    def refresh_expires(self) -> timedelta:
+        return timedelta(days=self.refresh_token_expires_days)
+
+
+
+
+class AuthConfig(BaseSettings):
+    """
+    Runtime configuration loaded from environment variables with ``AUTH_`` prefix.
+
+    Host applications can still pass an ``AuthConfig`` instance directly;
+    in that case, the passed values override the environment values.
+    """
+    jwt: JwtConfig = JwtConfig()
+
+    router_prefix: str = "/auth"
+    router_tags: List[str] = Field(default_factory=lambda: ["authentication"])
+
+    enable_password_recovery: bool = True
+    enable_user_registration: bool = True
+    enable_token_refresh: bool = True
+    enable_html_content: bool = True
+
+    email_from: str = "noreply@example.com"
+    email_from_name: str = "Auth System"
+    password_reset_url_template: str = (
+        "https://yourapp.com/reset-password?token={token}"
+    )
+    verification_url_template: str = (
+        "https://yourapp.com/verify-email?token={token}"
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="AUTH_",
+        extra="ignore",
+    )
+    
+    # 属性访问器：直接访问 jwt 中的属性，兼容现有代码
+    @property
+    def secret_key(self) -> str:
+        """JWT secret key"""
+        return self.jwt.secret_key
+    
+    @property
+    def algorithm(self) -> str:
+        """JWT algorithm"""
+        return self.jwt.algorithm
+    
+    @property
+    def access_token_expire_minutes(self) -> Optional[int]:
+        """Access token expiration in minutes (compatible with auth.py)"""
+        return self.jwt.access_token_expires_minutes
+    
+    @property
+    def refresh_token_expire_days(self) -> int:
+        """Refresh token expiration in days"""
+        return self.jwt.refresh_token_expire_days
+
+_config = AuthConfig()
+
+class AuthDependencyConfig(BaseModel):
+    """
+    Optional dependency injection container.
+
+    Host projects can supply custom implementations for the overridable hooks.
+    """
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    user_repository: Optional[Any] = None
+    password_hasher: Optional[Any] = None
+    token_service: Optional[Any] = None
+    mailer: Optional[Any] = None
+    # 可选：自定义 token 提取依赖（例如自定义 Bearer/JWT 解析）
+    token_dependency: Optional[Any] = None

fastapi_authly-0.1.3/src/fastapi_authly/deps.py

@@ -0,0 +1,121 @@
+from typing import Annotated, Optional, List
+from fastapi import Request, HTTPException, status, Depends
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from fastapi.security.utils import get_authorization_scheme_param
+import jwt
+from jwt.exceptions import InvalidTokenError
+from pydantic import BaseModel, ValidationError
+from .core.config import _config
+from .models.user import User
+
+
+class FlexibleHTTPBearer(HTTPBearer):
+    """支持自定义 scheme 的 HTTP Bearer"""
+
+    def __init__(
+            self,
+            *,
+            accepted_schemes: Optional[List[str]] = None,
+            scheme_name: Optional[str] = None,
+            auto_error: bool = True,
+    ):
+        self.accepted_schemes_lower = [
+            s.lower() for s in (accepted_schemes or ["bearer", "jwt"])
+        ]
+        super().__init__(
+            scheme_name=scheme_name or "Bearer/JWT",
+            auto_error=auto_error,
+        )
+
+    async def __call__(
+            self, request: Request
+    ) -> Optional[HTTPAuthorizationCredentials]:
+        authorization = request.headers.get("Authorization")
+        scheme, credentials = get_authorization_scheme_param(authorization)
+
+        if not (authorization and scheme and credentials):
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Not authenticated",
+                )
+            return None
+
+        if scheme.lower() not in self.accepted_schemes_lower:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail=f"Invalid auth scheme. Accepted: {', '.join(self.accepted_schemes_lower)}",
+                )
+            return None
+
+        return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
+
+
+jwt_scheme = FlexibleHTTPBearer(
+    accepted_schemes=["bearer", "jwt"],  # 可以改成 ["bearer"] 或 ["jwt"]
+    auto_error=True
+)
+
+class TokenPayload(BaseModel):
+    """
+    JWT 载荷模型
+    - sub: 用户 ID
+    - type: 令牌类型（access/refresh），旧 token 可能缺少
+    - exp/nbf 等字段由 jwt 库自行校验
+    """
+
+    sub: int
+    type: str | None = None
+
+async def get_token(
+    credentials: HTTPAuthorizationCredentials = Depends(jwt_scheme),
+) -> str:
+    if credentials is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+        )
+    scheme = credentials.scheme  # "Bearer" / "JWT"
+    token = credentials.credentials
+
+    if scheme.lower() not in ("bearer", "jwt"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid auth scheme. Expected 'Bearer' or 'JWT', got '{scheme}'",
+        )
+    return token
+
+TokenDep = Annotated[str, Depends(get_token)]
+
+async def get_current_user(token: TokenDep) -> User:
+    try:
+        payload = jwt.decode(
+            token,
+            _config.jwt.secret_key,
+            algorithms=[_config.jwt.algorithm],
+        )
+        token_data = TokenPayload(**payload)
+        if token_data.type and token_data.type != "access":
+            raise InvalidTokenError("Invalid token type")
+    except (InvalidTokenError, ValidationError):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Could not validate credentials",
+        )
+
+    user = await User.get_or_none(id=token_data.sub)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    if not user.is_active:
+        raise HTTPException(status_code=400, detail="Inactive user")
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+def get_current_active_superuser(current_user: CurrentUser) -> User:
+    if not current_user.is_superuser:
+        raise HTTPException(
+            status_code=403, detail="The user doesn't have enough privileges"
+        )
+    return current_user