From a694362175bbc74a46f9ff26b3e04ec5dede1133 Mon Sep 17 00:00:00 2001 From: Danil Date: Mon, 31 Dec 2018 01:58:43 +0200 Subject: [PATCH 1/3] Set up documentation structure; introduction docs, examples, code references --- docs/source/NextCloud.rst | 7 +++++ docs/source/conf.py | 9 +++---- docs/source/examples.rst | 48 ++++++++++++++++++++++++++++++++++ docs/source/index.rst | 11 +++----- docs/source/introduction.rst | 50 ++++++++++++++++++++++++++++++++++++ docs/source/modules.rst | 8 ++++++ 6 files changed, 120 insertions(+), 13 deletions(-) create mode 100644 docs/source/NextCloud.rst create mode 100644 docs/source/examples.rst create mode 100644 docs/source/introduction.rst create mode 100644 docs/source/modules.rst diff --git a/docs/source/NextCloud.rst b/docs/source/NextCloud.rst new file mode 100644 index 0000000..0c3c883 --- /dev/null +++ b/docs/source/NextCloud.rst @@ -0,0 +1,7 @@ +NextCloud module +================ + +.. automodule:: NextCloud + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py index 6ff36a7..a59d807 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,10 +12,9 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - +import os +import sys +sys.path.insert(0, os.path.abspath('../../')) # -- Project information ----------------------------------------------------- @@ -39,7 +38,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.doctest', + 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..bce122c --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,48 @@ +Examples +======== + +Users API methods +----------------- + +.. code-block:: python + + # get all users + nxc.get_users() + + # add new user + nxc.add_user("user_username", "new_user_password321_123") + + # get user by user id + nxc.get_user("user_username") + + # edit user + nxc.edit_user("user_username", "phone", "123456789") + + # disable user by user id + nxc.disable_user("user_username") + + # enable user by user id + nxc.enable_user("user_username") + + # delete user by user id + nxc.delete_user("user_username") + + # add user to group by user id and group id + nxc.add_to_group("user_username", "group_id") + + # remove user from group id + nxc.remove_from_group("user_username", "group_id") + + # make user subadmin for group + nxc.create_subadmin("user_username", "group_id") + + # remove user from gorup subadmins + nxc.remove_subadmin("user_username", "group_id") + + # get groups in which user is subadmin + nxc.get_subadmin_groups("user_username") + + # trigger welcome email for user again + nxc.resend_welcome_mail("user_username") + + diff --git a/docs/source/index.rst b/docs/source/index.rst index 81079d3..6882c3e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,11 +5,6 @@ Welcome to nextcloud-API's documentation! :maxdepth: 2 :caption: Contents: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + introduction + examples + modules \ No newline at end of file diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 0000000..7c2ffae --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,50 @@ +Introduction +============ + +Nextcloud-API is Python (2 and 3) wrapper for NextCloud's API. With it you can manage your +NextCloud instances from Python scripts. + +If you have any question, remark or if you find a bug, don't hesitate to +`open an issue `_. + + + + +Quick start +----------- + +First, create your NextCloud instance: + +.. code-block:: python + + from NextCloud import NextCloud + + nxc = NextCloud.NextCloud("url", "user id", "password", js=True) + +Then you can work with NextCloud objects: + +.. code-block:: python + + nxc.get_users() + nxc.add_user("new_user_username", "new_user_password321_123") + nxc.add_group("new_group_name") + nxc.add_to_group("new_user_username", "new_group_name") + +Download and install +-------------------- + +TBD + +License +------- + +Nextcloud-API is licensed under the GNU General Public License v3.0. + + +What's next ? +------------- + +Check :doc:`examples` and :doc:`modules`. + + + diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..dc5731f --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,8 @@ +Nextcloud-API +============= + +.. toctree:: + :maxdepth: 4 + + NextCloud + From 256e94a2c41974607728a9721e68c9342d7a8dc7 Mon Sep 17 00:00:00 2001 From: Danil Date: Thu, 3 Jan 2019 00:40:27 +0200 Subject: [PATCH 2/3] nextcloud arguments renamed; examples from example.py; example.py update; --- NextCloud.py | 4 +-- docs/source/examples.rst | 43 ++------------------------------ example.py | 53 ++++++++++++++++++++++++++++++++++------ 3 files changed, 49 insertions(+), 51 deletions(-) diff --git a/NextCloud.py b/NextCloud.py index a455a9a..b263bed 100644 --- a/NextCloud.py +++ b/NextCloud.py @@ -77,10 +77,10 @@ def nextcloud_method(method_to_wrap): class NextCloud(object): - def __init__(self, endpoint, user, passwd, js=False): + def __init__(self, endpoint, user, password, js=False): self.query_components = [] - requester = Requester(endpoint, user, passwd, js) + requester = Requester(endpoint, user, password, js) self.functionality = { "Apps": Apps(requester), diff --git a/docs/source/examples.rst b/docs/source/examples.rst index bce122c..d5b8827 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -4,45 +4,6 @@ Examples Users API methods ----------------- -.. code-block:: python - - # get all users - nxc.get_users() - - # add new user - nxc.add_user("user_username", "new_user_password321_123") - - # get user by user id - nxc.get_user("user_username") - - # edit user - nxc.edit_user("user_username", "phone", "123456789") - - # disable user by user id - nxc.disable_user("user_username") - - # enable user by user id - nxc.enable_user("user_username") - - # delete user by user id - nxc.delete_user("user_username") - - # add user to group by user id and group id - nxc.add_to_group("user_username", "group_id") - - # remove user from group id - nxc.remove_from_group("user_username", "group_id") - - # make user subadmin for group - nxc.create_subadmin("user_username", "group_id") - - # remove user from gorup subadmins - nxc.remove_subadmin("user_username", "group_id") - - # get groups in which user is subadmin - nxc.get_subadmin_groups("user_username") - - # trigger welcome email for user again - nxc.resend_welcome_mail("user_username") - +.. include:: ../../example.py + :literal: diff --git a/example.py b/example.py index 2591939..ece3d81 100644 --- a/example.py +++ b/example.py @@ -1,13 +1,50 @@ import NextCloud -import json url = "INPUT_YOUR_CLOUD" -userid = "INPUT_YOUR_USERNAME" -passwd = "INPUT_YOUR_PASSWORD" +user_id = "INPUT_YOUR_USERNAME" +password = "INPUT_YOUR_PASSWORD" -#True if you want to get response as JSON -#False if you want to get response as XML -tojs = True +# True if you want to get response as JSON +# False if you want to get response as XML +to_js = True -nxc = NextCloud.NextCloud(url, userid, passwd, tojs) -print(nxc.get_users()) +nxc = NextCloud.NextCloud(endpoint=url, user=user_id, password=password, js=to_js) + +# get all users +nxc.get_users() + +# add new user +nxc.add_user("user_username", "new_user_password321_123") + +# get user by user id +nxc.get_user("user_username") + +# edit user +nxc.edit_user("user_username", "phone", "123456789") + +# disable user by user id +nxc.disable_user("user_username") + +# enable user by user id +nxc.enable_user("user_username") + +# add user to group by user id and group id +nxc.add_to_group("user_username", "group_id") + +# remove user from group id +nxc.remove_from_group("user_username", "group_id") + +# make user subadmin for group +nxc.create_subadmin("user_username", "group_id") + +# remove user from gorup subadmins +nxc.remove_subadmin("user_username", "group_id") + +# get groups in which user is subadmin +nxc.get_subadmin_groups("user_username") + +# trigger welcome email for user again +nxc.resend_welcome_mail("user_username") + +# delete user by user id +nxc.delete_user("user_username") From b74b9206f3c0c9572bec40ca60d9af887675678e Mon Sep 17 00:00:00 2001 From: Danil Date: Fri, 4 Jan 2019 01:03:47 +0200 Subject: [PATCH 3/3] documentation: add asserts to example.py; add running example.py as part of tests; introduction quick start from example.py --- docs/source/conf.py | 2 +- docs/source/examples.rst | 1 - docs/source/introduction.rst | 18 ++++------ example.py | 65 +++++++++++++----------------------- tests/README.md | 6 +++- 5 files changed, 37 insertions(+), 55 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a59d807..a137b07 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -74,7 +74,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/source/examples.rst b/docs/source/examples.rst index d5b8827..b759f98 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -6,4 +6,3 @@ Users API methods .. include:: ../../example.py :literal: - diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 7c2ffae..ddf0df8 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -15,20 +15,16 @@ Quick start First, create your NextCloud instance: -.. code-block:: python - - from NextCloud import NextCloud - - nxc = NextCloud.NextCloud("url", "user id", "password", js=True) +.. include:: ../../example.py + :literal: + :end-before: # Quick start Then you can work with NextCloud objects: -.. code-block:: python - - nxc.get_users() - nxc.add_user("new_user_username", "new_user_password321_123") - nxc.add_group("new_group_name") - nxc.add_to_group("new_user_username", "new_group_name") +.. include:: ../../example.py + :literal: + :start-after: # Quick start + :end-before: # End quick start Download and install -------------------- diff --git a/example.py b/example.py index ece3d81..67b3e58 100644 --- a/example.py +++ b/example.py @@ -1,50 +1,33 @@ +import os + import NextCloud -url = "INPUT_YOUR_CLOUD" -user_id = "INPUT_YOUR_USERNAME" -password = "INPUT_YOUR_PASSWORD" +NEXTCLOUD_URL = "http://{}:80".format(os.environ['NEXTCLOUD_HOST']) +NEXTCLOUD_USERNAME = os.environ.get('NEXTCLOUD_USERNAME') +NEXTCLOUD_PASSWORD = os.environ.get('NEXTCLOUD_PASSWORD') # True if you want to get response as JSON # False if you want to get response as XML to_js = True -nxc = NextCloud.NextCloud(endpoint=url, user=user_id, password=password, js=to_js) +nxc = NextCloud.NextCloud(endpoint=NEXTCLOUD_URL, user=NEXTCLOUD_USERNAME, password=NEXTCLOUD_PASSWORD, js=to_js) -# get all users +# Quick start nxc.get_users() - -# add new user -nxc.add_user("user_username", "new_user_password321_123") - -# get user by user id -nxc.get_user("user_username") - -# edit user -nxc.edit_user("user_username", "phone", "123456789") - -# disable user by user id -nxc.disable_user("user_username") - -# enable user by user id -nxc.enable_user("user_username") - -# add user to group by user id and group id -nxc.add_to_group("user_username", "group_id") - -# remove user from group id -nxc.remove_from_group("user_username", "group_id") - -# make user subadmin for group -nxc.create_subadmin("user_username", "group_id") - -# remove user from gorup subadmins -nxc.remove_subadmin("user_username", "group_id") - -# get groups in which user is subadmin -nxc.get_subadmin_groups("user_username") - -# trigger welcome email for user again -nxc.resend_welcome_mail("user_username") - -# delete user by user id -nxc.delete_user("user_username") +new_user_id = "new_user_username" +add_user_res = nxc.add_user(new_user_id, "new_user_password321_123") +group_name = "new_group_name" +add_group_res = nxc.add_group(group_name) +add_to_group_res = nxc.add_to_group(new_user_id, group_name) +# End quick start + +assert add_group_res['ocs']['meta']['statuscode'] == 100 +assert new_user_id in nxc.get_group(group_name)['ocs']['data']['users'] +assert add_user_res['ocs']['meta']['statuscode'] == 100 +assert add_to_group_res['ocs']['meta']['statuscode'] == 100 + +# remove user +remove_user_res = nxc.delete_user(new_user_id) +assert remove_user_res['ocs']['meta']['statuscode'] == 100 +user_res = nxc.get_user(new_user_id) +assert user_res['ocs']['meta']['statuscode'] == 404 diff --git a/tests/README.md b/tests/README.md index 647d430..3173c1a 100644 --- a/tests/README.md +++ b/tests/README.md @@ -15,4 +15,8 @@ Enable NextCloud groupfolders application: Run tests: - docker-compose run --rm python-api pytest \ No newline at end of file + docker-compose run --rm python-api pytest + +Run examples: + + docker-compose run --rm python-api python examples.py