ruffs Dxxx checks (#62)

Added checks:

- D101 _Missing docstring in public class_
- D209 _Multi-line docstring closing quotes should be on a separate
line_
- D210 _No whitespaces allowed surrounding docstring text_
- D404 _First word of the docstring should not be "This"_

---------

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

Author: bigcat88

CHANGELOG.md

@@ -12,7 +12,7 @@ All notable changes to this project will be documented in this file.
 
 - Switched to `hatching` as a build system, now correct install optional dependencies.
 - Renamed methods, attributes that was `shadowing a Python builtins`. Enabled additional `Ruff` linters checks.
-- Regroup APIs, now Users related stuff starts with `user`, file related stuff with `file`.
+- Regroup APIs, now Users related stuff starts with `user`, file related stuff with `file`, UI stuff with `gui`.
 
 ## [0.0.26 - 2023-07-29]
 

nc_py_api/__init__.py

@@ -11,11 +11,11 @@
     ShareStatus,
     ShareType,
 )
+from .gui_defs import GuiActionFileInfo, GuiFileActionHandlerInfo
 from .integration_fastapi import (
     enable_heartbeat,
     nc_app,
     set_enabled_handler,
     set_scopes,
 )
 from .nextcloud import Nextcloud, NextcloudApp
-from .ui_files_actions_menu import UiActionFileInfo, UiFileActionHandlerInfo

nc_py_api/_version.py

@@ -1,3 +1,3 @@
-""" Version of nc_py_api."""
+"""Version of nc_py_api."""
 
 __version__ = "0.0.27.dev2"

nc_py_api/appconfig_preferences_ex.py renamed to nc_py_api/appcfg_prefs_ex.py

@@ -10,6 +10,8 @@
 
 @dataclass
 class CfgRecord:
+    """A representation of a single key-value pair returned from the `get_values` method."""
+
     key: str
     value: str
 
@@ -18,8 +20,8 @@ def __init__(self, raw_data: dict):
         self.value = raw_data["configvalue"]
 
 
-class BasicAppCfgPref:
-    url_suffix: str
+class _BasicAppCfgPref:
+    _url_suffix: str
 
     def __init__(self, session: NcSessionBasic):
         self._session = session
@@ -40,7 +42,7 @@ def get_values(self, keys: list[str]) -> list[CfgRecord]:
             raise ValueError("`key` parameter can not be empty")
         require_capabilities("app_ecosystem_v2", self._session.capabilities)
         data = {"configKeys": keys}
-        results = self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self.url_suffix}/get-values", json=data)
+        results = self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self._url_suffix}/get-values", json=data)
         return [CfgRecord(i) for i in results]
 
     def delete(self, keys: Union[str, list[str]], not_fail=True) -> None:
@@ -52,25 +54,29 @@ def delete(self, keys: Union[str, list[str]], not_fail=True) -> None:
             raise ValueError("`key` parameter can not be empty")
         require_capabilities("app_ecosystem_v2", self._session.capabilities)
         try:
-            self._session.ocs(method="DELETE", path=f"{APP_V2_BASIC_URL}/{self.url_suffix}", json={"configKeys": keys})
+            self._session.ocs(method="DELETE", path=f"{APP_V2_BASIC_URL}/{self._url_suffix}", json={"configKeys": keys})
         except NextcloudExceptionNotFound as e:
             if not not_fail:
                 raise e from None
 
 
-class PreferencesExAPI(BasicAppCfgPref):
-    url_suffix = "ex-app/preference"
+class PreferencesExAPI(_BasicAppCfgPref):
+    """User specific preferences API."""
+
+    _url_suffix = "ex-app/preference"
 
     def set_value(self, key: str, value: str) -> None:
         if not key:
             raise ValueError("`key` parameter can not be empty")
         require_capabilities("app_ecosystem_v2", self._session.capabilities)
         params = {"configKey": key, "configValue": value}
-        self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self.url_suffix}", json=params)
+        self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self._url_suffix}", json=params)
+
 
+class AppConfigExAPI(_BasicAppCfgPref):
+    """Non-user(App) specific preferences API."""
 
-class AppConfigExAPI(BasicAppCfgPref):
-    url_suffix = "ex-app/config"
+    _url_suffix = "ex-app/config"
 
     def set_value(self, key: str, value: str, sensitive: bool = False) -> None:
         if not key:
@@ -79,4 +85,4 @@ def set_value(self, key: str, value: str, sensitive: bool = False) -> None:
         params: dict = {"configKey": key, "configValue": value}
         if sensitive:
             params["sensitive"] = True
-        self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self.url_suffix}", json=params)
+        self._session.ocs(method="POST", path=f"{APP_V2_BASIC_URL}/{self._url_suffix}", json=params)

nc_py_api/apps.py

@@ -37,7 +37,8 @@ def disable(self, app_name: str) -> None:
 
         :param app_name: id of the application.
 
-        .. note:: Does not work in NextcloudApp mode, only for Nextcloud client mode."""
+        .. note:: Does not work in NextcloudApp mode, only for Nextcloud client mode.
+        """
         if not app_name:
             raise ValueError("`app_name` parameter can not be empty")
         self._session.ocs(method="DELETE", path=f"{ENDPOINT}/{app_name}")
@@ -47,7 +48,8 @@ def enable(self, app_name: str) -> None:
 
         :param app_name: id of the application.
 
-        .. note:: Does not work in NextcloudApp mode, only for Nextcloud client mode."""
+        .. note:: Does not work in NextcloudApp mode, only for Nextcloud client mode.
+        """
         if not app_name:
             raise ValueError("`app_name` parameter can not be empty")
         self._session.ocs(method="POST", path=f"{ENDPOINT}/{app_name}")

nc_py_api/constants.py

@@ -42,11 +42,15 @@ class ApiScope(IntEnum):
 
 
 class ApiScopesStruct(TypedDict):
+    """Reply of the Nextcloud App with the desired scopes."""
+
     required: list[int]
     optional: list[int]
 
 
 class OCSRespond(IntEnum):
+    """Special Nextcloud respond statuses for OCS calls."""
+
     RESPOND_SERVER_ERROR = 996
     RESPOND_UNAUTHORISED = 997
     RESPOND_NOT_FOUND = 998

nc_py_api/files.py

@@ -54,7 +54,7 @@
 
 
 class FilesAPI:
-    """This class provides all File System functionality and File Sharing abilities."""
+    """Class that encapsulates the file system and file sharing functionality."""
 
     sharing: FilesSharingAPI
     """API for managing Files Shares"""

nc_py_api/files_defs.py

@@ -38,7 +38,8 @@ def __init__(self, **kwargs):
     def last_modified(self) -> datetime:
         """Time when the object was last modified.
 
-        .. note:: ETag if more preferable way to check if the object was changed."""
+        .. note:: ETag if more preferable way to check if the object was changed.
+        """
         return self._last_modified
 
     @last_modified.setter
@@ -53,7 +54,8 @@ def last_modified(self, value: Union[str, datetime]):
 class FsNode:
     """A class that represents a Nextcloud file object.
 
-    Acceptable itself as a ``path`` parameter for the most file APIs."""
+    Acceptable itself as a ``path`` parameter for the most file APIs.
+    """
 
     full_path: str
     """Path to the object, including the username. Does not include `dav` prefix"""
@@ -92,7 +94,8 @@ def __eq__(self, other):
     @property
     def has_extra(self) -> bool:
         """Flag indicating whether this ``FsNode`` was obtained by the `mkdir` or `upload`
-        methods and does not contain extended information."""
+        methods and does not contain extended information.
+        """
         return bool(self.info.permissions)
 
     @property

nc_py_api/files_sharing.py

@@ -10,7 +10,7 @@
 
 
 class FilesSharingAPI:
-    """This class provides all File Sharing functionality."""
+    """Class provides all File Sharing functionality."""
 
     def __init__(self, session: NcSessionBasic):
         self._session = session

nc_py_api/gui.py

@@ -0,0 +1,16 @@
+"""Nextcloud API for User Interface."""
+
+from dataclasses import dataclass
+
+from ._session import NcSessionApp
+from .gui_files import GuiFilesActionsAPI
+
+
+@dataclass
+class GuiApi:
+    """Class that encapsulates all UI functionality."""
+
+    files_dropdown_menu: GuiFilesActionsAPI
+
+    def __init__(self, session: NcSessionApp):
+        self.files_dropdown_menu = GuiFilesActionsAPI(session)