[IMP] File object methods : get_tags, add_tag, remove_tag ; Tag object methods : get_related_files

Author: luffah

src/nextcloud/api_wrappers/activity.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
 Activity API wrapper
-See https://doc.owncloud.com/server/user_manual/apps/activity.html
+See https://github.com/nextcloud/activity
+    https://doc.owncloud.com/server/user_manual/apps/activity.html
     https://doc.owncloud.com/server/developer_manual/core/apis/
 """
 from nextcloud import base

src/nextcloud/api_wrappers/apps.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 """
 Apps API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
+See https://docs.nextcloud.com/server/14/admin_manual/configuration_user/instruction_set_for_users.html
+    https://docs.nextcloud.com/server/14/admin_manual/configuration_user/user_provisioning_api.html
+    https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
 """
 from nextcloud import base
 

src/nextcloud/api_wrappers/capabilities.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
 Capabilities API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/ocs-capabilities.html
+See https://docs.nextcloud.com/server/14/developer_manual/client_apis/OCS/index.html#capabilities-api
+    https://doc.owncloud.com/server/developer_manual/core/apis/ocs-capabilities.html
 """
 from nextcloud import base
 

src/nextcloud/api_wrappers/group.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 """
 Group API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
+See https://docs.nextcloud.com/server/14/admin_manual/configuration_user/instruction_set_for_groups.html
+    https://docs.nextcloud.com/server/14/admin_manual/configuration_user/user_provisioning_api.html
+    https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
 """
 from nextcloud.base import ProvisioningApiWrapper
 

src/nextcloud/api_wrappers/group_folders.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
 GroupFolders API wrapper
-See https://apps.nextcloud.com/apps/groupfolders
+See https://github.com/nextcloud/groupfolders
+    https://apps.nextcloud.com/apps/groupfolders
 """
 from nextcloud import base
 

src/nextcloud/api_wrappers/notifications.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
 """
 Notification API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/ocs-notification-endpoint-v1.html
-See https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html?highlight=notification#notifications
+See https://github.com/nextcloud/notifications/
+    https://doc.owncloud.com/server/developer_manual/core/apis/ocs-notification-endpoint-v1.html
+    https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html?highlight=notification#notifications
 """
 from nextcloud import base
 

src/nextcloud/api_wrappers/share.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 """
 Share API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/ocs-share-api.html
 See https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-share-api.html
+    https://doc.owncloud.com/server/developer_manual/core/apis/ocs-share-api.html
 """
 from nextcloud import base
 from nextcloud.codes import ShareType

src/nextcloud/api_wrappers/systemtags.py

@@ -7,6 +7,7 @@
 from nextcloud.base import WebDAVApiWrapper
 from nextcloud.common.collections import PropertySet
 from nextcloud.common.properties import Property as Prop
+from nextcloud.api_wrappers import webdav
 
 
 class Tag(PropertySet):
@@ -19,18 +20,111 @@ class Tag(PropertySet):
         Prop('oc:user-assignable', json='userAssignable', default=True)
     ]
 
+    def __repr__(self):
+        add_info = (' %s' % repr(self.display_name)) if hasattr(
+            self, 'display_name') else ''
+        return super(Tag, self).__repr__(add_info=add_info)
+
+    def get_related_files(self, path=''):
+        """
+        Get files related to current tag
+        :param path: (optionnal) a path to search in
+        """
+        _id = int(self.id)
+        ret = self._wrapper.client.fetch_files_with_filter(
+            path=path,
+            filter_rules={'oc': {'systemtag': _id}}
+        )
+        return ret.data or []
+
+
+class File(webdav.File):
+
+    def _get_file_kwargs(self):
+        kwargs = {}
+        if not getattr(self, 'file_id', False):
+            kwargs['path'] = self._get_remote_path()
+        else:
+            kwargs['file_id'] = self.file_id
+        return kwargs
+
+    def get_tags(self):
+        """
+        Get tags related to current file
+        :returns :  list<Tag>
+        """
+        kwargs = self._get_file_kwargs()
+        return self._wrapper.client.get_systemtags_relation(**kwargs)
+
+    def add_tag(self, **kwargs):
+        """
+        Assign tag to the current file
+        :param tag_id:   tag id
+        :param tag_name: tag name (if tag_id in not provided)
+        :returns : False if failure
+        """
+        kwargs.update(self._get_file_kwargs())
+        resp = self._wrapper.client.add_systemtags_relation(**kwargs)
+        return resp.is_ok
+
+    def remove_tag(self, **kwargs):
+        """
+        Unassign tag to the current file
+        :param tag_id:   tag id
+        :param tag_name: tag name (if tag_id in not provided)
+        :returns : False if failure
+        """
+        kwargs.update(self._get_file_kwargs())
+        resp = self._wrapper.client.remove_systemtags_relation(**kwargs)
+        return resp.is_ok
+
+
+webdav.File = File
 
 class SystemTags(WebDAVApiWrapper):
     """ SystemTags API wrapper """
     API_URL = '/remote.php/dav/systemtags'
 
-    def get_sytemtag(self, name, fields=None, json_output=None):
+    @classmethod
+    def _get_tags_from_response(cls, ret, one=False):
+        if ret.data:
+            ret = ret.data
+            if ret[0].href.endswith('/'):
+                ret = ret[1:]
+        else:
+            ret = []
+        if one:
+            return ret[0] if ret else None
+        return ret
+
+    def get_systemtags(self):
+        """
+        Get list of all tags
+
+        :returns: list<Tag>
+        """
+        return self._get_tags_from_response(
+            self.fetch_systemtags(json_output=False)
+        )
+
+    def get_systemtag(self, name):
+        """
+        Return a nammed tag
+
+        :returns: Tag
+        """
+        return self._get_tags_from_response(
+            self.fetch_sytemtag(name, json_output=False),
+            one=True
+        )
+
+    def fetch_sytemtag(self, name, fields=None, json_output=None):
         """
         Get attributes of a nammed tag
 
         :param name (str): tag name
         :param fields (<list>str): field names
-        :returns: requester response with <list>Tag in data
+        :returns: requester response with list<Tag> in data
         """
         if not fields:
             fields = Tag._fields
@@ -40,21 +134,24 @@ def get_sytemtag(self, name, fields=None, json_output=None):
             }))
         if json_output is None:
             json_output = self.json_output
-        return Tag.from_response(resp,
+        return Tag.from_response(resp, wrapper=self,
                                  json_output=json_output,
                                  init_attrs=True,
                                  filtered=lambda t: t.display_name == name)
 
-    def get_systemtags(self):
+    def fetch_systemtags(self, json_output=None):
         """
-        Get list of all tags
+        List of all tags
 
-        :returns: requester response with <list>Tag in data
+        :returns: requester response with list<Tag> in data
         """
         resp = self.requester.propfind(
             data=Tag.build_xml_propfind(use_default=True)
         )
-        return Tag.from_response(resp, json_output=self.json_output)
+        if json_output is None:
+            json_output = self.json_output
+        return Tag.from_response(resp, wrapper=self,
+                                 json_output=json_output)
 
     def create_systemtag(self, name, **kwargs):
         """
@@ -100,13 +197,13 @@ class SystemTagsRelation(WebDAVApiWrapper):
     def _get_fileid_from_path(self, path):
         """ Tricky function to fetch file """
         resp = self.client.get_file_property(path, 'fileid')
-        id_ = None
+        _id = None
         if resp.data:
-            id_ = int(resp.data)
-        return id_
+            _id = int(resp.data)
+        return _id
 
     def _get_systemtag_id_from_name(self, name):
-        resp = self.client.get_sytemtag(name, ['id'], json_output=False)
+        resp = self.client.fetch_sytemtag(name, ['id'], json_output=False)
         tag_id = None
         if resp.data:
             tag_id = int(resp.data[0].id)
@@ -131,13 +228,31 @@ def get_systemtags_relation(self, file_id=None, **kwargs):
         :param file_id (int): file id found from file object
         :param path (str): if no file_id provided, path to file/folder
 
-        :returns: requester response with <list>Tag in data
+        :returns: requester response with list<Tag> in data
+        """
+        return SystemTags._get_tags_from_response(
+            self.fetch_systemtags_relation(file_id=file_id,
+                                           json_output=False, **kwargs)
+        )
+
+    def fetch_systemtags_relation(self, file_id=None, json_output=None, **kwargs):
+        """
+        Get all tags from a given file/folder
+
+        :param file_id (int): file id found from file object
+        :param path (str): if no file_id provided, path to file/folder
+
+        :returns: requester response with list<Tag> in data
         """
         file_id, = self._arguments_get(['file_id'], dict(file_id=file_id,
                                                          **kwargs))
-        data = Tag.build_xml_propfind()
+        data = Tag.build_xml_propfind(use_default=True)
         resp = self.requester.propfind(additional_url=file_id, data=data)
-        return Tag.from_response(resp, json_output=(self.json_output))
+        return Tag.from_response(resp,
+                                 json_output=(
+                                     self.json_output if
+                                     json_output is None else json_output)
+                                 )
 
     def remove_systemtags_relation(self, file_id=None, tag_id=None, **kwargs):
         """
@@ -155,7 +270,8 @@ def remove_systemtags_relation(self, file_id=None, tag_id=None, **kwargs):
         if not file_id:
             raise ValueError('No file found')
         if not tag_id:
-            raise ValueError('No tag found (%s)' % kwargs.get('tag_name', None))
+            raise ValueError('No tag found (%s)' %
+                             kwargs.get('tag_name', None))
         resp = self.requester.delete(url=('{}/{}'.format(file_id, tag_id)))
         return resp
 
@@ -175,7 +291,8 @@ def add_systemtags_relation(self, file_id=None, tag_id=None, **kwargs):
         if not file_id:
             raise ValueError('No file found')
         if not tag_id:
-            data = Tag.default_get(display_name=kwargs.get('tag_name'), **kwargs)
+            data = Tag.default_get(
+                display_name=kwargs.get('tag_name'), **kwargs)
             resp = self.requester.post(
                 url=file_id,
                 data=json.dumps(data),

src/nextcloud/api_wrappers/user.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 """
 User API wrapper
-See https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
+See https://docs.nextcloud.com/server/14/admin_manual/configuration_user/instruction_set_for_users.html
+    https://docs.nextcloud.com/server/14/admin_manual/configuration_user/user_provisioning_api.html
+    https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
 """
 from nextcloud import base
 

src/nextcloud/api_wrappers/user_ldap.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
 User LDAP wrapper
-See https://doc.owncloud.com/server/10.7/admin_manual/configuration/server/occ_commands/app_commands/ldap_integration_commands.html
+See https://docs.nextcloud.com/server/14/admin_manual/configuration_user/user_auth_ldap_api.html
+    https://doc.owncloud.com/server/10.7/admin_manual/configuration/server/occ_commands/app_commands/ldap_integration_commands.html
 """
 import re
 from nextcloud import base