curious.core.httpclient

The main Discord HTTP interface.

Functions

encode_multipart(fields, files[, boundary])	Encode dict of form fields and dict of files as multipart/form-data.
parse_date_header(header)	Parses a date header.

Classes

Endpoints(base_url)	type base_url:str
HTTPClient(token, *, bot, max_connections)	The HTTP client object used to make requests to Discord’s servers.

class curious.core.httpclient.HTTPClient(token: str, *, bot: bool = True, max_connections: int = 10)

Bases: object

The HTTP client object used to make requests to Discord’s servers.

If a particular method is not listed here, you can use one of the five following methods to make a manual request:

• HTTPClient.get()
• HTTPClient.post()
• HTTPClient.put()
• HTTPClient.delete()
• HTTPClient.patch()

All of these functions require a ratelimit bucket which will be used to prevent the client from hitting 429 ratelimits.

Parameters:

• token (str) – The token to use for all HTTP requests.
• bot (bool) – Is this client a bot?
• max_connections (int) – The max connections for this HTTP client.

await _get_app_info_me()

Returns:The application info for this bot.

await _make_request(*args, **kwargs)

Makes a request via the current session.

Return type:Response Returns:The response body.

await add_member_role(guild_id, member_id, role_id)

Adds a single role to a member.

If you want to add multiple roles to a member, use add_roles().

Parameters:

• guild_id (int) – The guild ID that contains the objects.
• member_id (int) – The member ID to add the role to.
• role_id (int) – The role ID to add to the member.

await add_reaction(channel_id, message_id, emoji)

Reacts to a message.

Parameters:

• channel_id (int) – The channel ID that the message is in.
• message_id (int) – The message ID of the message.
• emoji (str) – The emoji to react with.

await authorize_bot(application_id, guild_id, *, permissions=0)

Authorize a bot to be added to a guild.

Warning

This is a user-acount only endpoint.

Parameters:

• application_id (int) – The client ID of the bot to be added.
• guild_id (int) – The guild ID to add the bot to.
• permissions (int) – The permissions to add the bot with.

await ban_user(guild_id, user_id, delete_message_days=7, reason=None)

Bans a user from a guild.

Parameters:

• guild_id (int) – The ID of the guild to ban on.
• user_id (int) – The user ID to ban from the guild.
• delete_message_days (int) – The number of days to delete messages from this user.
• reason (Optional[str]) – The reason for this ban.

await change_nickname(guild_id, nickname, *, member_id=None, me=False)

Changes the nickname of a member.

If me is True, then member_id is not required. Otherwise, member_id is required.

Parameters:

• guild_id (int) – The guild ID that contains the member.
• nickname (str) – The nickname to set, None to reset.
• member_id (Optional[int]) – The member ID to change the nickname of.
• me (bool) – If this should change our own nickname.

await create_channel(guild_id, name, type, *, bitrate=None, user_limit=None, permission_overwrites=None)

Creates a new channel.

Parameters:

• guild_id (int) – The guild ID to create the channel in.
• name (str) – The name of the channel.
• type (int) – The type of the channel (text/voice).
• bitrate (Optional[int]) – The bitrate of the channel, if it is a voice channel.
• user_limit (Optional[int]) – The maximum number of users that can be in the channel.
• permission_overwrites (Optional[list]) – The list of permission overwrites to use for this channel.

await create_guild(name, region=None, icon=None, verification_level=None, default_message_notifications=None, roles=None, channels=None)

Creates a new guild.

Parameters:

• name (str) – The name of the new guild.
• region (Optional[str]) – The region of the new guild.
• icon (Optional[str]) – The base64 icon of the new guild.
• verification_level (Optional[int]) – The verification level of the new guild.
• default_message_notifications (Optional[int]) – The default notification level of the new guild.
• roles (Optional[List[dict]]) – A dict of role objects.
• channels (Optional[List[dict]]) – A dict of channel objects.

await create_guild_emoji(guild_id, *, name, image, roles=None)

Creates an emoji in a guild.

Parameters:

• guild_id (int) – The ID of the guild to create the emoji in.
• name (str) – The name of the emoji.
• image (str) – The base64 image data for the emoji.
• roles (Optional[List[int]]) – A list of roles this emoji is limited to.

await create_invite(channel_id, *, max_age=None, max_uses=None, temporary=None, unique=None)

Creates an invite.

Parameters:

• channel_id (int) – The channel ID to create the invite in.
• max_age (Optional[int]) – The maximum age of the invite.
• max_uses (Optional[int]) – The maximum uses of the invite.
• temporary (Optional[bool]) – Is this invite temporary?
• unique (Optional[bool]) – Is this invite unique?

await create_private_channel(user_id)

Opens a new private channel with a user.

Parameters:user_id (int) – The user ID of the user to open with.

await create_role(guild_id)

Creates a role in a guild.

Parameters:guild_id (int) – The guild to create the role in. Return type:dict

await create_webhook(channel_id, *, name=None, avatar=None)

Creates a webhook.

Parameters:

• channel_id (int) – The channel ID to create the webhook in.
• name (Optional[str]) – The name of the webhook to create.
• avatar (Optional[str]) – The base64 encoded avatar to send.

await delete(url, bucket, *args, **kwargs)

Makes a DELETE request.

Parameters:

• url (str) – The URL to request.
• bucket (str) – The ratelimit bucket to file this request under.

await delete_all_reactions(channel_id, message_id)

Removes all reactions from a message.

Parameters:

• channel_id (int) – The channel ID of the channel containing the message.
• message_id (int) – The message ID to remove reactions from.

await delete_channel(channel_id)

Deletes a channel.

Parameters:channel_id (int) – The channel ID to delete.

await delete_guild_emoji(guild_id, emoji_id)

Deletes an emoji in a guild.

Parameters:

• guild_id (int) – The ID of the guild the emoji is in.
• emoji_id (int) – The ID of the emoji to delete.

await delete_invite(invite_code)

Deletes the invite specified by the code.

Parameters:invite_code (str) – The code of the invite to delete.

await delete_message(channel_id, message_id)

Deletes a message.

This requires the MANAGE_MESSAGES permission.

Parameters:

• channel_id (int) – The channel ID that the message is in.
• message_id (int) – The message ID of the message.

await delete_multiple_messages(channel_id, message_ids)

Deletes multiple messages.

This will silently discard any messages that don’t exist.

This requires MANAGE_MESSAGES on the channel, regardless of what messages are being deleted.

Parameters:

• channel_id (int) – The channel ID to delete messages from.
• message_ids (List[int]) – A list of messages to delete.

await delete_reaction(channel_id, message_id, emoji, victim=None)

Deletes a reaction from a message.

Parameters:

• channel_id (int) – The channel ID of the channel containing the message.
• message_id (int) – The message ID to remove reactions from.
• emoji (str) – The emoji to remove.
• victim (Optional[int]) – The victim to remove. If this is None, our own reaction is removed.

await delete_role(guild_id, role_id)

Deletes a role.

Parameters:

• guild_id (int) – The guild ID that contains the role.
• role_id (int) – The role ID to delete.

await delete_webhook(webhook_id)

Deletes a webhook.

Parameters:webhook_id (int) – The ID of the webhook to delete.

await delete_webhook_with_token(webhook_id, token)

Deletes a webhook with a token.

Parameters:

• webhook_id (int) – The ID of the webhook to delete.
• token (str) – The token of the webhook.

await edit_channel(channel_id, *, name=None, position=None, topic=None, bitrate=None, user_limit=-1)

Edits a channel.

Parameters:

• channel_id (int) – The channel ID to edit.
• name (Optional[str]) – The new name of the channel.
• position (Optional[int]) – The new position of the channel.
• topic (Optional[str]) – The new topic of the channel.
• bitrate (Optional[int]) – The new bitrate of the channel.
• user_limit (int) – The user limit of the channel.

await edit_guild(guild_id, *, name=None, icon_content=None, region=None, verification_level=None, default_message_notifications=None, afk_channel_id=None, afk_timeout=None, splash_content=None, explicit_content_filter=None, system_channel_id=None)

Modifies a guild.

See https://discordapp.com/developers/docs/resources/guild#modify-guild for the fields available.

await edit_guild_emoji(guild_id, emoji_id, *, name=None, roles=None)

Modifies an emoji in a guild.

Parameters:

• guild_id (int) – The ID of the guild the emoji is in.
• emoji_id (int) – The ID of the emoji to modify.
• name (Optional[str]) – The name of the emoji to edit.
• roles (Optional[List[int]]) – A list of roles this emoji is limited to.

await edit_member_roles(guild_id, member_id, role_ids)

Modifies the roles that a member object contains.

Parameters:

• guild_id (int) – The guild ID that contains the objects.
• member_id (int) – The member ID to add the role to.
• role_ids (Iterable[int]) – The role IDs to add to the member.

await edit_member_voice_state(guild_id, member_id, *, deaf=None, mute=None, channel_id=None)

Edits the voice state of a member.

Parameters:

• guild_id (int) – The guild ID to edit in.
• member_id (int) – The member ID to edit.
• deaf (Optional[bool]) – Should the member be deafened?
• mute (Optional[bool]) – Should the member be muted?
• channel_id (Optional[int]) – What channel should the member be moved to?

await edit_message(channel_id, message_id, content=None, embed=None)

Edits a message.

This will only work on your own messages.

Parameters:

• channel_id (int) – The channel ID that the message is in.
• message_id (int) – The message ID of the message.
• content (Optional[str]) – The new content of the message.
• embed (Optional[dict]) – The new embed of the message.

await edit_overwrite(channel_id, target_id, type_, *, allow=0, deny=0)

Modifies or adds an overwrite.

Parameters:

• channel_id (int) – The channel ID to edit.
• target_id (int) – The target of the override.
• type (str) – The type the target is.
• allow (int) – The permission bitfield of permissions to allow.
• deny (int) – The permission bitfield of permissions to deny.

await edit_role(guild_id, role_id, name=None, permissions=None, position=None, colour=None, hoist=None, mentionable=None)

Edits a role.

Parameters:

• guild_id (int) – The guild ID that contains the role.
• role_id (int) – The role ID to edit.
• name (Optional[str]) – The new name of the role.
• permissions (Optional[int]) – The new permissions for the role.
• position (Optional[int]) – The position for the role.
• colour (Optional[int]) – The colour for the role.
• hoist (Optional[bool]) – Is this role hoisted?
• mentionable (Optional[bool]) – Is this role mentionable?

await edit_role_positions(guild_id, role_mapping)

Changes the position of a set of roles.

Parameters:

• guild_id (int) – The guild ID that contains the roles.
• role_mapping (List[Tuple[str, int]]) – An iterable of (role_id, new_position) values.

await edit_user(username=None, avatar=None, password=None)

Edits the profile of the bot.

Parameters:

• username (Optional[str]) – The new username of the bot, or None if it is not to be changed.
• avatar (Optional[str]) – The new avatar of the bot, or None if it not to be changed.
• password (Optional[str]) – The password of the bot. Only needed for user bots.

await edit_vanity_url(guild_id, code)

Edits the vanity URL for a guild.

Parameters:

• guild_id (int) – The guild ID to edit the vanity URL in.
• code (str) – The code of the vanity url (the part after the /).

await edit_webhook(webhook_id, *, name=None, avatar=None)

Edits a webhook.

Parameters:

• webhook_id (int) – The ID of the webhook to edit.
• name (Optional[str]) – The name of the webhook.
• avatar (Optional[str]) – The base64 encoded avatar to send.

await edit_webhook_with_token(webhook_id, token, *, name=None, avatar=None)

Edits a webhook, with a token.

Parameters:

• webhook_id (int) – The ID of the webhook to edit.
• token (str) – The token of the webhook to edit.
• name (Optional[str]) – The name of the webhook to edit.
• avatar (Optional[str]) – The base64 encoded avatar to send.

await edit_widget(guild_id, enabled=None, channel_id=0)

Edits the widget status for this guild.

Parameters:

• guild_id (int) – The guild ID to edit the widget of.
• enabled (Optional[bool]) – Is the widget enabled in this guild?
• channel_id (int) – What channel ID is the instant invite for? This can be None to disable the channel.

await execute_webhook(webhook_id, webhook_token, *, content=None, embeds=None, username=None, avatar_url=None, wait=False)

Executes a webhook.

Parameters:

• webhook_id (int) – The ID of the webhook to execute.
• webhook_token (str) – The token of this webhook.
• content (Optional[str]) – Any message content to send.
• embeds (Optional[List[Dict[~KT, ~VT]]]) – A list of embeds to send.
• username (Optional[str]) – The username to override with.
• avatar_url (Optional[str]) – The avatar URL to send.
• wait (bool) – If we should wait for the message to send.

await get(url, bucket, *args, **kwargs)

Makes a GET request.

Parameters:

• url (str) – The URL to request.
• bucket (str) – The ratelimit bucket to file this request under.

await get_app_info(application_id)

Gets some basic info about an application.

Parameters:application_id (Optional[int]) – The ID of the application to get info about. If this is None, it will fetch the current application info.

await get_application(application_id)

Gets an application by ID.

Parameters:application_id (int) – The ID of the application to get.

await get_audit_logs(guild_id, *, limit=50, user_id=None, action_type=None)

Gets the audit log for this guild.

Parameters:

• guild_id (int) – The guild ID to get audit logs for.
• limit (int) – The maximum number of entries to return.
• user_id (Optional[int]) – The user ID to filter by.
• action_type (Optional[int]) – The action type to filter by.

await get_authorized_apps()

Gets authorized apps for this account.

Warning

This is a user-account only endpoint.

await get_bans(guild_id)

Gets a list of bans from a guild.

Parameters:guild_id (int) – The guild to get bans from. Returns:A list of user dicts containing ban information.

await get_channel(channel_id)

Gets a channel.

Parameters:channel_id (int) – The channel ID to get.

await get_gateway_url()

It is not recommended to use this method - use HTTPClient.get_shard_count() instead. That method provides the gateway URL as well.

Returns:The websocket gateway URL to get.

await get_guild(guild_id)

Gets a guild by guild ID.

Parameters:guild_id (int) – The ID of the guild to get. Returns:A guild object.

await get_guild_channels(guild_id)

Gets a list of channels in a guild.

Parameters:guild_id (int) – The ID of the guild to get. Returns:A list of channel objects.

await get_guild_emoji(guild_id, emoji_id)

Gets an emoji object.

Parameters:

• guild_id (int) – The guild ID the emoji is in.
• emoji_id (int) – The emoji ID to get.

await get_guild_emojis(guild_id)

Gets the emojis for a guild.

Parameters:guild_id (int) – The guild ID to get emojis for.

await get_guild_member(guild_id, member_id)

Gets a guild member.

Parameters:

• guild_id (int) – The guild ID to get.
• member_id (int) – The member ID to get.

await get_guild_members(guild_id, *, limit=None, after=None)

Gets guild members for the specified guild.

Parameters:

• guild_id (int) – The ID of the guild to get.
• limit (Optional[int]) – The maximum number of members to get.
• after (Optional[int]) – The ID to fetch members after.

await get_invite(invite_code, *, with_counts=True)

Gets an invite by code.

Parameters:

• invite_code (str) – The invite to get.
• with_counts (bool) – Should the estimated total and online members be included?

await get_invites_for(guild_id)

Gets the invites for the specified guild.

Parameters:guild_id (int) – The guild ID to get invites inside.

await get_mentions(*, guild_id=None, limit=25, roles=True, everyone=True)

Gets your recent mentions.

Warning

This is a user-acount only endpoint.

Parameters:

• guild_id (Optional[int]) – The guild ID to limit mentions for.
• limit (int) – The maximum number of messages to return.
• roles (bool) – Should role mentions be included?
• everyone (bool) – Should @everyone/@here mentions be included?

await get_message(channel_id, message_id)

Gets a single message from the channel.

Parameters:

• channel_id (int) – The channel ID to get the message from.
• message_id (int) – The message ID of the message to get.

Returns:

The message data.

await get_message_history(channel_id, *, before=None, after=None, around=None, limit=100)

Gets a list of messages from a channel.

This requires READ_MESSAGES on the channel.

Parameters:

• channel_id (int) – The channel ID to receive messages from.
• before (Optional[int]) – Get messages before this snowflake.
• after (Optional[int]) – Get messages after this snowflake.
• around (Optional[int]) – Get messages around this snowflake.
• limit (int) – The maximum number of messages to return.

Returns:

A list of message dictionaries.

await get_pins(channel_id)

Gets the pins for a channel.

Parameters:channel_id (int) – The channel ID to get pins from.

get_ratelimit_lock(bucket)

Gets a ratelimit lock from the dict if it exists, otherwise creates a new one.

Return type:Lock

await get_reaction_users(channel_id, message_id, emoji)

Gets a list of users who reacted to this message with the specified reaction.

Parameters:

• channel_id (int) – The channel ID to check in.
• message_id (int) – The message ID to check.
• emoji (str) – The emoji to get reactions for.

staticmethod get_response_data()

Return either the text of a request or the JSON.

Parameters:response (Response) – The response to use. Return type:Union[str, dict]

await get_shard_count()

Returns:The recommended number of shards for this bot.

await get_this_user()

Gets the current user.

await get_user(user_id)

Gets a user from a user ID.

Parameters:user_id (int) – The ID of the user to fetch. Returns:A user dictionary.

await get_user_applications()

Gets the list of applications for a user.

await get_vanity_url(guild_id)

Gets the vanity URL for a guild.

Parameters:guild_id (int) – The guild ID to get the vanity URL of.

await get_webhook(webhook_id)

Gets a webhook object for the specified ID.

Parameters:webhook_id (int) – The ID of the webhook to get.

await get_webhooks_for_channel(channel_id)

Gets the webhooks for the specified channel.

Parameters:channel_id (int) – The ID of the channel to get the webhooks for.

await get_webhooks_for_guild(guild_id)

Gets the webhooks for the specified guild.

Parameters:guild_id (int) – The ID of the guild to get the webhooks for.

await get_widget_data(guild_id)

Gets the current widget data for a guild.

Parameters:guild_id (int) – The guild ID of the widget to fetch.

await get_widget_status(guild_id)

Gets the current widget status information for a guild.

Parameters:guild_id (int) – The guild ID to fetch.

await kick_member(guild_id, member_id)

Kicks a member from a guild.

Parameters:

• guild_id (int) – The guild ID to kick in.
• member_id (int) – The member ID to kick from the guild.

await leave_guild(guild_id)

Leaves a guild.

Parameters:guild_id (str) – The guild ID of the guild to leave.

await patch(url, bucket, *args, **kwargs)

Makes a PATCH request.

Parameters:

• url (str) – The URL to request.
• bucket (str) – The ratelimit bucket to file this request under.

await pin_message(channel_id, message_id)

Pins a message to the channel.

Parameters:

• channel_id (int) – The channel ID to pin in.
• message_id (int) – The message ID of the message to pin.

await post(url, bucket, *args, **kwargs)

Makes a POST request.

Parameters:

• url (str) – The URL to request.
• bucket (str) – The ratelimit bucket to file this request under.

await put(url, bucket, *args, **kwargs)

Makes a PUT request.

Parameters:

• url (str) – The URL to request.
• bucket (str) – The ratelimit bucket to file this request under.

await remove_overwrite(channel_id, target_id)

Removes an overwrite.

Parameters:

• channel_id (int) – The channel ID to edit.
• target_id (int) – The target of the override.

await request(bucket, *args, **kwargs)

Makes a rate-limited request.

This will respect Discord’s X-Ratelimit-Limit headers to make requests.

Parameters:bucket (object) – The bucket this request falls under.

await revoke_authorized_app(app_id)

Revokes an application authorization.

Warning

This is a user-acount only endpoint.

Parameters:app_id (int) – The ID of the application to revoke the authorization of.

await search_channel(channel_id, params)

Searches a channel.

Parameters:

• channel_id (int) – The channel ID of the channel to search.
• params (dict) – Params to search with.

await search_guild(guild_id, params)

Searches a guild.

Parameters:

• guild_id (int) – The guild ID of the guild to search.
• params (dict) – Params to search with.

await send_file(channel_id, file_content, *, filename=None, content=None)

Uploads a file to the current channel.

This will encode the data as multipart/form-data.

Parameters:

• channel_id (int) – The channel ID to upload to.
• file_content (bytes) – The content of the file being uploaded.
• filename (Optional[str]) – The filename of the file being uploaded.
• content (Optional[str]) – Any optional message content to send with this file.

await send_message(channel_id, content, tts=False, embed=None)

Sends a message to a channel.

Parameters:

• channel_id (int) – The ID of the channel to send to.
• content (str) – The content of the message.
• tts (bool) – Is this message a text to speech message?
• embed (Optional[dict]) – The embed dict to send with this message.

await send_typing(channel_id)

Starts typing in a channel.

Parameters:channel_id (str) – The ID of the channel to type in.

await unban_user(guild_id, user_id, reason=None)

Unbans a user from a guild.

Parameters:

• guild_id (int) – The ID of the guild to unban on.
• user_id (int) – The user ID that has been forgiven.
• reason (Optional[str]) – The reason for this unban.

await unpin_message(channel_id, message_id)

Unpins a message from the channel.

Parameters:

• channel_id (int) – The channel ID to unpin in.
• message_id (int) – The message ID of the message to unpin.

await update_channel_positions(channels)

Updates the positions of

await update_user_settings(**settings)

Updates the current user’s settings.

Warning

This is a user-acount only endpoint.

Parameters:settings – The dict of settings to update.

curious.core.httpclient.encode_multipart(fields, files, boundary=None)

Encode dict of form fields and dict of files as multipart/form-data. Return tuple of (body_string, headers_dict). Each value in files is a dict with required keys ‘filename’ and ‘content’, and optional ‘mimetype’ (if not specified, tries to guess mime type or uses ‘application/octet-stream’). >>> body, headers = encode_multipart({‘FIELD’: ‘VALUE’}, … {‘FILE’: {‘filename’: ‘F.TXT’, ‘content’: ‘CONTENT’}}, … boundary=’BOUNDARY’) >>> print(‘n’.join(repr(l) for l in body.split(‘rn’))) ‘–BOUNDARY’ ‘Content-Disposition: form-data; name=”FIELD”’ ‘’ ‘VALUE’ ‘–BOUNDARY’ ‘Content-Disposition: form-data; name=”FILE”; filename=”F.TXT”’ ‘Content-Type: text/plain’ ‘’ ‘CONTENT’ ‘–BOUNDARY–’ ‘’ >>> print(sorted(headers.items())) [(‘Content-Length’, ‘193’), (‘Content-Type’, ‘multipart/form-data; boundary=BOUNDARY’)] >>> len(body) 193 Copied from: https://code.activestate.com/recipes/578668-encode-multipart-form-data-for-uploading-files-via/

curious.core.httpclient.parse_date_header(header)

Parses a date header.

Parameters:header (str) – The contents of the header to parse. Return type:datetime Returns:A datetime.datetime that corresponds to the date header.