Implements fallback for required tokens (#50)

* Implements fallback value for required tokens

* Update docs to include new fallback attribute of Token

Author: xiancg

docs/source/changelog.rst

@@ -1,6 +1,13 @@
 Changelog
 ================================
 
+1.4.5-beta
+---------------------------------------
+
+**Improvements:**
+    - Adds user values to validate function so names can be validated against expected data.
+    - Adds fallback to required Tokens, useful for when a Token is required but a default value is needed in case the user doesn't provide one.
+
 1.3.1-beta
 ---------------------------------------
 

docs/source/tokens.rst

@@ -4,20 +4,25 @@ Tokens are the meaningful parts of a template. A token can be required, meaning
 
 If options are present, then one of them is the default one. Each option follows a {full_name:abbreviation} schema, so that names can be short but meaning can be recovered easily. The default option might be passed explicitly by the user by passing a *default* argument (it must match one of the options in the Token). If no default options is explicitly passed, the Token will sort options alphabetically and pick the first one. Please notice if you pass the *default* option explicitly, you can use the abbreviation or the full option name.
 
+If fallback is defined, it will be used on required tokens if nothing is passed by the user.
+
 .. code-block:: python
     :linenos:
 
-    n.add_token('whatAffects')
+    n.add_token('whatLights')
+    n.add_token('shadowType', fallback='soft')
     n.add_token_number('digits')
     n.add_token('category', natural='nat', 
                 practical='pra', dramatic='dra',
                 volumetric='vol', default='nat')
 
-In line 1 we're creating a **Required Token**. This means that for solving the user must provide a value. This is a explicit solve.
+In line 1 we're creating a **Required Token**. This means that in order to solve the user must provide a value, else an error will be raised. This is a explicit solve.
+
+In line 2 we're creating a **Required Token** with a fallback. This means that if the user doesn't provide a value, the Token will solve to the fallback value. This is an implicit solve.
 
-In line 2 we're creating a **Number Token**. This is a special Token really useful for working with version like or counting parts of a name. It's always required.
+In line 3 we're creating a **Number Token**. This is a special Token really useful for working with version like or counting parts of a name. It's always required.
 
-In line 3 we're creating an **Optional Token**, which means that for solving the user can pass one of the options in the Token or simply ignore passing a value and the Token will solve to it's default option. This is an implicit solve, which helps to greatly reduce the amount of info that needs to be passed to solve for certain cases.
+In line 4 we're creating an **Optional Token**, which means that for solving the user can pass one of the options in the Token or simply ignore passing a value and the Token will solve to it's default option. This is an implicit solve, which helps to greatly reduce the amount of info that needs to be passed to solve for certain cases.
 
 For more information on implicit and explicit solving please check :doc:`usage/solving`
 

docs/source/usage/repositories.rst

@@ -57,18 +57,21 @@ When saving the session, all Tokens and Rules in memory will be saved to the rep
     :linenos:
 
     n.add_token('whatAffects')
+    n.add_token('shadowType', fallback='soft')
     n.add_token_number('digits')
     n.add_token(
         'category',
         natural='nat', practical='pra', dramatic='dra',
         volumetric='vol', default='nat'
     )
 
-In line 1 we're creating a **Required Token**. This means that for solving the user has to provide a value. This is a explicit solve.
+In line 1 we're creating a **Required Token**. This means that in order to solve the user must provide a value, else an error will be raised. This is a explicit solve.
 
-In line 2 we're creating a **Number Token**. This is a special Token really useful for working with version like or counting parts of a name. It's always required.
+In line 2 we're creating a **Required Token** with a fallback. This means that if the user doesn't provide a value, the Token will solve to the fallback value. This is an implicit solve.
 
-In line 3 we're creating an **Optional Token**, which means that for solving the user can pass one of the options in the Token or simply ignore passing a value and the Token will solve to it's default option. This is an implicit solve, which helps to greatly reduce the amount of info that needs to be passed to solve for certain cases.
+In line 3 we're creating a **Number Token**. This is a special Token really useful for working with version like or counting parts of a name. It's always required.
+
+In line 4 we're creating an **Optional Token**, which means that for solving the user can pass one of the options in the Token or simply ignore passing a value and the Token will solve to it's default option. This is an implicit solve, which helps to greatly reduce the amount of info that needs to be passed to solve for certain cases.
 
 For more information on implicit and explicit solving please check :doc:`solving`
 

docs/source/usage/solving.rst

@@ -14,6 +14,7 @@ Let's set these Tokens and Rules.
 
     # CREATE TOKENS
     n.add_token('whatAffects')
+    n.add_token('shadowType', fallback='soft')
     n.add_token_number('digits')
     n.add_token(
         'category',
@@ -33,7 +34,7 @@ Let's set these Tokens and Rules.
     # CREATE RULES
     n.add_rule(
         'lights',
-        '{category}_{function}_{whatAffects}_{digits}_{type}'
+        '{category}_{function}_{whatAffects}_{shadowType}_{digits}_{type}'
     )
 
     n.set_active_rule("lights")
@@ -45,6 +46,8 @@ It would not make any sense to make the user pass each and every Token all the t
 
 That's why vfxnaming.solve() accepts both args and kwargs. Not only that, but if given Token is optional and you want to use it's default value, you don't need to pass it at all.
 
+Even if you make a required tokken, you can still define a fallback value for it.
+
 .. code-block:: python
 
     n.solve(
@@ -57,9 +60,9 @@ That's why vfxnaming.solve() accepts both args and kwargs. Not only that, but if
 Each of these calls to vfxnaming.solve() will produce the exact same result:
 
 .. note::
-    natural_custom_chars_001_LGT
+    natural_custom_chars_soft_001_LGT
 
-If you don't pass a required Token (either as an argument or keyword argument), such as 'whatAffects' in this example, you'll get a **TokenError**. You'll also get a **TokenError** if you try to parse a value that doesn't match any of the options in the Token.
+If you don't pass a required Token (either as an argument or keyword argument), such as 'whatAffects' in this example, you'll get a **TokenError**, unless it has a fallback value defined. You'll also get a **TokenError** if you try to parse a value that doesn't match any of the options in the Token.
 
 Solving rules with repeated tokens
 -----------------------------------------

docs/source/usage/validating.rst

@@ -23,7 +23,7 @@ Let's set these Tokens and Rule.
 
     # CREATE TOKENS
     n.reset_tokens()
-    n.add_token("whatAffects")
+    n.add_token("whatAffects", fallback="nothing")
     n.add_token_number("digits")
     n.add_token(
         "category",
@@ -58,6 +58,9 @@ And then let's validate these names:
     n.validate("dramatic_bounce_chars_001_LGT")
     # Result: True
 
+    n.validate("dramatic_bounce_nothing_001_LGT")
+    # Result: True
+
     n.validate("dramatic_bounce_chars_001")
     # Result: False. Last token is missing.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vfxnaming"
-version = "1.4.5-beta"
+version = "1.5.0-beta"
 authors = [
   { name="Chris Granados", email="info@chrisgranados.com" },
 ]

src/vfxnaming/naming.py

@@ -113,7 +113,14 @@ def solve(*args, **kwargs) -> AnyStr:
                 fields_inc += 1
                 continue
             elif token.required and kwargs.get(f) is None and len(args) == 0:
-                raise SolvingError(f"Token {token.name} is required but was not passed.")
+                if len(token.fallback):
+                    values[f] = token.fallback
+                    fields_inc += 1
+                    continue
+                else:
+                    raise SolvingError(
+                        f"Token {token.name} is required but was not passed."
+                    )
             # Not required and not passed as keyword argument
             elif not token.required and kwargs.get(f) is None:
                 values[f] = token.solve()
@@ -191,6 +198,11 @@ def validate(name: AnyStr, **kwargs) -> bool:
                 values[f] = token.solve(kwargs.get(rule.fields[fields_inc]))
                 fields_inc += 1
                 continue
+            elif token.required and isinstance(token, tokens.Token):
+                if len(token.fallback):
+                    values[f] = token.fallback
+                    fields_inc += 1
+                    continue
             fields_inc += 1
     logger.debug(f"Validating rule '{rule.name}' with values {values}")
     return rule.validate(name, **values)

src/vfxnaming/rules.py

@@ -203,6 +203,8 @@ def validate(self, name: AnyStr, **validate_values) -> bool:  # noqa: C901
                     repeated_fields[each] = 1
         if repeated_fields:
             logger.debug(f"Repeated tokens: {', '.join(repeated_fields.keys())}")
+
+        # Validate values passed by the user
         if len(validate_values):
             for key, value in name_parts:
                 # Strip number that was added to make group name unique

src/vfxnaming/tokens.py

@@ -27,6 +27,7 @@ def __init__(self, name: AnyStr):
         self._name: AnyStr = name
         self._default = None
         self._options: Dict = {}
+        self._fallback = ""
 
     def add_option(self, fullname: AnyStr, abbreviation: AnyStr) -> bool:
         """Add an option pair to this Token.
@@ -138,7 +139,9 @@ def solve(self, name: Union[AnyStr, None] = None) -> AnyStr:
         """
         if self.required and name:
             return name
-        elif self.required and name is None:
+        elif self.required and len(self._fallback):
+            return self._fallback
+        elif self.required and not name:
             raise TokenError(
                 f"Token {self.name} is required. name parameter must be passed."
             )
@@ -227,6 +230,19 @@ def options(self) -> Dict:
         """
         return copy.deepcopy(self._options)
 
+    @property
+    def fallback(self) -> AnyStr:
+        return self._fallback
+
+    @fallback.setter
+    def fallback(self, f: AnyStr):
+        if self.required:
+            self._fallback = f
+        else:
+            logger.warning(
+                f"Token '{self.name}' has options, use {self.name}.default instead."
+            )
+
 
 class TokenNumber(Serializable):
     def __init__(self, name: AnyStr):
@@ -288,7 +304,7 @@ def parse(self, value: AnyStr) -> int:
                 suffix_index += 1
 
             if prefix_index != -1 and self.prefix != "":
-                if value[prefix_index : len(self.prefix)] != self.prefix:
+                if value[prefix_index : len(self.prefix)] != self.prefix:  # noqa: E203
                     logger.warning(f"Prefix '{self.prefix}' not found in '{value}'")
             if suffix_index != -1 and self.suffix != "":
                 if value[-suffix_index:] != self.suffix:
@@ -358,15 +374,18 @@ def options(self) -> Dict:
         return copy.deepcopy(self._options)
 
 
-def add_token(name: AnyStr, **kwargs) -> Token:
+def add_token(name: AnyStr, fallback: AnyStr = "", **kwargs) -> Token:
     """Add token to current naming session. If 'default' keyword argument is found,
     set it as default for the token instance.
 
     Args:
         name (str): Name that best describes the token, this will be used as a way
         to invoke the Token object.
 
-        kwargs: Each argument following the name is treated as an option for the
+        fallback (str, optional): Fallback value to use if token is required. Default is ""
+        and will raise and error, making the token mandatory.
+
+        kwargs: Each argument following fallback is treated as an option for the
         new Token.
 
     Raises:
@@ -392,6 +411,12 @@ def add_token(name: AnyStr, **kwargs) -> Token:
                     break
         else:
             raise TokenError("Default value must match one of the options passed.")
+    if len(fallback):
+        if isinstance(fallback, str):
+            token.fallback = fallback
+        else:
+            raise TokenError(f"Fallback must be a string. Got {type(fallback)}")
+
     _tokens[name] = token
     return token
 

tests/tokens_test.py

@@ -13,11 +13,12 @@ def setup(self):
         tokens.reset_tokens()
 
     @pytest.mark.parametrize(
-        "name,kwargs",
+        "name,fallback,kwargs",
         [
-            ("test", {}),
+            ("test", "", {}),
             (
                 "category",
+                "",
                 {
                     "natural": "natural",
                     "practical": "practical",
@@ -26,10 +27,11 @@ def setup(self):
                     "default": "natural",
                 },
             ),
+            ("fallbacktest", "imfallback", {}),
         ],
     )
-    def test_add(self, name: str, kwargs):
-        result = tokens.add_token(name, **kwargs)
+    def test_add(self, name: str, fallback: str, kwargs):
+        result = tokens.add_token(name, fallback, **kwargs)
         assert isinstance(result, tokens.Token) is True
 
     def test_reset_tokens(self):
@@ -118,6 +120,69 @@ def test_has_option_abbreviation(self, abbreviation: str, expected: bool):
         assert result is expected
 
 
+class Test_TokenFallback:
+    @pytest.fixture(autouse=True)
+    def setup(self):
+        rules.reset_rules()
+        tokens.reset_tokens()
+        tokens.add_token("whatAffects", fallback="nothing")
+        tokens.add_token_number("number")
+        tokens.add_token(
+            "category",
+            natural="natural",
+            practical="practical",
+            dramatic="dramatic",
+            volumetric="volumetric",
+            default="natural",
+        )
+        tokens.add_token(
+            "function",
+            key="key",
+            fill="fill",
+            ambient="ambient",
+            bounce="bounce",
+            rim="rim",
+            kick="kick",
+            custom="custom",
+            default="custom",
+        )
+        tokens.add_token("type", lighting="LGT", default="LGT")
+        rules.add_rule("lights", "{category}_{function}_{whatAffects}_{number}_{type}")
+
+    def test_token_has_fallback(self):
+        assert tokens.get_token("whatAffects").fallback == "nothing"
+
+    @pytest.mark.parametrize(
+        "name,data,expected",
+        [
+            (
+                "natural_ambient_chars_024_LGT",
+                {
+                    "category": "natural",
+                    "function": "ambient",
+                    "whatAffects": "chars",
+                    "number": 24,
+                    "type": "lighting",
+                },
+                True,
+            ),
+            (
+                "natural_ambient_nothing_003_LGT",
+                {
+                    "category": "natural",
+                    "function": "ambient",
+                    "number": 3,
+                    "type": "lighting",
+                },
+                True,
+            ),
+        ],
+    )
+    def test_fallback_solve(self, name: str, data: dict, expected: bool):
+        solved = n.solve(**data)
+        assert (name == solved) is expected
+
+
 class Test_TokenNumber:
     @pytest.fixture(autouse=True)
     def setup(self):