NAFF 1.11.0

NAFF 1.11.0

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: docs-builder
+on:
+  push:
+    branches:
+      - dev
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install -e .[docs]
+      - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+      - run: mkdocs gh-deploy
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}
+  DEPLOY: True

.pre-commit-config.yaml

@@ -40,5 +40,15 @@ repos:
           - flake8-print
           - flake8-dunder-all
         language_version: python3.10
+
+  # - repo: https://github.com/kumaraditya303/mirrors-pyright
+  #   rev: "v1.1.258"
+  #   hooks:
+  #     - id: pyright
+  #       args: [--warnings]
+
+exclude:
+  CNAME
+
 ci:
   autoupdate_branch: 'dev'

docs/src/API Reference/.pages

@@ -6,3 +6,5 @@ nav:
     - events
     - models
     - ext
+    - utils.md
+    - monopage.md

docs/src/API Reference/models/Naff/active_voice_state.md

@@ -1 +1,23 @@
+??? Hint "Example Usage:"
+    ```python
+    from naff import slash_command, slash_option, OptionTypes, InteractionContext
+    from naff.api.voice.audio import AudioVolume
+
+
+    @slash_command("play")
+    @slash_option("song", "The song to play", OptionTypes.STRING, required=True)
+    async def test_cmd(ctx: InteractionContext, song: str):
+        await ctx.defer()
+
+        if not ctx.voice_state:
+            await ctx.author.voice.channel.connect() # (1)!
+
+        await ctx.send(f"Playing {song}")
+        await ctx.voice_state.play(AudioVolume(song)) # (2)!
+    ```
+    { .annotate }
+
+    1.  This connects the bot to the author's voice channel if we are not already connected
+    2.  Check out the [Voice Support Guide](/Guides/22 Voice.html) for more info on audio playback
+
 ::: naff.models.naff.active_voice_state

docs/src/API Reference/models/Naff/checks.md

@@ -1 +1,12 @@
+??? Hint "Example Usage:"
+    ```python
+        from naff import check, has_any_role, slash_command
+
+        @slash_command(name='cmd')
+        @check(has_any_role(174918559539920897, 970018521511768094))
+        async def some_command(ctx):
+            ...
+
+
+    ```
 ::: naff.models.naff.checks

docs/src/API Reference/models/Naff/cooldowns.md

@@ -1 +1,14 @@
-::: naff.models.naff.command
+??? Hint "Example Usage:"
+    ```python
+    from naff import slash_command, cooldown, Buckets
+
+    @slash_command(name='cmd')
+    @cooldown(Buckets.user, 1, 10) # (1)!
+    async def some_command(ctx):
+        ...
+    ```
+    { .annotate }
+
+    1.  This will create a cooldown for each user; allowing them to use the command once every 10 seconds
+
+::: naff.models.naff.cooldowns

docs/src/API Reference/monopage.md

@@ -0,0 +1,105 @@
+---
+search:
+  exclude: true
+---
+# Mono-Doc
+This file holds the entire API reference in a single page; should that be your preference.
+
+[//]: # (":::: naff" - while this would be an option, the order sucks)
+
+---
+## Clients
+::: naff.client.client
+::: naff.client.auto_shard_client
+::: naff.models.naff.active_voice_state
+
+---
+## User
+::: naff.models.discord.user
+::: naff.models.discord.voice_state
+
+---
+## Guild
+::: naff.models.discord.guild
+::: naff.models.discord.scheduled_event
+::: naff.models.discord.sticker
+::: naff.models.discord.webhooks
+::: naff.models.discord.channel
+::: naff.models.discord.invite
+::: naff.models.discord.role
+::: naff.models.discord.emoji
+
+---
+## Message
+::: naff.models.discord.message
+::: naff.models.discord.reaction
+
+---
+## UX.
+::: naff.models.discord.embed
+::: naff.models.discord.asset
+::: naff.models.discord.color
+::: naff.models.discord.file
+
+---
+## Commands
+::: naff.models.naff.command
+::: naff.models.naff.prefixed_command
+
+---
+## Application Commands
+
+::: naff.models.discord.components
+::: naff.models.discord.modal
+::: naff.models.naff.application_commands
+
+---
+## Context
+::: naff.models.naff.context
+
+---
+## Presence
+::: naff.models.discord.activity
+
+---
+## Data
+::: naff.models.discord.application
+::: naff.models.discord.team
+::: naff.models.discord.enums
+::: naff.models.discord.timestamp
+
+---
+## naff Models
+::: naff.models.naff.extension
+::: naff.models.naff.cooldowns
+::: naff.models.naff.checks
+::: naff.models.naff.auto_defer
+::: naff.models.naff.annotations
+::: naff.models.naff.converters
+::: naff.models.naff.listener
+::: naff.models.naff.localisation
+::: naff.models.naff.tasks
+::: naff.models.naff.wait
+::: naff.models.misc.iterator
+
+---
+## API
+::: naff.api.gateway.state
+::: naff.api.gateway.gateway
+::: naff.api.voice.voice_gateway
+::: naff.api.http.http_client
+
+---
+## Voice
+::: naff.api.voice.audio
+::: naff.api.voice.player
+
+
+---
+## Errors
+::: naff.client.errors
+
+---
+## Events
+::: naff.api.events.discord
+::: naff.api.events.internal

docs/src/API Reference/utils.md

@@ -0,0 +1,21 @@
+These are a collection of utility methods that are used throughout the library. There are several more that are not included here, as they are reserved for internal use.
+
+!!! info
+    All of these methods can be imported from the `naff.client.utils` namespace
+
+## Formatting
+These methods are to help you format strings for messages.
+
+::: naff.client.utils.formatting
+
+## Attrs Utilities
+These methods are intended to be used with attrs dataclasses
+
+::: naff.client.utils.attr_converters
+
+::: naff.client.utils.attr_utils
+
+## Misc Utilities
+Uncategorized utilities, might be useful, might not.
+
+::: naff.client.utils.misc_utils

docs/src/CNAME

@@ -0,0 +1 @@
+naff.info

docs/src/FAQ.md

@@ -1,2 +1,7 @@
+---
+hide:
+  - navigation
+  - toc
+---
 !!! danger "Notice"
     This page is a placeholder, and will be populated at a later date.

docs/src/Guides/07 Creating Prefixed Commands.md

@@ -46,7 +46,7 @@ A user can use them like so:
 
 ## Parameters
 
-Often, when using prefixed commands, you typically want to parse in what the user says into seperated parameters/arguments. This can be done easily in this library using a Python-esque syntax.
+Often, when using prefixed commands, you typically want to parse what the user says into separated parameters/arguments. This can be done easily in this library using a Python-esque syntax.
 
 For example, to make a command that takes in one argument, we can do:
 ```python
@@ -79,7 +79,7 @@ async def test(ctx: PrefixedContext, arg1, arg2):
 
 ### Variable and Keyword-Only Arguments
 
-There may be times where you wish for an argument to be able to have multiple words without wrapping them in quotes. There are two ways of apporaching this.
+There may be times where you wish for an argument to be able to have multiple words without wrapping them in quotes. There are two ways of approaching this.
 
 #### Variable
 
@@ -121,7 +121,7 @@ The result looks like this:
 
 ### Basic Types
 
-Parameters, by default, are assumed to be strings, since `Message.content`, the content used for prefixed commands, is one. However, there are many times where you want to have a parameter be a more specific type, like a integer or boolean.
+Parameters, by default, are assumed to be strings, since `Message.content`, the content used for prefixed commands, is one. However, there are many times where you want to have a parameter be a more specific type, like an integer or boolean.
 
 `NAFF` provides an easy syntax to do so:
 
@@ -133,7 +133,7 @@ async def test(ctx: PrefixedContext, an_int: int, a_float: float):
 
 ![Basic Type Conversion](../images/PrefixedCommands/BasicTypeConversion.png "The above running with the arguments: 1 2.5")
 
-Words/arguments will automatically be converted to the specified type. If `NAFF` is unable to convert it (a user could easily pass a letter into `an_int`), then it will raise a `BadArgument` error, which can be handled by an error handler. Error handling is handled similarily to how it is handled with [slash commands](/Guides/03 Creating Commands).
+Words/arguments will automatically be converted to the specified type. If `NAFF` is unable to convert it (a user could easily pass a letter into `an_int`), then it will raise a `BadArgument` error, which can be handled by an error handler. Error handling is handled similarly to how it is handled with [slash commands](/Guides/03 Creating Commands).
 
 You can even pass in a function for parameters:
 
@@ -166,7 +166,7 @@ elif lowered in {"no", "n", "false", "f", "0", "disable", "off"}:
 
 ### Converters
 
-Converters work much of the same way as they do for other commands; see [the guide for converters for reference](/Guides/08 Converters).
+Converters work much in the same way as they do for other commands; see [the guide for converters for reference](/Guides/08 Converters).
 
 There are a few specific converters that only work with prefixed commands due to their nature, however.
 
@@ -177,7 +177,7 @@ Prefixed commands can be typehinted with some Discord models, like so:
 ```python
 @prefixed_command()
 async def poke(ctx: PrefixedContext, target: Member):
-    await ctx.send(f"{target.user.mention}, you got poked by {ctx.author.mention}!")
+    await ctx.reply(f"{target.mention}, you got poked by {ctx.author.mention}!")
 ```
 
 The argument here will automatically be converted into a `Member` object:
@@ -212,7 +212,7 @@ For example, you could use the following code:
 @prefixed_command()
 async def ban(ctx: PrefixedContext, member: Member, delete_message_days: Optional[int] = 0, *, reason: str):
     await member.ban(delete_message_days=delete_message_days, reason=reason)
-    await ctx.reply(f"Banned {member.user.mention} for {reason}. Deleted {delete_message_days} days of their messages.")
+    await ctx.reply(f"Banned {member.mention} for {reason}. Deleted {delete_message_days} days of their messages.")
 ```
 
 And if a user omits the `delete_message_days` parameter, it would act as so:
@@ -236,7 +236,7 @@ async def one_or_two(ctx: PrefixedContext, num: Literal[1, 2]):
 Using `typing.Annotated` can allow you to have more proper typehints when using converters:
 
 ```python
-class JudgementConverter(molter.Converter):
+class JudgementConverter(Converter):
     async def convert(self, ctx: PrefixedContext, argument: str):
         return f"{ctx.author.mention} is {argument}."
 
@@ -282,6 +282,6 @@ With the default options, the result looks like:
 ![Help Command](../images/PrefixedCommands/HelpCommand.png "The help command running.")
 
 ## Other Notes
-- Checks, cooldowns, and concurrency all works as-is with prefixed commands.
-- Prefixed commands uses a different method to process `Converter`s compared to slash commands. While they should roughly give the same result, they may act slightly differently.
+- Checks, cooldowns, and concurrency all work as-is with prefixed commands.
+- Prefixed commands use a different method to process `Converter`s compared to slash commands. While they should roughly give the same result, they may act slightly differently.
 - All prefixed commands use `PrefixedContext`, which contains useful information based on the current instance of the command.

docs/src/Guides/22 Voice.md

@@ -13,7 +13,7 @@ Now you've got those; let's make a simple play command to get you started.
 
 ```python
 import naff
-from naff.api.voice.audio import YTDLAudio
+from naff.api.voice.audio import AudioVolume
 
 
 @naff.slash_command("play", "play a song!")
@@ -25,8 +25,8 @@ async def play(self, ctx: naff.InteractionContext, song: str):
         await ctx.author.voice.channel.connect()
 
     # Get the audio using YTDL
-    audio = await YTDLAudio.from_url(song)
-    await ctx.send(f"Now Playing: **{audio.entry['title']}**")
+    audio = await AudioVolume(song)
+    await ctx.send(f"Now Playing: **{song}**")
     # Play the audio
     await ctx.voice_state.play(audio)
 ```
@@ -54,3 +54,21 @@ async def play_file(ctx: naff.InteractionContext):
 ```
 
 Check out [Active Voice State](/API Reference/models/naff/active_voice_state/) for a list of available methods and attributes.
+
+## Okay, but what about Soundcloud?
+
+NAFF has an extension library called [`NAFFAudio`](https://github.com/NAFTeam/NAFF-Audio) which can help with that.
+It has an object called `YTAudio` which can be used to play audio from Soundcloud and other video platforms.
+
+```
+pip install naff_audio
+```
+
+```python
+from naff_audio import YTAudio
+
+audio = await YTAudio.from_url("https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-4")
+await voice_state.play(audio)
+```
+
+`NAFFAudio` also contains other useful features for audio-bots. Check it out if that's your *jam*.