iRODS Client API Reference¶
This page contains the API reference for the iRODS client module.
iRODSClient¶
class iRODSClient:
"""
Client for interacting with iRODS.
This class provides a simplified interface for common iRODS operations,
including collection and data object management, metadata operations, and more.
"""
def __init__(self, config: iRODSConfig):
"""
Initialize the iRODS client.
Args:
config: iRODS configuration
"""
The iRODSClient class provides a simplified interface for common iRODS operations.
Methods¶
session¶
def session(self, retries: int = 0, retry_delay: float = 1.0) -> ContextManager[iRODSSession]:
"""
Get an iRODS session as a context manager.
Args:
retries: Number of retries if connection fails
retry_delay: Delay between retries in seconds
Returns:
Context manager for an iRODS session
"""
This method returns an iRODS session as a context manager.
Parameters¶
retries: Number of retries if connection failsretry_delay: Delay between retries in seconds
Returns¶
Context manager for an iRODS session.
Example¶
with irods_client.session() as session:
# Use the session
coll = session.collections.get("/tempZone/home/rods")
print(f"Collection: {coll.path}")
collection_exists¶
def collection_exists(self, path: str) -> bool:
"""
Check if a collection exists.
Args:
path: Path to the collection
Returns:
True if the collection exists, False otherwise
"""
This method checks if a collection exists.
Parameters¶
path: Path to the collection
Returns¶
True if the collection exists, False otherwise.
Example¶
if irods_client.collection_exists("/tempZone/home/rods/test"):
print("Collection exists")
create_collection¶
def create_collection(self, path: str, create_parents: bool = True) -> iRODSCollection:
"""
Create a collection.
Args:
path: Path to the collection
create_parents: Whether to create parent collections if they don't exist
Returns:
The created collection
"""
This method creates a collection.
Parameters¶
path: Path to the collectioncreate_parents: Whether to create parent collections if they don't exist
Returns¶
The created collection.
Example¶
coll = irods_client.create_collection("/tempZone/home/rods/test")
get_collection¶
def get_collection(self, path: str) -> iRODSCollection:
"""
Get a collection.
Args:
path: Path to the collection
Returns:
The collection
"""
This method gets a collection.
Parameters¶
path: Path to the collection
Returns¶
The collection.
Example¶
coll = irods_client.get_collection("/tempZone/home/rods/test")
remove_collection¶
def remove_collection(self, path: str, recursive: bool = False, force: bool = False) -> None:
"""
Remove a collection.
Args:
path: Path to the collection
recursive: Whether to remove the collection recursively
force: Whether to force removal
"""
This method removes a collection.
Parameters¶
path: Path to the collectionrecursive: Whether to remove the collection recursivelyforce: Whether to force removal
Example¶
irods_client.remove_collection("/tempZone/home/rods/test", recursive=True)
data_object_exists¶
def data_object_exists(self, path: str) -> bool:
"""
Check if a data object exists.
Args:
path: Path to the data object
Returns:
True if the data object exists, False otherwise
"""
This method checks if a data object exists.
Parameters¶
path: Path to the data object
Returns¶
True if the data object exists, False otherwise.
Example¶
if irods_client.data_object_exists("/tempZone/home/rods/test.txt"):
print("Data object exists")
upload_file¶
def upload_file(
self,
local_path: str,
irods_path: str,
metadata: Dict[str, str] = None,
force: bool = False,
resource: str = None
) -> iRODSDataObject:
"""
Upload a file to iRODS.
Args:
local_path: Path to the local file
irods_path: Path to the iRODS data object
metadata: Metadata to add to the data object
force: Whether to overwrite existing data object
resource: Resource to use for upload
Returns:
The uploaded data object
"""
This method uploads a file to iRODS.
Parameters¶
local_path: Path to the local fileirods_path: Path to the iRODS data objectmetadata: Metadata to add to the data objectforce: Whether to overwrite existing data objectresource: Resource to use for upload
Returns¶
The uploaded data object.
Example¶
obj = irods_client.upload_file(
"/path/to/local/file.txt",
"/tempZone/home/rods/file.txt",
metadata={"key1": "value1", "key2": "value2"}
)
get_data_object¶
def get_data_object(self, path: str) -> iRODSDataObject:
"""
Get a data object.
Args:
path: Path to the data object
Returns:
The data object
"""
This method gets a data object.
Parameters¶
path: Path to the data object
Returns¶
The data object.
Example¶
obj = irods_client.get_data_object("/tempZone/home/rods/file.txt")
download_file¶
def download_file(
self,
irods_path: str,
local_path: str,
force: bool = False
) -> str:
"""
Download a file from iRODS.
Args:
irods_path: Path to the iRODS data object
local_path: Path to the local file
force: Whether to overwrite existing local file
Returns:
Path to the downloaded file
"""
This method downloads a file from iRODS.
Parameters¶
irods_path: Path to the iRODS data objectlocal_path: Path to the local fileforce: Whether to overwrite existing local file
Returns¶
Path to the downloaded file.
Example¶
local_path = irods_client.download_file(
"/tempZone/home/rods/file.txt",
"/path/to/local/download.txt"
)
remove_data_object¶
def remove_data_object(self, path: str, force: bool = False) -> None:
"""
Remove a data object.
Args:
path: Path to the data object
force: Whether to force removal
"""
This method removes a data object.
Parameters¶
path: Path to the data objectforce: Whether to force removal
Example¶
irods_client.remove_data_object("/tempZone/home/rods/file.txt")
upload_directory¶
def upload_directory(
self,
local_dir: str,
irods_path: str,
metadata: Dict[str, str] = None,
file_metadata: Dict[str, str] = None,
force: bool = False,
resource: str = None
) -> iRODSCollection:
"""
Upload a directory to iRODS.
Args:
local_dir: Path to the local directory
irods_path: Path to the iRODS collection
metadata: Metadata to add to the collection
file_metadata: Metadata to add to each file
force: Whether to overwrite existing data objects
resource: Resource to use for upload
Returns:
The uploaded collection
"""
This method uploads a directory to iRODS.
Parameters¶
local_dir: Path to the local directoryirods_path: Path to the iRODS collectionmetadata: Metadata to add to the collectionfile_metadata: Metadata to add to each fileforce: Whether to overwrite existing data objectsresource: Resource to use for upload
Returns¶
The uploaded collection.
Example¶
coll = irods_client.upload_directory(
"/path/to/local/dir",
"/tempZone/home/rods/dir",
metadata={"collection_key": "collection_value"},
file_metadata={"file_key": "file_value"}
)
Notes¶
- The
iRODSClientclass provides a simplified interface for common iRODS operations. - The
sessionmethod returns an iRODS session as a context manager, which automatically closes the session when the context is exited. - The
upload_fileandupload_directorymethods can add metadata to the uploaded data objects and collections. - The
download_filemethod returns the path to the downloaded file, which can be used to access the file locally.