4.0.0

4.0.0

파이썬 버전

• 최소 지원 버전이 Python 3.11 이상으로 변경되었습니다.

BREAKING CHANGE: 모델 전면 재작성

기존 koreanbots/model.py 기반의 단일 파일 모델 구조가 koreanbots/domain/ 패키지로 완전히 재작성되었습니다.

도메인 모델 구조 변경

• koreanbots.domain.entities 모듈이 추가되었습니다.
• 모든 모델은 @dataclass 기반으로 변경되었습니다.
• Bot, Server, User, Vote 등 핵심 엔티티가 재정의되었습니다.
• BotWithOwnerID, ServerWithOwnerID 모델이 추가되어 오너 ID 목록만 포함하는 임베디드 봇/서버를 표현합니다.
• 모든 응답은 KoreanbotsDataResponse[T] 제네릭 래퍼로 반환됩니다.

    # Before (3.x)
    r = await kb.botinfo(653534001742741552)
    owner = r.owners[0]

    # After (4.0)
    r = await kb.get_bot_info(653534001742741552)
    owner = r.data.owners[0]  # User 인스턴스

모델 필드 변경

• Bot.owners — list[str] 에서 list[User] 로 변경. /bots/{id} 응답의 owners는 완전한 User 객체입니다.
• User.bots — list[BotWithOwnerID] 로 변경. /users/{id} 응답의 bots는 owners 필드가 ID 목록인 봇 객체입니다.
• User.servers — list[ServerWithOwnerID] 로 변경.
• Server.owner — User 객체 (/servers/{id} 는 오너의 전체 유저 정보를 반환합니다). 오너 ID만 포함하는 임베디드 참조는 ServerWithOwnerID.owner: str 로 표현됩니다.
• AbstractUser.globalName — str 필드 추가.
• AbstractBot.enforcements — list[str] 필드 추가.
• AbstractServer.bots — list[str] (봇 ID 목록) 필드 추가.

역직렬화기 (Deserializer) 추가

• koreanbots.domain.deserializer.Deserializer 클래스가 새로 추가되었습니다.
• from_dict() 클래스 메서드를 통해 API 응답 딕셔너리를 자동으로 도메인 모델로 변환합니다.
• 알 수 없는 키가 수신되면 ValueError 를 발생시킵니다 (엄격 모드).
• list[Deserializer] 필드의 경우, 요소가 Mapping 이면 from_dict() 를 호출하고 문자열 등 기본형이면 그대로 유지합니다.
• Literal, Union, Optional 타입 힌트를 올바르게 처리합니다.

HTTP 클라이언트 재작성

• koreanbots/http.py 가 삭제되고 koreanbots/request.py (KoreanbotsRequester) 로 대체되었습니다.
• 레이트 리밋 처리가 추가되었습니다. 429 Too Many Requests 응답 시 x-ratelimit-reset 헤더값을 기준으로 대기 후 자동 재요청합니다.

클라이언트 변경

• koreanbots/decorator.py 가 삭제되었습니다.
• 서드파티 통합 모듈 (integrations/dico.py, integrations/discord.py) 이 삭제되었습니다.

import discord
from discord.ext import commands, tasks

from koreanbots.client import Koreanbots

BOT_TOKEN = "your_discord_bot_token"
KOREANBOTS_API_KEY = "your_koreanbots_api_key"

bot = commands.Bot(command_prefix="!", intents=discord.Intents.default())
koreanbots = Koreanbots(KOREANBOTS_API_KEY)


@tasks.loop(hours=1)
async def update_server_count():
    await koreanbots.update_bot_info(
        bot_id=bot.user.id,
        servers=len(bot.guilds),
        shards=bot.shard_count or 0,
    )


@update_server_count.before_loop
async def before_update_server_count():
    await bot.wait_until_ready()


@bot.event
async def on_ready():
    update_server_count.start()
    print(f"Logged in as {bot.user}")


bot.run(BOT_TOKEN)

• Koreanbots 클라이언트가 KoreanbotsRequester 를 상속하는 구조로 변경되었습니다.
• widget() 메서드가 BotWidgetURLBuilder 를 반환하는 빌더 패턴으로 변경되었습니다.

    from koreanbots.client import Koreanbots

    kb = Koreanbots(api_key="...")

    # 봇 정보 조회
    r = await kb.get_bot_info(653534001742741552)
    print(r.data.name)

    # 위젯 URL 빌더 (체이닝 가능)
    url = kb.widget(653534001742741552, "votes").style("flat").scale(1.5).icon()
    print(str(url))
    
  # or
  
    from koreanbots.client import BotWidgetURLBuilder

    widget = BotWidgetURLBuilder(653534001742741552, "votes").style("flat").scale(1.5).icon()

3.1.0

Release Note

Breaking Change

• 이제 모든 엔드포인트는 API키가 필수입니다. (#48)

3.0.0

Release note

이번 릴리즈는 메이저 업데이트로 다수의 breaking changes를 포함하고 있으니 유의해주시기 바랍니다.

주요 변경 사항

자세한 내용은 py-sdk 문서에서 확인하실 수 있습니다.

http 요청 메서드 접근 불가

더이상 KoreanbotsRequester의 메서드를 통한 HTTP 요청이 불가능합니다.

요청 메서드 이름 변경

기존 통일되지 않은 메서드 이름을 모두 변경하였습니다. 기존 메서드 이름은 아직 사용 가능하나 deprecated로 변경되며, 다음 메이저 릴리즈에서 제거되므로 새 메서드 이름으로 변경해주시기 바랍니다.

# Before
r = await koreanbots.botinfo(653534001742741552)

# After
r = await koreanbots.get_bot_info(653534001742741552)

모델 구조 변경

원본 REST API의 응답과 반환되던 응답 모델이 상이한 부분이 있어 혼선을 방지하기 위해 원본 REST API의 응답과 통일하고자 모델을 수정하였습니다.
이제 정보를 가져올 때 data 속성을 참조해야 합니다.

# Before
r = await koreanbots.botinfo(653534001742741552)
print(r.owners[0].bots)

# After
r = await koreanbots.get_bot_info(653534001742741552)
print(r.data.owners[0].bots)

2.1.2

Release note

버그 수정

• API로 요청 시 레이트리밋 관련 헤더가 누락된 경우 KeyError가 발생할 수 있는 문제를 해결했습니다. (#46)
• 서버 수 자동 업데이트 루프에서 오류가 발생하는 경우 루프가 멈추는 문제를 해결했습니다. (#46)

기타

• 서버 수 자동 업데이트 관련 로그 메시지를 수정했습니다.

2.1.1

Release note

버그 수정

• 서버 수 업데이트 불가 문제가 해결되었습니다. (#43)

2.1.0

Release note

Version: 2.1.0

중요한 변경 사항

• 한국 디스코드 서버의 엔드포인트를 지원합니다: #39

새로운 기능

• disnake 모듈 지원: #36

감사한분들

• @insanephin 님께서 한국 디스코드 서버의 엔드포인트를 래핑 해주셨습니다. 매우 감사합니다!

Release 2.0.0

Koreanbots py-sdk 2.0.0 릴리스

첫번째로 진행하는 메이저 업데이트 입니다.
이전버전과 지원이 되지않는 업데이트니 한번 잘 살펴보시기 바랍니다.

새로운기능

discord.py의 지원이 종료되면서 수많은 포크및 라이브러리의 선택지가 넓어졌습니다.
py-sdk는 이를 지원하고자 합니다.

discord.py의 포크와 다른 라이브러리중 어느것이 더 메이저 하게쓰일지 한번 구경해보자고요.

• koreanbots.integrations 에 여러 라이브러리를 지원하게되었습니다.

지원되는 라이브러리

@simsimler 님이 dico 라이브러리에 대해 기여해주셨습니다. 감사합니다.

py-sdk는 여러분의 기여를 환영해요. 언제든지 PR주세요!

• https://github.com/dico-api/dico
• https://github.com/nextcord/nextcord
• https://github.com/Pycord-Development/pycord

이전 버전 호환성

koreanbots.client.Koreanbots에서 자동으로 봇 서버 수를 보냈던 기능이 이젠 integrations에 옮겨졌습니다.

때로는 과감하게 버릴때도 있어야하는 법이죠.

• 더이상 koreanbots.client.Koreanbots.tasks_send_guildcount 를 사용할수없습니다.

감사의 말씀

이번 릴리즈에 큰도움을 주신분들입니다.

진짜진짜진짜 감사한분들이에요.

• @kijk2869 님이 discordABC에 기여를 해주셨습니다. 다만 해당 변경사항은 적용되지 않았습니다.
• @simsimler 님이 dico 라이브러리의 지원을 도와주셨습니다.

Release 1.1.3

Stable

• 봇 투표 여부를 가져올수 없는 문제를 해결했습니다.
  • GH-27, GH-28
    • Contributed by @Craphting

Release 1.1.2

Release 1.1.2

패키지로 사용할시 스텁파일이 존재하지 않다고 하는 문제 해결

Release 1.1.1

Stable

• 봇 서버수가 업데이트가 되지않는 문제를 해결했습니다
  • GH-26
    • Contributed by @eunwoo1104