sa-token-python-core 0.1.2__tar.gz → 0.1.4__tar.gz

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sa-token-python-core
-Version: 0.1.2
+Version: 0.1.4
 Summary: 有状态 Token 认证与权限鉴权框架（轻量核心）。灵感来源于 Java 的 Sa-Token。常用依赖请安装 sa-token-python；Web 框架按 extras 安装。
 Project-URL: Homepage, https://github.com/Star-yb/sa-token-python
 Project-URL: Documentation, https://github.com/Star-yb/sa-token-python
@@ -313,6 +313,7 @@ SaToken.builder() \
 | `is_write_cookie` | `False` | FastAPI 显式调用写 Cookie 助手时是否生效 |
 | `storage_key_prefix` | `satoken:` | 所有存储键前缀 |
 | `jwt_secret_key` | `None` | JWT 风格时必填 |
+| `is_print_banner` | `True` | 启动时打印 Sa-Token 标志，`.print_banner(False)` 关闭 |
 
 Token 读取顺序全局唯一：**Header → Authorization 兜底 → Cookie → Query**。各框架禁止自己再解析一遍。
 
@@ -504,8 +505,8 @@ class MyappConfig(AppConfig):
         from sa_token import SaToken
         from sa_token.storage import MemoryStorage, RedisStorage
 
-        SaToken.builder().storage(MemoryStorage()).timeout(86400).print_banner(False).build()
-        SaToken.builder().storage(RedisStorage.from_url("redis://127.0.0.1:6379/0")).timeout(86400).print_banner(False).build()
+        SaToken.builder().storage(MemoryStorage()).timeout(86400).build()
+        SaToken.builder().storage(RedisStorage.from_url("redis://127.0.0.1:6379/0")).timeout(86400).build()
 ```
 
 ### 2. 注册中间件

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/README.md

@@ -263,6 +263,7 @@ SaToken.builder() \
 | `is_write_cookie` | `False` | FastAPI 显式调用写 Cookie 助手时是否生效 |
 | `storage_key_prefix` | `satoken:` | 所有存储键前缀 |
 | `jwt_secret_key` | `None` | JWT 风格时必填 |
+| `is_print_banner` | `True` | 启动时打印 Sa-Token 标志，`.print_banner(False)` 关闭 |
 
 Token 读取顺序全局唯一：**Header → Authorization 兜底 → Cookie → Query**。各框架禁止自己再解析一遍。
 
@@ -454,8 +455,8 @@ class MyappConfig(AppConfig):
         from sa_token import SaToken
         from sa_token.storage import MemoryStorage, RedisStorage
 
-        SaToken.builder().storage(MemoryStorage()).timeout(86400).print_banner(False).build()
-        SaToken.builder().storage(RedisStorage.from_url("redis://127.0.0.1:6379/0")).timeout(86400).print_banner(False).build()
+        SaToken.builder().storage(MemoryStorage()).timeout(86400).build()
+        SaToken.builder().storage(RedisStorage.from_url("redis://127.0.0.1:6379/0")).timeout(86400).build()
 ```
 
 ### 2. 注册中间件

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/examples/native/quick_start.py

@@ -24,7 +24,7 @@ def on_auth_event(data: EventData) -> None:
 
 
 async def main() -> None:
-    SaToken.builder().storage(MemoryStorage()).timeout(7200).print_banner(False).on(
+    SaToken.builder().storage(MemoryStorage()).timeout(7200).on(
         Event.ALL, on_auth_event
     ).build()
 

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sa-token-python-core"
-version = "0.1.2"
+version = "0.1.4"
 description = "有状态 Token 认证与权限鉴权框架（轻量核心）。灵感来源于 Java 的 Sa-Token。常用依赖请安装 sa-token-python；Web 框架按 extras 安装。"
 readme = "README.md"
 requires-python = ">=3.10"

sa_token_python_core-0.1.4/src/sa_token/banner.py

@@ -0,0 +1,76 @@
+"""启动横幅。
+
+与 Java / Go 版一致：初始化时默认打印一次 ASCII 标志。
+Web 框架适配会在服务启动时再尝试打印；进程内只输出一次。
+``is_print_banner=False`` 或 ``.print_banner(False)`` 可关闭。
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查
+    from .manager import SaTokenManager
+
+__all__ = ["BANNER", "emit_banner", "emit_configured_banner", "reset_banner_state"]
+
+BANNER = r"""
+   _____         ______      __
+  / ___/____ _  /_  __/___  / /_____  ____
+  \__ \/ __ `/   / / / __ \/ //_/ _ \/ __ \
+ ___/ / /_/ /   / / / /_/ / ,< /  __/ / / /
+/____/\__,_/   /_/  \____/_/|_|\___/_/ /_/
+"""
+
+_printed = False
+
+
+def reset_banner_state() -> None:
+    """测试隔离：允许下一个用例再次打印。"""
+    global _printed
+    _printed = False
+
+
+def render_banner(manager: SaTokenManager) -> str:
+    from .manager import __version__
+
+    timeout = manager.config.timeout
+    timeout_text = "永久" if timeout < 0 else f"{timeout} 秒"
+    lines = [
+        BANNER.rstrip("\n"),
+        f":: sa-token-python ::   (v{__version__})",
+        f":: Python ::            {sys.version.split()[0]}",
+        f":: Token Style ::       {manager.config.token_style}",
+        f":: Token Timeout ::     {timeout_text}",
+        f":: Storage ::           {type(manager.storage).__name__}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def write_banner(manager: SaTokenManager) -> None:
+    """无条件写出横幅，供手动调用。"""
+    sys.stdout.write(render_banner(manager) + "\n")
+    sys.stdout.flush()
+
+
+def emit_banner(manager: SaTokenManager) -> None:
+    """按配置打印横幅，同一进程只打印一次。"""
+    global _printed
+    if _printed or not manager.config.is_print_banner:
+        return
+    _printed = True
+    write_banner(manager)
+
+
+def emit_configured_banner() -> None:
+    """框架启动钩子：全局 Manager 已就绪则打印。"""
+    from .exception import SaTokenNotInitializedException
+    from .stp_util import get_manager
+
+    try:
+        manager = get_manager()
+    except SaTokenNotInitializedException:
+        return
+    emit_banner(manager)

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/config.py

@@ -105,7 +105,13 @@ class SaTokenConfig:
     jwt_algorithm: str = "HS256"
 
     is_print_banner: bool = True
-    """初始化时是否打印启动横幅。"""
+    """是否打印启动横幅。默认 True，与 Java / Go 版一致。
+
+    原生 ``build()``、FastAPI / Starlette 服务启动、Flask ``init_app``、
+    Django 中间件加载时都会尝试打印，同一进程只输出一次。
+    关闭：``SaToken.builder().print_banner(False)`` 或
+    ``set_option(is_print_banner=False)``。
+    """
 
     extra: dict[str, Any] = field(default_factory=dict)
     """给扩展模块（OAuth2 / SSO / 在线用户）放自定义配置。"""

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/integration/django.py

@@ -14,6 +14,7 @@ from typing import Any, TypeVar
 from ..adapter.http import HttpContext
 from ..adapter.path import PathAuthConfig
 from ..adapter.pipeline import build_rule, resolve_token, run_auth_flow, run_path_auth
+from ..banner import emit_configured_banner
 from ..exception import SaTokenException
 from ..permission import MatchMode
 from ..stp_util import get_manager
@@ -78,6 +79,7 @@ class SaTokenDjangoMiddleware:
 
     def __init__(self, get_response: Callable[[Any], Any]) -> None:
         self._get_response = get_response
+        emit_configured_banner()
 
     def __call__(self, request: Any) -> Any:
         ctx = DjangoHttpContext(request)

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/integration/flask.py

@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Any, TypeVar
 from ..adapter.http import HttpContext
 from ..adapter.path import PathAuthConfig
 from ..adapter.pipeline import build_rule, resolve_token, run_auth_flow, run_path_auth
+from ..banner import emit_configured_banner
 from ..exception import SaTokenException
 from ..permission import MatchMode
 from ..stp_util import get_manager
@@ -77,6 +78,9 @@ class SaTokenFlask:
     def init_app(self, app: Flask) -> None:
         app.before_request(self._before_request)
         app.register_error_handler(SaTokenException, self._handle_exception)
+        if hasattr(app, "before_serving"):
+            app.before_serving(emit_configured_banner)
+        emit_configured_banner()
 
     # 请求钩子 --------------------------------------------------------------
 

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/integration/starlette.py

@@ -26,6 +26,7 @@ except ImportError as exc:  # pragma: no cover - 依赖缺失路径
 from ..adapter.http import HttpContext
 from ..adapter.path import PathAuthConfig
 from ..adapter.pipeline import build_rule, resolve_token, run_auth_flow, run_path_auth
+from ..banner import emit_configured_banner
 from ..exception import SaTokenException
 from ..permission import MatchMode
 from ..stp_util import get_manager
@@ -99,6 +100,7 @@ class SaTokenMiddleware(BaseHTTPMiddleware):
         super().__init__(app)
         self.path_auth = path_auth
         self.login_type = login_type
+        emit_configured_banner()
 
     async def dispatch(
         self,

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/manager.py

@@ -6,9 +6,9 @@ Manager 负责组装：配置 + 存储 + Token 策略 + 事件总线 + 权限数
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING, Any
 
+from .banner import emit_banner, write_banner
 from .config import SaTokenConfig
 from .listener import Event, EventBus, Listener
 from .model import DEFAULT_LOGIN_TYPE
@@ -22,15 +22,7 @@ if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查
 
 __all__ = ["SaTokenManager", "SaTokenBuilder", "SaToken", "__version__"]
 
-__version__ = "0.1.2"
-
-_BANNER = r"""
-   _____         ______      __
-  / ___/____ _  /_  __/___  / /_____  ____
-  \__ \/ __ `/   / / / __ \/ //_/ _ \/ __ \
- ___/ / /_/ /   / / / /_/ / ,< /  __/ / / /
-/____/\__,_/   /_/  \____/_/|_|\___/_/ /_/
-"""
+__version__ = "0.1.4"
 
 
 class SaTokenManager:
@@ -54,6 +46,7 @@ class SaTokenManager:
         self._nonce_manager: NonceManager | None = None
         self._refresh_token_manager: RefreshTokenManager | None = None
         self._temp_token_manager: TempTokenManager | None = None
+        emit_banner(self)
 
     def stp(self, login_type: str = DEFAULT_LOGIN_TYPE) -> StpLogic:
         """取得指定账号体系的逻辑实例，不同 ``login_type`` 之间存储完全隔离。"""
@@ -100,16 +93,8 @@ class SaTokenManager:
         return self._temp_token_manager
 
     def print_banner(self) -> None:
-        lines = [
-            _BANNER,
-            f":: sa-token-python ::   (v{__version__})",
-            f":: Python ::            {sys.version.split()[0]}",
-            f":: Token Style ::       {self.config.token_style}",
-            f":: Token Timeout ::     {self.config.timeout} 秒",
-            f":: Storage ::           {type(self.storage).__name__}",
-            "",
-        ]
-        print("\n".join(lines))
+        """手动打印启动横幅，不受「只打印一次」限制。"""
+        write_banner(self)
 
 
 class SaTokenBuilder:
@@ -190,6 +175,7 @@ class SaTokenBuilder:
         return self
 
     def print_banner(self, value: bool) -> SaTokenBuilder:
+        """是否打印启动横幅，默认 True。传入 False 关闭。"""
         self._config.is_print_banner = value
         return self
 
@@ -227,8 +213,6 @@ class SaTokenBuilder:
             stp_interface=self._stp_interface,
             events=self._events,
         )
-        if self._config.is_print_banner:
-            manager.print_banner()
         if self._set_global:
             from .stp_util import set_manager
 

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/security/refresh.py

@@ -228,15 +228,27 @@ class RefreshTokenManager:
             if cursor is None:
                 return
 
-    async def revoke_all_for_login(self, login_type: str, login_id: str) -> None:
+    async def revoke_all_for_login(
+        self,
+        login_type: str,
+        login_id: str,
+        *,
+        logout_access: bool = True,
+    ) -> None:
         raw = await self._storage.get(self._user_index_key(login_type, login_id))
         families = json.loads(raw) if raw else []
         if isinstance(families, list):
             for family_id in families:
-                await self.revoke_family(str(family_id))
+                await self.revoke_family(str(family_id), logout_access=logout_access)
         await self._storage.delete(self._user_index_key(login_type, login_id))
 
-    async def revoke_family(self, family_id: str) -> None:
+    async def revoke_family(self, family_id: str, *, logout_access: bool = True) -> None:
+        """吊销整个 token family。
+
+        ``logout_access=False`` 时只作废 refresh 侧记录。账号级 kickout/replaced
+        已经把 access token 标成下线原因，若这里再 ``logout_by_token`` 会把刚写入
+        的离线记录删掉，客户端就会看到 ``INVALID_TOKEN`` 而不是 ``KICK_OUT``。
+        """
         key = self._family_key(family_id)
         raw = await self._storage.get(key)
         family = _FamilyRecord.from_json(raw) if raw else None
@@ -245,8 +257,12 @@ class RefreshTokenManager:
         family.revoked = True
         await self._storage.set(key, family.to_json(), self._manager.config.refresh_token_timeout)
         logic = self._manager.stp(family.login_type)
-        for access_token in set(family.access_tokens):
-            await logic.logout_by_token(access_token, revoke_refresh=False)
+        if logout_access:
+            for access_token in set(family.access_tokens):
+                info = await logic.get_token_info(access_token)
+                if info is not None and info.is_offline:
+                    continue
+                await logic.logout_by_token(access_token, revoke_refresh=False)
         for token in set(family.refresh_tokens):
             await self._storage.delete(self._refresh_key(token))
 

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/stp_logic.py

@@ -370,8 +370,10 @@ class StpLogic:
         offline_count = await self._offline_terminals(session, normalized_id, device, state)
         await self._save_or_drop_session(session, normalized_id)
         if device is None:
+            # 离线原因已经写进 access token；family 吊销只作废 refresh，不能再
+            # logout 把记录删掉，否则客户端会看到 INVALID_TOKEN。
             await self._manager.refresh_tokens.revoke_all_for_login(
-                self.login_type, normalized_id
+                self.login_type, normalized_id, logout_access=False
             )
         if offline_count:
             await self._emit(event, login_id=normalized_id, device=device)

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/src/sa_token/stp_util.py

@@ -29,6 +29,9 @@ def set_manager(manager: SaTokenManager) -> None:
     """设置全局 Manager，一般由 ``SaTokenBuilder.build()`` 自动调用。"""
     global _manager
     _manager = manager
+    from .banner import emit_banner
+
+    emit_banner(manager)
 
 
 def get_manager() -> SaTokenManager:

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/tests/conftest.py

@@ -3,10 +3,18 @@ from __future__ import annotations
 import pytest
 
 from sa_token import SaToken, SaTokenManager
+from sa_token.banner import reset_banner_state
 from sa_token.storage import MemoryStorage
 from sa_token.stp_util import clear_manager
 
 
+@pytest.fixture(autouse=True)
+def _isolate_banner():
+    reset_banner_state()
+    yield
+    reset_banner_state()
+
+
 @pytest.fixture
 def build_manager():
     """返回一个构建 Manager 的工厂，测试之间互不干扰。"""
@@ -22,6 +30,7 @@ def build_manager():
 
     yield _build
     clear_manager()
+    reset_banner_state()
 
 
 @pytest.fixture

sa_token_python_core-0.1.4/tests/test_banner.py

@@ -0,0 +1,106 @@
+"""启动横幅：默认打印一次，可通过配置关闭。"""
+
+from __future__ import annotations
+
+import pytest
+
+from sa_token import SaToken, SaTokenConfig, SaTokenManager, __version__, set_manager
+from sa_token.banner import emit_configured_banner, reset_banner_state
+from sa_token.storage import MemoryStorage
+from sa_token.stp_util import clear_manager
+
+
+def test_build_prints_banner_by_default(capsys) -> None:
+    SaToken.builder().storage(MemoryStorage()).as_global(False).build()
+
+    output = capsys.readouterr().out
+    assert "sa-token-python" in output
+    assert f"(v{__version__})" in output
+    assert "MemoryStorage" in output
+    assert r"/ ___/____ _" in output
+
+
+def test_print_banner_false_silences_output(capsys) -> None:
+    SaToken.builder().storage(MemoryStorage()).print_banner(False).as_global(False).build()
+
+    assert capsys.readouterr().out == ""
+
+
+def test_set_option_can_disable_banner(capsys) -> None:
+    SaToken.builder().storage(MemoryStorage()).set_option(is_print_banner=False).as_global(
+        False
+    ).build()
+
+    assert capsys.readouterr().out == ""
+
+
+def test_banner_prints_only_once(capsys) -> None:
+    manager = SaToken.builder().storage(MemoryStorage()).as_global(False).build()
+    capsys.readouterr()
+
+    manager.print_banner()
+    assert "sa-token-python" in capsys.readouterr().out
+
+    set_manager(manager)
+    emit_configured_banner()
+    assert capsys.readouterr().out == ""
+
+
+def test_direct_manager_construction_prints(capsys) -> None:
+    SaTokenManager(SaTokenConfig(), MemoryStorage())
+
+    output = capsys.readouterr().out
+    assert "sa-token-python" in output
+
+
+def test_emit_configured_banner_without_manager_is_silent(capsys) -> None:
+    clear_manager()
+    emit_configured_banner()
+    assert capsys.readouterr().out == ""
+
+
+def test_reset_allows_reprint(capsys) -> None:
+    SaToken.builder().storage(MemoryStorage()).as_global(False).build()
+    assert "sa-token-python" in capsys.readouterr().out
+
+    reset_banner_state()
+    SaToken.builder().storage(MemoryStorage()).as_global(False).build()
+    assert "sa-token-python" in capsys.readouterr().out
+
+
+def test_fastapi_startup_prints_banner(capsys) -> None:
+    pytest.importorskip("fastapi")
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    from sa_token.integration.fastapi import SaTokenMiddleware
+
+    manager = SaToken.builder().storage(MemoryStorage()).print_banner(False).build()
+    manager.config.is_print_banner = True
+    reset_banner_state()
+
+    app = FastAPI()
+    app.add_middleware(SaTokenMiddleware)
+    with TestClient(app):
+        pass
+
+    output = capsys.readouterr().out
+    assert "sa-token-python" in output
+    assert "MemoryStorage" in output
+
+
+def test_flask_init_prints_banner(capsys) -> None:
+    pytest.importorskip("flask")
+    from flask import Flask
+
+    from sa_token.integration.flask import SaTokenFlask
+
+    SaToken.builder().storage(MemoryStorage()).build()
+    capsys.readouterr()
+    reset_banner_state()
+
+    app = Flask(__name__)
+    SaTokenFlask(app)
+
+    output = capsys.readouterr().out
+    assert "sa-token-python" in output

{sa_token_python_core-0.1.2 → sa_token_python_core-0.1.4}/tests/test_security.py

@@ -112,3 +112,37 @@ async def test_kickout_revokes_refresh_family(stp, manager) -> None:
     await stp.kickout("10001")
     with pytest.raises(SecurityException):
         await manager.refresh_tokens.refresh(pair.refresh_token)
+
+
+async def test_kickout_after_refresh_login_keeps_kick_out_reason(stp, manager) -> None:
+    pair = await stp.login_with_refresh("10001")
+    await stp.kickout("10001")
+
+    with pytest.raises(NotLoginException) as error:
+        await stp.check_login(pair.access_token)
+    assert error.value.type is NotLoginType.KICK_OUT
+
+    reason = await stp.get_offline_reason(pair.access_token)
+    assert reason is not None
+    assert reason["reason"] == "KICK_OUT"
+
+    with pytest.raises(SecurityException):
+        await manager.refresh_tokens.refresh(pair.refresh_token)
+
+
+async def test_replaced_after_refresh_login_keeps_replaced_reason(stp) -> None:
+    pair = await stp.login_with_refresh("10001")
+    await stp.replaced("10001")
+
+    with pytest.raises(NotLoginException) as error:
+        await stp.check_login(pair.access_token)
+    assert error.value.type is NotLoginType.BE_REPLACED
+
+
+async def test_kickout_by_token_after_refresh_login_keeps_kick_out_reason(stp) -> None:
+    pair = await stp.login_with_refresh("10001")
+    await stp.kickout_by_token(pair.access_token)
+
+    with pytest.raises(NotLoginException) as error:
+        await stp.check_login(pair.access_token)
+    assert error.value.type is NotLoginType.KICK_OUT