API reference¶

Client¶

class pluralkit.Client(token=None, *, async_mode=True, user_agent=None, loop=None)¶

Represents a client that interacts with the PluralKit API.

Parameters:

token (Optional[str]) – The PluralKit authorization token, from the pk;token command.

Keyword Arguments:

async_mode – Whether the client runs asynchronously (True, default) or not (False).
user_agent – The User-Agent header to use with the API.
loop – The asyncio event loop to use (if async_mode=True), default is the current event loop.

token¶: The client’s PluralKit authorization token.

async_mode¶: Whether the client runs asynchronously (True) or not (False).

headers¶: The headers the client uses to communicate with the API.

add_group_members(group, members)¶

Add members to a group.

Not to be confused with Client.add_member_groups.

Parameters:

group (Union[GroupId, Group]) – The group to add the members to.
members (Sequence[Union[Member,MemberId]]) – The members to add to the group.

Return type:

None

add_member_groups(member, groups)¶

Add a member to each group in a given list of groups.

Not to be confused with Client.add_group_members.

Parameters:

member (Union[MemberId, str]) – The member to add to the groups.
groups (Sequence[Union[GroupId,Group]]) – The groups to add the member to.

Return type:

None

delete_group(group)¶

Remove a group from your system.

Parameters:: group (Union[GroupId, Group]) – Group reference (GroupId).
Return type:: None

delete_member(member)¶

Remove a member from your system.

Parameters:: member (Union[MemberId, str]) – Member reference (MemberId).
Return type:: None

delete_switch(switch)¶

Remove a logged switch from your system.

Parameters:: switch (Union[SwitchId, Switch]) – Switch reference (SwitchId).
Return type:: None

get_autoproxy_settings(guild_id)¶

Get the autoproxy settings of your system.

Parameters:: guild_id (int) – Discord guild ID.
Return type:: AutoproxySettings

get_fronters(system=None)¶

Get list of current fronters.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await:

async for member in client.get_fronters(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

fronters = [m async for m in client.get_fronters(...)]
...

Parameters:: system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.
Return type:: Sequence[Member]

get_group(group)¶

Get a group by its reference ID.

Parameters:: group (Union[GroupId, str]) – Group reference (GroupId).
Return type:: Group

get_group_members(group)¶

Get the list of members of a group.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await. For example:

async for member in client.get_group_members(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

members = [m async for m in client.get_group_members(...)]
...

Parameters:: group (Union[GroupId, str]) – Group reference (GroupId).
Return type:: Sequence[Member]

get_groups(system=None)¶

Get the list of a system’s groups.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await. For example:

async for group in client.get_groups(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

groups = [g async for g in client.get_groups(...)]
...

Parameters:: system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.
Return type:: Sequence[Group]

get_member(member)¶

Get a member by its reference ID.

Parameters:: member (Union[MemberId, str]) – Member reference (MemberId).
Return type:: Member

get_member_groups(member)¶

Get the list of groups a member is a part of.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await. For example:

async for group in client.get_member_groups(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

groups = [g async for g in client.get_member_groups(...)]
...

Parameters:: member (Union[Member, str]) – Member reference (MemberId).
Return type:: Sequence[Group]

get_member_guild_settings(guild_id, member)¶

Get the guild settings of a member.

Parameters:

guild_id (int) – Discord guild ID.
member (Union[MemberId, str]) – Member reference (MemberId).

Return type:

MemberGuildSettings

get_members(system=None)¶

Get the list of a system’s members.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await. For example:

async for member in client.get_members(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

members = [m async for m in client.get_members(...)]
...

Parameters:: system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.
Return type:: Sequence[Member]

get_message(message)¶

Get information about a proxied message.

Parameters:: message (int) – The Discord ID of a proxied message, or the Discord ID of the message that sent the proxy.
Return type:: Message

get_switch(switch, system=None)¶

Get switch information by its reference ID.

Parameters:: switch (Union[SwitchId, str]) – Switch reference (SwitchId).
Return type:: Switch

get_switches(system=None, *, before=None, limit=None)¶

Get list of system switches.

Returns at most 100 switches. To get additional, specify the before parameter.

Note

Because this is a batch API call, the Switch objects returned by this method have MemberId objects for Switch.members rather than full Member objects.

Hint

This method returns an async generator when the Client is in asynchronous mode (and with async_mode=False, it returns a list), so use the async for syntax instead of await:

async for switch in client.get_switches(...):
    ...

If you find a list preferable to an async generator, use a list comprehension such as

switches = [s async for s in client.get_switches(...)]
...

Parameters:

system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.

Keyword Arguments:

before – Timestamp before which to get latest switches from. Default is None (“now”).
limit – Number of switches to return. Default (and maximum) is 100.

Return type:

Sequence[Switch]

get_system(system=None)¶

Get a system by its reference ID.

Parameters:: system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authorization token.
Return type:: System

get_system_guild_settings(guild_id, system=None)¶

Get the guild settings of a system.

Parameters:

guild_id (int) – Discord guild ID.
system (Union[SystemId, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.

Return type:

SystemGuildSettings

get_system_settings(system=None)¶

Get a system’s settings (e.g. defaults, timezone, limits).

Parameters:: system (Union[SystemId, str, int, None]) – System reference; a system’s ID (SystemId) or the ID of a Discord account linked to the system. Default is None, for the system corresponding to the client’s authoirzation token.
Return type:: SystemSettings

new_group(name, **kwargs)¶

Create a new group

Parameters:

name (str) – Name of the group. 100 character limit.

Keyword Arguments:

display_name (str) – Group display name (100 character limit).
description (str) – Group description (1,000 character limit).
icon (str) – Group icon url (256 character limit).
banner (str) – Group banner url (256 character limit).
color (Color) – Group color.
name_privacy (Privacy) – Whether the group name is visible to others or only the display name. Default is public.
description_privacy (Privacy) – Whether the group description is visilbe to others. Default is public.
icon_privacy (Privacy) – Whether the group icon is visible to others. Default is public.
list_privacy (Privacy) – Whether the group member list is visible to others. Default is public.
metadata_privacy (Privacy) – Whether the groups’s metadata (i.e. created timestamp) is visible to others. Default is public.
visibility (Privacy) – Whether this group is visible to others (i.e. in group lists). Default is public.

Return type:

Group

new_member(name, **kwargs)¶

Create a new member in your system.

Parameters:

name (str) – The name of the new member. 100 character limit.

Keyword Arguments:

display_name (str) – Member display name (100 character limit).
color (Color) – Member color.
birthday (Birthday) – Member birthday.
pronouns (str) – Member pronouns (100 character limit).
avatar_url (str) – Member avatar url (256 character limit).
banner (str) – Member banner url (256 character limit).
description (str) – Member description (1,000 character limit).
proxy_tags (Union[ProxyTag,ProxyTags,Sequence[ProxyTag]]) – Member proxy tags.
keep_proxy (bool) – Whether to keep the proxy prefix and/or suffix for this member’s proxied messages.
visibility (Privacy) – Whether this member is visible to others (i.e. in member lists). Default is public.
name_privacy (Privacy) – Whether the member name is visible to others or only the display name. Default is public.
description_privacy (Privacy) – Whether the member description is visible to others. Default is public.
birthday_privacy (Privacy) – Whether the member birthday is visible to others. Default is public.
pronoun_privacy (Privacy) – Whether the member pronouns are visible to others. Default is public.
avatar_privacy (Privacy) – Whether the member avatar is visible to others. Default is public.
metadata_privacy (Privacy) – Whether the member’s metadata (i.e. created timestamp, message count) is visible to others. Default is public.

Return type:

Member

new_switch(members, timestamp=None)¶

Log a new switch.

Parameters:: members (Sequence[Union[MemberId,Member]]) – List of members in this switch.
Keyword Arguments:: timestamp (Timestamp) – Time of switch. None for “now” (default).
Return type:: Switch

remove_group_members(group, members)¶

Remove members from a group.

Not to be confused with Client.remove_member_groups.

Tip

If you want to remove all members from a group, consider using Client.set_group_members with no members.

Parameters:

group (Union[GroupId, Group]) – The group to remove the members from.
members (Sequence[Union[Member,MemberId]]) – The members to remove from the group.

Return type:

None

remove_member_groups(member, groups)¶

Remove a member from each group in a given list of groups.

Not to be confused with Client.remove_group_members.

Tip

If you want to remove all groups from a member, consider using Client.set_member_groups with no groups.

Parameters:

member (Union[MemberId, str]) – The member to remove from the groups.
groups (Sequence[Union[GroupId,Group]]) – The groups to remove the member from.

Return type:

None

set_group_members(group, members)¶

Remove members from a group.

Not to be confused with Client.set_member_groups.

An empty list is accepted, effectively removing all members from a group.

Parameters:

group (Union[GroupId, Group]) – The group to remove the members from.
members (Sequence[Union[Member,MemberId]]) – The members to assign to the group.

Return type:

None

set_member_groups(member, groups)¶

Explicitly set which groups a member belongs to.

Not to be confused with Client.set_group_members.

An empty list is accepted, effectively removing the member from any & all groups.

Parameters:

member (Union[MemberId, str]) – The member for which to set the groups.
groups (Sequence[Union[GroupId,Group]]) – The groups to assign to the member.

Return type:

None

update_autoproxy_settings(guild_id, autoproxy_mode, **kwargs)¶

Update your system’s autoproxy settings.

Parameters:

guild_id (int) – Discord guild ID.
autoproxy_mode (AutoproxyMode) – The autoproxy mode to use for this Discord server.

Keyword Arguments:

autoproxy_member (Union[MemberId,Member,None]) – The member to autoproxy, when autoproxy mode is set to AutoproxyMode.MEMBER.

Return type:

AutoproxySettings

update_group(group, **kwargs)¶

Update a group’s settings.

Parameters:

group (Union[GroupId, Group]) – Group reference (GroupId).

Keyword Arguments:

name (str) – Group name (100 character limit).
display_name (Optional[str]) – Group display name (100 character limit). None to clear.
description (Optional[str]) – Group description (1,000 character limit). None to clear.
icon (Optional[str]) – Group icon url (256 character limit). None to clear.
banner (Optional[str]) – Group banner url (256 character limit). None to clear.
color (Color) – Group color.
name_privacy (Optional[Privacy]) – Whether the group name is visible to others or only the display name. None to reset to default (public).
description_privacy (Optional[Privacy]) – Whether the group description is visilbe to others. None to reset to default (public).
icon_privacy (Optional[Privacy]) – Whether the group icon is visible to others. None to reset to default (public).
list_privacy (Optional[Privacy]) – Whether the group member list is visible to others. None to reset to default (public).
metadata_privacy (Optional[Privacy]) – Whether the groups’s metadata (i.e. created timestamp) is visible to others. None to reset to default (public).
visibility (Optional[Privacy]) – Whether this group is visible to others (i.e. in group lists). None to reset to default (public).

Return type:

Group

update_member(member, **kwargs)¶

Update a system member.

Parameters:

member (Union[MemberId, Member]) – Member reference (MemberId).

Keyword Arguments:

name (str) – Member name (100 character limit).
display_name (Optional[str]) – Member display name (100 character limit). None to clear.
color (Color) – Member color.
birthday (Optional[Birthday]) – Member birthday. None to clear.
pronouns (Optional[str]) – Member pronouns (100 character limit). None to clear.
avatar_url (Optional[str]) – Member avatar url (256 character limit). None to clear.
banner (Optional[str]) – Member banner url (256 character limit). None to clear.
description (Optional[str]) – Member description (1,000 character limit). None to clear.
proxy_tags (Union[ProxyTag,ProxyTags,Sequence[ProxyTag]]) – Member proxy tags. Use an empty list to remove the member’s set of proxy tags.
keep_proxy (bool) – Whether to keep the proxy prefix and/or suffix for this member’s proxied messages.
visibility (Optional[Privacy]) – Whether this member is visible to others (i.e. in member lists). None to reset to default (public).
name_privacy (Optional[Privacy]) – Whether the member name is visible to others or only the display name. None to reset to default (public).
description_privacy (Optional[Privacy]) – Whether the member description is visible to others. None to reset to default (public).
birthday_privacy (Optional[Privacy]) – Whether the member birthday is visible to others. None to reset to default (public).
pronoun_privacy (Optional[Privacy]) – Whether the member pronouns are visible to others. None to reset to default (public).
avatar_privacy (Optional[Privacy]) – Whether the member avatar is visible to others. None to reset to default (public).
metadata_privacy (Optional[Privacy]) – Whether the member’s metadata (i.e. created timestamp, message count) is visible to others. None to reset to default (public).

Return type:

Member

update_member_guild_settings(guild_id, member, **kwargs)¶

Update a member’s guild settings.

Parameters:

guild_id (int) – Discord guild ID.
member (Union[Member, MemberId]) – Member reference (MemberId).

Keyword Arguments:

display_name (Optional[str]) – Member display name (100 character limit). None to clear.
avatar_url (Optional[str]) – Member avatar url (256 character limit). None to clear.

Return type:

MemberGuildSettings

update_switch(switch, **kwargs)¶

Update a logged switch.

Parameters:

switch (Union[SwitchId, Switch]) – Switch reference (SwitchId).

Keyword Arguments:

timestamp – When the switch happened.
members (Sequence[Union[Member,MemberId]]) – The list of member IDs.

Return type:

Switch

update_system(**kwargs)¶

Update your system.

Keyword Arguments:

name (str) – System name (100 character limit).
description (Optional[str]) – System description (1,000 character limit). None to clear.
tag (str) – System tag (79 character limit).
pronouns (Optional[str]) – System pronouns (100 character limit). None to clear.
avatar_url (Optional[str]) – System avatar url (256 character limite). None to clear.
banner (Optional[str]) – System banner url (256 character limite). None to clear.
color (Color) – System color.
description_privacy (Optional[Privacy]) – System description privacy. None to reset (to public).
pronoun_privacy (Optional[Privacy]) – System pronoun privacy. None to reset (to public).
member_list_privacy (Optional[Privacy]) – System member list privacy. None to reset (to public).
group_list_privacy (Optional[Privacy]) – System group list privacy. None to reset (to public).
front_privacy (Optional[Privacy]) – System current fronter privacy. None to reset (to public).
front_history_privacy (Optional[Privacy]) – System front history privacy. None to reset (to public).

Return type:

System

update_system_guild_settings(guild_id, **kwargs)¶

Update your system’s guild settings.

Parameters:

guild_id (int) – Discord guild ID.

Keyword Arguments:

proxying_enabled (bool) – Whether the system can proxy messages in this guild.
tag (Optional[str]) – System tag in this guild (79 character limit). Use None to clear.
tag_enabled (bool) – Whether the system tag is enabled for this guild.

Return type:

SystemGuildSettings

update_system_settings(**kwargs)¶

Update your system settings.

Keyword Arguments:

timezone (Timezone) – System timezone. None resets to UTC.
pings_enabled (bool) – Whether other users are able to ping your system (with a 🔔 reaction).
latch_timeout (Optional[int]) – For autoproxy latch mode, this sets the amount of time elapsed since the last proxied message in the server that resets the latch. None resets to default (6 hr).
member_default_private (bool) – Whether member privacy is automatically set to private for new members. Applies only to new members created by the bot and not created by the PluralKit API directly.
group_default_private (bool) – Whether group privacy is automatically set to private for new groups. Applies only to new groups created by the bot and not created by the PluralKit API directly.
show_private_info (bool) – Whether the bot shows the system’s own private information without a -private flag.

Return type:

SystemSettings

Models¶

System¶

class pluralkit.System(json)¶

Represents a PluralKit system.

id¶

The system reference ID.

Type:: pluralkit.v2.models.SystemId

name¶

The system’s name.

Type:: Optional[str]

description¶

The system’s description.

Type:: Optional[str]

created¶

The system’s creation timestamp.

Type:: pluralkit.v2.models.Timestamp

tag¶

The system’s tag appended to display names.

Type:: Optional[str]

pronouns¶

The system’s pronouns.

Type:: Optional[str]

avatar_url¶

The system’s avatar url.

Type:: Optional[str]

banner¶

The system’s banner url.

Type:: Optional[str]

tz¶

The system’s tzdb timezone.

Type:: pluralkit.v2.models.Timezone

color¶

The system’s color.

Type:: Optional[pluralkit.v2.models.Color]

description_privacy¶

Whether the system’s description is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

pronoun_privacy¶

Whether the system’s pronouns are visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

member_list_privacy¶

Whether the system’s member list is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

group_list_privacy¶

Whether the system’s group list is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

front_privacy¶

Whether the system’s current fronter information is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

front_history_privacy¶

Whether the system’s front history is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

SystemSettings¶

class pluralkit.SystemSettings(json)¶

Represents a system’s settings.

timezone¶

The system’s timezone.

Type:: pluralkit.v2.models.Timezone

pings_enabled¶

Whether this system has pings enabled.

Type:: bool

latch_timeout¶

System’s autoproxy latch timeout.

Type:: Optional[int]

member_default_private¶

Whether members created through the bot have privacy settings set to private by default.

Type:: bool

group_default_private¶

Whether groups created through the bot have privacy settings set to private by default.

Type:: bool

show_private_info¶

Whether the bot shows the system’s own private information without requiring a -private flag.

Type:: bool

member_limit¶

System member limit, usually 1000.

Type:: int

group_limit¶

System group limit, usually 250.

Type:: int

AutoproxySettings¶

class pluralkit.AutoproxySettings(json, ignore_keys=None)¶

Represents a system’s autoproxy settings.

autoproxy_mode¶

The system’s autoproxy mode.

Type:: pluralkit.v2.models.AutoproxyMode

autoproxy_member¶

ID of current autoproxy member. (None if autoproxy mode is set to front.)

Type:: Optional[pluralkit.v2.models.MemberId]

last_latch_timestamp¶

Timestamp of last message. (None if autoproxy mode isn’t set to latch.)

Type:: Optional[pluralkit.v2.models.Timestamp]

SystemGuildSettings¶

class pluralkit.SystemGuildSettings(json, ignore_keys=None)¶

System settings for a specific server.

proxying_enabled¶

Whether proxying is enabled in the given server.

Type:: bool

tag¶

The system’s tag (appended to the server username) for the given server.

Type:: Optional[str]

tag_enabled¶

Whether or not the system tag is shown in this server.

Type:: bool

Member¶

class pluralkit.Member(json)¶

Represents a PluralKit system member.

id¶

The member reference ID.

Type:: pluralkit.v2.models.MemberId

system¶

The ID of the system this member belongs to.

Type:: pluralkit.v2.models.SystemId

name¶

The member’s name.

Type:: str

created¶

The member’s creation timestamp.

Type:: pluralkit.v2.models.Timestamp

display_name¶

The member’s display name.

Type:: Optional[str]

description¶

The member’s description.

Type:: Optional[str]

color¶

The member’s color.

Type:: Optional[pluralkit.v2.models.Color]

birthday¶

The member’s birthday.

Type:: Optional[pluralkit.v2.models.Birthday]

pronouns¶

The member’s pronouns.

Type:: Optional[str]

avatar_url¶

The member’s main avatar url that appears uncropped on the member card.

Type:: Optional[str]

webhook_avatar_url¶

The member’s avatar url used for proxied messages instead of the main avatar.

Type:: Optional[str]

banner¶

The member’s banner url.

Type:: Optional[str]

proxy_tags¶

The member’s proxy tags.

Type:: Optional[pluralkit.v2.models.ProxyTags]

keep_proxy¶

Whether the member’s proxy tags remain in the proxied message or not.

Type:: bool

name_privacy¶

Whether the member name is visible to others or only the display name.

Type:: Optional[pluralkit.v2.models.Privacy]

description_privacy¶

Whether this member’s description is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

birthday_privacy¶

Whether the member’s birthday is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

pronoun_privacy¶

Whether the member’s pronouns are visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

avatar_privacy¶

Whether the member’s avatar is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

metadata_privacy¶

Whether the member’s metadata (i.e. creation timestamp, message count) is visible to others.

Type:: Optional[pluralkit.v2.models.Privacy]

visibility¶

Whether this member is visible to others (i.e. in member lists).

Type:: Optional[pluralkit.v2.models.Privacy]

autoproxy_enabled¶

Whether this member has autoproxy enabled. None if the member is not from the client’s system.

Type:: Optional[bool]

message_count¶

Member message count. None if the member’s metadata privacy is set to private and the member is not from the client’s system.

Type:: Optional[int]

last_message_timestamp¶

Timestamp of member’s last message. None if the member’s metadata privacy is set to private and the member is not from the client’s system.

Type:: Optional[pluralkit.v2.models.Timestamp]

MemberGuildSettings¶

class pluralkit.MemberGuildSettings(json, ignore_keys=None)¶

Member settings for a specific server.

display_name¶

The member’s display name in the guild.

Type:: Optional[str]

avatar_url¶

The URL of the member’s avatar image in the guild.

Type:: Optional[str]

Group¶

class pluralkit.Group(json)¶

Represents a PluralKit system group.

id¶

The group reference ID.

Type:: Optional[pluralkit.v2.models.GroupId]

system¶

The ID of the system this group belongs to.

Type:: pluralkit.v2.models.SystemId

name¶

Group name.

Type:: str

display_name¶

Group display name.

Type:: Optional[str]

description¶

Group description.

Type:: Optional[str]

icon¶

Group icon url.

Type:: Optional[str]

banner¶

Group banner url.

Type:: Optional[str]

color¶

Group color.

Type:: Optional[pluralkit.v2.models.Color]

created¶

The group’s creation timestamp.

Type:: pluralkit.v2.models.Timestamp

name_privacy¶

Whether the group name is visible to others or only the display name.

Type:: pluralkit.v2.models.Privacy

description_privacy¶

Whether the group description is visilbe to others.

Type:: pluralkit.v2.models.Privacy

icon_privacy¶

Whether the group icon is visible to others.

Type:: pluralkit.v2.models.Privacy

list_privacy¶

Whether the group member list is visible to others.

Type:: pluralkit.v2.models.Privacy

metadata_privacy¶

Whether the groups’s metadata (i.e. created timestamp) is visible to others.

Type:: pluralkit.v2.models.Privacy

visibility¶

Whether this group is visible to others (i.e. in group lists).

Type:: pluralkit.v2.models.Privacy

Switch¶

class pluralkit.Switch(json)¶

Represents a switch event.

Note

members can either be a list of Member models or a list of MemberId objects, depending on the client method used.

In particular, switch models from Client.get_switches carry MemberId objects, whereas switch models from get_switch, new_switch, and update_switch carry full Member objects.

id¶

Switch’s unique universal identifier (uuid).

Type:: pluralkit.v2.models.SwitchId

timestamp¶

Timestamp of the switch.

Type:: pluralkit.v2.models.Timestamp

members¶

Members involved.

Type:: Union[Sequence[pluralkit.v2.models.Member], Sequence[pluralkit.v2.models.MemberId]]

Message¶

class pluralkit.Message(json)¶

Represents a proxied message.

timestamp¶

Timestamp of the message.

Type:: pluralkit.v2.models.Timestamp

id¶

The ID of the Discord message sent by the webhook.

Type:: int

original¶

The ID of the (presumably deleted) original Discord message sent by the account.

Type:: int

sender¶

The user ID of the account that sent the message.

Type:: int

channel¶

The ID of the channel the message was sent to.

Type:: int

guild¶

The ID of the guild the message was sent in.

Type:: int

system¶

The system that proxied the message. None if system was deleted.

Type:: Optional[pluralkit.v2.models.System]

member¶

The member that proxied the message. None if member was deleted.

Type:: Optional[pluralkit.v2.models.Member]

Primitives¶

SystemId¶

class pluralkit.SystemId(id=None, uuid=None)¶: System IDs.

MemberId¶

class pluralkit.MemberId(id=None, uuid=None)¶: Member IDs.

GroupId¶

class pluralkit.GroupId(id=None, uuid=None)¶: Group IDs.

Birthday¶

class pluralkit.Birthday(dt=None, *, year=None, month=None, day=None, hour=0, minute=0, second=0, microsecond=0)¶

Represents a birthday.

This model inherits from Timestamp.

staticmethod from_json(bd)¶

Takes in a string (as returned by the API) and returns the Birthday.

Parameters:: bd (str) – The YYYY-MM-DD formatted string representing the birthdate.
Returns:: The corresponding birthday.
Return type:: Birthday

property hidden_year: bool¶

Whether this birthday’s year is hidden.

If set to False, sets the birthday’s year to 0001, which internally represents a hidden year in PluralKit’s API.

Return type:: bool

json()¶

Returns the YYYY-MM-DD formatted birthdate.

Return type:: str

Color¶

class pluralkit.Color(*args, **kwargs)¶

Represents a color.

This class is initialized in the same way that a colour.Color object is. It may also take a colour.Color object directly.

json()¶: Return a JSON object representing this model.

ProxyTag¶

class pluralkit.ProxyTag(prefix=None, suffix=None, *, proxy_tag=None)¶

Represents a single PluralKit proxy tag.

Hint

A ProxyTag object can be called to see if it would match a message:

>>> pt = ProxyTag("{", "}")
>>> pt("This is an example.")
False
>>> pt("{This is another example.}")
True

Parameters:

prefix (Optional[str]) – Prefix that will enclose proxied messages.
suffix (Optional[str]) – Suffix that will enclose proxied messages.

Keyword Arguments:

proxy_tag – Dictionary representing a proxy tag. Must have at least one of prefix or suffix as keys. The prefix and suffix args will overrule this dict.

Important

At least one of the suffix or prefix arguments must be passed.

prefix¶

Prefix that will enclose proxied messages.

Type:: Optional[str]

suffix¶

Suffix that will enclose proxied messages.

Type:: Optional[str]

json()¶

Return the JSON object representing this proxy tag as a Python dict.

Return type:: Dict[str, Optional[str]]

ProxyTags¶

class pluralkit.ProxyTags(proxy_tags=None)¶

Represents a set of PluralKit proxy tags.

Hint

A ProxyTags object can be called to see if it would match a message:

>>> pt_1 = ProxyTag("{", "}")
>>> pt_2 = ProxyTag("A:")
>>> pts = ProxyTags([pt_1, pt_2])
>>> pts("{This is an example.}")
True
>>> pts("A: This is another example.")
True

Hint

ProxyTags objects can be iterated or indexed to yield its underlying ProxyTag objects.

Parameters:: proxy_tags (Optional[Generator[ProxyTag, None, None]]) – A sequence of ProxyTag objects.

json()¶

Return the JSON object representing this proxy tag as a list of Python dict.

Return type:: List[Dict[str, str]]

Timestamp¶

class pluralkit.Timestamp(dt=None, *, year=None, month=None, day=None, hour=0, minute=0, second=0, microsecond=0)¶

Represents a PluralKit UTC timestamp.

This class works by wrapping around a datetime object. Use ts.datetime to access it, for any Timestamp ts.

This class may be initialized in the same way that a datetime object is. It may also take a datetime object, a Timestamp object, or an ISO 8601 formatted string directly.

json()¶

Convert this timestamp to the ISO 8601 format that PluralKit uses internally.

Return type:: str

Timezone¶

class pluralkit.Timezone(tz)¶

Represents a tzdb time zone.

This class is initialized in the same way that pytz.timezone initializes tzinfo objects. It may also take a tzinfo object directly.

Hint

Here is a link to a list of tz database time zones

Parameters:: tz (Union[str,tzinfo]) – The timezone, either as a string or as a tzinfo (e.g. from pytz.timezone).

json()¶: Returns the string representation of this timezone as expected by the API.

Enumerations¶

AutoproxyMode¶

class pluralkit.AutoproxyMode(value)¶

Represents the autproxy modes.

OFF = 'off'¶: Represents disabled autoproxying.

FRONT = 'front'¶: Represents front-mode autoproxying, when messages are proxied as the current first fronter of the system.

LATCH = 'latch'¶: Represents latch-mode autoproxying, when messages are proxied as the last proxied member.

MEMBER = 'member'¶: Represents member-mode autoproxying, when messages are proxied as a specified member.

Privacy¶

class pluralkit.Privacy(value)¶

Represents the privacies accepted by PluralKit.

In general, default privacies are public.

PUBLIC = 'public'¶: Represents a public PluralKit privacy setting.

PRIVATE = 'private'¶: Represents a private PluralKit privacy setting.

Exceptions¶

PluralKitException¶

class pluralkit.PluralKitException¶: Base exception class for pluralkit.py

HTTPError¶

class pluralkit.HTTPError¶: General PluralKit exception class for unexpected HTTP codes (e.g. 500).

GenericBadRequest¶

class pluralkit.GenericBadRequest¶: Thrown when the API server informs the client that the request was malformed (400).

NotFound¶

class pluralkit.NotFound¶: Thrown when the resource cannot be found (404).

SystemNotFound¶

class pluralkit.SystemNotFound¶: Thrown when the System ID is apparently not in PluralKit’s database (404).

MemberNotFound¶

class pluralkit.MemberNotFound¶: Thrown when the Member ID is apparently not in PluralKit’s database (404).

GroupNotFound¶

class pluralkit.GroupNotFound¶: Thrown when the Group ID is apparently not in PluralKit’s database (404).

SwitchNotFound¶

class pluralkit.SwitchNotFound¶: Thrown when the Switch ID is apparently not in PluralKit’s database (404).

MessageNotFound¶

class pluralkit.MessageNotFound¶: Thrown when the message ID is apparently not in PluralKit’s database (404).

GuildNotFound¶

class pluralkit.GuildNotFound¶: Thrown when the member or system has no guild settings for a given guild (404).

Unauthorized¶

class pluralkit.Unauthorized¶: Thrown when the authorization token passed to PluralKit’s API is invalid or missing (403).

NotOwnSystem¶

class pluralkit.NotOwnSystem¶: Thrown when the client doesn’t have access to a system’s private info (403).

NotOwnMember¶

class pluralkit.NotOwnMember¶: Thrown when the client doesn’t have access to a member’s private info (403).

NotOwnGroup¶

class pluralkit.NotOwnGroup¶: Thrown when the client doesn’t have access to a group’s private info (403).

Getting started Version history

pluralkit.py v1.1.5 docs

API reference¶

Client¶

Models¶

System¶

SystemSettings¶

AutoproxySettings¶

SystemGuildSettings¶

Member¶

MemberGuildSettings¶

Group¶

Switch¶

Message¶

Primitives¶

SystemId¶

MemberId¶

GroupId¶

Birthday¶

Color¶

ProxyTag¶

ProxyTags¶

Timestamp¶

Timezone¶

Enumerations¶

AutoproxyMode¶

Privacy¶

Exceptions¶

PluralKitException¶

HTTPError¶

GenericBadRequest¶

NotFound¶

SystemNotFound¶

MemberNotFound¶

GroupNotFound¶

SwitchNotFound¶

MessageNotFound¶

GuildNotFound¶

Unauthorized¶

NotOwnSystem¶

NotOwnMember¶

NotOwnGroup¶