From ac33698f936ce3c9fef65981765174d7433d1898 Mon Sep 17 00:00:00 2001
From: Jesse Bannon <jbann1994@gmail.com>
Date: Wed, 28 Sep 2022 09:04:37 -0700
Subject: [PATCH] docs

---
 src/ytdl_sub/downloaders/downloader.py        |  6 ++--
 .../generic/collection_validator.py           | 30 +++++++++++--------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/src/ytdl_sub/downloaders/downloader.py b/src/ytdl_sub/downloaders/downloader.py
index b07a9751..93b76614 100644
--- a/src/ytdl_sub/downloaders/downloader.py
+++ b/src/ytdl_sub/downloaders/downloader.py
@@ -415,10 +415,12 @@ class Downloader(DownloadArchiver, Generic[DownloaderOptionsT], ABC):
             for child in entry.parent_children():
                 self._set_collection_variables(collection_url, child)
             for child in entry.entry_children():
-                child.add_variables(variables_to_add=collection_url.variables)
+                child.add_variables(
+                    variables_to_add=collection_url.variables.dict_with_format_strings
+                )
 
         elif isinstance(entry, Entry):
-            entry.add_variables(variables_to_add=collection_url.variables)
+            entry.add_variables(variables_to_add=collection_url.variables.dict_with_format_strings)
 
     def _download_url_metadata(
         self, collection_url: CollectionUrlValidator
diff --git a/src/ytdl_sub/downloaders/generic/collection_validator.py b/src/ytdl_sub/downloaders/generic/collection_validator.py
index ec2fb580..540c2577 100644
--- a/src/ytdl_sub/downloaders/generic/collection_validator.py
+++ b/src/ytdl_sub/downloaders/generic/collection_validator.py
@@ -48,8 +48,9 @@ class CollectionUrlValidator(StrictDictValidator):
 
         # TODO: url validate using yt-dlp IE
         self._url = self._validate_key(key="url", validator=StringValidator)
-        variables = self._validate_key_if_present(key="variables", validator=DictFormatterValidator)
-        self._variables = variables.dict_with_format_strings if variables else {}
+        self._variables = self._validate_key_if_present(
+            key="variables", validator=DictFormatterValidator, default={}
+        )
 
         self._source_thumbnails = self._validate_key_if_present(
             key="source_thumbnails", validator=CollectionThumbnailListValidator, default=[]
@@ -61,23 +62,25 @@ class CollectionUrlValidator(StrictDictValidator):
     @property
     def url(self) -> str:
         """
-        Returns
-        -------
-        URL to download from
+        URL to download from, listed in priority from lowest (top) to highest (bottom). If a
+        download exists in more than one URL, it will resolve to the bottom-most one and inherit
+        those variables.
         """
         return self._url.value
 
     @property
-    def variables(self) -> Dict[str, str]:
+    def variables(self) -> DictFormatterValidator:
         """
-        Variables to add to each entry
+        Source variables to add to each entry. The top-most collection must define all possible
+        variables. Collections below can redefine all of them or a subset of the top-most variables.
         """
         return self._variables
 
     @property
     def source_thumbnails(self) -> Optional[CollectionThumbnailListValidator]:
         """
-        TODO:docstring
+        Thumbnails to download from the source, if any exist. The hierarchy is
+        source -> playlist -> entry.
         """
         return self._source_thumbnails
 
@@ -96,13 +99,13 @@ class CollectionUrlListValidator(ListValidator[CollectionUrlValidator]):
     def __init__(self, name, value):
         super().__init__(name, value)
 
-        added_variables: Dict[str, str] = self.list[0].variables
+        added_variables: Dict[str, str] = self.list[0].variables.dict_with_format_strings
 
         for idx, collection_url_validator in enumerate(self.list[1:]):
             collection_variables = collection_url_validator.variables
 
             # see if this collection contains new added vars (it should not)
-            for var in collection_variables.keys():
+            for var in collection_variables.keys:
                 if var not in added_variables:
                     raise self._validation_exception(
                         f"Collection url {idx} contains the variable '{var}' that the first "
@@ -141,7 +144,7 @@ class CollectionValidator(StrictDictValidator, AddsVariablesMixin):
         -------
         List of variables added. The first collection url always contains all the variables.
         """
-        return list(self._urls.list[0].variables.keys())
+        return list(self._urls.list[0].variables.keys)
 
     def validate_with_variables(
         self, source_variables: List[str], override_variables: Dict[str, str]
@@ -162,7 +165,10 @@ class CollectionValidator(StrictDictValidator, AddsVariablesMixin):
 
         # Apply formatting to each new source variable, ensure it resolves
         for collection_url in self.collection_urls.list:
-            for source_var_name, source_var_formatter_str in collection_url.variables.items():
+            for (
+                source_var_name,
+                source_var_formatter_str,
+            ) in collection_url.variables.dict_with_format_strings.items():
                 _ = StringFormatterValidator(
                     name=f"{self._name}.{source_var_name}", value=source_var_formatter_str
                 ).apply_formatter(base_variables)