WIP: Add tyephints for Source classchandan/types

This is rather rudimentary at this stage. It is primarily here to serve
as a demo of this feature.

1 files changed, 27 insertions, 26 deletions

diff --git a/src/buildstream/source.py b/src/buildstream/source.py
index 9fc9cf17d..9cb6d549d 100644
--- a/src/buildstream/source.py
+++ b/src/buildstream/source.py
@@ -163,6 +163,7 @@ Class Reference
 
 import os
 from contextlib import contextmanager
+from typing import Union, Iterator
 
 from . import _yaml, utils
 from .plugin import Plugin
@@ -353,11 +354,11 @@ class Source(Plugin):
         """
         raise ImplError("Source plugin '{}' does not implement get_consistency()".format(self.get_kind()))
 
-    def load_ref(self, node):
+    def load_ref(self, node: dict) -> None:
         """Loads the *ref* for this Source from the specified *node*.
 
         Args:
-           node (dict): The YAML node to load the ref from
+           node: The YAML node to load the ref from
 
         .. note::
 
@@ -371,11 +372,11 @@ class Source(Plugin):
         """
         raise ImplError("Source plugin '{}' does not implement load_ref()".format(self.get_kind()))
 
-    def get_ref(self):
+    def get_ref(self) -> Union[None, str, list, dict]:
         """Fetch the internal ref, however it is represented
 
         Returns:
-           (simple object): The internal source reference, or ``None``
+           The internal source reference, or ``None``
 
         .. note::
 
@@ -389,12 +390,12 @@ class Source(Plugin):
         """
         raise ImplError("Source plugin '{}' does not implement get_ref()".format(self.get_kind()))
 
-    def set_ref(self, ref, node):
+    def set_ref(self, ref: Union[None, str, list, dict], node: dict):
         """Applies the internal ref, however it is represented
 
         Args:
-           ref (simple object): The internal source reference to set, or ``None``
-           node (dict): The same dictionary which was previously passed
+           ref: The internal source reference to set, or ``None``
+           node: The same dictionary which was previously passed
                         to :func:`Plugin.configure() <buildstream.plugin.Plugin.configure>`
 
         See :func:`Source.get_ref() <buildstream.source.Source.get_ref>`
@@ -453,11 +454,11 @@ class Source(Plugin):
         """
         raise ImplError("Source plugin '{}' does not implement fetch()".format(self.get_kind()))
 
-    def stage(self, directory):
+    def stage(self, directory: str) -> None:
         """Stage the sources to a directory
 
         Args:
-           directory (str): Path to stage the source
+           directory: Path to stage the source
 
         Raises:
            :class:`.SourceError`
@@ -470,11 +471,11 @@ class Source(Plugin):
         """
         raise ImplError("Source plugin '{}' does not implement stage()".format(self.get_kind()))
 
-    def init_workspace(self, directory):
+    def init_workspace(self, directory: str) -> None:
         """Initialises a new workspace
 
         Args:
-           directory (str): Path of the workspace to init
+           directory: Path of the workspace to init
 
         Raises:
            :class:`.SourceError`
@@ -490,7 +491,7 @@ class Source(Plugin):
         """
         self.stage(directory)
 
-    def get_source_fetchers(self):
+    def get_source_fetchers(self) -> Iterator[SourceFetcher]:
         """Get the objects that are used for fetching
 
         If this source doesn't download from multiple URLs,
@@ -498,7 +499,7 @@ class Source(Plugin):
         is recommended.
 
         Returns:
-           iterable: The Source's SourceFetchers, if any.
+           The Source's SourceFetchers, if any.
 
         .. note::
 
@@ -512,7 +513,7 @@ class Source(Plugin):
         """
         return []
 
-    def validate_cache(self):
+    def validate_cache(self) -> None:
         """Implement any validations once we know the sources are cached
 
         This is guaranteed to be called only once for a given session
@@ -528,11 +529,11 @@ class Source(Plugin):
     #############################################################
     #                       Public Methods                      #
     #############################################################
-    def get_mirror_directory(self):
+    def get_mirror_directory(self) -> str:
         """Fetches the directory where this source should store things
 
         Returns:
-           (str): The directory belonging to this source
+           The directory belonging to this source
         """
 
         # Create the directory if it doesnt exist
@@ -541,17 +542,17 @@ class Source(Plugin):
         os.makedirs(directory, exist_ok=True)
         return directory
 
-    def translate_url(self, url, *, alias_override=None, primary=True):
+    def translate_url(self, url: str, *, alias_override: str = None, primary: bool = True) -> str:
         """Translates the given url which may be specified with an alias
         into a fully qualified url.
 
         Args:
-           url (str): A URL, which may be using an alias
-           alias_override (str): Optionally, an URI to override the alias with. (*Since: 1.2*)
-           primary (bool): Whether this is the primary URL for the source. (*Since: 1.2*)
+           url: A URL, which may be using an alias
+           alias_override: Optionally, an URI to override the alias with. (*Since: 1.2*)
+           primary: Whether this is the primary URL for the source. (*Since: 1.2*)
 
         Returns:
-           str: The fully qualified URL, with aliases resolved
+           The fully qualified URL, with aliases resolved
         .. note::
 
            This must be called for every URL in the configuration during
@@ -583,12 +584,12 @@ class Source(Plugin):
             project = self._get_project()
             return project.translate_url(url, first_pass=self.__first_pass)
 
-    def mark_download_url(self, url, *, primary=True):
+    def mark_download_url(self, url: str, *, primary: bool = True) -> None:
         """Identifies the URL that this Source uses to download
 
         Args:
-           url (str): The URL used to download
-           primary (bool): Whether this is the primary URL for the source
+           url: The URL used to download
+           primary: Whether this is the primary URL for the source
 
         .. note::
 
@@ -630,14 +631,14 @@ class Source(Plugin):
             assert (url in self.__marked_urls or not _extract_alias(url)), \
                 "URL was not seen at configure time: {}".format(url)
 
-    def get_project_directory(self):
+    def get_project_directory(self) -> str:
         """Fetch the project base directory
 
         This is useful for sources which need to load resources
         stored somewhere inside the project.
 
         Returns:
-           str: The project base directory
+           The project base directory
         """
         project = self._get_project()
         return project.directory