feat: Use docstrings to provide descriptions for arguments

Author: mwja

README.md

@@ -41,20 +41,32 @@ async def foo(ctx: SlashContext, member: discord.Member):
 
 ### Descriptions
 
-By default, each argument has the description `No description`, but that can be changed by providing a `Tuple` of any type and a `Literal`.
+By default, each argument and command has the description `No description`, but that can be changed by providing a docstring. Docstrings are supported as provided by [docstring-parser](https://pypi.org/project/docstring-parser/) — *at time of writing, that is [ReST](https://www.python.org/dev/peps/pep-0287/), [Google](https://google.github.io/styleguide/pyguide.html), and [Numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html).*
 ```python
 from typing import Tuple, Literal
 
 # ...
 
-description = Literal["my description here"]
 @s.slash()
-async def foo(ctx: SlashContext, member: Tuple[discord.Member, description]):
-    # This command will automatically be called 'foo', and the argument member
-    # will have the description "my description here"
+async def foo(ctx: SlashContext, member: discord.Member):
+    """
+    My command description here!
+
+    :param member: my description here
+    """
+    # This command will automatically be called 'foo', and have the description
+    # "My command description here!", and the argument `member` will have the
+    # description "my description here".
     await ctx.send(f"Hello, {member.mention}")
 ```
 
+It's also possible to pass the command description through the decorator as follows, although that's not recommended (and will override any docstring provided description):
+```python
+@s.slash(description="My description!")
+async def command(ctx):
+    pass
+```
+
 ## Advanced usage
 The same usage applies for cogs, but a different function is used.
 

pyslash/__init__.py

@@ -8,4 +8,4 @@
 from .converters import convert
 from .decorators import slash, slash_cog
 
-__version__ = "1.1.1"
+__version__ = "1.2.0rc1"

pyslash/decorators.py

@@ -26,7 +26,7 @@ def slash_cog(name: str = None, description: str = None, guild_ids: List[int] =
     def decorator(function):
         # Use annotations
         params, converter_params = get_slash_kwargs(
-            name, description, guild_ids, remove_underscore_keywords, function)
+            function, name, description, guild_ids, remove_underscore_keywords)
         return cog_ext.cog_slash(**params)(convert(**converter_params)(function))
 
     return decorator
@@ -53,7 +53,7 @@ def slash(slash_class: SlashCommand, name: str = None, description: str = None,
     def decorator(function):
         # Use annotations
         params, converter_params = get_slash_kwargs(
-            name, description, guild_ids, remove_underscore_keywords, function)
+            function, name, description, guild_ids, remove_underscore_keywords)
         return slash_class.slash(**params)(convert(**converter_params)(function))
 
     return decorator

pyslash/utils.py

@@ -1,12 +1,14 @@
 import inspect
 import keyword
-from typing import Any, List, Literal, Union
+from typing import Any, Dict, List, Literal, Union
 
 from discord.ext import commands
 from discord.ext.commands.errors import CommandError
 from discord_slash.context import SlashContext
 from discord_slash.model import SlashCommandOptionType
 from discord_slash.utils.manage_commands import create_choice, create_option
+from docstring_parser import parse
+from docstring_parser.common import DocstringParam
 
 
 class InvalidParameter(CommandError):
@@ -105,34 +107,61 @@ def get_slash_command_type(annotation: Any) -> SlashCommandOptionType:
     InvalidParameter
         No parameter type could be found
     """
+    root_type = get_root_type(annotation)
+
     # If it's a converter or an optional of a converter, it will always be a string
-    if issubclass(get_root_type(annotation), commands.Converter):
+    if issubclass(root_type, commands.Converter):
         return SlashCommandOptionType.STRING
 
-    type_ = SlashCommandOptionType.from_type(get_root_type(annotation))
+    # Otherwise, try to fetch from enum
+    type_ = SlashCommandOptionType.from_type(root_type)
     if type_ is None:
         raise InvalidParameter(
             f"Parameter: {str(annotation)} does not match any Discord type")
 
     return type_
 
 
-def get_slash_kwargs(name: str, description: str, guild_ids: List[int], remove_underscore_keywords: bool, function):
+def get_descriptions(params: List[DocstringParam]) -> Dict[str, str]:
+    """
+    Turn a list of docstring paramsinto a dictionary
+
+    Parameters
+    ----------
+    params : List[DocstringParam]
+        The docstring params
+
+    Returns
+    -------
+    Dict[str, str]
+        The dictionary of parameter: description
+    """
+    descriptions = {}
+    for param in params:
+        name, description = param.arg_name, param.description
+        descriptions[name] = description
+
+    return descriptions
+
+
+def get_slash_kwargs(function: Any, name: str = None, description: str = None, guild_ids: List[int] = None, remove_underscore_keywords: bool = False):
     """
     Get the kwargs required for cog_ext.cog_slash or SlashCommand.slash
 
     Parameters
     ----------
-    name : str
-        The name of the command
-    description : str
-        The description of the command
-    guild_ids : List[int]
-        List of guild IDs to add the command to
-    remove_underscore_keywords : bool
-        Whether to remove _ from the end of arguments that would be keywords
     function : any
         The command
+    name : str, optional
+        The name of the command, by default None
+    description : str, optional
+        The description of the command (will override any docstring provided
+        description if not None), by default None
+    guild_ids : List[int], optional
+        List of guild IDs to add the command to, by default None
+    remove_underscore_keywords : bool, optional
+        Whether to remove _ from the end of arguments that would be keywords,
+        by default False
 
     Returns
     -------
@@ -143,7 +172,14 @@ def get_slash_kwargs(name: str, description: str, guild_ids: List[int], remove_u
     """
     # Use annotations
     signature = inspect.signature(function)
-
+    # Use docstring signatures to get descriptions
+    parsed_docstring = parse(function.__doc__)
+    # Command description
+    description = description or parsed_docstring.short_description
+    # Parameter descriptions
+    param_descriptions = get_descriptions(parsed_docstring.params)
+
+    # Building params for function
     params = dict(
         name=name or function.__name__,
         description=description or "No description",
@@ -165,11 +201,9 @@ def get_slash_kwargs(name: str, description: str, guild_ids: List[int], remove_u
             param_name_mapping[param_name[:-1]] = param_name
             param_name = param_name[:-1]
 
-        # If it's a tuple of a type and a literal, the second argument is a description
-        param_description = "No description"
-        if getattr(annotation, "__origin__", None) == tuple and len(annotation.__args__) == 2:
-            param_description = annotation.__args__[1].__args__[0]
-            annotation = annotation.__args__[0]
+        # Get descriptions or use default
+        param_description = param_descriptions.get(
+            param_name, "No description")
 
         # Default to no choices
         choices = None
@@ -188,6 +222,7 @@ def get_slash_kwargs(name: str, description: str, guild_ids: List[int], remove_u
             # Just use converter params
             converter_params[param_name] = annotation
 
+        # Add the parameter/"option"
         params['options'].append(create_option(
             name=param_name,
             description=param_description,

requirements.txt

@@ -1,2 +1,3 @@
-discord.py
-discord-py-slash-command
+discord.py==1.6.*
+discord-py-slash-command==1.1.*
+docstring_parser==0.7.*

setup.py

@@ -8,7 +8,7 @@
     install_requires = f.readlines()
 
 setup(name='dpyslash',
-      version='1.1.1',
+      version='1.2.0rc1',
       description='Improves slash commands for Python',
       author='starsflower',
       url='https://github.com/starsflower/discordpy-slash-commands',

tests/test.py

@@ -41,7 +41,7 @@ def test_slash_kwarg_generation(self):
         def func(foo: str, bar: Union[Literal[1], Literal[2, "name"]], baz: Union[commands.Converter, int] = "bin"):
             pass
 
-        kwargs, _ = get_slash_kwargs("test", "test", [], False, func)
+        kwargs, _ = get_slash_kwargs(func, "test", "test", [], False)
         self.assertEqual(kwargs["options"][0], {
             "name": "foo",
             "description": "No description",
@@ -69,19 +69,47 @@ def func(foo: str, bar: Union[Literal[1], Literal[2, "name"]], baz: Union[comman
             "choices": []
         })
 
-    def test_optional_converter(self):
+    def test_docstrings(self):
         def func(baz: Optional[commands.Converter] = "bin"):
+            """
+            My description for the command
+
+            Parameters
+            ----------
+            baz : Optional[commands.Converter], optional
+                My description, by default "bin"
+            """
             pass
 
-        kwargs, _ = get_slash_kwargs("test", "test", [], False, func)
+        kwargs, _ = get_slash_kwargs(func)
+        self.assertEqual(kwargs["description"], "My description for the command")
         self.assertEqual(kwargs["options"][0], {
             "name": "baz",
-            "description": "No description",
+            "description": "My description, by default \"bin\"",
+            "type": SlashCommandOptionType.STRING,
+            "required": False,
+            "choices": []
+        })
+    
+    def test_plain_details(self):
+        def func(baz: Optional[commands.Converter] = "bin"):
+            """
+            My description for the command
+
+            :param baz: My description
+            """
+            pass
+
+        kwargs, _ = get_slash_kwargs(func)
+        self.assertEqual(kwargs["description"], "My description for the command")
+        self.assertEqual(kwargs["options"][0], {
+            "name": "baz",
+            "description": "My description",
             "type": SlashCommandOptionType.STRING,
             "required": False,
             "choices": []
         })
 
 
 if __name__ == "__main__":
-    unittest.main()
+    unittest.main(verbosity=2)

tests/test_bot.py

@@ -19,12 +19,25 @@
 s = SlashCommand(bot, sync_commands=True)
 
 
-@s.slash(description="Test", guild_ids=guild_ids)
-async def echo(ctx: SlashContext, my_arg: Tuple[str, Literal["a description"]]):
+@s.slash(guild_ids=guild_ids)
+async def echo(ctx: SlashContext, my_arg: str):
+    """
+    Test
+
+    Parameters
+    ----------
+    my_arg : str
+        The description
+    """
     await ctx.send(f"You said {my_arg}")
 
 @s.slash(name="test", guild_ids=guild_ids)
 async def _test(ctx: SlashContext, member: discord.Member):
+    """
+    My command using another style
+
+    :param member: The member to say hello to
+    """
     await ctx.send(f"Hello {member.mention}")