Merge pull request #7 from cs3org/dev

Adapted tokens to be external, CI now builds and installs the package, and unit tests are now using the installed package.

Author: diocas

.github/workflows/ci-tests.yml

@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a single version of Python
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
-name: Linting and unit tests
+name: Lint, Build and Test
 on:
   push:
     branches: [ "main" ]
@@ -15,10 +15,10 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v4
 
-    - name: Set up Python 3.12
+    - name: Set up Python 3.9
       uses: actions/setup-python@v3
       with:
-        python-version: "3.12"
+        python-version: "3.9"
 
     - name: Install dependencies
       run: |
@@ -32,8 +32,11 @@ jobs:
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide, we further relax this
         flake8 . --count --exit-zero --max-complexity=30 --max-line-length=130 --statistics
-
+    - name: Build
+      run: |
+        pip install build
+        python -m build
     - name: Test with pytest
       run: |
         if [ -f tests/requirements.txt ]; then pip install -r tests/requirements.txt; fi
-        pytest --cov-report term --cov=src tests/
+        pytest --cov-report term --cov=cs3client tests/

.gitignore

@@ -157,6 +157,9 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 
+# MacOS
+.DS_Store
+
 # PyCharm
 #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore

README.md

@@ -37,8 +37,7 @@ Alternatively, you can clone this repository and install manually:
 ```bash
 git clone [email protected]:cs3org/cs3-python-client.git
 cd cs3-python-client
-pip install -e . 
-export PYTHONPATH="path/to/cs3-python-client/:$PYTHONPATH"
+pip install . 
 ```
 
 
@@ -89,12 +88,14 @@ ssl_verify = False
 # Optional, defaults to an empty string
 ssl_client_cert = test_client_cert
 # Optional, defaults to an empty string
-ssl_client_key  = test_client_key
+ssl_client_key = test_client_key
 # Optional, defaults to an empty string
-ssl_ca_cert =  test_ca_cert
+ssl_ca_cert = test_ca_cert
 
 # Optinal, defaults to an empty string
 auth_client_id = einstein
+# Optional (can also be set when instansiating the class)
+auth_client_secret = relativity
 # Optional, defaults to basic
 auth_login_type = basic
 
@@ -112,129 +113,180 @@ lock_expiration = 1800
 
 To use `cs3client`, you first need to import and configure it. Here's a simple example of how to set up and start using the client. For configuration see [Configuration](#configuration). For more in depth examples see `cs3-python-client/examples/`. 
 
-### Initilization
+### Initilization and Authentication
 ```python
 import logging
 import configparser
-from cs3client import CS3Client
-from cs3resource import Resource
+from cs3client.cs3client import CS3Client
+from cs3client.auth import Auth
 
 config = configparser.ConfigParser()
 with open("default.conf") as fdef:
     config.read_file(fdef)
-
 log = logging.getLogger(__name__)
 
 client = CS3Client(config, "cs3client", log)
-# client.auth.set_token("<your_token_here>")
-# OR
-client.auth.set_client_secret("<your_client_secret_here>")
+auth = Auth(client)
+# Set the client id (can also be set in the config)
+auth.set_client_id("<your_client_id_here>")
+# Set client secret (can also be set in config)
+auth.set_client_secret("<your_client_secret_here>")
+# Checks if token is expired if not return ('x-access-token', <token>)
+# if expired, request a new token from reva
+auth_token = auth.get_token()
+
+# OR if you already have a reva token
+# Checks if token is expired if not return (x-access-token', <token>)
+# if expired, throws an AuthenticationException (so you can refresh your reva token)
+token = "<your_reva_token>"
+auth_token = Auth.check_token(token)
+
 ```
 
 ### File Example
 ```python
 # mkdir
-directory_resource = Resource.from_file_ref_and_endpoint(f"/eos/user/r/rwelande/test_directory")
-res = client.file.make_dir(directory_resource)
+directory_resource = Resource(abs_path=f"/eos/user/r/rwelande/test_directory")
+res = client.file.make_dir(auth.get_token(), directory_resource)
 
 # touchfile
-touch_resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/touch_file.txt")
-res = client.file.touch_file(touch_resource)
+touch_resource = Resource(abs_path="/eos/user/r/rwelande/touch_file.txt")
+res = client.file.touch_file(auth.get_token(), touch_resource)
 
 # setxattr
-resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/text_file.txt")
-res = client.file.set_xattr(resource, "iop.wopi.lastwritetime", str(1720696124))
+resource = Resource(abs_path="/eos/user/r/rwelande/text_file.txt")
+res = client.file.set_xattr(auth.get_token(), resource, "iop.wopi.lastwritetime", str(1720696124))
 
 # rmxattr
-res = client.file.remove_xattr(resource, "iop.wopi.lastwritetime")
+res = client.file.remove_xattr(auth.get_token(), resource, "iop.wopi.lastwritetime")
 
 # stat
-res = client.file.stat(resource)
+res = client.file.stat(auth.get_token(), resource)
 
 # removefile
-res = client.file.remove_file(touch_resource)
+res = client.file.remove_file(auth.get_token(), touch_resource)
 
 # rename
-rename_resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/rename_file.txt")
-res = client.file.rename_file(resource, rename_resource)
+rename_resource = Resource(abs_path="/eos/user/r/rwelande/rename_file.txt")
+res = client.file.rename_file(auth.get_token(), resource, rename_resource)
 
 # writefile
 content = b"Hello World"
 size = len(content)
-res = client.file.write_file(rename_resource, content, size)
+res = client.file.write_file(auth.get_token(), rename_resource, content, size)
 
 # listdir
-list_directory_resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande")
-res = client.file.list_dir(list_directory_resource)
+list_directory_resource = Resource(abs_path="/eos/user/r/rwelande")
+res = client.file.list_dir(auth.get_token(), list_directory_resource)
 
 
 # readfile
-file_res = client.file.read_file(rename_resource)
+file_res = client.file.read_file(auth.get_token(), rename_resource)
+```
+### Lock Example
+```python
+
+WEBDAV_LOCK_PREFIX = 'opaquelocktoken:797356a8-0500-4ceb-a8a0-c94c8cde7eba'
+
+
+def encode_lock(lock):
+    '''Generates the lock payload for the storage given the raw metadata'''
+    if lock:
+        return WEBDAV_LOCK_PREFIX + ' ' + b64encode(lock.encode()).decode()
+    return None
+
+resource = Resource(abs_path="/eos/user/r/rwelande/lock_test.txt")
+
+# Set lock
+client.file.set_lock(auth_token, resource, app_name="a", lock_id=encode_lock("some_lock"))
+
+# Get lock
+res = client.file.get_lock(auth_token, resource)
+if res is not None:
+    lock_id = res["lock_id"]
+    print(res)
+
+# Unlock
+res = client.file.unlock(auth_token, resource, app_name="a", lock_id=lock_id)
+
+# Refresh lock
+client.file.set_lock(auth_token, resource, app_name="a", lock_id=encode_lock("some_lock"))
+res = client.file.refresh_lock(
+    auth_token, resource, app_name="a", lock_id=encode_lock("new_lock"), existing_lock_id=lock_id
+)
+
+if res is not None:
+    print(res)
+
+res = client.file.get_lock(auth_token, resource)
+if res is not None:
+    print(res)
+
 ```
 
 ### Share Example
 ```python
 # Create share #
-resource = Resource.from_file_ref_and_endpoint("/eos/user/r/<some_username>/text.txt")
-resource_info = client.file.stat(resource)
+resource = Resource(abs_path="/eos/user/r/<some_username>/text.txt")
+resource_info = client.file.stat(auth.get_token(), resource)
 user = client.user.get_user_by_claim("username", "<some_username>")
-res = client.share.create_share(resource_info, user.id.opaque_id, user.id.idp, "EDITOR", "USER")
+res = client.share.create_share(auth.get_token(), resource_info, user.id.opaque_id, user.id.idp, "EDITOR", "USER")
 
 # List existing shares #
 filter_list = []
 filter = client.share.create_share_filter(resource_id=resource_info.id, filter_type="TYPE_RESOURCE_ID")
 filter_list.append(filter)
 filter = client.share.create_share_filter(share_state="SHARE_STATE_PENDING", filter_type="TYPE_STATE")
 filter_list.append(filter)
-res, _ = client.share.list_existing_shares()
+res, _ = client.share.list_existing_shares(auth.get_token(), )
 
 # Get share #
 share_id = "58"
-res = client.share.get_share(opaque_id=share_id)
+res = client.share.get_share(auth.get_token(), opaque_id=share_id)
 
 # update share #
-res = client.share.update_share(opaque_id=share_id, role="VIEWER")
+res = client.share.update_share(auth.get_token(), opaque_id=share_id, role="VIEWER")
 
 # remove share #
-res = client.share.remove_share(opaque_id=share_id)
+res = client.share.remove_share(auth.get_token(), opaque_id=share_id)
 
 # List existing received shares #
 filter_list = []
 filter = client.share.create_share_filter(share_state="SHARE_STATE_ACCEPTED", filter_type="TYPE_STATE")
 filter_list.append(filter)
-res, _ = client.share.list_received_existing_shares()
+res, _ = client.share.list_received_existing_shares(auth.get_token())
 
 # get received share #
-received_share = client.share.get_received_share(opaque_id=share_id)
+received_share = client.share.get_received_share(auth.get_token(), opaque_id=share_id)
 
 # update recieved share #
-res = client.share.update_received_share(received_share=received_share, state="SHARE_STATE_ACCEPTED")
+res = client.share.update_received_share(auth.get_token(), received_share=received_share, state="SHARE_STATE_ACCEPTED")
 
 # create public share #
-res = client.share.create_public_share(resource_info, role="VIEWER")
+res = client.share.create_public_share(auth.get_token(), resource_info, role="VIEWER")
 
 # list existing public shares #
 filter_list = []
 filter = client.share.create_public_share_filter(resource_id=resource_info.id, filter_type="TYPE_RESOURCE_ID")
 filter_list.append(filter)
 res, _ = client.share.list_existing_public_shares(filter_list=filter_list)
 
-res = client.share.get_public_share(opaque_id=share_id, sign=True)
+res = client.share.get_public_share(auth.get_token(), opaque_id=share_id, sign=True)
 # OR token = "<token>"
 # res = client.share.get_public_share(token=token, sign=True)
 
 # update public share #
-res = client.share.update_public_share(type="TYPE_PASSWORD", token=token, role="VIEWER", password="hello")
+res = client.share.update_public_share(auth.get_token(), type="TYPE_PASSWORD", token=token, role="VIEWER", password="hello")
 
 # remove public share #
-res = client.share.remove_public_share(token=token)
+res = client.share.remove_public_share(auth.get_token(), token=token)
 
 ```
 
 ### User Example
 ```python
 # find_user
-res = client.user.find_users("rwel")
+res = client.user.find_users(auth.get_token(), "rwel")
 
 # get_user
 res = client.user.get_user("https://auth.cern.ch/auth/realms/cern", "asdoiqwe")
@@ -253,21 +305,21 @@ res = client.user.get_user_by_claim("username", "rwelande")
 ### App Example
 ```python
 # list_app_providers
-res = client.app.list_app_providers()
+res = client.app.list_app_providers(auth.get_token())
 
 # open_in_app
-resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/collabora.odt")
-res = client.app.open_in_app(resource)
+resource = Resource(abs_path="/eos/user/r/rwelande/collabora.odt")
+res = client.app.open_in_app(auth.get_token(), resource)
 ```
 
 ### Checkpoint Example
 ```python
 # list file versions
-resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/test.md")
-res = client.checkpoint.list_file_versions(resource)
+resource = Resource(abs_path="/eos/user/r/rwelande/test.md")
+res = client.checkpoint.list_file_versions(auth.get_token(), resource)
 
 # restore file version
-res = client.checkpoint.restore_file_version(resource, "1722936250.0569fa2f")
+res = client.checkpoint.restore_file_version(auth.get_token(), resource, "1722936250.0569fa2f")
 ```
 
 ## Documentation