pyLoa (py-lostark)

로스트아크 API를 위한 Python 래퍼 라이브러리

개요

pyLoa는 로스트아크 공식 OpenAPI를 위한 직관적이고 사용하기 쉬운 Python 래퍼 라이브러리입니다.

주요 기능

• 직관적인 인터페이스: API 엔드포인트가 자연스럽게 메서드로 매핑
• 타입 안정성: Type hints를 통한 IDE 자동완성 및 타입 체크 지원
• 유연한 Rate Limiting 제어: 외부에서 Redis 기반 유량 제어 구현 가능 (예제 제공)
• 간단한 인증: API 키만으로 쉽게 초기화
• 풍부한 모델링: API 응답을 Python 객체로 자동 변환

설치 (Installation)

pip install py-lostark

시작하기

API 키 발급

1. 로스트아크 개발자 포털에 접속
2. 계정으로 로그인
3. 클라이언트 생성에서 새 클라이언트 생성
4. 발급받은 JWT 토큰 복사

기본 사용법

from pyloa import LostArkAPI

# 1. 클라이언트 초기화
api = LostArkAPI(api_key="your_jwt_token_here")

# 2. 진행 중인 이벤트 조회
events = api.news.get_events()
for event in events:
    print(f"{event.title}: {event.start_date} ~ {event.end_date}")

# 3. 캐릭터 정보 조회
siblings = api.characters.get_siblings("캐릭터명")
for char in siblings:
    print(f"{char.character_name} ({char.server_name}): {char.item_avg_level}")

# 4. 캐릭터 프로필 상세 조회
profile = api.armories.get_profile("캐릭터명")
print(f"{profile.character_name} 레벨: {profile.character_level}")
if profile.stats:
    for stat in profile.stats:
        print(f"{stat.type}: {stat.value}")

# 5. 거래소 아이템 검색
result = api.markets.search_items(ItemName="파괴강석", CategoryCode=50000)
print(f"총 {result.total_count}개 검색됨")
for item in result.items:
    print(f"{item.name}: {item.current_min_price}골드")

API 문서

주요 엔드포인트

News (뉴스/공지)

# 공지사항 조회
notices = api.news.get_notices(searchText="점검", type="점검")

# 진행 중인 이벤트 조회
events = api.news.get_events()

Characters (캐릭터 기본 정보)

# 계정의 모든 캐릭터 목록 조회
siblings = api.characters.get_siblings("캐릭터명")

Armories (캐릭터 상세 정보)

# 캐릭터 종합 정보 조회 (필터 사용)
total = api.armories.get_total_info(
    "캐릭터명",
    filters=["profiles", "equipment", "gems"]
)

# 캐릭터 프로필
profile = api.armories.get_profile("캐릭터명")

# 장비 정보
equipment = api.armories.get_equipment("캐릭터명")

# 아바타 정보
avatars = api.armories.get_avatars("캐릭터명")

# 전투 스킬
skills = api.armories.get_combat_skills("캐릭터명")

# 각인 정보
engravings = api.armories.get_engravings("캐릭터명")

# 카드 정보
cards = api.armories.get_cards("캐릭터명")

# 보석 정보
gems = api.armories.get_gems("캐릭터명")

Markets (거래소)

# 거래소 검색 옵션 조회 (Dict 리턴)
options = api.markets.get_options()

# 특정 아이템 정보 조회 (MarketItem)
item = api.markets.get_item(item_id=66110221)

# 아이템 검색 (Market)
result = api.markets.search_items(
    CategoryCode=50000,
    ItemName="파괴강석",
    PageNo=1
)

# 최근 거래 내역 (List[TradeMarketItem])
trades = api.markets.get_trades(ItemName="파괴강석")

Auctions (경매장)

# 경매장 검색 옵션 조회
options = api.auctions.get_options()

# 경매장 아이템 검색 (Auction)
result = api.auctions.get_items(
    CategoryCode=200000,
    ItemGrade="유물",
    ItemTier=3,
    PageNo=1
)

Game Contents (게임 컨텐츠)

# 주간 캘린더 정보 (ContentsCalendar)
calendar = api.game_contents.get_calendar()

고급 사용법

Rate Limiting 처리

참고: v2.0부터 Rate Limiting은 라이브러리 외부에서 제어합니다. 멀티 프로세스 환경에서는 examples/fastapi-flow-control 또는 examples/flask-flow-control 예제를 참조하세요.

# 429 오류 처리 예시
from pyloa import LostArkAPI, RateLimitError

api = LostArkAPI(api_key="your_jwt_token")

try:
    api.news.get_events()
except RateLimitError:
    # 외부 유량 제어 로직으로 처리 (예: slowapi, flask-limiter)
    print("Rate limit 초과, 잠시 후 재시도하세요.")

에러 처리

from pyloa import LostArkAPI, APIError, AuthenticationError, RateLimitError

api = LostArkAPI(api_key="your_jwt_token")

try:
    character = api.characters.get_siblings("존재하지않는캐릭터")
except AuthenticationError:
    print("API 키가 잘못되었습니다.")
except APIError as e:
    print(f"API 오류 발생: {e}")

프로젝트 구조

pyLoa/
├── pyloa/                  # 메인 패키지
│   ├── __init__.py        # 패키지 초기화, 주요 클래스 내보내기
│   ├── client.py          # LostArkAPI 메인 클라이언트
│   ├── exceptions.py      # 커스텀 예외 정의
│   ├── endpoints/         # API 엔드포인트 모듈
│   │   ├── base.py       # BaseEndpoint 추상 클래스
│   │   ├── news.py       # 뉴스/공지 엔드포인트
│   │   ├── characters.py # 캐릭터 기본 정보 엔드포인트
│   │   ├── armories.py   # 캐릭터 상세 정보 엔드포인트
│   │   ├── markets.py    # 거래소 엔드포인트
│   │   ├── auctions.py   # 경매장 엔드포인트
│   │   └── game_contents.py # 게임 컨텐츠 엔드포인트
│   └── models/            # 데이터 모델
│       ├── base.py       # BaseModel 추상 클래스
│       ├── character.py  # 캐릭터 관련 모델
│       ├── armory.py     # Armory 관련 모델
│       ├── market.py     # 거래소 관련 모델
│       ├── auction.py    # 경매장 관련 모델
│       ├── news.py       # 뉴스 관련 모델
│       └── game_content.py # 게임 컨텐츠 관련 모델
├── docs/                  # 문서 및 다이어그램
│   ├── architecture.mmd   # 아키텍처 다이어그램 Mermaid 소스
│   └── architecture_diagram.png # 아키텍처 다이어그램 이미지
├── tests/                 # 테스트 코드
├── requirements.txt       # 의존성 패키지
├── setup.py              # 패키지 설정
└── README.md             # 프로젝트 문서 (본 파일)

아키텍처

pyLoa는 다음과 같은 계층 구조로 설계되었습니다:

핵심 계층

1. Client Layer (LostArkAPI): 모든 API 접근의 진입점
2. Endpoint Layer (BaseEndpoint 및 하위 클래스): 각 API 카테고리별 메서드 제공
3. Model Layer (BaseModel 및 하위 클래스): API 응답 데이터를 Python 객체로 변환
4. Utility Layer (exceptions): 공통 유틸리티 기능

관련 링크

• 로스트아크 개발자 포털

Note: 이 라이브러리는 비공식 프로젝트이며, Smilegate 또는 Lost Ark와 공식적인 관련이 없습니다.