irods-http 0.1.0__tar.gz

irods_http-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, The University of North Carolina at Chapel Hill
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

irods_http-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: irods-http
+Version: 0.1.0
+Summary: A Python wrapper for the iRODS HTTP API
+Author-email: iRODS Consortium <info@irods.org>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/irods/irods_client_http_python
+Project-URL: Issues, https://github.com/irods/irods_client_http_python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# iRODS HTTP API Python Wrapper
+
+This is a Python wrapper for the [iRODS HTTP API](https://github.com/irods/irods_client_http_api). 
+
+Documentation for the endpoint operations can be found [here](https://github.com/irods/irods_client_http_api/blob/main/API.md).
+
+## Install
+
+This wrapper is available via pip:
+
+```
+pip install irods-http
+```
+
+## Usage
+To use the wrapper, follow the steps listed below.
+
+```py
+import irods_http
+
+# Placeholder values needed for irods_http.authenticate()
+url_base = "http://<host>:<port>/irods-http-api/<version>"
+username = "<username>"
+password = "<password>"
+
+# Create an IRODSHTTPSession to an iRODS HTTP API server
+session = irods_http.authenticate(url_base, username, password)
+
+# Use the session for all other operations
+response = irods_http.collections.create(session, '/<zone_name>/home/<username>/new_collection')
+
+# Check the resopnse for errors
+if response['status_code'] != 200:
+    # Handle HTTP error.
+
+if response['data']['irods_response']['status_code'] < 0:
+    # Handle iRODS error.
+```
+
+The response dict will have this format:
+```py
+{
+    'status_code': <integer>,
+    'data': <dict>
+}
+```
+where `status_code` is the HTTP status code from the response, and `data` is the result of the iRODS operation.
+
+`response['data']` will contain a dict named `irods_response`, which will contain the `status_code` returned by the iRODS Server as well as any other expected properties.
+
+```py
+{
+    'irods_response': {
+        'status_code': <integer>
+        # Other properties vary between endpoints
+    }
+}
+```
+
+When calling `data_objects.read()`, the `response['data']` will contain the raw bytes instead of a dict.
+
+More information regarding iRODS HTTP API response data is available [here](https://github.com/irods/irods_client_http_api/blob/main/API.md).

irods_http-0.1.0/README.md

@@ -0,0 +1,62 @@
+# iRODS HTTP API Python Wrapper
+
+This is a Python wrapper for the [iRODS HTTP API](https://github.com/irods/irods_client_http_api). 
+
+Documentation for the endpoint operations can be found [here](https://github.com/irods/irods_client_http_api/blob/main/API.md).
+
+## Install
+
+This wrapper is available via pip:
+
+```
+pip install irods-http
+```
+
+## Usage
+To use the wrapper, follow the steps listed below.
+
+```py
+import irods_http
+
+# Placeholder values needed for irods_http.authenticate()
+url_base = "http://<host>:<port>/irods-http-api/<version>"
+username = "<username>"
+password = "<password>"
+
+# Create an IRODSHTTPSession to an iRODS HTTP API server
+session = irods_http.authenticate(url_base, username, password)
+
+# Use the session for all other operations
+response = irods_http.collections.create(session, '/<zone_name>/home/<username>/new_collection')
+
+# Check the resopnse for errors
+if response['status_code'] != 200:
+    # Handle HTTP error.
+
+if response['data']['irods_response']['status_code'] < 0:
+    # Handle iRODS error.
+```
+
+The response dict will have this format:
+```py
+{
+    'status_code': <integer>,
+    'data': <dict>
+}
+```
+where `status_code` is the HTTP status code from the response, and `data` is the result of the iRODS operation.
+
+`response['data']` will contain a dict named `irods_response`, which will contain the `status_code` returned by the iRODS Server as well as any other expected properties.
+
+```py
+{
+    'irods_response': {
+        'status_code': <integer>
+        # Other properties vary between endpoints
+    }
+}
+```
+
+When calling `data_objects.read()`, the `response['data']` will contain the raw bytes instead of a dict.
+
+More information regarding iRODS HTTP API response data is available [here](https://github.com/irods/irods_client_http_api/blob/main/API.md).

irods_http-0.1.0/irods_http/__init__.py

@@ -0,0 +1,31 @@
+"""iRODS HTTP client library for Python."""
+
+from . import (
+	collections,
+	data_objects,
+	queries,
+	resources,
+	rules,
+	tickets,
+	users_groups,
+	zones,
+)
+from .irods_http import (
+	IRODSHTTPSession,
+	authenticate,
+	get_server_info,
+)
+
+__all__ = [
+	"IRODSHTTPSession",
+	"authenticate",
+	"collections",
+	"data_objects",
+	"get_server_info",
+	"queries",
+	"resources",
+	"rules",
+	"tickets",
+	"users_groups",
+	"zones",
+]

irods_http-0.1.0/irods_http/collections.py

@@ -0,0 +1,307 @@
+"""Collection operations for iRODS HTTP API."""
+
+import builtins
+import json
+
+import requests
+
+from . import common
+from .irods_http import IRODSHTTPSession  # noqa: TC001
+
+
+def create(session: IRODSHTTPSession, lpath: str, create_intermediates: int = 0) -> dict:
+	"""
+	Create a new collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to be created.
+	    create_intermediates: Set to 1 to create intermediates, otherwise set to 0. Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_0_or_1(create_intermediates)
+
+	data = {
+		"op": "create",
+		"lpath": lpath,
+		"create-intermediates": create_intermediates,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def remove(session: IRODSHTTPSession, lpath: str, recurse: int = 0, no_trash: int = 0) -> dict:
+	"""
+	Remove an existing collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to be removed.
+	    recurse: Set to 1 to remove contents of the collection, otherwise set to 0. Defaults to 0.
+	    no_trash: Set to 1 to permanently remove, 0 to move to trash.  Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_0_or_1(recurse)
+	common.validate_0_or_1(no_trash)
+
+	data = {
+		"op": "remove",
+		"lpath": lpath,
+		"recurse": recurse,
+		"no-trash": no_trash,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def stat(session: IRODSHTTPSession, lpath: str, ticket: str = "") -> dict:
+	"""
+	Give information about a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection being accessed.
+	    ticket: Ticket to be enabled before the operation. Defaults to an empty string.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_instance(ticket, str)
+
+	params = {"op": "stat", "lpath": lpath, "ticket": ticket}
+
+	r = requests.get(session.url_base + "/collections", params=params, headers=session.get_headers)  # noqa: S113
+	return common.process_response(r)
+
+
+def list(session: IRODSHTTPSession, lpath: str, recurse: int = 0, ticket: str = "") -> dict:  # noqa: A001
+	"""
+	Show the contents of a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to have its contents listed.
+	    recurse: Set to 1 to list the contents of objects in the collection,
+	      otherwise set to 0. Defaults to 0.
+	    ticket: Ticket to be enabled before the operation. Defaults to an empty string.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_0_or_1(recurse)
+	common.validate_instance(ticket, str)
+
+	params = {"op": "list", "lpath": lpath, "recurse": recurse, "ticket": ticket}
+
+	r = requests.get(session.url_base + "/collections", params=params, headers=session.get_headers)  # noqa: S113
+	return common.process_response(r)
+
+
+def set_permission(
+	session: IRODSHTTPSession,
+	lpath: str,
+	entity_name: str,
+	permission: str,
+	admin: int = 0,
+) -> dict:
+	"""
+	Set the permission of a user for a given collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to have a permission set.
+	    entity_name: The name of the user or group having its permission set.
+	    permission: The permission level being set. Either 'null', 'read', 'write', or 'own'.
+	    admin: Set to 1 to run this operation as an admin, otherwise set to 0. Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+
+	Raises:
+	    ValueError: If permission is not 'null', 'read', 'write', or 'own'.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_instance(entity_name, str)
+	common.validate_instance(permission, str)
+	if permission not in ["null", "read", "write", "own"]:
+		raise ValueError("permission must be either 'null', 'read', 'write', or 'own'")
+	common.validate_0_or_1(admin)
+
+	data = {
+		"op": "set_permission",
+		"lpath": lpath,
+		"entity-name": entity_name,
+		"permission": permission,
+		"admin": admin,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def set_inheritance(session: IRODSHTTPSession, lpath: str, enable: int, admin: int = 0) -> dict:
+	"""
+	Set the inheritance for a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to have its inheritance set.
+	    enable: Set to 1 to enable inheritance, or 0 to disable.
+	    admin: Set to 1 to run this operation as an admin, otherwise set to 0. Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_0_or_1(enable)
+	common.validate_0_or_1(admin)
+
+	data = {
+		"op": "set_inheritance",
+		"lpath": lpath,
+		"enable": enable,
+		"admin": admin,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def modify_permissions(session: IRODSHTTPSession, lpath: str, operations: dict, admin: int = 0) -> dict:
+	"""
+	Modify permissions for multiple users or groups for a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to have its permissions modified.
+	    operations: Dictionary containing the operations to carry out. Should contain names
+	      and permissions for all operations.
+	    admin: Set to 1 to run this operation as an admin, otherwise set to 0. Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_instance(operations, builtins.list)
+	common.validate_instance(operations[0], dict)
+	common.validate_0_or_1(admin)
+
+	data = {
+		"op": "modify_permissions",
+		"lpath": lpath,
+		"operations": json.dumps(operations),
+		"admin": admin,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def modify_metadata(session: IRODSHTTPSession, lpath: str, operations: dict, admin: int = 0) -> dict:
+	"""
+	Modify the metadata for a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection to have its metadata modified.
+	    operations: Dictionary containing the operations to carry out. Should contain the
+	      operation, attribute, value, and optionally units.
+	    admin: Set to 1 to run this operation as an admin, otherwise set to 0. Defaults to 0.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_instance(operations, builtins.list)
+	common.validate_instance(operations[0], dict)
+	common.validate_0_or_1(admin)
+
+	data = {
+		"op": "modify_metadata",
+		"lpath": lpath,
+		"operations": json.dumps(operations),
+		"admin": admin,
+	}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def rename(session: IRODSHTTPSession, old_lpath: str, new_lpath: str) -> dict:
+	"""
+	Rename or move a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    old_lpath: The current absolute logical path of the collection.
+	    new_lpath: The absolute logical path of the destination for the collection.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(old_lpath, str)
+	common.validate_instance(new_lpath, str)
+
+	data = {"op": "rename", "old-lpath": old_lpath, "new-lpath": new_lpath}
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)
+
+
+def touch(session: IRODSHTTPSession, lpath: str, seconds_since_epoch: int = -1, reference: str = "") -> dict:
+	"""
+	Update mtime for a collection.
+
+	Args:
+	    session: IRODSHTTPSession object containing the base URL and authentication token.
+	    lpath: The absolute logical path of the collection being touched.
+	    seconds_since_epoch: The value to set mtime to, defaults to -1 as a flag.
+	    reference: The absolute logical path of the collection to use as a reference for mtime.
+
+	Returns:
+	    A dict containing the HTTP status code and iRODS response.
+	    The iRODS response is only valid if no error occurred during HTTP communication.
+	"""
+	common.validate_not_none(session.token)
+	common.validate_instance(lpath, str)
+	common.validate_gte_minus1(seconds_since_epoch)
+	common.validate_instance(reference, str)
+
+	data = {"op": "touch", "lpath": lpath}
+
+	if seconds_since_epoch != -1:
+		data["seconds-since-epoch"] = seconds_since_epoch
+
+	if reference != "":
+		data["reference"] = reference
+
+	r = requests.post(session.url_base + "/collections", headers=session.post_headers, data=data)  # noqa: S113
+	return common.process_response(r)

irods_http-0.1.0/irods_http/common.py

@@ -0,0 +1,107 @@
+"""Common utility functions for iRODS HTTP client operations."""
+
+
+def process_response(r):
+	"""
+	Process an HTTP response and return standardized response dict.
+
+	Args:
+	    r: The HTTP response object.
+
+	Returns:
+	    A dict with 'status_code' and 'data' keys containing the HTTP status code
+	    and parsed JSON response body (or None if response is empty).
+	"""
+	rdict = r.json() if r.text != "" else None
+	return {"status_code": r.status_code, "data": rdict}
+
+
+def validate_not_none(x):
+	"""
+	Validate that a value is not None.
+
+	Args:
+	    x: The value to validate.
+
+	Raises:
+	    ValueError: If x is None
+	"""
+	if x is None:
+		raise ValueError
+
+
+def validate_instance(x, expected_type):
+	"""
+	Validate that a value is an instance of the expected type.
+
+	Args:
+	    x: The value to validate.
+	    expected_type: The expected type.
+
+	Raises:
+	    TypeError: If x is not an instance of expected_type.
+	"""
+	if not isinstance(x, expected_type):
+		raise TypeError
+
+
+def validate_0_or_1(x):
+	"""
+	Validate that a value is either 0 or 1.
+
+	Args:
+	    x: The value to validate (must be an int).
+
+	Raises:
+	    TypeError: If x is not an integer.
+	    ValueError: If x is not 0 or 1.
+	"""
+	validate_instance(x, int)
+	if x not in [0, 1]:
+		raise ValueError(f"{x} must be 0 or 1")
+
+
+def validate_gte_zero(x):
+	"""
+	Validate that a value is greater than or equal to zero.
+
+	Args:
+	    x: The value to validate (must be an int).
+
+	Raises:
+	    TypeError: If x is not an integer.
+	    ValueError: If x is less than 0.
+	"""
+	validate_instance(x, int)
+	if not x >= 0:
+		raise ValueError(f"{x} must be >= 0")
+
+
+def validate_gte_minus1(x):
+	"""
+	Validate that a value is greater than or equal to -1.
+
+	Args:
+	    x: The value to validate (must be an int).
+
+	Raises:
+	    TypeError: If x is not an integer.
+	    ValueError: If x is less than -1.
+	"""
+	validate_instance(x, int)
+	if not x >= -1:
+		raise ValueError(f"{x} must be >= 0, or flag value of -1")
+
+
+def assert_success(cls, response):
+	"""
+	Validate HTTP and iRODS status codes are successes.
+
+	Args:
+	    cls: The unittest.TestCase class
+	    response: The response from the iRODS HTTP API request
+	"""
+	# HTTP status code
+	cls.assertEqual(response["status_code"], 200)
+	# iRODS status code
+	cls.assertEqual(response["data"]["irods_response"]["status_code"], 0)