maplestory-openapi 3.6.0__py3-none-any.whl

maplestory_openapi/__init__.py

@@ -0,0 +1,3 @@
+from .api import kms, msea, tms, common
+
+__all__ = ['kms', 'msea', 'tms', 'common']

maplestory_openapi/api/__init__.py

@@ -0,0 +1,3 @@
+from . import kms, msea, tms, common
+
+__all__ = ['kms', 'msea', 'tms', 'common']

maplestory_openapi/api/common/__init__.py

@@ -0,0 +1,6 @@
+from . import dto, enum, param
+from .maplestory_api import MapleStoryApi
+from .maplestory_friends_api import MapleStoryFriendsApi
+from .maplestory_api_error import MapleStoryApiError, MapleStoryApiException
+
+__all__ = ['dto', 'enum', 'param', 'MapleStoryApi', 'MapleStoryFriendsApi', 'MapleStoryApiError', 'MapleStoryApiException']

maplestory_openapi/api/common/enum/__init__.py

@@ -0,0 +1,3 @@
+from .character_image import CharacterImageAction, CharacterImageEmotion, CharacterImageWeaponMotion
+
+__all__ = ['CharacterImageAction', 'CharacterImageEmotion', 'CharacterImageWeaponMotion']

maplestory_openapi/api/common/enum/character_image.py

@@ -0,0 +1,89 @@
+from enum import Enum
+
+
+class CharacterImageAction(Enum):
+    """
+    Character action
+    """
+    Stand1 = 'A00'
+    Stand2 = 'A01'
+    Walk1 = 'A02'
+    Walk2 = 'A03'
+    Prone = 'A04'
+    Fly = 'A05'
+    Jump = 'A06'
+    Sit = 'A07'
+    Ladder = 'A08'
+    Rope = 'A09'
+    Heal = 'A10'
+    Alert = 'A11'
+    ProneStab = 'A12'
+    SwingO1 = 'A13'
+    SwingO2 = 'A14'
+    SwingO3 = 'A15'
+    SwingOF = 'A16'
+    SwingP1 = 'A17'
+    SwingP2 = 'A18'
+    SwingPF = 'A19'
+    SwingT1 = 'A20'
+    SwingT2 = 'A21'
+    SwingT3 = 'A22'
+    SwingTF = 'A23'
+    StabO1 = 'A24'
+    StabO2 = 'A25'
+    StabOF = 'A26'
+    StabT1 = 'A27'
+    StabT2 = 'A28'
+    StabTF = 'A29'
+    Shoot1 = 'A30'
+    Shoot2 = 'A31'
+    ShootF = 'A32'
+    Dead = 'A33'
+    GhostWalk = 'A34'
+    GhostStand = 'A35'
+    GhostJump = 'A36'
+    GhostProneStab = 'A37'
+    GhostLadder = 'A38'
+    GhostRope = 'A39'
+    GhostFly = 'A40'
+    GhostSit = 'A41'
+
+class CharacterImageEmotion(Enum):
+    """
+    Character emotion
+    """
+    Default = 'E00'
+    Wink = 'E01'
+    Smile = 'E02'
+    Cry = 'E03'
+    Angry = 'E04'
+    Bewildered = 'E05'
+    Blink = 'E06'
+    Blaze = 'E07'
+    Bowing = 'E08'
+    Cheers = 'E09'
+    Chu = 'E10'
+    Dam = 'E11'
+    Despair = 'E12'
+    Glitter = 'E13'
+    Hit = 'E14'
+    Hot = 'E15'
+    Hum = 'E16'
+    Love = 'E17'
+    Oops = 'E18'
+    Pain = 'E19'
+    Troubled = 'E20'
+    QBlue = 'E21'
+    Shine = 'E22'
+    Stunned = 'E23'
+    Vomit = 'E24'
+
+class CharacterImageWeaponMotion(Enum):
+    """
+    Character weapon motion
+    """
+    Default = 'W00'
+    OneHand = 'W01'
+    TwoHands = 'W02'
+    Gun = 'W03'
+    Nothing = 'W04'

maplestory_openapi/api/common/maplestory_api.py

@@ -0,0 +1,263 @@
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+from typing import Any
+from pydantic import BaseModel
+import httpx
+
+from maplestory_openapi.api.common.dto.character.character import Character
+from maplestory_openapi.api.common.dto.character.character_basic import CharacterBasic
+from maplestory_openapi.api.common.dto.character.character_popularity import CharacterPopularity
+from maplestory_openapi.api.common.dto.character.character_stat import CharacterStat
+from maplestory_openapi.api.common.dto.character.character_hyper_stat import CharacterHyperStat
+from maplestory_openapi.api.common.dto.character.character_propensity import CharacterPropensity
+from maplestory_openapi.api.common.dto.character.character_ability import CharacterAbility
+from maplestory_openapi.api.common.dto.character.character_item_equipment import CharacterItemEquipment
+from maplestory_openapi.api.common.dto.character.character_cashitem_equipment import CharacterCashitemEquipment
+from maplestory_openapi.api.common.dto.character.character_symbol_equipment import CharacterSymbolEquipment
+from maplestory_openapi.api.common.dto.character.character_set_effect import CharacterSetEffect
+from maplestory_openapi.api.common.dto.character.character_beauty_equipment import CharacterBeautyEquipment
+from maplestory_openapi.api.common.dto.character.character_android_equipment import CharacterAndroidEquipment
+from maplestory_openapi.api.common.dto.character.character_pet_equipment import CharacterPetEquipment
+from maplestory_openapi.api.common.dto.character.character_skill import CharacterSkill
+from maplestory_openapi.api.common.dto.character.character_link_skill import CharacterLinkSkill
+from maplestory_openapi.api.common.dto.character.character_vmatrix import CharacterVMatrix
+from maplestory_openapi.api.common.dto.character.character_hexamatrix import CharacterHexaMatrix
+from maplestory_openapi.api.common.dto.character.character_hexamatrix_stat import CharacterHexaMatrixStat
+from maplestory_openapi.api.common.dto.character.character_dojang import CharacterDojang
+from maplestory_openapi.api.common.dto.character.character_image import CharacterImage
+
+from maplestory_openapi.api.common.dto.union.union import Union
+from maplestory_openapi.api.common.dto.union.union_artifact import UnionArtifact
+from maplestory_openapi.api.common.dto.union.union_raider import UnionRaider
+
+from maplestory_openapi.api.common.dto.guild.guild import Guild
+from maplestory_openapi.api.common.dto.guild.guild_basic import GuildBasic
+
+from maplestory_openapi.api.common.maplestory_api_error import MapleStoryApiError, MapleStoryApiException
+
+from maplestory_openapi.api.common.param.character_image_option import CharacterImageOption
+
+
+class MapleStoryApi(ABC, BaseModel):
+    api_key: str
+    BASE_URL: str = 'https://open.api.nexon.com/'
+    timeout: int
+    timezone: str
+    sub_url: str
+
+    def __init__(self, api_key: str, timezone: str, sub_url: str, timeout:int):
+        super().__init__(
+            api_key=api_key,
+            timezone=timezone,
+            sub_url=sub_url,
+            timeout=timeout,
+        )
+
+    #region Character Information Retrieval
+
+    @abstractmethod
+    async def get_character_id(self, character_name: str) -> Character:
+        pass
+
+    @abstractmethod
+    async def get_character_basic(self, ocid: str, date: datetime | None = None) -> CharacterBasic | None:
+        pass
+
+    @abstractmethod
+    async def get_character_image(self, ocid: str, option: CharacterImageOption | None = None, date: datetime | None = None) -> CharacterImage | None:
+        pass
+
+    @abstractmethod
+    async def get_character_popularity(self, ocid: str, date: datetime | None = None) -> CharacterPopularity | None:
+        pass
+
+    @abstractmethod
+    async def get_character_stat(self, ocid: str, date: datetime | None = None) -> CharacterStat | None:
+        pass
+
+    @abstractmethod
+    async def get_character_hyper_stat(self, ocid: str, date: datetime | None = None) -> CharacterHyperStat | None:
+        pass
+
+    @abstractmethod
+    async def get_character_propensity(self, ocid: str, date: datetime | None = None) -> CharacterPropensity | None:
+        pass
+
+    @abstractmethod
+    async def get_character_ability(self, ocid: str, date: datetime | None = None) -> CharacterAbility | None:
+        pass
+
+    @abstractmethod
+    async def get_character_item_equipment(self, ocid: str, date: datetime | None = None) -> CharacterItemEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_cashitem_equipment(self, ocid: str, date: datetime | None = None) -> CharacterCashitemEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_symbol_equipment(self, ocid: str, date: datetime | None = None) -> CharacterSymbolEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_set_effect(self, ocid: str, date: datetime | None = None) -> CharacterSetEffect | None:
+        pass
+
+    @abstractmethod
+    async def get_character_beauty_equipment(self, ocid: str, date: datetime | None = None) -> CharacterBeautyEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_android_equipment(self, ocid: str, date: datetime | None = None) -> CharacterAndroidEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_pet_equipment(self, ocid: str, date: datetime | None = None) -> CharacterPetEquipment | None:
+        pass
+
+    @abstractmethod
+    async def get_character_skill(self, ocid: str, character_skill_grade: str, date: datetime | None = None) -> CharacterSkill | None:
+        pass
+
+    @abstractmethod
+    async def get_character_link_skill(self, ocid: str, date: datetime | None = None) -> CharacterLinkSkill | None:
+        pass
+
+    @abstractmethod
+    async def get_character_vmatrix(self, ocid: str, date: datetime | None = None) -> CharacterVMatrix | None:
+        pass
+
+    @abstractmethod
+    async def get_character_hexamatrix(self, ocid: str, date: datetime | None = None) -> CharacterHexaMatrix | None:
+        pass
+
+    @abstractmethod
+    async def get_character_hexamatrix_stat(self, ocid: str, date: datetime | None = None) -> CharacterHexaMatrixStat | None:
+        pass
+
+    @abstractmethod
+    async def get_character_dojang(self, ocid: str, date: datetime | None = None) -> CharacterDojang | None:
+        pass
+
+    #endregion
+
+    #region Union Information Retrieval
+
+    @abstractmethod
+    async def get_union(self, ocid: str, date: datetime | None = None) -> Union | None:
+        pass
+
+    @abstractmethod
+    async def get_union_raider(self, ocid: str, date: datetime | None = None) -> UnionRaider | None:
+        pass
+
+    @abstractmethod
+    async def get_union_artifact(self, ocid: str, date: datetime | None = None) -> UnionArtifact | None:
+        pass
+
+    #endregion
+
+    #region Guild Information Retrieval
+
+    @abstractmethod
+    async def get_guild_id(self, guild_name: str, world_name: str) -> Guild | None:
+        pass
+
+    @abstractmethod
+    async def get_guild_basic(self, oguid_id: str, date: datetime | None = None) -> GuildBasic | None:
+        pass
+
+    #endregion
+
+    async def fetch(self, path: str, query: dict) -> Any:
+
+        params = {key: value for key, value in query.items() if value is not None}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f'{self.BASE_URL}{path}',
+                params=params,
+                headers={
+                    'x-nxopen-api-key': self.api_key,
+                },
+            )
+
+        r = response.json()
+
+        if (r.get('error')):
+            raise MapleStoryApiException(MapleStoryApiError(**r.get('error')))
+
+        return r
+
+    def _is_empty_response(self, response: dict) -> bool:
+        """
+        API 응답 데이터가 비어있는지 확인 합니다.
+        API 요청 시 날짜에 해당하는 데이터가 없을 경우 date 필드만 값이 존재하는 상황을 검증할 때 사용 합니다.
+        일반적으로 API 지원 시작일과 캐릭터 생성일 사이의 날짜를 조회할 때 발생 합니다.
+        """
+        for key, value in response.items():
+            if key == 'date':
+                continue
+            if value is None:
+                continue
+            if isinstance(value, list) and len(value) == 0:
+                continue
+            return False
+        return True
+
+    def _to_date_string(self, date: datetime, min: datetime | None = None) -> str:
+        """
+        날짜 정보를 API 서버에서 요구하는 포맷으로 변환합니다.
+
+        Args:
+            date (datetime): 조회 하려는 날짜
+            min (datetime or None): API 호출 가능한 최소 날짜
+        """
+
+        target_date = self.__get_datetime(date)
+        date_str = target_date.strftime('%Y-%m-%d')
+
+        if min is not None:
+            min_date = self.__get_datetime(min)
+            if target_date < min_date:
+                raise ValueError(
+                    f'You can only retrieve data after {min_date.strftime("%Y-%m-%d")}')
+
+        return date_str
+
+    def __get_datetime(self, date: datetime) -> datetime:
+        """
+        datetime 객체를 timezone이 지정된 datetime 객체로 변환합니다.
+
+        datetime.astimezone()을 사용하면 지역에 따라 다른 결과가 나오고 date.replace()에도 버그가 존재하므로 datetime으로 재설정합니다.
+        """
+        return datetime(year=date.year, month=date.month, day=date.day, tzinfo=ZoneInfo(self.timezone))
+
+    def _get_proper_default_datetime(self, day_offset: int, update_hour: int = 0, update_minute: int = 0) -> datetime:
+        """
+        API 서버의 데이터 갱신 시간에 따라 데이터가 조회 가능한 최신 날짜를 반환합니다.
+
+        Args:
+            day_offset(int): 갱신시간에 갱신되는 데이터가 오늘인지 어제인지에 따라 숫자를 지정합니다 (0: 오늘, 1: 어제)
+            update_hour(int): 갱신 시간의 시간을 지정합니다
+            update_minute(int): 갱신 시간의 분을 지정합니다
+        """
+        now = datetime.now(
+            tz=ZoneInfo(self.timezone))
+        update_time = datetime(
+            year=now.year,
+            month=now.month,
+            day=now.day,
+            hour=update_hour,
+            minute=update_minute,
+            tzinfo=ZoneInfo(self.timezone))
+
+        adjusted_time: datetime
+
+        if now > update_time:
+            adjusted_time = update_time - timedelta(days=day_offset)
+        else:
+            adjusted_time = update_time - timedelta(days=day_offset + 1)
+
+        return adjusted_time

maplestory_openapi/api/common/maplestory_api_error.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+
+
+class MapleStoryApiError(BaseModel):
+    name: str
+    message: str
+
+
+class MapleStoryApiException(Exception):
+    """
+    MapleStory API Exception
+
+    https://openapi.nexon.com/guide/request-api/#error-code-table
+    """
+
+    def __init__(self, error: MapleStoryApiError) -> None:
+        self.error_code = error.name
+        self.message = error.message
+        super().__init__(error.message)

maplestory_openapi/api/common/maplestory_friends_api.py

@@ -0,0 +1,99 @@
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+from typing import Any
+from pydantic import BaseModel
+import httpx
+
+from maplestory_openapi.api.common.maplestory_api_error import MapleStoryApiError, MapleStoryApiException
+
+class MapleStoryFriendsApi(ABC, BaseModel):
+    access_token: str
+    BASE_URL: str = 'https://open.api.nexon.com/'
+    timeout: int
+    timezone: str
+    sub_url: str
+
+    def __init__(self, access_token: str, timezone: str, sub_url: str, timeout: int):
+        super().__init__(
+            access_token=access_token,
+            timezone=timezone,
+            sub_url=sub_url,
+            timeout=timeout,
+        )
+
+    async def fetch(self, path: str, query: dict) -> Any:
+
+        params = {key: value for key, value in query.items() if value is not None}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f'{self.BASE_URL}{path}',
+                params=params,
+                headers={
+                    'Authorization': f'Bearer {self.access_token}',
+                },
+            )
+
+        r = response.json()
+
+        if (r.get('error')):
+            raise MapleStoryApiException(MapleStoryApiError(**r.get('error')))
+
+        return r
+
+    def _to_date_string(self, date: datetime, min: datetime | None = None) -> str:
+        """
+        날짜 정보를 API 서버에서 요구하는 포맷으로 변환합니다.
+
+        Args:
+            date (datetime): 조회 하려는 날짜
+            min (datetime or None): API 호출 가능한 최소 날짜
+        """
+
+        target_date = self.__get_datetime(date)
+        date_str = target_date.strftime('%Y-%m-%d')
+
+        if min is not None:
+            min_date = self.__get_datetime(min)
+            if target_date < min_date:
+                raise ValueError(
+                    f'You can only retrieve data after {min_date.strftime("%Y-%m-%d")}')
+
+        return date_str
+
+    def __get_datetime(self, date: datetime) -> datetime:
+        """
+        datetime 객체를 timezone이 지정된 datetime 객체로 변환합니다.
+
+        datetime.astimezone()을 사용하면 지역에 따라 다른 결과가 나오고 date.replace()에도 버그가 존재하므로 datetime으로 재설정합니다.
+        """
+        return datetime(year=date.year, month=date.month, day=date.day, tzinfo=ZoneInfo(self.timezone))
+
+    def _get_proper_default_datetime(self, day_offset: int, update_hour: int = 0, update_minute: int = 0) -> datetime:
+        """
+        API 서버의 데이터 갱신 시간에 따라 데이터가 조회 가능한 최신 날짜를 반환합니다.
+
+        Args:
+            day_offset(int): 갱신시간에 갱신되는 데이터가 오늘인지 어제인지에 따라 숫자를 지정합니다 (0: 오늘, 1: 어제)
+            update_hour(int): 갱신 시간의 시간을 지정합니다
+            update_minute(int): 갱신 시간의 분을 지정합니다
+        """
+        now = datetime.now(
+            tz=ZoneInfo(self.timezone))
+        update_time = datetime(
+            year=now.year,
+            month=now.month,
+            day=now.day,
+            hour=update_hour,
+            minute=update_minute,
+            tzinfo=ZoneInfo(self.timezone))
+
+        adjusted_time: datetime
+
+        if now > update_time:
+            adjusted_time = update_time - timedelta(days=day_offset)
+        else:
+            adjusted_time = update_time - timedelta(days=day_offset + 1)
+
+        return adjusted_time

maplestory_openapi/api/common/param/__init__.py

@@ -0,0 +1,3 @@
+from .character_image_option import CharacterImageOption
+
+__all__ = ['CharacterImageOption']

maplestory_openapi/api/common/param/character_image_option.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+
+from maplestory_openapi.api.common.enum.character_image import CharacterImageAction, CharacterImageEmotion, CharacterImageWeaponMotion
+
+
+class CharacterImageOption(BaseModel):
+    action: CharacterImageAction
+    emotion: CharacterImageEmotion
+    wmotion: CharacterImageWeaponMotion
+    action_frame: int
+    emotion_frame: int

maplestory_openapi/api/kms/__init__.py

@@ -0,0 +1,5 @@
+from . import dto
+from .maplestory_api import MapleStoryApi
+from .maplestory_friends_api import MapleStoryFriendsApi
+
+__all__ = ['dto', 'MapleStoryApi', 'MapleStoryFriendsApi']

maplestory_openapi/api/kms/dto/character/character.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+from maplestory_openapi.api.common.dto.character.character import Character as BaseCharacter
+
+
+class Character(BaseModel, BaseCharacter):
+    """
+   캐릭터 식별자(ocid)
+
+    Attributes:
+        ocid (str): 캐릭터 식별자
+    """
+    ocid: str

maplestory_openapi/api/kms/dto/character/character_ability.py

@@ -0,0 +1,70 @@
+from datetime import datetime
+from pydantic import BaseModel, field_validator
+
+from maplestory_openapi.api.common.dto.character.character_ability import CharacterAbilityInfo as BaseCharacterAbilityInfo
+from maplestory_openapi.api.common.dto.character.character_ability import CharacterAbilityPreset as BaseCharacterAbilityPreset
+from maplestory_openapi.api.common.dto.character.character_ability import CharacterAbility as BaseCharacterAbility
+
+
+class CharacterAbilityInfo(BaseModel, BaseCharacterAbilityInfo):
+    """
+    캐릭터 어빌리티 상세 정보
+
+    Attributes:
+        ability_no (str): 어빌리티 번호
+        ability_grade (str): 어빌리티 등급
+        ability_value (str): 어빌리티 값
+    """
+    ability_no: str
+    ability_grade: str
+    ability_value: str
+
+
+class CharacterAbilityPreset(BaseModel, BaseCharacterAbilityPreset):
+    """
+    캐릭터 어빌리티 프리셋 정보
+
+    Attributes:
+        ability_preset_grade (str): 프리셋의 어빌리티 등급
+        ability_info (list[CharacterAbilityInfo]): 프리셋의 어빌리티 정보
+    """
+    ability_preset_grade: str
+    ability_info: list[CharacterAbilityInfo]
+
+    @field_validator("ability_info", mode="before")
+    @classmethod
+    def null_as_empty(cls, v):
+        if v is None:
+            return []
+        return v
+
+
+class CharacterAbility(BaseModel, BaseCharacterAbility):
+    """
+    캐릭터 어빌리티 정보
+
+    Attributes:
+        date (datetime or None): 조회 기준일 (KST, 일 단위 데이터로 시, 분은 일괄 0으로 표기)
+        ability_grade (str): 어빌리티 등급
+        ability_info (list[CharacterAbilityInfo]): 어빌리티 정보
+        remain_fame (int): 보유 명성치
+        preset_no (int or None): 적용 중인 어빌리티 프리셋 번호
+        ability_preset_1 (CharacterAbilityPreset or None): 어빌리티 1번 프리셋 전체 정보
+        ability_preset_2 (CharacterAbilityPreset or None): 어빌리티 2번 프리셋 전체 정보
+        ability_preset_3 (CharacterAbilityPreset or None): 어빌리티 3번 프리셋 전체 정보
+    """
+    date: datetime | None
+    ability_grade: str
+    ability_info: list[CharacterAbilityInfo]
+    remain_fame: int
+    preset_no: int | None
+    ability_preset_1: CharacterAbilityPreset | None
+    ability_preset_2: CharacterAbilityPreset | None
+    ability_preset_3: CharacterAbilityPreset | None
+
+    @field_validator("ability_info", mode="before")
+    @classmethod
+    def null_as_empty(cls, v):
+        if v is None:
+            return []
+        return v