Pycord v3 Rewrite

REWRITE_OVERVIEW.md

@@ -1,87 +1,88 @@
-# Rewrite Overview
+# The Pycord Rewrite
 
-Complete overview of every breaking change
-made in v3, and why we made them.
+v3 aims at making an interface objectively easier to use, faster, and more intuitive than v2.
+To do this we have elected that breaking changes in any degree are tolerated.
 
-## Namespace
+This means, that with v3 we did not add constraints to differences in UI, or other such.
+That means that v3 will feel like a fundamentally different library as compared to v2.
+Do not expect v3 to be a drop-in replacement for v2. You will *most likely* have to rewrite
+the majority of your bot-facing code.
 
-By far one of the smallest yet most significant
-changes is our namespace.
-While v2 used to have the discord namespace
-for v3 to signify we're not a fork anymore
-we changed it to pycord.
+We do not have all of these "breaking changes" documented or covered, primarily because they
+aren't changes in their own right, they are a new way to do it. V3 is a rewrite of v2, so we
+do not have any obligation to hold back on necessary breaking changes, especially since we follow
+SemVer.
 
-So instead of `import discord` its just
-`import pycord` now.
 
-## Generalized Commands
+This document will justify and showcase many of these major breaking changes and show
+why they were made. So let's get started.
 
-In v3, commands have been restructured
-into one system to allow the easy creation
-of new ones.
 
-Instead of having `bot.slash_command` and the other types
-like in v2, you instead use our one decorator `bot.command`.
+### Bots
 
-Expansibility has been made a priority
-for v3, so we also made Commands easy to customize.
-Command creators provide a `cls` field to
-show which Command class they want to use.
-This is required and is not set to any default 
+Firstly is just your bot. Pycord v3 removes `commands.Bot` (we don't support prefix commands anymore,)
+and `Client` for just a single `Bot` class abstracting all of these things.
+
+We try to make the Bot class as extensible as possible so as to not force you to sub-class, but if needed,
+The opportunity is always there.
+
+`.run` has been removed from Bots, and bots must now have to be started manually.
+This forces developers to grapple with async i/o and makes it easier to do things like
+database connections before your bot starts.
 
-An example Slash Command could be the following:
 
 ```py
-import pycord
+# decorator for identifying commands, or parent commands.
+# sub commands should use a sort of `parent.command` design.
 
-bot = pycord.Bot(...)
+@command()
+async def echo(
+   cx: Context,
+   input: Annotated[str, Option(description="What do you want me to say?")]
+):
+   await cx.say(input)
 
-@bot.command('echo', pycord.ApplicationCommand, description='Command to echo a message')
-async def echo(inter: pycord.Interaction, msg: str = pycord.Option(name='message', description='The message to echo')):
-   await inter.resp.send(msg)
 
-bot.run(...)
-```
+# events now use classes instead of strings.
+# this is a much more extensible system and makes it easier for
+# developers to make extensions
 
-## Extensible Cache
+@listen()
+async def on_ready(event: Ready):
+   print(f"I'm online and logged into {event.user.name}!")
 
-Caching has been rebuilt to allow
-higher levels of extensibility.
 
-Do you want to cache on redis? Now you can!
-It's extremely easy, just subclass our
-Store class and rebuild it for your cacher.
+async def main():
+   bot = Bot(
+      token='token',
+      guild_ids=[...],
+      commands=[await echo.build()]
+   )
 
-## Extensions
+   await bot.start()
 
-### Cogs
 
-Cogs have been completely reformed from the
-ground up to build a brand new and better
-experience.
+if __name__ == "__main__":
+   asyncio.run(main())
+```
 
-To show that difference, we have renamed Cogs
-to Gears, also because it's particularly a better name.
+### Cogs are Gone.
 
-- Basic Cog with Slash Command
-  ```py
-     from discord.cogs import Cog
-     from discord.commands import slash_command
+As of version 3, Pycord will no longer be supporting Cogs in their current design.
+We will still support grouping your commands and listeners in separate files, just with a
+smarter and less object-oriented way.
 
-     class MyCog(Cog):
-        @slash_command
-        async def dunce(self) -> None:
-           ...
-   ```
 
-- Basic Gear with Slash Command
-  ```py
-     import pycord
-     from pycord.ext.gears import Gear
+```py
+async def setup():
+   return [
+      cx,
+      command,
+      listener
+   ]
+```
+
 
-     gear = Gear(__name__)
+# A tiny note
 
-     @gear.command('dunce', pycord.ApplicationCommand, type=1, description='duncy command')
-     async def dunce(inter: pycord.Interaction) -> None:
-        ...
-  ```
+There is still more content on the way! The more v3 develops, the more we'll add here :)

docs/conf.py

@@ -9,58 +9,58 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Pycord'
+project = "Pycord"
 
-copyright = '2021-present, Pycord Development'
-author = 'Pycord Development'
-release = '3.0.0'
+copyright = "2021-present, Pycord Development"
+author = "Pycord Development"
+release = "3.0.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.append(os.path.abspath('extensions'))
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.append(os.path.abspath("extensions"))
 
 extensions = [
-    'resourcelinks',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx',
+    "resourcelinks",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
 ]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-autodoc_member_order = 'bysource'
-autodoc_typehints = 'none'
+autodoc_member_order = "bysource"
+autodoc_typehints = "none"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named 'default.css' will overwrite the builtin 'default.css'.
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
-html_logo = 'https://raw.githubusercontent.com/Pycord-Development/pycord-v3/main/docs/assets/pycord-v3.png'
+html_logo = "https://raw.githubusercontent.com/Pycord-Development/pycord-v3/main/docs/assets/pycord-v3.png"
 
 # Any option(s) added to your certain theme.
 # in this case, Pydata
 html_theme_options = {
-    'footer_items': ['copyright', 'sphinx-version'],
+    "footer_items": ["copyright", "sphinx-version"],
 }
 
-html_sidebars = {'**': ['sidebar-nav-bs']}
+html_sidebars = {"**": ["sidebar-nav-bs"]}
 
 resource_links = {
-    'guide': 'https://guide.pycord.dev',
-    'repository': 'https://github.com/pycord-development/pycord-v3',
+    "guide": "https://guide.pycord.dev",
+    "repository": "https://github.com/pycord-development/pycord-v3",
 }
 
 # Links used for cross-referencing stuff in other documentation
 intersphinx_mapping = {
-    'py': ('https://docs.python.org/3', None),
-    'aio': ('https://docs.aiohttp.org/en/stable/', None),
+    "py": ("https://docs.python.org/3", None),
+    "aio": ("https://docs.aiohttp.org/en/stable/", None),
 }

docs/extensions/resourcelinks.py

@@ -35,10 +35,10 @@ def role(
 
 
 def add_link_role(app: Sphinx) -> None:
-    app.add_role('resource', make_link_role(app.config.resource_links))
+    app.add_role("resource", make_link_role(app.config.resource_links))
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
-    app.add_config_value('resource_links', {}, 'env')
-    app.connect('builder-inited', add_link_role)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    app.add_config_value("resource_links", {}, "env")
+    app.connect("builder-inited", add_link_role)
+    return {"version": sphinx.__display_version__, "parallel_read_safe": True}