Getting started

Getting started with SBLPy

While the README.md file has some examples, since its just a brief overview, it doesn't provide much detail. So, here's how everything works.

Creating the SBLPy Client

SBLPy uses a class named "Client". This is the centralised class (when instantiated) that will control all of your SBLP HTTP related Functions. This ranges from receiving requests, and verifying them, calling your bump functions, to sending requests to other SBLP users soon:tm:.

Example:

from discord.ext import commands
from sblpy.revised import Client

bot = commands.Bot("prefix!")
bot.sblp = Client(
    bot,
    "bump_command_name",  # or the function itself.
    bump_cooldown=3600,  # defaults to 3600 (1 hour) anyway.
    require_authentication=True  # defaults to True. If True, authentication must be loaded (either manually or by the `auth_config_path` keyword.)
)

And that's it loaded and ready to go.

However, it hasn't quite finished.

Starting the server (to receive requests)

This is rather simple. Just requires 2 (technically 3) lines.

# somewhere
bot.sblp.init_server("127.0.0.1", port=8080, reload_on_file_edit=False)  # see "Explanation" below for details
bot.sblp.start_server()  # actually starts the server and allows for listening to new requests

That's all fine and dandy, but if you're like me and don't like random unsupressable error messages, you'll also probably want to close the server at some point.

# ...
# some cool code
# ...
bot.sblp.stop_server()

This will stop the internal server (and task), and change the internal state to false. This means you can then start the server up again later down the line should you require.

Explanation:

from sblpy.revised import Client

sblpy.revised is the part of the module that is maintained and clean. This houses the methods.

import Client is where you get the Client class from.

bot.sblp = Client(
    bot,
    "bump_command_name",  # or the function itself.
    bump_cooldown=3600,  # defaults to 3600 (1 hour) anyway.
    require_authentication=True  # defaults to True. If True, authentication must be loaded (either manually or by the `auth_config_path` keyword.)
)

This assigns a bot variable named sblp (which you can access anywhere by doing [self/ctx.]bot.sblp) that points to our Client.

• The first argument, bot, is the bot instance.
• The second argument, "bump_command_name" is the name of your bump command, or the actual function. Please remember you should always pass a function to this, unless you want to Jerry-rig your bump command to be context-less
• The third argument, the keyword bump_cooldown, is how long (in seconds) the cooldown on bumping is. Defaults to 3600 (1 hour)
• The fourth argument, keyword require_authentication, is a boolean of True or False. If False, the Client will not check for valid authentication when it receives a bump request via SBLP. It is not recommended to turn this off. You can add a configuration file or client.add_auth(source_url, source_token).
• the fifth (optional) argument, keyword auth_config_path, is a string path to your configuration file that houses your authentication. This can be changed later via client.load_config(path).

Adding authentication

There's two ways to do this:

1. Load a config file during client initialisation OR the load_config function
2. manually client.add_auth for each acceptable token

Solution 1:

config.json

{
    "Literally anything": "token",
}
// `token` is the authentication token that clients have to provide if they are to be able to verify.
// The token is unique per bot.
// NOTE: Please speak to Looat#0001 (422373229278003231) for more information on this, since I'm not too sure myself.

// "literally anything" is the "slug". While this may be used in the future to verify incoming requests, its currently just ignored and is simply there for human reading purposes.