Skip to content

Commit 9846852

Browse files
bigcat88bigcat88
authored
More documentation (#67)
Signed-off-by: Alexander Piskun <bigcat88@icloud.com>
1 parent e8c68dc commit 9846852

33 files changed

+415
-176
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
All notable changes to this project will be documented in this file.
44

5+
## [0.0.28 - 2023-08-11]
6+
7+
### Changed
8+
9+
- Finished documentation.
10+
- Different small adjustments to API, to be it more consistent.
11+
512
## [0.0.27 - 2023-08-05]
613

714
### Added

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ In a very close near future we will publish examples
4444
### More Information
4545

4646
- [Documentation](https://cloud-py-api.github.io/nc_py_api/)
47-
- [Using it as a simple client](to-do)
47+
- [First steps](https://cloud-py-api.github.io/nc_py_api/FirstSteps.html)
4848
- [Writing a simple Nextcloud application](to-do)
4949
- [Writing a Nextcloud System Application](to-do)
5050
- [Examples](https://github.com/cloud-py-api/nc_py_api/tree/main/examples)

‎docs/FirstSteps.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
.. _first-steps:
2+
3+
First steps
4+
===========
5+
6+
For this part, you will need an environment with **nc_py_api** installed and Nextcloud version 26 or higher.
7+
8+
Full support is only available from version ``27.1`` of Nextcloud.
9+
10+
Nextcloud client
11+
^^^^^^^^^^^^^^^^
12+
13+
.. note:: In many cases, even if you want to develop an application,
14+
it's a good idea to first debug and develop part of it as a client.
15+
16+
Creation
17+
""""""""
18+
19+
.. code-block:: python
20+
21+
from nc_py_api import Nextcloud
22+
23+
24+
nc = Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
25+
26+
Where ``nc_auth_pass`` can be usual Nextcloud application password.
27+
28+
To test if this works, let's print the capabilities of the Nextcloud instance:
29+
30+
.. code-block:: python
31+
32+
from json import dumps
33+
34+
from nc_py_api import Nextcloud
35+
36+
37+
nc = Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
38+
pretty_capabilities = dumps(nc.capabilities, indent=4, sort_keys=True)
39+
print(pretty_capabilities)
40+
41+
Getting list of files of User
42+
"""""""""""""""""""""""""""""
43+
44+
This is a hard way to get list of all files recursively:
45+
46+
.. literalinclude:: ../examples/as_client/files_listing.py
47+
48+
This code do the same in one DAV call, but prints **directories** in addition to files:
49+
50+
.. code-block:: python
51+
52+
from nc_py_api import Nextcloud
53+
54+
55+
nc = Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
56+
print("Files & folders on the instance for the selected user:")
57+
all_files_folders = nc.files.listdir(depth=-1)
58+
for obj in all_files_folders:
59+
print(obj.user_path)
60+
61+
To print only files, you can use list comprehension:
62+
63+
.. code-block:: python
64+
65+
print("Files on the instance for the selected user:")
66+
all_files = [i for i in nc.files.listdir(depth=-1) if not i.is_dir]
67+
for obj in all_files:
68+
print(obj.user_path)
69+
70+
Uploading a single file
71+
"""""""""""""""""""""""
72+
73+
It is always better to use ``upload_stream`` instead of ``upload`` as it works
74+
with chunks and ``in future`` will support **multi threaded** upload.
75+
76+
.. literalinclude:: ../examples/as_client/files_upload.py
77+
78+
Downloading a single file
79+
"""""""""""""""""""""""""
80+
81+
A very simple example of downloading an image as one piece of data to memory and displaying it.
82+
83+
.. note:: For big files, it is always better to use ``download2stream`` method, as it uses chunks.
84+
85+
.. literalinclude:: ../examples/as_client/files_download.py

‎docs/Installation.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Installation
2+
============
3+
4+
First it is always a good idea to update ``pip`` to the latest version with :command:`pip`::
5+
6+
python3 -m pip install --upgrade pip
7+
8+
To use it as a simple Nextcloud client install it without any additional dependencies with :command:`pip`::
9+
10+
python3 -m pip install --upgrade nc_py_api
11+
12+
To use in the Nextcloud Application mode install it with additional ``app`` dependencies with :command:`pip`::
13+
14+
python3 -m pip install --upgrade "nc_py_api[app]"
15+
16+
To join the development of **nc_py_api** api install development dependencies with :command:`pip`::
17+
18+
python3 -m pip install --upgrade "nc_py_api[dev]"
19+
20+
Congratulations, the next chapter :ref:`first-steps` awaits.
21+
22+
.. note::
23+
If you have any installation or building questions, you can ask them in the discussions or create a issue
24+
and we will do our best to help you.

‎docs/Options.rst‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,41 @@
11
.. _options:
22

3-
``Currently, this section is `under construction` and will be changed in the near future.``
4-
53
Options
64
-------
75

8-
.. autodata:: nc_py_api.options.XDEBUG_SESSION
9-
.. autodata:: nc_py_api.options.NPA_TIMEOUT
10-
.. autodata:: nc_py_api.options.NPA_TIMEOUT_DAV
11-
.. autodata:: nc_py_api.options.NPA_NC_CERT
6+
.. automodule:: nc_py_api.options
7+
:members:
8+
9+
Usage examples
10+
^^^^^^^^^^^^^^
11+
12+
Using kwargs
13+
""""""""""""
14+
15+
.. note:: The names of the options if you wish to specify it in ``kwargs`` is **lowercase**.
16+
17+
.. code-block:: python
18+
19+
nc_client = Nextcloud(xdebug_session="PHPSTORM", npa_nc_cert=False)
20+
21+
Will set `XDEBUG_SESSION` to ``"PHPSTORM"`` and `NPA_NC_CERT` to ``False``.
22+
23+
With .env
24+
"""""""""
25+
26+
Place **.env** file in your project's directory, and it will be automatically loaded using `dotenv <https://github.com/theskumar/python-dotenv>`_
27+
28+
Modifying at module level
29+
"""""""""""""""""""""""""
30+
31+
Import **nc_py_api** and modify options by setting values you need directly in **nc_py_api.options**,
32+
and all newly created classes will respect that.
33+
34+
.. code-block:: python
35+
36+
import nc_py_api
37+
38+
nc_py_api.options.NPA_TIMEOUT = None
39+
nc_py_api.options.NPA_TIMEOUT_DAV = None
40+
41+
.. note:: In case you debugging PHP code it is always a good idea to set **Timeouts** to ``None``.

‎docs/benchmarks/AppEcosystem.rst‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,51 @@ is a trade-off for the enhanced security provided by the authentication process.
3333

3434
Overall, the AppEcosystem authentication proves to be a reliable and effective method for application authentication.
3535

36-
.. toctree::
37-
:maxdepth: 1
36+
.. _appecosystem-bench-results:
3837

39-
AppEcosystem_results.rst
38+
Detailed Benchmark Results
39+
--------------------------
40+
41+
Tests on MacOS (M2 CPU) are run when NC is in Docker and `nc_py_api` is in the host.
42+
43+
Tests are run with session cache enabled and disabled to see the difference in authentication speed.
44+
45+
| All benchmarks are run one after the other in the single thread.
46+
| Size of chunk for file stream operations = **4MB**
47+
48+
nc-py-api version = **0.0.24**
49+
50+
'ocs/v1.php/cloud/USERID' endpoint
51+
----------------------------------
52+
53+
.. image:: ../../benchmarks/results/ocs_user_get_details__cache0_iters100__shurik.png
54+
55+
.. image:: ../../benchmarks/results/ocs_user_get_details__cache1_iters100__shurik.png
56+
57+
Downloading a 1 MB file
58+
-----------------------
59+
60+
.. image:: ../../benchmarks/results/dav_download_1mb__cache0_iters30__shurik.png
61+
62+
.. image:: ../../benchmarks/results/dav_download_1mb__cache1_iters30__shurik.png
63+
64+
Uploading a 1 Mb file
65+
---------------------
66+
67+
.. image:: ../../benchmarks/results/dav_upload_1mb__cache0_iters30__shurik.png
68+
69+
.. image:: ../../benchmarks/results/dav_upload_1mb__cache1_iters30__shurik.png
70+
71+
Downloading of a 100 Mb file to the memory BytesIO python object
72+
----------------------------------------------------------------
73+
74+
.. image:: ../../benchmarks/results/dav_download_stream_100mb__cache0_iters10__shurik.png
75+
76+
.. image:: ../../benchmarks/results/dav_download_stream_100mb__cache1_iters10__shurik.png
77+
78+
Chunked uploading of a 100 Mb file from the BytesIO python object
79+
-----------------------------------------------------------------
80+
81+
.. image:: ../../benchmarks/results/dav_upload_stream_100mb__cache0_iters10__shurik.png
82+
83+
.. image:: ../../benchmarks/results/dav_upload_stream_100mb__cache1_iters10__shurik.png

‎docs/benchmarks/AppEcosystem_results.rst‎

Lines changed: 0 additions & 59 deletions
This file was deleted.

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ Have a great time with Python and Nextcloud!
2727
.. toctree::
2828
:maxdepth: 1
2929

30-
Nextcloud
30+
Installation
31+
FirstSteps
3132
Options
3233
reference/index.rst
3334
benchmarks/AppEcosystem.rst

‎docs/reference/Apps.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,27 @@ Applications Management
88

99
.. autoclass:: ExAppInfo
1010
:members:
11+
12+
Preferences
13+
^^^^^^^^^^^
14+
15+
.. autoclass:: nc_py_api.appcfg_prefs_ex.CfgRecord
16+
:members:
17+
:undoc-members:
18+
19+
User specific
20+
"""""""""""""
21+
22+
.. autoclass:: nc_py_api.preferences.PreferencesAPI
23+
:members:
24+
25+
.. autoclass:: nc_py_api.appcfg_prefs_ex.PreferencesExAPI
26+
:members:
27+
:inherited-members:
28+
29+
Non-user specific
30+
"""""""""""""""""
31+
32+
.. autoclass:: nc_py_api.appcfg_prefs_ex.AppConfigExAPI
33+
:members:
34+
:inherited-members:

‎docs/reference/Exceptions.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,9 @@ Exceptions
88

99
.. autoclass:: NextcloudExceptionNotFound
1010
:members:
11+
12+
13+
Functions
14+
---------
15+
16+
.. autofunction:: check_error

0 commit comments

Comments
 (0)