docs: Add documentation and lint

Author: delilahw

src/artifacts-helper/codespaces_artifacts_helper_keyring/pyproject.toml

@@ -53,6 +53,7 @@ indent-width = 4
 
 [tool.ruff.lint]
 extend-select = ["B", "C4", "D", "E", "F", "I", "W", "Q"]
+ignore = ["D102"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

src/artifacts-helper/codespaces_artifacts_helper_keyring/src/codespaces_artifacts_helper_keyring/__init__.py

@@ -1,2 +1,4 @@
+"""Provides a keyring backend for the Codespaces Artifacts Helper."""
+
 from .artifacts_helper_credential_provider import ArtifactsHelperCredentialProvider
 from .keyring_backend import CodespacesArtifactsHelperKeyringBackend

src/artifacts-helper/codespaces_artifacts_helper_keyring/src/codespaces_artifacts_helper_keyring/artifacts_helper_credential_provider.py

@@ -1,7 +1,4 @@
-# --------------------------------------------------------------------------------------------
-# Copyright (c) Microsoft Corporation. All rights reserved.
-# Licensed under the MIT License. See LICENSE in the project root for license information.
-# --------------------------------------------------------------------------------------------
+"""Wrapper to interface with the artifacts authentication helper."""
 
 from __future__ import absolute_import
 
@@ -18,38 +15,80 @@
 
 @dataclass
 class Credentials:
+    """A set of credentials, consisting of a username and password."""
+
     username: str
     password: str
 
 
 class ArtifactsHelperCredentialProviderError(RuntimeError):
-    pass
+    """Generic error for ArtifactsHelperCredentialProvider."""
 
 
 class ArtifactsHelperCredentialProvider:
+    """A wrapper retrieve credentials from the artifacts authentication helper.
+
+    The authentication helper should be installed from
+    https://github.com/microsoft/ado-codespaces-auth.
+
+    Attributes:
+        DEFAULT_AUTH_HELPER_PATH: The default path to the authentication helper
+            executable.
+
+    Raises:
+        ArtifactsHelperCredentialProviderError: When the credentials could not be
+            retrieved.
+    """
+
     DEFAULT_AUTH_HELPER_PATH = "~/ado-auth-helper"
 
     def __init__(
         self,
         auth_helper_path: Union[os.PathLike, str] = DEFAULT_AUTH_HELPER_PATH,
         timeout: int = 30,
     ):
+        """Initialise the provider.
+
+        Args:
+            auth_helper_path: The path to the authentication helper executable, or the
+                name of the executable if it is in the PATH. Defaults to
+                DEFAULT_AUTH_HELPER_PATH.
+
+            timeout: The timeout in seconds for calling the authentication helper and
+                any HTTP requests made to test credentials. Defaults to 30.
+        """
         self.auth_tool_path = self.resolve_auth_helper_path(auth_helper_path)
         self.timeout = timeout
 
     @staticmethod
     def resolve_auth_helper_path(
         auth_helper_path: Union[os.PathLike, str],
     ) -> Optional[str]:
+        """Resolve the path to the authentication helper executable.
+
+        Returns:
+            The path to the authentication helper executable, or `None` if it is not
+            executable or not found.
+        """
         return shutil.which(str(Path(auth_helper_path).expanduser()), mode=os.X_OK)
 
     @classmethod
     def auth_helper_installed(cls, auth_helper_path: Union[os.PathLike, str]) -> bool:
+        """Check whether the authentication helper is installed and executable."""
         return cls.resolve_auth_helper_path(auth_helper_path) is not None
 
-    def get_credentials(self, url) -> Optional[Credentials]:
-        # Public feed short circuit: return nothing if not getting credentials for the upload endpoint
-        # (which always requires auth) and the endpoint is public (can authenticate without credentials).
+    def get_credentials(self, url: str) -> Optional[Credentials]:
+        """Get credentials for the given URL.
+
+        Args:
+            url: The URL to retrieve credentials for.
+
+        Returns:
+            The credentials for the URL, or `None` if no credentials could be retrieved.
+        """
+        # Public feed short circuit: return nothing if not getting credentials for the
+        # upload endpoint (which always requires auth) and the endpoint is public (can
+        # authenticate without credentials).
         if not self._is_upload_endpoint(url) and self._can_authenticate(url, None):
             return None
 
@@ -87,16 +126,19 @@ def _get_jwt_from_helper(self) -> str:
                 return stdout.strip()
             else:
                 raise ArtifactsHelperCredentialProviderError(
-                    f"Failed to get credentials: No output from subprocess {self.auth_tool_path}"
+                    "Failed to get credentials: "
+                    f"No output from subprocess {self.auth_tool_path}"
                 )
 
         except subprocess.CalledProcessError as e:
             raise ArtifactsHelperCredentialProviderError(
-                f"Failed to get credentials: Process {self.auth_tool_path} exited with code {e.returncode}. Error: {e.stderr}"
+                f"Failed to get credentials: Process {self.auth_tool_path} exited with "
+                f"code {e.returncode}. Error: {e.stderr}"
             ) from e
         except subprocess.TimeoutExpired as e:
             raise ArtifactsHelperCredentialProviderError(
-                f"Failed to get credentials: Process {self.auth_tool_path} timed out after {self.timeout} seconds"
+                f"Failed to get credentials: Process {self.auth_tool_path} timed out "
+                f"after {self.timeout} seconds"
             ) from e
 
     def _get_credentials_from_jwt(self, jwt_str: str) -> Credentials:

src/artifacts-helper/codespaces_artifacts_helper_keyring/src/codespaces_artifacts_helper_keyring/keyring_backend.py

@@ -1,3 +1,5 @@
+"""Keyring backend for Codespaces Artifacts Helper."""
+
 import warnings
 from typing import Optional, Type
 from urllib.parse import urlsplit
@@ -10,6 +12,8 @@
 
 
 class CodespacesArtifactsHelperKeyringBackend(KeyringBackend):
+    """A keyring backend for Azure Artifacts using the ADO Codespaces Auth Helper."""
+
     SUPPORTED_NETLOC = (
         "pkgs.dev.azure.com",
         "pkgs.visualstudio.com",

src/artifacts-helper/codespaces_artifacts_helper_keyring/tests/test_artifacts_helper_credential_provider.py

@@ -5,17 +5,15 @@
 from typing import Optional, Union
 
 import pytest
-from codespaces_artifacts_helper_keyring import (
-    ArtifactsHelperCredentialProvider,
-)
+from codespaces_artifacts_helper_keyring import ArtifactsHelperCredentialProvider
 from codespaces_artifacts_helper_keyring.artifacts_helper_credential_provider import (
     ArtifactsHelperCredentialProviderError,
 )
 
 
 class TestArtifactsHelperWrapper(unittest.TestCase):
     SUPPORTED_HOST = "https://pkgs.dev.azure.com/"
-    TEST_JWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cG4iOiJ1cG5AY29udG9zby5jb20iLCJ1bmlxdWVfbmFtZSI6Im5hbWVAY29udG9zby5jb20ifQ.srKYrr5B0i29XERHsvE6mqZpLBzyyrX-gUKe9OHZODw"
+    TEST_JWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cG4iOiJ1cG5AY29udG9zby5jb20iLCJ1bmlxdWVfbmFtZSI6Im5hbWVAY29udG9zby5jb20ifQ.srKYrr5B0i29XERHsvE6mqZpLBzyyrX-gUKe9OHZODw"  # noqa: E501
     TEST_JWT_USERNAME = "name@contoso.com"
 
     def __init__(self, *args, **kwargs) -> None:

src/artifacts-helper/codespaces_artifacts_helper_keyring/tests/test_keyring_backend.py

@@ -1,8 +1,3 @@
-# --------------------------------------------------------------------------------------------
-# Copyright (c) Microsoft Corporation. All rights reserved.
-# Licensed under the MIT License. See License.txt in the project root for license information.
-# --------------------------------------------------------------------------------------------
-
 import keyring
 import keyring.backend
 import keyring.backends.chainer