seerapi 103.2.0__py3-none-any.whl

seerapi/_model_map.py

@@ -0,0 +1,60 @@
+import seerapi_models as M
+
+from seerapi._typing import ModelName, ModelType
+
+MODEL_MAP: dict[ModelName, ModelType] = {
+    'achievement': M.Achievement,
+    'achievement_branch': M.AchievementBranch,
+    'achievement_category': M.AchievementCategory,
+    'achievement_type': M.AchievementType,
+    'title': M.Title,
+    'battle_effect': M.BattleEffect,
+    'battle_effect_type': M.BattleEffectCategory,
+    'pet_effect': M.PetEffect,
+    'pet_effect_group': M.PetEffectGroup,
+    'pet_variation': M.VariationEffect,
+    'energy_bead': M.EnergyBead,
+    'equip': M.Equip,
+    'suit': M.Suit,
+    'equip_type': M.EquipType,
+    'equip_effective_occasion': M.EquipEffectiveOccasion,
+    'soulmark': M.Soulmark,
+    'soulmark_tag': M.SoulmarkTagCategory,
+    'element_type': M.ElementType,
+    'element_type_combination': M.TypeCombination,
+    'item': M.Item,
+    'item_category': M.ItemCategory,
+    'gem': M.Gem,
+    'gem_category': M.GemCategory,
+    'gem_generation_category': M.GemGenCategory,
+    'skill_activation_item': M.SkillActivationItem,
+    'skill_stone': M.SkillStone,
+    'skill_stone_category': M.SkillStoneCategory,
+    'mintmark': M.Mintmark,
+    'ability_mintmark': M.AbilityMintmark,
+    'skill_mintmark': M.SkillMintmark,
+    'universal_mintmark': M.UniversalMintmark,
+    'mintmark_class': M.MintmarkClassCategory,
+    'mintmark_type': M.MintmarkTypeCategory,
+    'mintmark_rarity': M.MintmarkRarityCategory,
+    'pet': M.Pet,
+    'pet_class': M.PetClass,
+    'pet_gender': M.PetGenderCategory,
+    'pet_vipbuff': M.PetVipBuffCategory,
+    'pet_mount_type': M.PetMountTypeCategory,
+    'pet_skin': M.PetSkin,
+    'pet_skin_category': M.PetSkinCategory,
+    'pet_archive_story_entry': M.PetArchiveStoryEntry,
+    'pet_archive_story_book': M.PetArchiveStoryBook,
+    'pet_encyclopedia_entry': M.PetEncyclopediaEntry,
+    'peak_pool': M.PeakPool,
+    'peak_expert_pool': M.PeakExpertPool,
+    'nature': M.Nature,
+    'skill': M.Skill,
+    'skill_effect_type': M.SkillEffectType,
+    'skill_effect_param': M.SkillEffectParam,
+    'skill_hide_effect': M.SkillHideEffect,
+    'skill_category': M.SkillCategory,
+    'skill_effect_type_tag': M.SkillEffectTypeTag,
+    'eid_effect': M.EidEffect,
+}

seerapi/_models.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass, field
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+
+
+@dataclass
+class PageInfo:
+    offset: int = field(default=0)
+    limit: int = field(default=100)
+
+    def __post_init__(self) -> None:
+        if self.offset < 0:
+            raise ValueError('offset must be greater than or equal to 0')
+        if self.limit < 0:
+            raise ValueError('limit must be greater than or equal to 0')
+
+
+@dataclass
+class PagedResponse(Generic[T]):
+    results: AsyncGenerator[T, None]
+    count: int
+    next: PageInfo | None = None
+    previous: PageInfo | None = None
+    first: PageInfo | None = None
+    last: PageInfo | None = None

seerapi/_typing.py

@@ -0,0 +1,125 @@
+from typing import Literal, TypeAlias, TypeVar
+
+import seerapi_models as M
+from seerapi_models.build_model import BaseResModel
+from seerapi_models.common import ResourceRef
+
+NamedModelName: TypeAlias = Literal[
+    'achievement',
+    'achievement_branch',
+    'achievement_category',
+    'achievement_type',
+    'title',
+    'battle_effect',
+    'battle_effect_type',
+    'pet_effect',
+    'pet_effect_group',
+    'pet_variation',
+    'energy_bead',
+    'equip',
+    'suit',
+    'equip_type',
+    'soulmark_tag',
+    'element_type',
+    'element_type_combination',
+    'item',
+    'item_category',
+    'gem',
+    'gem_category',
+    'skill_activation_item',
+    'skill_stone',
+    'skill_stone_category',
+    'mintmark',
+    'ability_mintmark',
+    'skill_mintmark',
+    'universal_mintmark',
+    'mintmark_class',
+    'mintmark_type',
+    'pet',
+    'pet_gender',
+    'pet_vipbuff',
+    'pet_mount_type',
+    'pet_skin',
+    'pet_archive_story_book',
+    'pet_encyclopedia_entry',
+    'nature',
+    'skill',
+    'skill_hide_effect',
+    'skill_category',
+    'skill_effect_type_tag',
+    'soulmark',
+]
+
+# 所有可用的模型路径名称
+ModelName: TypeAlias = Literal[
+    NamedModelName,
+    'equip_effective_occasion',
+    'gem_generation_category',
+    'mintmark_rarity',
+    'pet_class',
+    'pet_skin_category',
+    'pet_archive_story_entry',
+    'skill_effect_type',
+    'skill_effect_param',
+    'eid_effect',
+    'peak_pool',
+    'peak_expert_pool',
+]
+
+ModelInstance: TypeAlias = BaseResModel
+NamedModelInstance: TypeAlias = (
+    M.Achievement
+    | M.AchievementBranch
+    | M.AchievementCategory
+    | M.AchievementType
+    | M.Title
+    | M.BattleEffect
+    | M.BattleEffectCategory
+    | M.PetEffect
+    | M.PetEffectGroup
+    | M.VariationEffect
+    | M.EnergyBead
+    | M.Equip
+    | M.Suit
+    | M.EquipType
+    | M.SoulmarkTagCategory
+    | M.ElementType
+    | M.TypeCombination
+    | M.Item
+    | M.ItemCategory
+    | M.Gem
+    | M.GemCategory
+    | M.SkillActivationItem
+    | M.SkillStone
+    | M.SkillStoneCategory
+    | M.Soulmark
+    | M.Mintmark
+    | M.AbilityMintmark
+    | M.SkillMintmark
+    | M.UniversalMintmark
+    | M.MintmarkClassCategory
+    | M.MintmarkTypeCategory
+    | M.Pet
+    | M.PetGenderCategory
+    | M.PetVipBuffCategory
+    | M.PetMountTypeCategory
+    | M.PetSkin
+    | M.PetArchiveStoryBook
+    | M.PetEncyclopediaEntry
+    | M.Nature
+    | M.Skill
+    | M.SkillHideEffect
+    | M.SkillCategory
+    | M.SkillEffectTypeTag
+)
+ModelType: TypeAlias = type[ModelInstance]
+
+T_ModelInstance = TypeVar('T_ModelInstance', bound=ModelInstance)
+T_NamedModelInstance = TypeVar('T_NamedModelInstance', bound=NamedModelInstance)
+
+ResourceArg: TypeAlias = (
+    ModelName | type[T_ModelInstance] | ResourceRef[T_ModelInstance]
+)
+NamedResourceArg: TypeAlias = (
+    NamedModelName | type[T_NamedModelInstance] | ResourceRef[T_NamedModelInstance]
+)

seerapi-103.2.0.dist-info/METADATA

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: seerapi
+Version: 103.2.0
+Summary: SeerAPI Python Client
+Author-email: Nattsu39 <Nattsu39@outlook.com>
+License: MIT License
+        
+        Copyright (c) 2025 SeerAPI
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/SeerAPI/seerapi-python
+Project-URL: Repository, https://github.com/SeerAPI/seerapi-python
+Keywords: seerapi,client
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hishel[httpx]>=1.1.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: seerapi-models<104.0.0,>=103.2.0
+Requires-Dist: typing-extensions>=4.15.0
+Dynamic: license-file
+
+# SeerAPI Python 客户端
+
+[SeerAPI](https://github.com/SeerAPI) 是一个提供赛尔号游戏数据的开放 API 平台。本项目是 SeerAPI 的官方 Python 客户端库，提供了简洁易用的异步接口，支持获取精灵、技能、装备、刻印等 50+ 种游戏资源数据。
+
+## 特性
+
+- 🚀 **异步优先**：基于 `httpx` 和 `hishel` 构建，提供高性能的异步 HTTP 请求
+- 💾 **自动缓存**：集成 HTTP 缓存机制，减少重复请求
+- 🎯 **类型安全**：完整的类型提示支持，提供良好的 IDE 智能提示
+- 📦 **分页支持**：内置分页处理，方便获取大量数据
+- 🔄 **同步兼容**：提供 `async_to_sync` 装饰器，在同步代码中也能使用
+## 安装
+
+使用 pip 安装：
+
+```bash
+pip install seerapi
+```
+
+或使用 uv：
+
+```bash
+uv add seerapi
+```
+
+## 快速开始
+
+### 异步使用方式
+
+```python
+import asyncio
+from seerapi import SeerAPI, PageInfo
+
+async def main():
+    # 使用异步上下文管理器，自动管理连接
+    async with SeerAPI() as client:
+        # 获取单个精灵信息
+        pet = await client.get('pet', id=1)
+        print(f"精灵名称: {pet.name}")
+        
+        # 获取所有精灵（自动分页）
+        count = 0
+        async for pet in client.list('pet'):
+            print(f"ID: {pet.id}, 名称: {pet.name}")
+            count += 1
+            if count >= 10:  # 只显示前 10 个
+                break
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### 同步使用方式
+
+如果你需要在同步代码中使用，可以使用 `async_to_sync` 装饰器：
+
+```python
+from seerapi import SeerAPI, PageInfo, async_to_sync
+
+@async_to_sync
+async def get_pet_info(pet_id: int):
+    async with SeerAPI() as client:
+        pet = await client.get('pet', id=pet_id)
+        return pet
+
+# 像普通同步函数一样调用
+pet = get_pet_info(1)
+print(pet.name)
+```
+
+## API 文档
+
+### SeerAPI 客户端
+
+#### 初始化
+
+```python
+from seerapi import SeerAPI
+
+# 使用默认配置（指向官方 API）
+client = SeerAPI()
+
+# 自定义配置
+client = SeerAPI(
+    scheme='https',
+    hostname='api.seerapi.com',
+    version_path='v1'
+)
+```
+
+#### 方法
+
+##### `get(resource_name, id)`
+
+获取单个资源的详细信息。
+
+**参数：**
+- `resource_name` (str): 资源类型名称
+- `id` (int): 资源 ID
+
+**返回：**
+- 对应的模型实例
+
+**示例：**
+
+```python
+# 获取精灵信息
+pet = await client.get('pet', id=1)
+
+# 获取技能信息
+skill = await client.get('skill', id=100)
+
+# 获取装备信息
+equip = await client.get('equip', id=50)
+```
+
+##### `list(resource_name)`
+
+获取所有资源的异步生成器，自动处理分页。
+
+**参数：**
+- `resource_name` (str): 资源类型名称
+
+**返回：**
+- `AsyncGenerator`: 异步生成器，用于遍历所有资源
+
+**示例：**
+
+```python
+# 遍历所有精灵
+async for pet in client.list('pet'):
+    print(pet.name)
+
+# 只获取前 100 个
+count = 0
+async for pet in client.list('pet'):
+    print(pet.name)
+    count += 1
+    if count >= 100:
+        break
+```
+
+##### `paginated_list(resource_name, page_info)`
+
+获取资源列表（手动分页控制）。
+
+**参数：**
+- `resource_name` (str): 资源类型名称
+- `page_info` (PageInfo): 分页信息对象
+
+**返回：**
+- `PagedResponse` 对象，包含：
+  - `count` (int): 总记录数
+  - `results` (AsyncGenerator): 异步生成器，用于遍历当前页结果
+  - `next` (PageInfo | None): 下一页信息
+  - `previous` (PageInfo | None): 上一页信息
+  - `first` (PageInfo | None): 首页信息
+  - `last` (PageInfo | None): 末页信息
+
+**示例：**
+
+```python
+from seerapi import PageInfo
+
+# 获取前 20 条记录
+page_info = PageInfo(offset=0, limit=20)
+response = await client.paginated_list('pet', page_info)
+
+# 查看总数
+print(f"总数: {response.count}")
+
+# 遍历当前页的结果
+async for pet in response.results:
+    print(pet.name)
+
+# 获取下一页
+if response.next:
+    next_response = await client.paginated_list('pet', response.next)
+```
+
+##### `get_by_name(resource_name, name)`
+
+通过名称获取资源。该方法仅支持具有名称属性的资源类型。
+
+**参数：**
+- `resource_name` (str): 资源类型名称（必须是支持按名称查询的资源类型）
+- `name` (str): 资源名称
+
+**返回：**
+- `NamedData` 对象，包含：
+  - `data[int, named_model_instance]`: 同名的模型实例字典，key 为 ID，value 为模型实例
+
+**示例：**
+
+```python
+# 通过名称获取技能
+    async with SeerAPI() as client:
+        skills = await client.get_by_name('skill', '虚妄幻境') # 有三个技能都叫虚妄幻境
+        for id, skill in skills.data.items():
+            print(id)
+            print(skill.skill_effect)
+
+```
+### PageInfo 类
+
+用于指定分页参数。
+
+**属性：**
+- `offset` (int): 偏移量，默认为 0
+- `limit` (int): 每页记录数，默认为 100
+
+**示例：**
+
+```python
+from seerapi import PageInfo
+
+# 获取第 1-10 条记录
+page1 = PageInfo(offset=0, limit=10)
+
+# 获取第 11-20 条记录
+page2 = PageInfo(offset=10, limit=10)
+
+# 获取第 21-30 条记录
+page3 = PageInfo(offset=20, limit=10)
+```
+
+### async_to_sync 装饰器
+
+将异步函数转换为同步函数的装饰器。
+
+**示例：**
+
+```python
+from seerapi import async_to_sync, SeerAPI
+
+@async_to_sync
+async def fetch_pet_list(limit: int = 10):
+    async with SeerAPI() as client:
+        pets = []
+        count = 0
+        async for pet in client.list('pet'):
+            pets.append(pet)
+            count += 1
+            if count >= limit:
+                break
+        return pets
+
+# 同步调用
+pets = fetch_pet_list(limit=5)
+for pet in pets:
+    print(pet.name)
+```
+
+## 错误处理
+
+```python
+import asyncio
+from httpx import HTTPStatusError
+from seerapi import SeerAPI
+
+async def safe_get_pet(pet_id: int):
+    async with SeerAPI() as client:
+        try:
+            pet = await client.get('pet', id=pet_id)
+            return pet
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                print(f"精灵 ID {pet_id} 不存在")
+            else:
+                print(f"HTTP 错误: {e.response.status_code}")
+            return None
+        except Exception as e:
+            print(f"发生错误: {e}")
+            return None
+
+asyncio.run(safe_get_pet(999999))
+```
+
+## 开发环境设置
+
+### 环境要求
+
+- Python >= 3.10
+- uv（推荐）或 pip
+
+### 安装开发依赖
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-org/seerapi-python.git
+cd seerapi-python
+
+# 使用 uv 安装依赖（推荐）
+uv sync
+
+# 或使用 pip
+pip install -e .
+```
+
+### 代码风格
+
+项目使用 Ruff 进行代码格式化和检查：
+
+```bash
+# 格式化代码
+ruff format .
+
+# 检查代码
+ruff check .
+
+# 自动修复问题
+ruff check --fix .
+```
+
+### 类型检查
+
+项目使用 Pyright 进行类型检查：
+
+## 依赖项
+
+- [httpx](https://www.python-httpx.org/) - 现代化的 HTTP 客户端
+- [hishel](https://hishel.com/) - HTTP 缓存库
+- [seerapi-models](https://github.com/SeerAPI/seerapi-models) - SeerAPI 数据模型
+
+## 许可证
+
+本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

seerapi-103.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+seerapi/__init__.py,sha256=oP4s_fhv48V6PnHnOA0VuQ9YIsSjMxAs0E2fgTF00gs,1869
+seerapi/_client.py,sha256=m43ISsdfVyuwV4B2WhHBLk9Or4v_UrY-li_7zvWAvhs,5606
+seerapi/_client.pyi,sha256=9mFaaIZtwctzbX6SetxMuyEwYjmxZiK2SKkywpuGJi0,31442
+seerapi/_model_map.py,sha256=clqSMCBUKGYTY81ZauER59X5NvLEWB9BJExV9KITz20,2210
+seerapi/_models.py,sha256=fubjnRAZDxwuJl2JSUDQe_nLR0XAHAGJ9-b_vBgCJdg,713
+seerapi/_typing.py,sha256=KAj_odULHSC062ZnracbZGvpLJcdrEdWOgjopUS0wjU,2883
+seerapi-103.2.0.dist-info/licenses/LICENSE,sha256=4tEK_JQJu8HGOJCCahAO8SlqOjMaNqvXo6hO92aqTew,1064
+seerapi-103.2.0.dist-info/METADATA,sha256=ppHNOuVSP2j06-ojE66b1aOYfFSFHyG7SwBzEszzUGw,9401
+seerapi-103.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+seerapi-103.2.0.dist-info/top_level.txt,sha256=GpG2Z0LTRIfLCHgYzyFT-idDu4FqvPhNw77DGBg-Q00,8
+seerapi-103.2.0.dist-info/RECORD,,

seerapi-103.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

seerapi-103.2.0.dist-info/licenses/LICENSE

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

seerapi-103.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+seerapi