docs docs docs

src/ytdl_sub/script/functions/array_functions.py

@@ -8,6 +8,9 @@ from ytdl_sub.script.types.resolvable import Resolvable
 class ArrayFunctions:
     @staticmethod
     def array_extend(*arrays: Array) -> Array:
+        """
+        Combine multiple Arrays into a single Array.
+        """
         output: List[Resolvable] = []
         for array in arrays:
             output.extend(array.value)
@@ -16,10 +19,16 @@ class ArrayFunctions:
 
     @staticmethod
     def array_at(array: Array, idx: Integer) -> Resolvable:
+        """
+        Return the element in the Array at index ``idx``.
+        """
         return array.value[idx.value]
 
     @staticmethod
     def array_flatten(array: Array) -> Array:
+        """
+        Flatten any nested Arrays into a single-dimensional Array.
+        """
         output: List[Resolvable] = []
         for elem in array.value:
             if isinstance(elem, Array):
@@ -31,4 +40,7 @@ class ArrayFunctions:
 
     @staticmethod
     def array_reverse(array: Array) -> Array:
+        """
+        Reverse an Array.
+        """
         return Array(list(reversed(array.value)))

src/ytdl_sub/script/functions/boolean_functions.py

@@ -1,6 +1,8 @@
 from ytdl_sub.script.types.resolvable import AnyType
 from ytdl_sub.script.types.resolvable import Boolean
 
+# pylint: disable=invalid-name
+
 
 class BooleanFunctions:
     """

src/ytdl_sub/script/functions/conditional_functions.py

@@ -10,6 +10,10 @@ class ConditionalFunctions:
     def if_(
         condition: Boolean, true: AnyTypeReturnableA, false: AnyTypeReturnableB
     ) -> Union[AnyTypeReturnableA, AnyTypeReturnableB]:
+        """
+        Conditional ``if`` statement that returns the ``true`` or ``false`` parameter
+        depending on the ``condition`` value.
+        """
         if condition.value:
             return true
         return false

src/ytdl_sub/script/functions/error_functions.py

@@ -7,10 +7,16 @@ from ytdl_sub.script.utils.exceptions import UserThrownRuntimeError
 class ErrorFunctions:
     @staticmethod
     def throw(error_message: String) -> AnyType:
+        """
+        Explicitly throw an error with the provided error message.
+        """
         raise UserThrownRuntimeError(error_message)
 
     @staticmethod
     def assert_(condition: Boolean, assert_message: String) -> Boolean:
+        """
+        Explicitly throw an error with the provided assert message if ``condition`` is False.
+        """
         if not condition.value:
             raise UserThrownRuntimeError(assert_message)
         return condition

src/ytdl_sub/script/functions/map_functions.py

@@ -1,33 +1,17 @@
-from typing import Dict
 from typing import Optional
 
-from ytdl_sub.script.types.array import Array
 from ytdl_sub.script.types.map import Map
 from ytdl_sub.script.types.resolvable import AnyType
 from ytdl_sub.script.types.resolvable import Hashable
-from ytdl_sub.script.types.resolvable import Resolvable
-from ytdl_sub.utils.exceptions import StringFormattingException
 
 
 class MapFunctions:
-    @staticmethod
-    def map(*key_values: Array) -> Map:
-        output: Dict[Resolvable, Resolvable] = {}
-
-        for key_value in key_values:
-            if len(key_value.value) != 2:
-                raise StringFormattingException(
-                    "%map must take Arrays containing pairs of keys and values"
-                )
-
-            output[key_value.value[0]] = key_value.value[1]
-
-        return Map(output)
-
     @staticmethod
     def map_get(mapping: Map, key: Hashable, default: Optional[AnyType] = None) -> AnyType:
-        if key not in mapping.value:
-            if default is not None:
-                return default
-            raise StringFormattingException("key not found")
+        """
+        Return ``key``'s value within the Map. If ``key`` does not exist, and ``default`` is
+        provided, it will return ``default``. Otherwise, will error.
+        """
+        if default is not None:
+            return mapping.value.get(key, default=default)
         return mapping.value[key]

src/ytdl_sub/script/functions/numeric_functions.py

@@ -1,6 +1,5 @@
 from typing import Union
 
-from ytdl_sub.script.types.resolvable import AnyType
 from ytdl_sub.script.types.resolvable import Boolean
 from ytdl_sub.script.types.resolvable import Float
 from ytdl_sub.script.types.resolvable import Integer
@@ -17,36 +16,63 @@ def _to_numeric(value: int | float) -> Numeric:
 class NumericFunctions:
     @staticmethod
     def float(value: Union[Float, Integer, Boolean, String]) -> Float:
+        """
+        Cast to Float.
+        """
         return Float(value=float(value.value))
 
     @staticmethod
     def int(value: Union[Float, Integer, Boolean, String]) -> Integer:
+        """
+        Cast to Integer.
+        """
         return Integer(value=int(value.value))
 
     @staticmethod
     def add(left: Numeric, right: Numeric) -> Numeric:
+        """
+        ``+`` operator. Returns ``left + right``.
+        """
         return _to_numeric(left.value + right.value)
 
     @staticmethod
     def sub(left: Numeric, right: Numeric) -> Numeric:
+        """
+        ``-`` operator. Returns ``left - right``.
+        """
         return _to_numeric(left.value - right.value)
 
     @staticmethod
     def mul(left: Numeric, right: Numeric) -> Numeric:
+        """
+        ``*`` operator. Returns ``left * right``.
+        """
         return _to_numeric(left.value * right.value)
 
     @staticmethod
     def div(left: Numeric, right: Numeric) -> Numeric:
+        """
+        ``/`` operator. Returns ``left / right``.
+        """
         return _to_numeric(left.value / right.value)
 
     @staticmethod
-    def mod(value: Numeric, modulo: Numeric) -> Numeric:
-        return _to_numeric(value=value.value % modulo.value)
+    def mod(left: Numeric, right: Numeric) -> Numeric:
+        """
+        ``%`` operator. Returns ``left % right``.
+        """
+        return _to_numeric(value=left.value % right.value)
 
     @staticmethod
-    def max(left: Numeric, right: Numeric) -> Numeric:
-        return _to_numeric(max(left.value, right.value))
+    def max(*values: Numeric) -> Numeric:
+        """
+        Returns max of all values.
+        """
+        return _to_numeric(max(val.value for val in values))
 
     @staticmethod
-    def min(left: Numeric, right: Numeric) -> Numeric:
-        return _to_numeric(min(left.value, right.value))
+    def min(*values: Numeric) -> Numeric:
+        """
+        Returns min of all values.
+        """
+        return _to_numeric(min(val.value for val in values))

src/ytdl_sub/script/functions/string_functions.py

@@ -8,32 +8,29 @@ from ytdl_sub.script.types.resolvable import String
 class StringFunctions:
     @staticmethod
     def string(value: AnyType) -> String:
+        """
+        Cast to String.
+        """
         return String(value=str(value.value))
 
     @staticmethod
     def lower(string: String) -> String:
         """
-        Returns
-        -------
-        Lower-cased string
+        Lower-case the entire String.
         """
         return String(string.value.lower())
 
     @staticmethod
     def upper(string: String) -> String:
         """
-        Returns
-        -------
-        Upper-cased string
+        Upper-case the entire String.
         """
         return String(string.value.upper())
 
     @staticmethod
     def capitalize(string: String) -> String:
         """
-        Returns
-        -------
-        Capitalized string
+        Capitalize all words in the String.
         """
         return String(string.value.capitalize())
 
@@ -41,6 +38,10 @@ class StringFunctions:
     def replace(
         string: String, old: String, new: String, count: Optional[Integer] = None
     ) -> String:
+        """
+        Replace the ``old`` part of the String with the ``new``. Optionally only replace it
+        ``count`` number of times.
+        """
         if count:
             return String(string.value.replace(old.value, new.value, count.value))
 
@@ -48,4 +49,7 @@ class StringFunctions:
 
     @staticmethod
     def concat(*args: String) -> String:
+        """
+        Concatenate multiple Strings into a single String.
+        """
         return String("".join(*args))

src/ytdl_sub/script/types/resolvable.py

@@ -15,6 +15,11 @@ NumericT = TypeVar("NumericT", bound=int | float)
 class NamedType(ABC):
     @classmethod
     def type_name(cls) -> str:
+        """
+        Returns
+        -------
+        The type name to present to users. Defaults to the class name.
+        """
         return cls.__name__