initial commit for future SharesAPI (#42)

Signed-off-by: Alexander Piskun <[email protected]>

Author: bigcat88

CHANGELOG.md

@@ -6,8 +6,8 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
-- Updated documentation, description
--
+- Updated documentation, description.
+- Updated `FsNode` class with properties for parsing permissions.
 
 ## [0.0.24 - 2023-07-18]
 

README.md

@@ -25,7 +25,7 @@ Project cloud-py-api was **abandoned** and divided into two parts:
  * User status manipulation
  * Weather status
  * ~~Nextcloud notifications support~~
- * ~~Shares operations support~~
+ * Shares support
  * ~~Talk support~~
 
 ### Extended Features with installed App_ecosystem_v2:

docs/reference/Shares.rst

@@ -0,0 +1,13 @@
+.. py:currentmodule:: nc_py_api.files_sharing
+
+File Sharing
+============
+
+The Shares API is universal for both modes and provides all the necessary methods for working with the Nextcloud Shares system.
+Refer to the **share examples** to see how to use them nicely.
+
+.. autoclass:: Share
+    :members:
+
+.. autoclass:: FilesSharingAPI
+    :members:

docs/reference/constants.rst

@@ -0,0 +1,13 @@
+.. py:currentmodule:: nc_py_api
+
+Constants
+=========
+
+.. autoclass:: SharePermissions
+    :members:
+
+.. autoclass:: ShareType
+    :members:
+
+.. autoclass:: ShareStatus
+    :members:

docs/reference/index.rst

@@ -4,5 +4,7 @@ Reference
 .. toctree::
    :maxdepth: 2
 
-   Files.rst
-   Session.rst
+   Files
+   Shares
+   Session
+   constants

nc_py_api/__init__.py

@@ -3,9 +3,10 @@
 """
 
 from ._version import __version__
-from .constants import ApiScope, LogLvl
+from .constants import ApiScope, LogLvl, SharePermissions, ShareStatus, ShareType
 from .exceptions import NextcloudException, NextcloudExceptionNotFound, check_error
 from .files import FsNode, FsNodeInfo
+from .files_sharing import Share
 from .integration_fastapi import (
     enable_heartbeat,
     nc_app,

nc_py_api/constants.py

@@ -1,6 +1,6 @@
 """Common constants. Do not use them directly, all public ones are imported to __init__.py"""
 
-from enum import IntEnum
+from enum import IntEnum, IntFlag
 from typing import TypedDict
 
 
@@ -22,6 +22,7 @@ class ApiScope(IntEnum):
     USER_STATUS = 11
     NOTIFICATIONS = 12
     WEATHER_STATUS = 13
+    FILES_SHARING = 14
 
 
 class ApiScopesStruct(TypedDict):
@@ -34,3 +35,56 @@ class OCSRespond(IntEnum):
     RESPOND_UNAUTHORISED = 997
     RESPOND_NOT_FOUND = 998
     RESPOND_UNKNOWN_ERROR = 999
+
+
+class SharePermissions(IntFlag):
+    """The share permissions to be set"""
+
+    PERMISSION_READ = 1
+    """Access to read"""
+    PERMISSION_UPDATE = 2
+    """Access to write"""
+    PERMISSION_CREATE = 4
+    """Access to create new objects in the share"""
+    PERMISSION_DELETE = 8
+    """Access to remove objects in the share"""
+    PERMISSION_SHARE = 16
+    """Access to re-share objects in the share"""
+
+
+class ShareType(IntEnum):
+    """Type of the object that will receive share"""
+
+    TYPE_USER = 0
+    """Share to the user"""
+    TYPE_GROUP = 1
+    """Share to the group"""
+    TYPE_LINK = 3
+    """Share by link"""
+    TYPE_EMAIL = 4
+    """Share by the email"""
+    TYPE_REMOTE = 6
+    """Share to the Federation"""
+    TYPE_CIRCLE = 7
+    """Share to the Nextcloud Circle"""
+    TYPE_GUEST = 8
+    """Share to `Guest`"""
+    TYPE_REMOTE_GROUP = 9
+    """Share to the Federation group"""
+    TYPE_ROOM = 10
+    """Share to the Talk room"""
+    TYPE_DECK = 11
+    """Share to the Nextcloud Deck"""
+    TYPE_SCIENCE_MESH = 15
+    """Share to the Reva instance(Science Mesh)"""
+
+
+class ShareStatus(IntEnum):
+    """Status of the share"""
+
+    STATUS_PENDING = 0
+    """The share waits for acceptance"""
+    STATUS_ACCEPTED = 1
+    """The share was for accepted"""
+    STATUS_REJECTED = 2
+    """The share was for rejected"""

nc_py_api/files.py

@@ -1,5 +1,5 @@
 """
-Nextcloud API for working with file system.
+Nextcloud API for working with the file system.
 """
 
 import builtins
@@ -35,6 +35,7 @@ class FsNodeInfo(TypedDict):
     content_length: int
     last_modified: datetime
     permissions: str
+    """Permissions for the object."""
     favorite: bool
 
 
@@ -99,6 +100,38 @@ def __str__(self):
             f" last modified at {str(self.last_modified)} and {self.info['permissions']} permissions."
         )
 
+    @property
+    def is_shared(self) -> bool:
+        return self.info["permissions"].find("S") != -1
+
+    @property
+    def is_shareable(self) -> bool:
+        return self.info["permissions"].find("R") != -1
+
+    @property
+    def is_mounted(self) -> bool:
+        return self.info["permissions"].find("M") != -1
+
+    @property
+    def is_readable(self) -> bool:
+        return self.info["permissions"].find("G") != -1
+
+    @property
+    def is_deletable(self) -> bool:
+        return self.info["permissions"].find("D") != -1
+
+    @property
+    def is_updatable(self) -> bool:
+        if self.is_dir:
+            return self.info["permissions"].find("NV") != -1
+        return self.info["permissions"].find("W") != -1
+
+    @property
+    def is_creatable(self) -> bool:
+        if not self.is_dir:
+            return False
+        return self.info["permissions"].find("CK") != -1
+
 
 PROPFIND_PROPERTIES = [
     "d:resourcetype",
@@ -135,6 +168,8 @@ def __str__(self):
 
 
 class FilesAPI:
+    """This class provides all WebDAV functionality related to the files."""
+
     def __init__(self, session: NcSessionBasic):
         self._session = session
 

nc_py_api/files_sharing.py

@@ -0,0 +1,146 @@
+"""
+Nextcloud API for working with the files shares.
+"""
+
+from typing import Union
+
+from ._session import NcSessionBasic
+from .constants import SharePermissions, ShareType
+from .files import FsNode
+from .misc import check_capabilities, require_capabilities
+
+ENDPOINT_BASE = "/ocs/v1.php/apps/files_sharing/api/v1/"
+
+
+class Share:
+    """Class represents one Nextcloud Share."""
+
+    def __init__(self, raw_data: dict):
+        self.raw_data = raw_data
+
+    @property
+    def share_id(self) -> int:
+        return int(self.raw_data["id"])
+
+    @property
+    def type(self) -> ShareType:
+        return ShareType(int(self.raw_data["share_type"]))
+
+    @property
+    def permissions(self) -> SharePermissions:
+        """Recipient permissions"""
+
+        return SharePermissions(int(self.raw_data["permissions"]))
+
+    @property
+    def url(self) -> str:
+        return self.raw_data.get("url", "")
+
+    @property
+    def path(self) -> str:
+        return self.raw_data.get("path", "")
+
+    @property
+    def label(self) -> str:
+        return self.raw_data.get("label", "")
+
+    @property
+    def note(self) -> str:
+        return self.raw_data.get("note", "")
+
+    @property
+    def mimetype(self) -> str:
+        return self.raw_data.get("mimetype", "")
+
+
+class FilesSharingAPI:
+    """This class provides all File Sharing functionality."""
+
+    def __init__(self, session: NcSessionBasic):
+        self._session = session
+
+    @property
+    def available(self) -> bool:
+        """Returns True if the Nextcloud instance supports this feature, False otherwise."""
+
+        return not check_capabilities("files_sharing", self._session.capabilities)
+
+    def get_list(
+        self, shared_with_me=False, reshares=False, subfiles=False, path: Union[str, FsNode] = ""
+    ) -> list[Share]:
+        """Returns lists of shares."""
+
+        require_capabilities("files_sharing", self._session.capabilities)
+        path = path.path if isinstance(path, FsNode) else path
+        params = {
+            "shared_with_me": "true" if shared_with_me else "false",
+            "reshares": "true" if reshares else "false",
+            "subfiles": "true" if subfiles else "false",
+        }
+        if path:
+            params["path"] = path
+        result = self._session.ocs(method="GET", path=f"{ENDPOINT_BASE}/shares", params=params)
+        return [Share(i) for i in result]
+
+    def create(
+        self,
+        path: Union[str, FsNode],
+        permissions: SharePermissions,
+        share_type: ShareType,
+        share_with: str = "",
+        **kwargs,
+    ) -> Share:
+        """Creates a new share.
+
+        :param path: The path of an existing file/directory.
+        :param permissions: combination of the :py:class:`~nc_py_api.SharePermissions` object values.
+        :param share_type: :py:class:`~nc_py_api.ShareType` value.
+        :param share_with: the recipient of the shared object.
+        :param kwargs: *Additionally supported arguments*
+
+        Additionally supported arguments:
+            ``public`` - boolean indicating should share be available for non-registered users.
+                default = ``False``
+            ``password`` - string with password to protect share.
+                default = ``""``
+            ``send_password_by_talk`` - boolean indicating should password be automatically delivered using Talk.
+                default = ``False``
+            ``expire_date`` - py:class:`datetime` time when share should expire. `hours, minutes, seconds` are ignored.
+                default = None
+            ``note`` - string with note, if any.
+                default = ``""``
+            ``label`` - string with label, if any.
+                default = ``""``
+        """
+
+        require_capabilities("files_sharing", self._session.capabilities)
+        path = path.path if isinstance(path, FsNode) else path
+        params = {
+            "path": path,
+            "permissions": int(permissions),
+            "shareType": int(share_type),
+        }
+        if share_with:
+            kwargs["shareWith"] = share_with
+        if kwargs.get("public", False):
+            params["publicUpload"] = "true"
+        if "password" in kwargs:
+            params["publicUpload"] = kwargs["password"]
+        if kwargs.get("send_password_by_talk", False):
+            params["sendPasswordByTalk"] = "true"
+        if "expire_date" in kwargs:
+            params["expireDate"] = kwargs["expire_date"].isoformat()
+        if "note" in kwargs:
+            params["note"] = kwargs["note"]
+        if "label" in kwargs:
+            params["label"] = kwargs["label"]
+        return Share(self._session.ocs(method="POST", path=f"{ENDPOINT_BASE}/shares", params=params))
+
+    def delete(self, share_id: Union[int, Share]) -> None:
+        """Removes the given share.
+
+        :param share_id: The Share object or an ID of the share.
+        """
+
+        share_id = share_id.share_id if isinstance(share_id, Share) else share_id
+        self._session.ocs(method="DELETE", path=f"{ENDPOINT_BASE}/shares/{share_id}")

nc_py_api/nextcloud.py

@@ -11,6 +11,7 @@
 from .apps import AppAPI
 from .constants import APP_V2_BASIC_URL, ApiScope, LogLvl
 from .files import FilesAPI
+from .files_sharing import FilesSharingAPI
 from .misc import check_capabilities
 from .preferences import PreferencesAPI
 from .theming import ThemingInfo, get_parsed_theme
@@ -24,6 +25,7 @@
 class NextcloudBasic(ABC):
     apps: AppAPI
     files: FilesAPI
+    files_sharing: FilesSharingAPI
     preferences_api: PreferencesAPI
     users: UsersAPI
     users_groups: UserGroupsAPI
@@ -34,6 +36,7 @@ class NextcloudBasic(ABC):
     def _init_api(self, session: NcSessionBasic):
         self.apps = AppAPI(session)
         self.files = FilesAPI(session)
+        self.files_sharing = FilesSharingAPI(session)
         self.preferences_api = PreferencesAPI(session)
         self.users = UsersAPI(session)
         self.users_groups = UserGroupsAPI(session)