API reference

sechat.ChatClient

A base class for objects which interact with chat.

Attributes:

Name	Type	Description
`user_id`		The unique id of the bot user.
`server`		The chat instance this room belongs to.

upload_image `async`

upload_image(image: BytesIO, filename: str = 'upload') -> str

Upload an image to Stack Exchange's image hosting.

Parameters:

Name	Type	Description	Default
`image`	`BytesIO`	The image data to upload.	required
`filename`	`str`	The filename supplied to Stack Exchange. It is unknown if this parameter is used by anything.	`'upload'`

Returns: The URL of the uploaded image.

sechat.Credentials `dataclass`

Cookies necessary to interact with Stack Exchange chat.

It is strongly recommended to use load_or_authenticate instead of just authenticate, because Stack Exchange will present you with a CAPTCHA if you make too many login attempts in too short of a time. load_and_authenticate will save your cookies to a file and try to reuse them instead of logging in again and risking tripping the CAPTCHA, and automatically handles expiration and fetching new credentials.

Attributes:

Name	Type	Description
`server`	`Server`	The chat instance these cookies are valid for.
`prov`	`Morsel[str]`	The `prov` cookie returned by logging into Meta Stack Exchange.
`acct`	`Morsel[str]`	The `acct` cookie returned by logging into Meta Stack Exchange.
`chatusr`	`Morsel[str]`	The `sechatusr` (chat.stackexchange.com) or `chatusr` (the other two chat servers) cookie returned by logging into chat.
`user_id`	`int`	The ID of the chat account (not main site account!) these cookies are for.

authenticate `async` `staticmethod`

authenticate(email: str, password: str, *, server: Server = STACK_EXCHANGE) -> Credentials

Log into a chat server.

Every time this function is called it will perform the entire login process again, which will trigger a CAPTCHA if done too many times. Unless you need complete control over the login process, use load_or_authenticate instead. The account must have 20 reputation to use chat.

Parameters:

Name	Type	Description	Default
`email`	`str`	The email address of the account to log into.	required
`password`	`str`	The password of the account to log into.	required
`server`	`Server`	The chat server to log into.	`STACK_EXCHANGE`

Returns:

Type	Description
`Credentials`	A new `Credentials` instance that can be used to join chatrooms.

Raises:

Type	Description
`LoginError`	Something went wrong while logging in, most likely a CAPTCHA or incorrect credentials.

load `async` `staticmethod`

load(path: FileDescriptorOrPath) -> Optional[Credentials]

Read and validate a Credentials instance from a file.

Parameters:

Name	Type	Description	Default
`path`	`FileDescriptorOrPath`	The file descriptor or path to load from.	required

Returns:

Type	Description
`Optional[Credentials]`	The loaded `Credentials` instance, or `None` if it was invalid.

load_or_authenticate `async` `staticmethod`

load_or_authenticate(path: FileDescriptorOrPath, email: str, password: str, *, server: Server = STACK_EXCHANGE) -> Credentials

Load and validate credentials from a file, or log in if they aren't valid.

This function automatically handles preserving credentials to minimize logins and avoid a CAPTCHA, as well as renewing them when necessary. The account must have 20 reputation to use chat.

Parameters:

Name	Type	Description	Default
`path`	`FileDescriptorOrPath`	The file descriptor or path to load credentials from and save them to.	required
`email`	`str`	The email address of the account to log into.	required
`password`	`str`	The password of the account to log into.	required
`server`	`Server`	The chat server to log into.	`STACK_EXCHANGE`

save

save(path: FileDescriptorOrPath) -> None

Save a Credentials instance to a file.

Parameters:

Name	Type	Description	Default
`path`	`FileDescriptorOrPath`	The file descriptor or path to save to.	required

sechat.Profile

Bases: ChatClient

A utility class for modifying a user's profile details.

edit_bio `async`

edit_bio(bio: str) -> None

Update the account's bio.

The maximum length is 200 characters, anything longer will be truncated.

Parameters:

Name	Type	Description	Default
`message`		The new bio text.	required

open `staticmethod`

open(credentials: Credentials)

Create a new context manager for a Profile object.

sechat.Room

Bases: ChatClient

A chatroom that a bot is in.

This class should ideally be used as a context manager; if it is not, ensure that close is called before your application exits so the bot account will leave the room and the underlying [aiohttp.ClientSession][] gets closed.

Warning

Do not directly construct this class; use join instead.

Attributes: room_id: The unique id of this room.

anonymous `async` `staticmethod`

anonymous(room_id: int, *, server: Server = STACK_EXCHANGE, poll_interval: int = 3, retries: int = 5) -> AsyncGenerator[Event, None]

Anonymously poll for events in a room. This method does not require any authentication.

Parameters:

Name	Type	Description	Default
`room_id`	`int`	The id of the room to fetch events for.	required
`server`	`Server`	The chat server of the room. Room ids are only unique to a single chat server.	`STACK_EXCHANGE`
`poll_interval`	`int`	The interval at which new events should be checked, in seconds. It is not recommended to change this value.	`3`
`retries`	`int`	The number of consecutive request errors to ignore before crashing.	`5`

Yields: A sequence of sechat.events.Events which occur in the room.

bookmark `async`

bookmark(start_message: int, end_message: int, title: str) -> str

Bookmark a conversation.

The start message and end message must not be the same, and must be in the same room. Which one is first chronologically does not matter. The slug of the conversation will be the supplied title, converted to lowercase, with spaces replaced with dashes and non-alphanumeric characters filtered out.

Parameters:

Name	Type	Description	Default
`start_message`	`int`	The id of the first message in the conversation.	required
`end_message`	`int`	The id of the last message in the conversation.	required
`title`	`str`	The title of the bookmark.	required

Returns: The slug of the conversation, which may be used to delete it.

clear_stars `async`

clear_stars(message_id: int) -> None

Clear stars on a message, removing it from the starboard.

The account must be an owner of the room the message was sent in.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to clear stars against.	required

close `async`

close() -> None

Close this room, releasing the underlying [aiohttp.ClientSession][] and visually leaving the room for other users.

delete `async`

delete(message_id: int) -> None

Delete a message.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to delete. The message must have been sent by this account less than two and a half minutes ago.	required

delete_bookmark `async`

delete_bookmark(slug: str) -> None

Delete a conversation.

The account must have created the conversation in order to delete it.

Parameters:

Name	Type	Description	Default
`slug`	`str`	The slug of the conversation to delete.	required

edit `async`

edit(message_id: int, new_body: str) -> None

Edit a message.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to edit. The message must have been sent by this account less than two and a half minutes ago.	required
`new_body`	`str`	The new body of the message.	required

events `async`

events() -> AsyncGenerator[Event, None]

Listen for events in the room.

This function may be called multiple times to open several websockets; however, this is not advised as chat may react unpredictably.

Warning

Unless this function is called, bot accounts will not appear in the room's user list until they send a message and may sporadically disappear after some time. If your bot does not consume events, it is advised to consume the events in a background task so the bot will stay in the user list:

async for event in room.events():
    pass

Yields: A sequence of sechat.events.Events which occur in the room.

join `staticmethod`

join(credentials: Credentials, room_id: int)

Join a room.

Parameters:

Name	Type	Description	Default
`credentials`	`Credentials`	The credentials for the account to join the room with.	required
`room_id`	`int`	The id of the room to join.	required

Returns: A context manager which provides a Room instance when entered.

move_messages `async`

move_messages(message_ids: set[int], target_room: int) -> None

Move messages from one room to another.

All messages must be in the same room, and the account must be an owner of that room. The account does not have to be an owner of the destination room or of any of the messages. Starred and pinned messages which are moved will appear on the destination room's starboard.

Parameters:

Name	Type	Description	Default
`message_ids`	`set[int]`	A set of message ids to move to the target room.	required
`target_room`	`int`	The id of the room to move the messages to.	required

pin `async`

pin(message_id: int) -> None

Pin a message.

The account must be an owner of the room the message was sent in.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to pin.	required

send `async`

send(message: str, reply_to: Optional[int] = None) -> int

Send a message.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to send, formatted using chat-compatible Markdown.	required
`reply_to`	`Optional[int]`	A message id to reply to.	`None`

Returns: The id of the newly-sent message.

star `async`

star(message_id: int) -> None

Star or unstar a message. This function will toggle the starred state.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to star or unstar. An account can only star twenty messages every 24 hours, resetting at UTC midnight; after some amount of time (exact duration unknown), the star cannot be removed.	required

unpin `async`

unpin(message_id: int) -> None

Unpin a message.

The account must be an owner of the room the message was sent in.

Parameters:

Name	Type	Description	Default
`message_id`	`int`	The id of the message to unpin.	required

sechat.Server

Bases: StrEnum

A URL for a chat instance.

Errors

sechat.errors.ChatException

Bases: Exception

Base exception type

sechat.errors.LoginError

Bases: ChatException

Raised when an error occurs while logging in

sechat.errors.OperationFailedError

Bases: ChatException

Raised when chat returns an unexpected response

sechat.errors.RatelimitError

Bases: ChatException

Raised when a ratelimit is hit.

This error is automatically handled by the library and should never escape to user code.

API reference

sechat.ChatClient

upload_image async

sechat.Credentials dataclass

authenticate async staticmethod

load async staticmethod

load_or_authenticate async staticmethod

save

sechat.Profile

edit_bio async

open staticmethod

sechat.Room

anonymous async staticmethod

bookmark async

clear_stars async

close async

delete async

delete_bookmark async

edit async

events async

join staticmethod

move_messages async

pin async

send async

star async

unpin async

sechat.Server

Errors

sechat.errors.ChatException

sechat.errors.LoginError

sechat.errors.OperationFailedError

sechat.errors.RatelimitError

upload_image `async`

sechat.Credentials `dataclass`

authenticate `async` `staticmethod`

load `async` `staticmethod`

load_or_authenticate `async` `staticmethod`

edit_bio `async`

open `staticmethod`

anonymous `async` `staticmethod`

bookmark `async`

clear_stars `async`

close `async`

delete `async`

delete_bookmark `async`

edit `async`

events `async`

join `staticmethod`

move_messages `async`

pin `async`

send `async`

star `async`

unpin `async`