diff --git a/src/ytdl_sub/script/functions/array_functions.py b/src/ytdl_sub/script/functions/array_functions.py index 7fccf58c..880afe58 100644 --- a/src/ytdl_sub/script/functions/array_functions.py +++ b/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))) diff --git a/src/ytdl_sub/script/functions/boolean_functions.py b/src/ytdl_sub/script/functions/boolean_functions.py index bd024b3d..ac466883 100644 --- a/src/ytdl_sub/script/functions/boolean_functions.py +++ b/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: """ diff --git a/src/ytdl_sub/script/functions/conditional_functions.py b/src/ytdl_sub/script/functions/conditional_functions.py index e6383e9f..4faaa2b4 100644 --- a/src/ytdl_sub/script/functions/conditional_functions.py +++ b/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 diff --git a/src/ytdl_sub/script/functions/error_functions.py b/src/ytdl_sub/script/functions/error_functions.py index a76dffe9..133c40c0 100644 --- a/src/ytdl_sub/script/functions/error_functions.py +++ b/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 diff --git a/src/ytdl_sub/script/functions/map_functions.py b/src/ytdl_sub/script/functions/map_functions.py index fb9400f1..1b2067b6 100644 --- a/src/ytdl_sub/script/functions/map_functions.py +++ b/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] diff --git a/src/ytdl_sub/script/functions/numeric_functions.py b/src/ytdl_sub/script/functions/numeric_functions.py index 82163d15..fe157742 100644 --- a/src/ytdl_sub/script/functions/numeric_functions.py +++ b/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)) diff --git a/src/ytdl_sub/script/functions/string_functions.py b/src/ytdl_sub/script/functions/string_functions.py index bc27d898..37751a6c 100644 --- a/src/ytdl_sub/script/functions/string_functions.py +++ b/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)) diff --git a/src/ytdl_sub/script/types/resolvable.py b/src/ytdl_sub/script/types/resolvable.py index cb0538d3..65d56a1a 100644 --- a/src/ytdl_sub/script/types/resolvable.py +++ b/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__