Merge branch 'main' into discord-messages-colors-guide

4 files changed, 146 insertions, 0 deletions

diff --git a/pydis_site/apps/content/resources/guides/python-guides/discord-embed-limits.md b/pydis_site/apps/content/resources/guides/python-guides/discord-embed-limits.md
new file mode 100644
index 00000000..ca97462b
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/python-guides/discord-embed-limits.md
@@ -0,0 +1,21 @@
+---
+title: Discord Embed Limits
+description: A guide that shows the limits of embeds in Discord and how to avoid them.
+---
+
+If you plan on using embed responses for your bot you should know the limits of the embeds on Discord or you will get `Invalid Form Body` errors:
+
+- Embed **title** is limited to **256 characters**
+- Embed **description** is limited to **4096 characters**
+- An embed can contain a maximum of **25 fields**
+- A **field name/title** is limited to **256 character** and the **value of the field** is limited to **1024 characters**
+- Embed **footer** is limited to **2048 characters**
+- Embed **author name** is limited to **256 characters**
+- The **total of characters** allowed in an embed is **6000**
+
+Now if you need to get over this limit (for example for a help command), you would need to use pagination.
+There are several ways to do that:
+
+- A library called **[disputils](https://pypi.org/project/disputils)**
+- An experimental library made by the discord.py developer called **[discord-ext-menus](https://github.com/Rapptz/discord-ext-menus)**
+- Make your own setup using **[wait_for()](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.Bot.wait_for)** and wait for a reaction to be added
diff --git a/pydis_site/apps/content/resources/guides/python-guides/discordpy_help_command.md b/pydis_site/apps/content/resources/guides/python-guides/discordpy_help_command.md
new file mode 100644
index 00000000..4b475146
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/python-guides/discordpy_help_command.md
@@ -0,0 +1,66 @@
+---
+title: Custom Help Command
+description: "Overwrite discord.py's help command to implement custom functionality"
+---
+
+First, a basic walkthrough can be found [here](https://gist.github.com/InterStella0/b78488fb28cadf279dfd3164b9f0cf96) by Stella#2000 on subclassing the HelpCommand. It will provide some foundational knowledge that is required before attempting a more customizable help command.
+
+## Custom Subclass of Help Command
+If the types of classes of the HelpCommand do not fit your needs, you can subclass HelpCommand and use the class mehods to customize the output. Below is a simple demonstration using the following methods that can also be found on the documenation:
+
+- [filter_commands](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands)
+
+- [send_group_help](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.HelpCommand.send_bot_help)
+
+- [send_command_help](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.HelpCommand.send_command_help)
+
+- [send_group_help](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.HelpCommand.send_group_help)
+
+- [send_error_message](https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.HelpCommand.send_error_message)
+
+```python
+class MyHelp(commands.HelpCommand):
+
+    async def send_bot_help(self, mapping):
+        """
+        This is triggered when !help is invoked.
+
+        This example demonstrates how to list the commands that the member invoking the help command can run.
+        """
+        filtered = await self.filter_commands(self.context.bot.commands, sort=True) # returns a list of command objects
+        names = [command.name for command in filtered] # iterating through the commands objects getting names
+        available_commands = "\n".join(names) # joining the list of names by a new line
+        embed  = disnake.Embed(description=available_commands)
+        await self.context.send(embed=embed)
+
+    async def send_command_help(self, command):
+        """This is triggered when !help <command> is invoked."""
+        await self.context.send("This is the help page for a command")
+
+    async def send_group_help(self, group):
+        """This is triggered when !help <group> is invoked."""
+        await self.context.send("This is the help page for a group command")
+
+    async def send_cog_help(self, cog):
+        """This is triggered when !help <cog> is invoked."""
+        await self.context.send("This is the help page for a cog")
+
+    async def send_error_message(self, error):
+        """If there is an error, send a embed containing the error."""
+        channel = self.get_destination() # this defaults to the command context channel
+        await channel.send(error)
+
+bot.help_command = MyHelp()
+```
+
+You can handle when a user does not pass a command name when invoking the help command and make a fancy and customized embed; here a page that describes the bot and shows a list of commands is generally used. However if a command is passed in, you can display detailed information of the command. Below are references from the documentation below that can be utilised:
+
+- [Get the command object](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_command)
+
+- [Get the command name](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.name)
+
+- [Get the command aliases](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.aliases)
+
+- [Get the command brief](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief)
+
+- [Get the command usage](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.usage)
diff --git a/pydis_site/apps/content/resources/guides/python-guides/vps-services.md b/pydis_site/apps/content/resources/guides/python-guides/vps-services.md
new file mode 100644
index 00000000..0acd3e55
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/python-guides/vps-services.md
@@ -0,0 +1,31 @@
+---
+title: VPS Services
+description: On different VPS services
+---
+
+If you need to run your bot 24/7 (with no downtime), you should consider using a virtual private server (VPS). This is a list of VPS services that are sufficient for running Discord bots.
+
+* Europe
+    * [netcup](https://www.netcup.eu/)
+        * Germany & Austria data centres.
+        * Great affiliate program.
+    * [Yandex Cloud](https://cloud.yandex.ru/)
+        * Vladimir, Ryazan, and Moscow region data centres.
+    * [Scaleway](https://www.scaleway.com/)
+        * France data centre.
+    * [Time 4 VPS](https://www.time4vps.eu/)
+        * Lithuania data centre.
+* US
+    * [GalaxyGate](https://galaxygate.net/)
+        * New York data centre.
+        * Great affiliate program.
+* Global
+    * [Linode](https://www.linode.com/)
+    * [Digital Ocean](https://www.digitalocean.com/)
+    * [OVHcloud](https://www.ovhcloud.com/)
+    * [Vultr](https://www.vultr.com/)
+
+---
+# Free hosts
+There are no reliable free options for VPS hosting. If you would rather not pay for a hosting service, you can consider self-hosting.
+Any modern hardware should be sufficient for running a bot. An old computer with a few GB of ram could be suitable, or a Raspberry Pi.
diff --git a/pydis_site/apps/content/resources/guides/python-guides/why-not-json-as-database.md b/pydis_site/apps/content/resources/guides/python-guides/why-not-json-as-database.md
new file mode 100644
index 00000000..ae34c2b4
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/python-guides/why-not-json-as-database.md
@@ -0,0 +1,28 @@
+---
+title: Why JSON is unsuitable as a database
+description: The many reasons why you shouldn't use JSON as a database, and instead opt for SQL.
+relevant_links:
+    Tips on Storing Data: https://tutorial.vcokltfre.dev/tips/storage/
+---
+
+JSON, quite simply, is not a database. It's not designed to be a data storage format,
+rather a wayof transmitting data over a network. It's also often used as a way of doing configuration files for programs.
+
+There is no redundancy built in to JSON. JSON is just a format, and Python has libraries for it
+like json and ujson that let you load and dump it, sometimes to files, but that's all it does, write data to a file.
+There is no sort of DBMS (Database Management System), which means no sort of sophistication in how the data is stored,
+or built in ways to keep it safe and backed up, there's no built in encryption either - bear in mind
+in larger applications encryption may be necessary for GDPR/relevant data protection regulations compliance.
+
+JSON, unlike relational databases, has no way to store relational data,
+which is a very commonly needed way of storing data.
+Relational data, as the name may suggest, is data that relates to other data.
+For example if you have a table of users and a table of servers, the server table will probably have an owner field,
+where you'd reference a user from the users table. (**This is only relevant for relational data**).
+
+JSON is primarily a KV (key-value) format, for example `{"a": "b"}` where `a` is the key and `b` is the value,
+but what if you want to search not by that key but by a sub-key? Well, instead of being able to quickly use `var[key]`,
+which in a Python dictionary has a constant return time (for more info look up hash tables),
+you now have to iterate through every object in the dictionary and compare to find what you're looking for.
+Most relational database systems, like MySQL, MariaDB, and PostgreSQL have ways of indexing secondary fields
+apart from the primary key so that you can easily search by multiple attributes.