From db4ace7c3addeacec9483651189516a4a5c16c67 Mon Sep 17 00:00:00 2001 From: Chandan Singh Date: Mon, 24 Jun 2019 23:25:51 +0100 Subject: WIP: Add tyephints for Source class This is rather rudimentary at this stage. It is primarily here to serve as a demo of this feature. --- src/buildstream/source.py | 53 ++++++++++++++++++++++++----------------------- 1 file 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() ` See :func:`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 -- cgit v1.2.1