Docstrings

scopesim/server/database.py

@@ -28,6 +28,7 @@ class PkgNotFoundError(Exception):
 
 
 def get_base_url():
+    """Get instrument package server URL from rc.__config__."""
     return rc.__config__["!SIM.file.server_base_url"]
 
 
@@ -179,6 +180,7 @@ def get_all_package_versions(client=None) -> Dict[str, List[str]]:
 
 
 def get_package_folders(client) -> Dict[str, str]:
+    """Map package names to server locations."""
     folders_dict = {pkg: path.strip("/")
                     for path, pkgs in dict(crawl_server_dirs(client)).items()
                     for pkg in pkgs}

scopesim/server/download_utils.py

@@ -36,6 +36,7 @@ def _make_tqdm_kwargs(desc: str = ""):
 
 
 def create_client(base_url, cached: bool = False, cache_name: str = ""):
+    """Create httpx Client instance, should support cache at some point."""
     if cached:
         raise NotImplementedError("Caching not yet implemented with httpx.")
     transport = httpx.HTTPTransport(retries=5)
@@ -47,6 +48,7 @@ def handle_download(client, pkg_url: str,
                     save_path: Path, pkg_name: str,
                     padlen: int, chunk_size: int = 128,
                     disable_bar=False) -> None:
+    """Perform a streamed download and write the content to disk."""
     tqdm_kwargs = _make_tqdm_kwargs(f"Downloading {pkg_name:<{padlen}}")
 
     stream = send_get(client, pkg_url, stream=True)
@@ -75,6 +77,7 @@ def handle_download(client, pkg_url: str,
 
 def handle_unzipping(save_path: Path, save_dir: Path,
                      pkg_name: str, padlen: int) -> None:
+    """Unpack a zipped folder, usually called right after downloading."""
     with ZipFile(save_path, "r") as zip_ref:
         namelist = zip_ref.namelist()
         tqdm_kwargs = _make_tqdm_kwargs(f"Extracting  {pkg_name:<{padlen}}")
@@ -83,6 +86,10 @@ def handle_unzipping(save_path: Path, save_dir: Path,
 
 
 def send_get(client, sub_url, stream: bool = False):
+    """Send a GET request (streamed or not) using an existing client.
+
+    The point of this function is mostly elaborate exception handling.
+    """
     try:
         if stream:
             response = client.stream("GET", sub_url)
@@ -106,6 +113,7 @@ def send_get(client, sub_url, stream: bool = False):
 
 def get_server_folder_contents(client, dir_name: str,
                                unique_str: str = ".zip$") -> Iterator[str]:
+    """Find all zip files in a given server folder."""
     dir_name = dir_name + "/" if not dir_name.endswith("/") else dir_name
     response = send_get(client, dir_name)
 

scopesim/server/github_utils.py

@@ -20,7 +20,7 @@
 
 def create_github_url(url: str) -> None:
     """
-    From the given url, produce a URL that is compatible with Github's REST API.
+    From the given url, produce a URL compatible with Github's REST API.
 
     Can handle blob or tree paths.
     """
@@ -46,7 +46,7 @@ def create_github_url(url: str) -> None:
 def download_github_folder(repo_url: str,
                            output_dir: Union[Path, str] = "./") -> None:
     """
-    Downloads the files and directories in repo_url.
+    Download the files and directories in repo_url.
 
     Re-written based on the on the download function
     `here <https://github.com/sdushantha/gitdir/blob/f47ce9d85ee29f8612ce5ae804560a12b803ddf3/gitdir/gitdir.py#L55>`_