DisCum Documentation

The docs/using.md file serves as a high-level table of contents for the DisCum library. It organizes documentation into logical functional areas to help you find specific implementation guides:

• Get Started: Installation and client initialization.
• General Functions and Variables: Logging, gateway variables, and utility functions (e.g., snowflake conversion).
• Start: Authentication and initial handshake actions (REST and Gateway).
• User: Actions related to user profiles, settings, security (2FA), and connections.
• Science/Analytics: Client UUID management and analytics requests.
• Guild: Guild management, member/role manipulation, and thread operations.
• DMs: Direct Message and Group DM management.
• Channels: Channel and invite management.
• Messages: Sending, editing, deleting, and searching messages.
• Stickers: Sticker data and file retrieval.
• Media/Calling: Gateway-based call management.

If you cannot see any channels in a guild, or if you need to scrape the entire member list (including offline members), use the query-based search method via bot.gateway.queryGuildMembers. This uses Discord's opcode 8.

When to use

• Use this when you have no visibility into guild categories/channels.
• Pros: Can potentially get the entire member list and can scrape multiple guilds simultaneously.
• Cons: It is significantly slower as it relies on a brute-force optimization algorithm.

Usage

To use the brute-force search, you typically invoke a command that runs the search algorithm. A wait time of at least 0.5 is recommended to prevent frequent rate limiting.

Capabilities

• With member-viewing permissions: You can fetch all members. Use limit=0 and keep="all" to attempt a full scrape.
• Without member-viewing permissions: You are limited to the first 100 members if many users share the same nickname/username (since discriminators cannot be searched).

# Example: Full guild search if permissions allow
@bot.gateway.command
def test(resp):
    if resp.event.ready_supplemental:
        # limit=0 and keep="all" attempts to get everyone
        bot.gateway.queryGuildMembers(['guildID'], '', limit=0, keep="all")
    if resp.event.guild_members_chunk and bot.gateway.finishedGuildSearch(['guildID'], ''):
        bot.gateway.close()

bot.gateway.run()

You can fetch members by simulating the client's member list sidebar behavior using bot.gateway.fetchMembers. This method uses Discord's opcode 14.

When to use

• Use this if you can see any categories or channels in the guild.
• Pros: It is fast.
• Cons: In large servers (where bot.gateway.session.guild('GUILD_ID').large == True), only members who are currently online will be fetched.

Methods

DisCum supports two ways to subscribe to member ranges:

1. overlap: Subscribes to ranges that overlap to ensure coverage. Example sequence: [[0,99], [100,199]] -> [[0,99], [100,199], [200,299]].
2. nonoverlap: Subscribes to distinct ranges. Example sequence: [[0,99], [100,199]] -> [[0,99], [200,299], [300,399]]. This is faster (approx. 200 members/sec vs 100 members/sec for overlap) but less reliable/consistent.

Implementation Details

The algorithm involves:

1. Loading guild data (sending an op14 with range [0,99]).
2. Subscribing to a list of ranges in the member list sidebar.
3. Updating the saved member list data and subscribing to new ranges upon receiving a GUILD_MEMBER_LIST_UPDATE event.

# Example using the overlap method
bot.gateway.fetchMembers(guild_id, channel_id, method="overlap")

Gateway extensions follow a structured pattern involving three types of wrappers: request, parse, and combo. These are organized into folders (dms, guild, media, messages, user) containing __init__.py, combo.py, parse.py, and request.py.

1. Implement the Wrapper Type

Request Wrappers

Located in request.py. These send messages to Discord via the gateway. The core requirement is calling self.gatewayobject.send(data).

Parse Wrappers

Located in parse.py. These transform raw gateway responses into usable data.

• Must be a @staticmethod (unless using __init__).
• The first parameter must be the response.
• Must return a value.
• Naming convention: Use lowercase versions of the event types (e.g., GUILD_MEMBER_LIST_UPDATE becomes guild_member_list_update).

Combo Wrappers

Located in combo.py. These combine request and parse functions. They are often used for complex flows that require multiple responses or self-removing commands.

2. Wrap the Wrapper

• Parse wrappers are wrapped in gateway/parse.py.
• Request wrappers are wrapped in gateway/request.py.
• Combo wrappers are wrapped in gateway/gateway.py using the self.command method.

# Request wrapper example (gateway/guild/request.py)
def searchGuildMembers(self, guild_ids, query, limit, presences, user_ids):
    if isinstance(guild_ids, str):
        guild_ids = [guild_ids]
    data = {
        "op": self.gatewayobject.OPCODE.REQUEST_GUILD_MEMBERS,
        "d": {"guild_id": guild_ids},
    }
    if isinstance(user_ids, list):
        data["d"]["user_ids"] = user_ids
    else:
        data["d"]["query"] = query
        data["d"]["limit"] = limit
        data["d"]["presences"] = presences
    self.gatewayobject.send(data)

# Parse wrapper example (gateway/messages/parse.py)
@staticmethod
def message_create(response):
    message = response["d"]
    # ... logic to map message["type"] ...
    return message

# Combo wrapper registration (gateway/gateway.py)
def testfuncPOG(self, pog):
    self.command({'function': Guild(self).testfuncPOG, 'priority': 0, 'params': {'pog': pog}})

To add new HTTP API endpoints to Discum, you must implement the logic in a nested module file and then expose it in the main discum.py file.

1. Implement the Wrapper

Add the new method to the appropriate class within the nested directory structure (e.g., discum/messages/messages.py). Use Wrapper.sendRequest with the appropriate HTTP method.

2. Wrap the Wrapper

Expose the new method in discum.py to make it accessible to the end-user. This step handles organization and provides access to the necessary session and logging objects.

Required context for the wrapper:

• self.discord: The Discord API URL (e.g., https://discord.com/api/v9/).
• self.s: The current client's requests session.
• self.log: The logging configuration object.

# Example GET wrapper in a nested file
def wrapper(*args):
    url = "url"
    return Wrapper.sendRequest(self.s, 'get', url, log=self.log)

# Example POST wrapper in a nested file
def wrapper(*args):
    url = "url"
    body = {"something": something, ...}
    return Wrapper.sendRequest(self.s, 'post', url, body, log=self.log)

# Example of wrapping the wrapper in discum.py
def createDM(self, recipients):
    return Messages(self.discord, self.s, self.log).createDM(recipients)