Refactoring in order to ease creation of new wrappers outside this li…

…b (custom apps) + python2 compatibility + addition of a wrapper for SystemTags + some lints and documentation

README.md

@@ -9,8 +9,13 @@
 
 Python wrapper for NextCloud api
 
-This is Python wrapper for NextCloud's API. With it you can manage your NextCloud instances from Python scripts.
-Tested with python 3.7, NextCloud 14.
+This is Python wrapper for NextCloud's API.
+With it you can manage your NextCloud instances from Python scripts.
+
+Tested with :
+  * NextCloud 14, python 3.7
+  * NextCloud 20, python 2.7
+  * NextCloud 20, python 3.6
 
 
 ## FAQ
@@ -23,7 +28,7 @@ Check out the corresponding [nextcloud API documentation](https://nextcloud-api.
 
 #### How do I use it?
 
-Check out [the simple example](example.py) and also check out the [unit tests directory](tests).
+Check out [examples](examples) and also check out the [unit tests directory](tests).
 
 
 #### What do I do if it doesn't work?

api_implementation.json

@@ -21,6 +21,12 @@
       "implementation status": "OK",
       "date_last_checked": "2019-02-02"
     },
+    {
+      "name": "Tags API",
+      "url": "https://doc.owncloud.com/server/developer_manual/webdav_api/tags.html",
+      "implementation status": "OK",
+      "date_last_checked": "2021-05-03"
+    },
     {
       "name": "Activity app API",
       "url": "https://github.com/nextcloud/activity",

docs/source/examples.rst

@@ -4,5 +4,5 @@ Examples
 Users API methods
 -----------------
 
-.. include:: ../../example.py
+.. include:: ../../examples/user_management.py
     :literal:

requirements.in

@@ -1,2 +1,2 @@
-requests
-pytest
+requests>=2.0.1
+pytest

setup.py

@@ -10,19 +10,28 @@
 
 setuptools.setup(
     name='nextcloud',
-    version='0.0.1',
+    version='0.0.2',
     author='EnterpriseyIntranet',
     description="Python wrapper for NextCloud api",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/EnterpriseyIntranet/nextcloud-API",
     packages=setuptools.find_packages(PKGDIR),
     include_package_data=True,
-    install_requires=['requests'],
+    install_requires=[
+        'requests >= 2.0.1',
+        'six'
+    ],
     package_dir={'': 'src'},
     classifiers=[
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 2',
+        'Programming Language :: Python :: 3',
+        'Development Status :: 4 - Beta',
+        'Environment :: Web Environment',
+        'Intended Audience :: Developers',
+        'Topic :: Internet :: WWW/HTTP',
+        'Topic :: Software Development :: Libraries :: Python Modules',
         'License :: OSI Approved :: GNU General Public License (GPL)',
         "Operating System :: OS Independent",
     ],

src/nextcloud/__init__.py

@@ -1,3 +1,84 @@
 # -*- coding: utf-8 -*-
-from .NextCloud import NextCloud
+from .session import Session
+from .api_wrappers import API_WRAPPER_CLASSES
 
+
+class NextCloud(object):
+    """
+    A NextCloud/OwnCloud client.
+    Provides cookie persistence, connection-pooling, and configuration.
+
+    Basic Usage::
+
+      >>> from nextcloud import nextcloud
+      >>> s = Nextcloud('https://nextcloud.mysite.com', user='admin', password='admin')
+      >>> # or using use another auth method
+      >>> from requests.auth import HTTPBasicAuth
+      >>> s = Nextcloud('https://nextcloud.mysite.com', auth=HTTPBasicAuth('admin', 'admin'))
+      >>> #
+      >>> s.list_folders('/')
+      <Response [200] data={} is_ok=True>
+
+    For a persistent session::
+      >>> s.login()  # if no user, password, or auth in parameter use existing
+      >>> # some actions #
+      >>> s.logout()
+
+    Or as a context manager::
+
+      >>> with Nextcloud('https://nextcloud.mysite.com',
+      ...                user='admin', password='admin') as nxc:
+      ...     # some actions #
+    """
+
+    def __init__(self, endpoint, user=None, password=None, json_output=True, auth=None, session_kwargs=None):
+        self.query_components = []
+        self._session = Session(
+            url=endpoint, user=user, password=password, auth=auth,
+            session_kwargs=session_kwargs
+        )
+        self.json_output = json_output
+        for functionality_class in API_WRAPPER_CLASSES:
+            json_able = getattr(functionality_class, 'JSON_ABLE', False)
+            require_client = getattr(
+                functionality_class, 'REQUIRE_CLIENT', False)
+            functionality_instance = functionality_class(
+                self._session,
+                json_output=(json_able and json_output),
+                client=(require_client and self))
+            for potential_method in dir(functionality_instance):
+                if not potential_method.startswith('_'):
+                    if not callable(getattr(functionality_instance, potential_method)):
+                        pass
+                    else:
+                        setattr(self, potential_method, getattr(
+                            functionality_instance, potential_method))
+
+    @property
+    def user(self):
+        return self._session.user
+
+    @property
+    def url(self):
+        return self._session.url
+
+    def __enter__(self):
+        self.login()
+        return self
+
+    def __exit__(self, *args):
+        self.logout()
+
+    def login(self, user=None, password=None, auth=None):
+        self.logout()
+        self._session.login(user=user, password=password, auth=auth)
+
+    def with_auth(self, auth=None, **kwargs):
+        init_kwargs = {'session_kwargs': self._session._session_kwargs,
+                       'json_output': self.json_output}
+        init_kwargs.update(kwargs)
+        return (self.__class__)(self._session.url, auth=auth, **init_kwargs)
+
+    def logout(self):
+        if self._session.session:
+            self._session.logout()

src/nextcloud/api_wrappers/__init__.py

@@ -1,4 +1,5 @@
-# -*- coding: utf-8 -*-
+from nextcloud.base import API_WRAPPER_CLASSES
+
 from .activity import Activity
 from .apps import Apps
 from .capabilities import Capabilities
@@ -10,8 +11,4 @@
 from .user import User
 from .user_ldap import UserLDAP
 from .webdav import WebDAV
-
-OCS_API_CLASSES = [Activity, Apps, Capabilities, FederatedCloudShare, Group, GroupFolders,
-                   Notifications, Share, User, UserLDAP]
-
-WEBDAV_CLASS = WebDAV
+from .systemtags import SystemTags, SystemTagsRelation

src/nextcloud/api_wrappers/activity.py

@@ -1,10 +1,15 @@
 # -*- coding: utf-8 -*-
-from nextcloud.base import WithRequester
+"""
+Activity API wrapper
+See https://doc.owncloud.com/server/user_manual/apps/activity.html
+    https://doc.owncloud.com/server/developer_manual/core/apis/
+"""
+from nextcloud import base
 
 
-class Activity(WithRequester):
+class Activity(base.OCSv2ApiWrapper):
+    """ Activity API wrapper """
     API_URL = "/ocs/v2.php/apps/activity/api/v2/activity"
-    SUCCESS_CODE = 200
 
     def get_activities(self, since=None, limit=None, object_type=None, object_id=None, sort=None):
         """
@@ -24,7 +29,7 @@ def get_activities(self, since=None, limit=None, object_type=None, object_id=Non
                 (Default: desc)
 
         Returns:
-
+            requester response
         """
         params = dict(
             since=since,
@@ -34,5 +39,5 @@ def get_activities(self, since=None, limit=None, object_type=None, object_id=Non
             sort=sort
         )
         if params['object_type'] and params['object_id']:
-            return self.requester.get(url="filter", params=params)
+                return self.requester.get(url="filter", params=params)
         return self.requester.get(params=params)

src/nextcloud/api_wrappers/apps.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
-from nextcloud.base import WithRequester
+"""
+Apps API wrapper
+See https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
+"""
+from nextcloud import base
 
 
-class Apps(WithRequester):
+class Apps(base.ProvisioningApiWrapper):
     API_URL = "/ocs/v1.php/cloud/apps"
-    SUCCESS_CODE = 100
 
     def get_apps(self, filter=None):
         """
@@ -13,9 +16,7 @@ def get_apps(self, filter=None):
         :param filter: str, optional "enabled" or "disabled"
         :return:
         """
-        params = {
-            "filter": filter
-        }
+        params = {"filter": filter}
         return self.requester.get(params=params)
 
     def get_app(self, app_id):

src/nextcloud/api_wrappers/capabilities.py

@@ -1,10 +1,14 @@
 # -*- coding: utf-8 -*-
-from nextcloud.base import WithRequester
+"""
+Capabilities API wrapper
+See https://doc.owncloud.com/server/developer_manual/core/apis/ocs-capabilities.html
+"""
+from nextcloud import base
 
 
-class Capabilities(WithRequester):
+class Capabilities(base.OCSv1ApiWrapper):
+    """ Capabilities API wrapper """
     API_URL = "/ocs/v1.php/cloud/capabilities"
-    SUCCESS_CODE = 100
 
     def get_capabilities(self):
         """ Obtain capabilities provided by the Nextcloud server and its apps """

src/nextcloud/api_wrappers/federated_cloudshares.py

@@ -1,11 +1,15 @@
 # -*- coding: utf-8 -*-
-from nextcloud.base import WithRequester
+"""
+Federated Cloud Share wrapper.
+See https://doc.owncloud.com/server/developer_manual/core/apis/ocs-share-api.html#federated-cloud-shares
+"""
+from nextcloud import base
 
 
-class FederatedCloudShare(WithRequester):
+class FederatedCloudShare(base.OCSv2ApiWrapper):
+    """ Federated Cloud Share wrapper """
     API_URL = "/ocs/v2.php/apps/files_sharing/api/v1"
     FEDERATED = "remote_shares"
-    SUCCESS_CODE = 200
 
     def get_federated_url(self, additional_url=""):
         if additional_url:

src/nextcloud/api_wrappers/group.py

@@ -1,10 +1,14 @@
 # -*- coding: utf-8 -*-
-from nextcloud.base import WithRequester
+"""
+Group API wrapper
+See https://doc.owncloud.com/server/developer_manual/core/apis/provisioning-api.html
+"""
+from nextcloud.base import ProvisioningApiWrapper
 
 
-class Group(WithRequester):
+class Group(ProvisioningApiWrapper):
+    """ Group API wrapper """
     API_URL = "/ocs/v1.php/cloud/groups"
-    SUCCESS_CODE = 100
 
     def get_groups(self, search=None, limit=None, offset=None):
         """