docstrings

src/ytdl_sub/script/parser.py

@@ -25,6 +25,7 @@ from ytdl_sub.validators.string_formatter_validators import is_valid_source_vari
 
 # pylint: disable=invalid-name
 # pylint: disable=too-many-branches
+# pylint: disable=too-many-return-statements
 
 
 class ArgumentParser(Enum):
@@ -56,11 +57,11 @@ BOOLEAN_ONLY_ARGS = InvalidSyntaxException(
 )
 
 
-def UNEXPECTED_CHAR_ARGUMENT(parser: ArgumentParser):
+def _UNEXPECTED_CHAR_ARGUMENT(parser: ArgumentParser):
     return InvalidSyntaxException(f"Unexpected character when parsing {parser.value} arguments")
 
 
-def UNEXPECTED_COMMA_ARGUMENT(parser: ArgumentParser):
+def _UNEXPECTED_COMMA_ARGUMENT(parser: ArgumentParser):
     return InvalidSyntaxException(f"Unexpected comma when parsing {parser.value} arguments")
 
 
@@ -281,7 +282,7 @@ class _Parser:
             return self._parse_variable()
 
         self._set_highlight_position()
-        raise UNEXPECTED_CHAR_ARGUMENT(parser=argument_parser)
+        raise _UNEXPECTED_CHAR_ARGUMENT(parser=argument_parser)
 
     def _parse_args(
         self, argument_parser: ArgumentParser, breaking_chars: str = ")"
@@ -295,7 +296,7 @@ class _Parser:
             if ch in breaking_chars:
                 # i.e. ["arg", ] which is invalid
                 if arguments and len(arguments) == comma_count:
-                    raise UNEXPECTED_COMMA_ARGUMENT(argument_parser)
+                    raise _UNEXPECTED_COMMA_ARGUMENT(argument_parser)
                 break
 
             if ch.isspace():
@@ -304,7 +305,7 @@ class _Parser:
                 self._set_highlight_position()
                 comma_count += 1
                 if len(arguments) != comma_count:
-                    raise UNEXPECTED_COMMA_ARGUMENT(argument_parser)
+                    raise _UNEXPECTED_COMMA_ARGUMENT(argument_parser)
 
                 self._pos += 1
             else:
@@ -371,11 +372,11 @@ class _Parser:
 
             if ch == ",":
                 if in_comma:
-                    raise UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY)
+                    raise _UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY)
                 if key is not None:
                     raise MAP_KEY_WITH_NO_VALUE
                 if not output:
-                    raise UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY)
+                    raise _UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY)
                 in_comma = True
                 self._pos += 1
             elif key is None:
@@ -460,7 +461,7 @@ class _Parser:
                 ) or _is_boolean_false(self._read(increment_pos=False, length=5)):
                     raise BOOLEAN_ONLY_ARGS
                 else:
-                    raise UNEXPECTED_CHAR_ARGUMENT(parser=ArgumentParser.SCRIPT)
+                    raise _UNEXPECTED_CHAR_ARGUMENT(parser=ArgumentParser.SCRIPT)
             elif bracket_counter == 0:
                 # Only accumulate literal str if not in brackets
                 literal_str += ch

src/ytdl_sub/script/script.py

@@ -8,6 +8,13 @@ from ytdl_sub.script.types.variable import Variable
 
 
 class Script:
+    """
+    Takes a dictionary of both
+        ``{ variable_names: syntax }``
+    and
+        ``{ %custom_function: syntax }``
+    """
+
     @classmethod
     def _is_function(cls, override_name: str):
         return override_name.startswith("%")
@@ -32,6 +39,16 @@ class Script:
     def resolve(
         self, pre_resolved_variables: Optional[Dict[Variable, Resolvable]] = None
     ) -> Dict[str, Resolvable]:
+        """
+        Parameters
+        ----------
+        pre_resolved_variables
+            Optional variables that have been resolved elsewhere and could be used in this script
+
+        Returns
+        -------
+        Dict of resolved values
+        """
         return SyntaxTree.resolve_overrides(
             parsed_overrides=self._variables,
             custom_functions=self._functions,

tests/unit/script/test_parser.py

@@ -4,8 +4,8 @@ from typing import Union
 
 import pytest
 
+from ytdl_sub.script.parser import _UNEXPECTED_CHAR_ARGUMENT
 from ytdl_sub.script.parser import BRACKET_NOT_CLOSED
-from ytdl_sub.script.parser import UNEXPECTED_CHAR_ARGUMENT
 from ytdl_sub.script.parser import ArgumentParser
 from ytdl_sub.script.parser import parse
 from ytdl_sub.script.types.function import BuiltInFunction
@@ -168,6 +168,6 @@ class TestParserBracketFailures:
     def test_bracket_in_function(self):
         with pytest.raises(
             InvalidSyntaxException,
-            match=re.escape(str(UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.MAP_KEY))),
+            match=re.escape(str(_UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.MAP_KEY))),
         ):
             parse("hello {%capitalize({as_arg)}")

tests/unit/script/types/test_array.py

@@ -2,8 +2,8 @@ import re
 
 import pytest
 
-from ytdl_sub.script.parser import UNEXPECTED_CHAR_ARGUMENT
+from ytdl_sub.script.parser import _UNEXPECTED_CHAR_ARGUMENT
-from ytdl_sub.script.parser import UNEXPECTED_COMMA_ARGUMENT
+from ytdl_sub.script.parser import _UNEXPECTED_COMMA_ARGUMENT
 from ytdl_sub.script.parser import ArgumentParser
 from ytdl_sub.script.script import Script
 from ytdl_sub.script.types.array import ResolvedArray
@@ -81,7 +81,7 @@ class TestArray:
     def test_unexpected_comma(self, array: str):
         with pytest.raises(
             InvalidSyntaxException,
-            match=re.escape(str(UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.ARRAY))),
+            match=re.escape(str(_UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.ARRAY))),
         ):
             Script({"array": array}).resolve()
 
@@ -98,7 +98,7 @@ class TestArray:
     def test_array_not_closed(self, array: str):
         with pytest.raises(
             InvalidSyntaxException,
-            match=re.escape(str(UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.ARRAY))),
+            match=re.escape(str(_UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.ARRAY))),
         ):
             assert Script({"array": array}).resolve()
 
@@ -112,7 +112,7 @@ class TestArray:
     def test_array_not_opened(self, array: str):
         with pytest.raises(
             InvalidSyntaxException,
-            match=re.escape(str(UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.SCRIPT))),
+            match=re.escape(str(_UNEXPECTED_CHAR_ARGUMENT(ArgumentParser.SCRIPT))),
         ):
             assert Script({"array": array}).resolve()
 

tests/unit/script/types/test_map.py

@@ -2,12 +2,12 @@ import re
 
 import pytest
 
+from ytdl_sub.script.parser import _UNEXPECTED_COMMA_ARGUMENT
 from ytdl_sub.script.parser import BRACKET_NOT_CLOSED
 from ytdl_sub.script.parser import MAP_KEY_MULTIPLE_VALUES
 from ytdl_sub.script.parser import MAP_KEY_NOT_HASHABLE
 from ytdl_sub.script.parser import MAP_KEY_WITH_NO_VALUE
 from ytdl_sub.script.parser import MAP_MISSING_KEY
-from ytdl_sub.script.parser import UNEXPECTED_COMMA_ARGUMENT
 from ytdl_sub.script.parser import ArgumentParser
 from ytdl_sub.script.script import Script
 from ytdl_sub.script.types.map import ResolvedMap
@@ -129,7 +129,7 @@ class TestMap:
     def test_map_unexpected_comma(self, value: str):
         with pytest.raises(
             InvalidSyntaxException,
-            match=re.escape(str(UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY))),
+            match=re.escape(str(_UNEXPECTED_COMMA_ARGUMENT(ArgumentParser.MAP_KEY))),
         ):
             Script({"map": value}).resolve()