Use sphinx style docstrings for new lock utils

Author: ChrisLovering

pydis_core/utils/function.py

@@ -8,7 +8,14 @@
 import typing
 from collections.abc import Callable, Sequence, Set
 
-__all__ = ["command_wraps", "GlobalNameConflictError", "update_wrapper_globals"]
+__all__ = [
+    "command_wraps",
+    "get_arg_value",
+    "get_arg_value_wrapper",
+    "get_bound_args",
+    "GlobalNameConflictError",
+    "update_wrapper_globals",
+]
 
 
 if typing.TYPE_CHECKING:
@@ -29,10 +36,13 @@ def get_arg_value(name_or_pos: Argument, arguments: BoundArgs) -> typing.Any:
     """
     Return a value from `arguments` based on a name or position.
 
-    `arguments` is an ordered mapping of parameter names to argument values.
-
-    Raise TypeError if `name_or_pos` isn't a str or int.
-    Raise ValueError if `name_or_pos` does not match any argument.
+    Arguments:
+        arguments: An ordered mapping of parameter names to argument values.
+    Returns:
+        Value from `arguments` based on a name or position.
+    Raises:
+        TypeError: `name_or_pos` isn't a str or int.
+        ValueError: `name_or_pos` does not match any argument.
     """
     if isinstance(name_or_pos, int):
         # Convert arguments to a tuple to make them indexable.
@@ -62,12 +72,14 @@ def get_arg_value_wrapper(
     """
     Call `decorator_func` with the value of the arg at the given name/position.
 
-    `decorator_func` must accept a callable as a parameter to which it will pass a mapping of
-    parameter names to argument values of the function it's decorating.
+    Arguments:
+        decorator_func: A function that must accept a callable as a parameter to which it will pass a mapping of
+            parameter names to argument values of the function it's decorating.
+        name_or_pos: The name/position of the arg to get the value from.
+        func: An optional callable which will return a new value given the argument's value.
 
-    `func` is an optional callable which will return a new value given the argument's value.
-
-    Return the decorator returned by `decorator_func`.
+    Returns:
+        The decorator returned by `decorator_func`.
     """
     def wrapper(args: BoundArgs) -> typing.Any:
         value = get_arg_value(name_or_pos, args)

pydis_core/utils/lock.py

@@ -23,8 +23,8 @@ class LockedResourceError(RuntimeError):
     Exception raised when an operation is attempted on a locked resource.
 
     Attributes:
-        `type` -- name of the locked resource's type
-        `id` -- ID of the locked resource
+        type (str): Name of the locked resource's type
+        id (typing.Hashable): ID of the locked resource
     """
 
     def __init__(self, resource_type: str, resource_id: Hashable):
@@ -76,19 +76,20 @@ def lock(
     """
     Turn the decorated coroutine function into a mutually exclusive operation on a `resource_id`.
 
-    If `wait` is True, wait until the lock becomes available. Otherwise, if any other mutually
-    exclusive function currently holds the lock for a resource, do not run the decorated function
-    and return None.
-
-    If `raise_error` is True, raise `LockedResourceError` if the lock cannot be acquired.
-
-    `namespace` is an identifier used to prevent collisions among resource IDs.
-
-    `resource_id` identifies a resource on which to perform a mutually exclusive operation.
-    It may also be a callable or awaitable which will return the resource ID given an ordered
-    mapping of the parameters' names to arguments' values.
-
     If decorating a command, this decorator must go before (below) the `command` decorator.
+
+    Arguments:
+        namespace (typing.Hashable): An identifier used to prevent collisions among resource IDs.
+        resource_id: identifies a resource on which to perform a mutually exclusive operation.
+            It may also be a callable or awaitable which will return the resource ID given an ordered
+            mapping of the parameters' names to arguments' values.
+        raise_error (bool): If True, raise `LockedResourceError` if the lock cannot be acquired.
+        wait (bool): If True, wait until the lock becomes available. Otherwise, if any other mutually
+            exclusive function currently holds the lock for a resource, do not run the decorated function
+            and return None.
+
+    Raises:
+        :exc:`LockedResourceError`: If the lock can't be acquired and `raise_error` is set to True.
     """
     def decorator(func: types.FunctionType) -> types.FunctionType:
         name = func.__name__
@@ -144,8 +145,10 @@ def lock_arg(
     """
     Apply the `lock` decorator using the value of the arg at the given name/position as the ID.
 
-    `func` is an optional callable or awaitable which will return the ID given the argument value.
     See `lock` docs for more information.
+
+    Arguments:
+        func: An optional callable or awaitable which will return the ID given the argument value.
     """
     decorator_func = partial(lock, namespace, raise_error=raise_error, wait=wait)
     return function.get_arg_value_wrapper(decorator_func, name_or_pos, func)