docs: applies docstring results of 'make fix'

posit-dev · Mar 27, 2024 · 992bbf6 · 992bbf6
1 parent ffb0ea7
commit 992bbf6
Show file tree

Hide file tree

Showing 13 changed files with 93 additions and 33 deletions.
diff --git a/examples/connect/dash/app.py b/examples/connect/dash/app.py
@@ -37,7 +37,6 @@ def update_page(_):
     Dash example application that shows user information and
     the first few rows from a table hosted in Databricks.
     """
-
     session_token = flask.request.headers.get("Posit-Connect-User-Session-Token")
     credentials_provider = viewer_credentials_provider(user_session_token=session_token)
 

diff --git a/examples/connect/shiny-python/app.py b/examples/connect/shiny-python/app.py
@@ -24,7 +24,6 @@ def server(input: Inputs, output: Outputs, session: Session):
     Shiny for Python example application that shows user information and
     the first few rows from a table hosted in Databricks.
     """
-
     session_token = session.http_conn.headers.get("Posit-Connect-User-Session-Token")
     credentials_provider = viewer_credentials_provider(user_session_token=session_token)
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -35,3 +35,24 @@ addopts = [
 
 [tool.setuptools_scm]
 version_file = "src/posit/_version.py"
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 20
+
+[tool.ruff.lint]
+select = ["D"]
+ignore = [
+     'D107',
+     'D203',
+     'D212',
+     'D213',
+     'D402',
+     'D413',
+     'D415',
+     'D416',
+     'D417'
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
diff --git a/src/posit/connect/auth.py b/src/posit/connect/auth.py
@@ -5,6 +5,14 @@
 
 
 class Auth(AuthBase):
+    """_summary_
+
+    Parameters
+    ----------
+    AuthBase : _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_  _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_ _type_
+        _description_
+    """
+
     def __init__(self, config: Config) -> None:
         self._config = config
 

diff --git a/src/posit/connect/client.py b/src/posit/connect/client.py
@@ -96,7 +96,8 @@ def request(self, method: str, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to pass to the underlying session's request method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object containing the server's response to the request.
         """
         url = urls.append_path(self.config.url, path)
@@ -110,7 +111,8 @@ def get(self, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to be passed to the underlying session's `get` method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object.
 
         """
@@ -125,7 +127,8 @@ def post(self, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to be passed to the underlying session's `post` method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object.
 
         """
@@ -140,7 +143,8 @@ def put(self, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to be passed to the underlying session's `put` method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object.
 
         """
@@ -155,7 +159,8 @@ def patch(self, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to be passed to the underlying session's `patch` method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object.
 
         """
@@ -170,7 +175,8 @@ def delete(self, path: str, **kwargs) -> Response:
             path (str): The path to send the request to.
             **kwargs: Additional keyword arguments to be passed to the underlying session's `delete` method.
 
-        Returns:
+        Returns
+        -------
             Response: The response object.
 
         """

diff --git a/src/posit/connect/config.py b/src/posit/connect/config.py
@@ -8,10 +8,12 @@
 def _get_api_key() -> str:
     """Gets the API key from the environment variable 'CONNECT_API_KEY'.
 
-    Raises:
+    Raises
+    ------
         ValueError: if CONNECT_API_KEY is not set or invalid
 
-    Returns:
+    Returns
+    -------
         The API key
     """
     value = os.environ.get("CONNECT_API_KEY")
@@ -27,10 +29,12 @@ def _get_url() -> str:
 
     The `requests` library uses 'endpoint' instead of 'server'. We will use 'endpoint' from here forward for consistency.
 
-    Raises:
+    Raises
+    ------
         ValueError: if CONNECT_SERVER is not set or invalid.
 
-    Returns:
+    Returns
+    -------
         The endpoint.
     """
     value = os.environ.get("CONNECT_SERVER")

diff --git a/src/posit/connect/content.py b/src/posit/connect/content.py
@@ -243,7 +243,8 @@ def update(
             default_py_environment_management (Optional[bool]): Whether to use default Python environment management.
             service_account_name (Optional[str]): The service account name.
 
-        Returns:
+        Returns
+        -------
             None
         """
         ...
@@ -257,7 +258,8 @@ def update(self, *args, **kwargs) -> None:
             *args
             **kwargs
 
-        Returns:
+        Returns
+        -------
             None
         """
         ...
@@ -270,7 +272,8 @@ def update(self, *args, **kwargs) -> None:
             *args
             **kwargs
 
-        Returns:
+        Returns
+        -------
             None
         """
         body = dict(*args, **kwargs)

diff --git a/src/posit/connect/external/databricks.py b/src/posit/connect/external/databricks.py
@@ -13,7 +13,8 @@
 # In order to keep compatibility with the Databricks SDK
 class CredentialsProvider(abc.ABC):
     """CredentialsProvider is the protocol (call-side interface)
-    for authenticating requests to Databricks REST APIs"""
+    for authenticating requests to Databricks REST APIs
+    """
 
     @abc.abstractmethod
     def auth_type(self) -> str:

diff --git a/src/posit/connect/me.py b/src/posit/connect/me.py
@@ -14,7 +14,8 @@ def get(config: Config, session: requests.Session) -> User:
         config (Config): The configuration object containing the URL.
         session (requests.Session): The session object used for making HTTP requests.
 
-    Returns:
+    Returns
+    -------
         User: The current user.
     """
     url = urls.append_path(config.url, "v1/user")

diff --git a/src/posit/connect/paginator.py b/src/posit/connect/paginator.py
@@ -13,7 +13,8 @@ class Page:
     """
     Represents a page of results returned by the paginator.
 
-    Attributes:
+    Attributes
+    ----------
         current_page (int): The current page number.
         total (int): The total number of results.
         results (List[dict]): The list of results on the current page.
@@ -32,7 +33,8 @@ class Paginator:
         session (requests.Session): The session object to use for making API requests.
         url (str): The URL of the paginated API endpoint.
 
-    Attributes:
+    Attributes
+    ----------
         session (requests.Session): The session object to use for making API requests.
         url (str): The URL of the paginated API endpoint.
     """
@@ -46,7 +48,8 @@ def fetch_results(self) -> List[dict]:
         """
         Fetches and returns all the results from the paginated API endpoint.
 
-        Returns:
+        Returns
+        -------
             A list of dictionaries representing the fetched results.
         """
         results = []
@@ -58,7 +61,8 @@ def fetch_pages(self) -> Generator[Page, None, None]:
         """
         Fetches pages of results from the API.
 
-        Yields:
+        Yields
+        ------
             Page: A page of results from the API.
         """
         count = 0
@@ -87,7 +91,8 @@ def fetch_page(self, page_number: int) -> Page:
         Args:
             page_number (int): The page number to fetch.
 
-        Returns:
+        Returns
+        -------
             Page: The fetched page object.
 
         """

diff --git a/src/posit/connect/urls.py b/src/posit/connect/urls.py
@@ -12,7 +12,8 @@ def server_to_api_url(url: str) -> str:
     Args:
         url (str): The URL to fix.
 
-    Returns:
+    Returns
+    -------
         str: The fixed URL.
     """
     url = url.rstrip("/")
@@ -28,10 +29,12 @@ def validate(url: str) -> None:
     Args:
         url (str): The URL to be validated.
 
-    Returns:
+    Returns
+    -------
         bool: True if the URL is valid, False otherwise.
 
-    Raises:
+    Raises
+    ------
         ValueError: If the URL is missing a scheme or is not absolute.
     """
     split = urlsplit(url, allow_fragments=False)
@@ -54,7 +57,8 @@ def append_path(url: str, path: str) -> str:
         url (str): The original URL.
         path (str): The path to append.
 
-    Returns:
+    Returns
+    -------
         str: The modified URL with the appended path.
     """
     # See https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlsplit

diff --git a/src/posit/connect/users.py b/src/posit/connect/users.py
@@ -66,7 +66,8 @@ def lock(self, *, force: bool = False):
         Args:
             force (bool, optional): If set to True, overrides lock protection allowing a user to lock their own account. Defaults to False.
 
-        Returns:
+        Returns
+        -------
             None
         """
         _me = me.get(self.config, self.session)
@@ -83,7 +84,8 @@ def unlock(self):
         """
         Unlocks the user account.
 
-        Returns:
+        Returns
+        -------
             None
         """
         url = urls.append_path(self.config.url, f"v1/users/{self.guid}/lock")
@@ -110,7 +112,8 @@ def update(
             last_name (str): The last name for the user.
             user_role (str): The role for the user.
 
-        Returns:
+        Returns
+        -------
             None
         """
         ...
@@ -124,7 +127,8 @@ def update(self, *args, **kwargs) -> None:
             *args
             **kwargs
 
-        Returns:
+        Returns
+        -------
             None
         """
         ...
@@ -137,7 +141,8 @@ def update(self, *args, **kwargs) -> None:
             *args
             **kwargs
 
-        Returns:
+        Returns
+        -------
             None
         """
         body = dict(*args, **kwargs)

diff --git a/tests/posit/connect/api.py b/tests/posit/connect/api.py
@@ -25,7 +25,11 @@ def load_mock(path: str) -> dict:
 
     Examples
     --------
-    >>> data = load_mock("v1/example.json")
-    >>> data = load_mock("v1/example.jsonc")
+    >>> data = load_mock(
+    ...     "v1/example.json"
+    ... )
+    >>> data = load_mock(
+    ...     "v1/example.jsonc"
+    ... )
     """
     return json.loads((Path(__file__).parent / "__api__" / path).read_text())