(공식 API) API 래퍼런스¶

Client¶

class Client(client_id: str, client_secret: str, loop: asyncio.AbstractEventLoop | None = None)¶

치지직(네이버 스트리밍 서비스)의 API를 제공하는 클라이언트 객체입니다.

async connect(addition_connect: bool = False) → str¶

후원 정보 또는 채팅을 수신받기 위해 세션에 연결합니다. 클라이언트 세션은 최대 10개까지 생성할 수 있습니다.

매개변수:: addition_connect (Optional[bool]) – 이 매개변수는 다중 채널 연결을 위해 사용되며, 기본 값은 False 입니다. 만약에 addition_connect의 값이 False 라면 메인 스레드는 이벤트를 수신받기 위해 사용됩니다. 하지만 addition_connect의 값이 True 라면, 이벤트를 수신받기 위한 작업은 백그라운드에서 진행되게 됩니다.
반환:: 고유 세션 ID를 반환 받습니다. 세션 ID는 이벤트를 구독하는 용도로 사용됩니다.
반환 형식:: str

경고

만약에 메인 스레드의 작업이 없고, addition_connect 매개변수의 값이 True 라면, 모든 메인 스레드의 연산 작업을 마치고 연결은 중단됩니다.

예외 발생:: ChatConnectFailed.max_connection – 클라이언트 세션은 10개까지 연결할 수 있습니다. 만약 10개 이상의 연결을 시도한다면 ChatConnectFailed 예외가 유발될 수 있습니다.

async disconnect(session_id: str | None = None)¶

세션 연결을 종료합니다.

매개변수:: session_id (Optional[str]) – 연결을 종료할 세션의 ID 입니다. 만약 세션 ID를 담는 매개변수가 비어있다면, 모든 세션을 종료합니다.

async generate_access_token(code: str, state: str) → AccessToken¶

Access Token을 생성합니다. Access Token은 사용자 인증이 필요한 기능을 위해 사용됩니다.

매개변수:

code (str) – generate_authorization_token_url() 에서 응답받은 코드입니다.
state (str) – 인증을 위해 사용되는 임시 코드입니다. :meth:`generate_authorization_token_url`의 매개변수에 사용된 state 코드와 동일해야 합니다.

반환:

사용자 인증 정보를 담고 있는 객체입니다.

반환 형식:

AccessToken

generate_authorization_token_url(redirect_url: str, state: str) → str¶

치지직 Access Token을 발급받기 위한 URL를 생성합니다.

매개변수:

redirect_url (str) – 서드파티 인증을 마치고 이동될 리다이렉트 URL 입니다.
state (str) – generate_access_token() 등의 함수의 state 매개변수에 사용될 임시 코드입니다.

async generate_user_client(code: str, state: str) → UserClient¶

UserClient 객체를 생성합니다.

매개변수:

code (str) – generate_authorization_token_url() 에서 응답받은 코드입니다.
state (str) – 인증을 위해 사용되는 임시 코드입니다. :meth:`generate_authorization_token_url`의 매개변수에 사용된 state 코드와 동일해야 합니다.

async get_category(query: str, size: int | None = 20) → list[Category]¶

카테고리 정보를 불러옵니다.

매개변수:

query (str) – 카테고리 이름
size (Optional[int], optional) – 한 번에 불러올 카테고리의 개수입니다. 기본 값은 20개 입니다.

async get_channel(channel_ids: list[str]) → list[Channel]¶

채널 정보를 불러옵니다.

매개변수:: channel_ids (list[str]) – 검색할 채널의 ID입니다.

async get_live(size: int = 20) → SearchResult[Live]¶

방송 정보를 불러옵니다.

매개변수:: size (Optional[int], optional) – 한 번에 불러올 방송의 개수 입니다. 기본 값은 20개 입니다.

async get_user_client(access_token: AccessToken) → UserClient¶

Access Toekn을 이용하여 UserClient 객체를 생성합니다.

매개변수:: access_token (AccessToken) – Access Token 객체

get_user_client_cached(channel_id: str) → UserClient | None¶

channel_id 를 이용하여 UserClient 객체를 불러옵니다. UserClient`의 채널 ID는 이벤트 구독하는 과정 또는 `유저 정보 조회 권한을 통해 불러옵니다.

만약 :class:`UserClient`의 channel ID가 비어있다면, 클라이언트를 찾을 수 없습니다.

매개변수:: channel_id (str) – UserClient 객체를 불러올 채널 ID 입니다.

async login(state: str | None = None, redirect_url: str | None = None, remote_host: str = 'localhost', remote_port: int = 8080, remote_path: str = '/', success_response: webResponse | None = None, ssl: bool = False) → UserClient¶

UserClient 객체를 OAuth2 로그인 과정으로 불러옵니다.:meth:login 함수는 로그인을 위한 임시 웹 서버를 가동합니다.

매개변수:

state (Optional[str]) – 인증 과정에서 사용되는 임시 코드입니다.
redirect_url (Optional[str]) – 인증 과정에서 사용되는 리다이렉션 URL입니다.
remote_host (str) – 임시 웹 서버에서 사용되는 Host URL이며, 기본 값은 “localhost” 입니다. 만약 공개 환경에서 웹 서버를 기동하고 싶으면 “0.0.0.0” 값을 매개변수로 입력하세요.
remote_port (int) – 임시 웹 서버에 사용할 포트이며, 기본 값은 8080 입니다.
remote_path (int) – 임시 웹 서버에 사용할 주소이며, 기본 값은 ‘/’ 입니다.
success_response (aiohttp.web.Response) – 로그인을 성공하면 웹사이트에 표시할 내용입니다.
ssl (bool) – 웹 브라우저에 HTTP(s)를 사용할 여부입니다.

async refresh_access_token(refresh_token: str) → AccessToken¶

Access Token을 재생성 합니다. Access Token은 OAuth2 프로포콜을 따릅니다.

이 뜻은 일정 시간을 경과하면 Access Token이 만료된다는 것을 의미합니다.

매개변수:: refresh_token (str) – 재생성된 Access Token 입니다.

async refresh_user_client(refresh_token: str) → UserClient¶

Refresh Token으로 재생성한 UserClient 객체를 불러옵니다.

매개변수:: refresh_token (str) – 재생성된 Access Token 입니다.

async wait_until_connect()¶: 세션이 연결될 때까지 기다립니다.

User Client¶

class UserClient(parent: Client, access_token: AccessToken)¶

치지직(네이버 스트리밍 서비스)의 사용자 API를 제공하는 클라이언트 객체입니다.

async add_restrict_channel(user_id: str) → None¶

시청자 활동 제한합니다.

매개변수:: user_id (str) – 활동 제한할 시청자의 채널 ID입니다.

async connect(permission: UserPermission, addition_connect: bool = False)¶

후원, 채팅 정보를 수신받기 위하여 사용자 세션에 연결합니다.

매개변수:

permission (UserPermission) – 후원, 채팅과 같이 수신받을 이벤트의 권한을 설정합니다. 세션에 연결을 마친 후 이벤트 구독을 진행하여 권한을 부여받습니다.
addition_connect (Optional[bool]) – 이 매개변수는 다중 채널 연결을 위해 사용되며, 기본 값은 False 입니다. 만약에 addition_connect의 값이 False 라면 메인 스레드는 이벤트를 수신받기 위해 사용됩니다. 하지만 addition_connect의 값이 True 라면, 이벤트를 수신받기 위한 작업은 백그라운드에서 진행되게 됩니다.

반환:

고유 세션 ID를 반환 받습니다. 세션 ID는 이벤트를 구독하는 용도로 사용됩니다.

반환 형식:

str

경고

만약에 메인 스레드의 작업이 없고, addition_connect 매개변수의 값이 True 라면, 모든 메인 스레드의 연산 작업을 마치고 연결은 중단됩니다.

async disconnect()¶: 세션 연결을 종료합니다.

async fetch_self() → Channel¶

Access Token에 기반으로 한 자신의 채널 정보를 불러옵니다.이 함수를 사용하려면 “유저 정보 조회” API Scope가 필요합니다.

반환:: A channel based on the access token.
반환 형식:: Channel

async get_channel_administrator() → list[ChannelPermission]¶: 채널에 관리 권한을 가지고 있는 사용자 정보를 불러옵니다.

async get_chat_setting() → ChatSetting¶: 채팅 설정 정보를 불러옵니다.

async get_followers(size: int = 30) → SearchResult[FollowerInfo]¶

채널에 팔로우한 시청자를 불러옵니다.

매개변수:: size (Optional[int]) – 한 번에 불러올 팔로워 수입니다. 기본 값은 30명 입니다.

async get_live_setting() → BrodecastSetting¶: 방송 설정을 불러옵니다.

async get_restriction(size: int = 20) → SearchResult[RestrictUser]¶

채널에 활동 제한된 사용자를 불러옵니다.

매개변수:: size (Optional[int], optional) – 한 번에 불러올 방송의 개수 입니다. 기본 값은 20개 입니다.

async get_stream_key() → str¶: 방송에 사용되는 스트림키를 불러옵니다.

async get_subscribers(size: int = 30, sort: Literal['RECENT', 'LONGER'] = 'RECENT') → SearchResult[SubscriberInfo]¶

채널을 구독한 시청자를 불러옵니다.

매개변수:

size (Optional[int]) – 한 번에 불러올 구독자 수입니다. 기본 값은 30명 입니다.
sort (Optional[Literal['RECENT', 'LONGER']]) – 구독자를 정렬하는 방법입니다.

async refresh()¶: Access Token을 갱신합니다.

async remove_restrict_channel(user_id: str) → None¶

활동 제한된 사용자를 해제합니다.

매개변수:: user_id (str) – 활동 제한을 해제할 사용자의 채널 ID입니다.

async revoke()¶: Access Token을 만료합니다.

async send_announcement(content: str)¶

채팅에 공지사항을 전파합니다.이 함수를 사용하기 위해서는 “채널 공지 등록” API Scope가 필요합니다.

매개변수:: content (str) – 공지사항으로 전파할 내용

async send_message(content: str) → SentMessage¶

채팅창에 메시지를 보냅니다.이 함수를 사용하기 위해서는 “채팅 메시지 전송” API Scope가 필요합니다.

매개변수:: content (str) – 보낼 메시지의 내용

async subscribe(permission: UserPermission, session_id: str | None = None)¶

UserPermission을 이용하여 이벤트 구독을 진행합니다.

매개변수:

permission (UserPermission) – 수신받을 권한입니다.
session_id (Optional[str]) – 구독할 세션의 ID가 입력됩니다. 기본 값은 None이며, on_connect 이벤트에서 불러와진 매개변수를 입력하면 됩니다.

async unsubscribe(permission: UserPermission, session_id: str | None = None)¶

UserPermission으로 구독했던 이벤트 구독을 해제합니다. 입력되는 매개변수에 따라 더 이상 이벤트를 수신받지 않습니다.

매개변수:

permission (UserPermission) – 더 이상 수신을 받지않을 권한입니다.
session_id (Optional[str]) – 이벤트 구독을 취소할 세션의 ID가 입력됩니다. 기본 값은 None이며, on_connect 이벤트에서 불러와진 매개변수를 입력하면 됩니다.

async wait_until_connect()¶: 세션이 연결될 때까지 기다립니다.

property is_connected: bool¶: 세션 연결의 여부

property is_expired: bool¶: Access Token이 일정 시간 경과되어 만료된 여부

Event Reference¶

이 섹션은 Client 에서 수신받는 모든 이벤트에 대해 설명합니다. 이벤트는 Client.event 데코레이터를 이용하여 수신받을 수 있습니다.

예제:

>>> @client.event
... async def on_chat(message: Message):
...     print(message.content)

모든 이벤트 함수는 반드시 비동기(코루틴) 이어야합니다. 비동기(코루틴)로 이벤트 함수를 구성하지 않으면 예상치 못한 예외를 초래할 수 있습니다.

async on_chat(message: message.Message)¶

시청자와 주고 받는 메시지가 발생하면 호출되는 이벤트입니다.

매개변수:: message (Message) – 메시지

async on_connect()¶: 치지직 세션과 성공적으로 연결되면 호출되는 이벤트입니다.

async on_donation(donation: Donation)¶

방송 중에 후원이 발생하면 호츨되는 이벤트입니다. 수신받는 후원 이벤트는 채팅 후원과, 영상 후원이 있습니다.

매개변수:: donation (Donation) – 후원한 정보를 담고 있는 객체입니다.

async on_subscription(subscription: Subscription)¶

방송을 새롭게 구독한 시청자가 발생하면 호출되는 이벤트입니다.

매개변수:: subscription (Subscription) – 구독한 시청자의 정보를 담고 있는 객체입니다.

async on_permission_invoked(EventSubscribeMessage message)¶

:class:`subscribe <chzzkpy.client.Client.subscribe> 함수를 이용하여새로운 권한을 부여받게 되면 호출되는 이벤트입니다.

매개변수:: message (EventSubscribeMessage) – 이벤트 구독 관련 정보가 담겨 있습니다.

async on_permission_reinvoked(EventSubscribeMessage message)¶

unsubscribe 함수를 통해 권한이 취소되었다면 호출되는 이벤트입니다.

매개변수:: message (EventSubscribeMessage) – 이벤트 구독 관련 정보가 담겨 있습니다.

async on_permission_reinvoked_force(EventSubscribeMessage message)¶

사용자 권한 철회 등의 이유로 권한이 강제 취소되면 호출되는 이벤트입니다.

매개변수:: message (EventSubscribeMessage) – 이벤트 구독 관련 정보가 담겨 있습니다.

User Permission¶

class UserPermission¶

UserPermission 객체는 이벤트 구독을 위해 사용됩니다.

classmethod all() → UserPermission¶: :class:`UserPermission`의 모든 권한이 활성화 됩니다.

chat¶

방송 중 시청자가 주고 받는 메시지 이벤트를 수신받을 여부

Type:: bool

donation¶

방송 중 발생한 후원 이벤트를 수신받을 여부

Type:: bool

subscription¶

방송 중 발생한 신규 구독자 이벤트를 수신받을 여부

Type:: bool

Enumeration¶

class FollowingPeriod¶

DAY = 1440¶

FIVE_MINUTE = 5¶

HALF_HOUR = 30¶

HOUR = 60¶

MONTH = 43200¶

NONE = 0¶

TEN_MINUTE = 10¶

WEEK = 10080¶

Authorization¶

class AccessToken¶

access_token: str¶

expires_in: int¶

refresh_token: str¶

scope: str | None¶

token_type: str¶

Category¶

class Category¶

id: str¶

image: str | None¶

name: str¶

type: Literal['GAME', 'SPORTS', 'ETC'] | None¶

Channel¶

class Channel¶

follower_count: int | None¶

id: str¶

image: str | None¶

name: str¶

verified_mark: bool¶

class ChannelPermission¶

created_date: datetime¶

role: Literal['STREAMING_CHANNEL_OWNER', 'STREAMING_CHANNEL_MANAGER', 'STREAMING_CHAT_MANAGER', 'STREAMING_SETTLEMENT_MANAGER']¶

user_id: str¶

user_name: str¶

class FollowerInfo¶

created_date: datetime¶

user_id: str¶

user_name: str¶

class SubscriberInfo¶

created_date: datetime¶

month: int¶

tier_no: int¶

user_id: str¶

user_name: str¶

Chat¶

class ChatSetting¶

allow_subscriber_in_follower_mode: bool¶

chat_available_condition: Literal['NONE', 'REAL_NAME']¶

chat_available_group: Literal['ALL', 'FOLLOWER', 'MANAGER', 'SUBSCRIBER']¶

min_follower_minute: FollowingPeriod¶

Live¶

class Live¶

adult: bool¶

property category: Category | None¶

property channel: Channel¶

concurrent_user_count: int¶

live_id: int¶

live_image_url: str¶

live_title: str¶

open_date: datetime¶

tags: list[str]¶

class BrodecastSetting¶

category: Category¶

tags: list[str]¶

title: str¶

Message¶

class Profile¶

badges: list[Any]¶

nickname: str¶

verified_mark: bool¶

class Message¶

방송 중에 수신받은 메시지가 담긴 객체입니다.메시지는 on_chat 이벤트를 통해 수신받을 수 있습니다.

async send(content)¶

수신받은 채널로 메시지를 회신합니다.

매개변수:: content (str) – 보낼 메시지 내용
반환:: 보낸 메시지 정보를 담고 있는 객체
반환 형식:: SentMessage

channel: str¶

content: str¶

created_time: datetime.datetime¶

profile: Profile¶

user_id: str¶

class Donation¶

채널에 후원한 정보가 담긴 객체입니다.시청자가 방송 중에 후원하게 되면 on_donation 이벤트를 통해 수신받을 수 있습니다.

async send(content)¶

수신받은 채널로 메시지를 회신합니다.

매개변수:: content (str) – 보낼 메시지 내용
반환:: 보낸 메시지 정보를 담고 있는 객체
반환 형식:: SentMessage

channel: str¶

donation_text: str¶

donator_id: str¶

donator_name: str¶

pay_amount: int¶

type: Literal['CHAT', 'VIDEO']¶

class Subscription¶

채널을 구독한 시청자의 정보가 담긴 객체입니다.새롭게 구독한 시청자는 on_subscription 이벤트를 통해 수신받을 수 있습니다.

async send(content)¶

수신받은 채널로 메시지를 회신합니다.

매개변수:: content (str) – 보낼 메시지 내용
반환:: 보낸 메시지 정보를 담고 있는 객체
반환 형식:: SentMessage

channel: str¶

month: int¶

subscriber_id: str¶

subscriber_name: str¶

tier_name: str¶

tier_no: int¶

class SentMessage¶

client.send() 함수로 보낸 메시지 정보를 담고 있는 객체이빈다.

async pin() → None¶: 보낸 메시지를 고정합니다.

content: str¶

created_time: datetime.datetime¶

id: str¶

Restrict¶

class RestrictUser¶

channel_id: str¶

channel_name: str¶

created_date: datetime¶

release_date: datetime¶

예외 (Exceptions)¶

exception LoginRequired¶: 클라이언트가 로그인이 안된 상태에서 인증이 필요한 기능을 사용하면 호출되는 예욉니다.

exception ChatConnectFailed¶

exception ReceiveErrorPacket¶

exception HTTPException¶: 통신 과정에서 HTTP 오류가 발생하면 호출되는 예외입니다.

exception BadRequestException¶: 통신 과정에서 400(잘못된 요청)을 수신받으면 호출되는 예외입니다.

exception UnauthorizedException¶: 통신 과정에서 401(인증 안됨)을 수신받으면 호출되는 예외입니다.

exception ForbiddenException¶: 통신 과정에서 403(권한 없음)을 수신받으면 호출되는 예외입니다.

exception NotFoundException¶: 통신 과정에서 404을 수신받으면 호출되는 예외입니다.

exception TooManyRequestsException¶: 통신 과정에서 429(사용 한도 초과)을 수신받으면 호출되는 예외입니다.