iRODS Python Client

Common errors

• ModuleNotFoundError: No module named 'irods'

  cause Attempting to import from the top-level 'irods' module, or the package was not installed correctly.
  fix Ensure `python-irodsclient` is installed (`pip install python-irodsclient`). Imports should typically be from submodules like `from irods.session import iRODSSession`.

• irods.exception.iRODSAuthError: [CAT_AUTHENTICATION_ERROR] user authentication error

  cause Incorrect username, password, zone, or host details provided during session initialization, or issues with `irods_environment.json`.
  fix Verify all connection parameters (host, port, zone, user, password) are correct. Check `~/.irods/irods_environment.json` if used, or ensure environment variables are set correctly.

• AttributeError: 'iRODSSession' object has no attribute 'permissions'

  cause In v2.0.0, the `permissions` attribute was renamed to `acls` for clarity and consistency with iRODS terminology.
  fix Update your code to use `session.acls` instead of `session.permissions` when managing access control lists.

• RuntimeError: unsupported Python version

  cause The installed `python-irodsclient` version requires Python 3.9 or newer, but an older Python version is being used.
  fix Upgrade your Python environment to version 3.9 or later. You might need to create a new virtual environment with a compatible Python version.

Warnings

• breaking Python 2 compatibility was removed in v3.0.0. All subsequent versions require Python 3.
  Fix: Ensure your project uses Python 3.9 or newer. Upgrade your Python environment if necessary.
• breaking Support for Python versions older than 3.9 was removed in v3.1.0.
  Fix: Upgrade your Python environment to 3.9 or newer. The library will not function on older Python 3 releases.
• deprecated The `IRODS_VERSION` variable has been deprecated. It may be removed in a future release.
  Fix: Avoid using `IRODS_VERSION`. If you need to check the server version, use `session.server_version` after establishing a connection.
• gotcha The iRODS authentication framework was fully ported and updated in v3.1.0. Older authentication configurations or client certificates might require adjustments.
  Fix: Review your `irods_environment.json` and client authentication methods to ensure compatibility with iRODS 4.3+ authentication flows. Consult iRODS documentation for authentication specifics.
• gotcha Client redirection to resource servers is disabled by default starting v2.2.0. This might affect performance or behavior for operations that previously leveraged client redirection.
  Fix: If client redirection is desired, it must be explicitly re-enabled in your code or iRODS environment configuration. Refer to the official documentation on client redirection settings.

Install

• pip install python-irodsclient Install stable version

Imports

• iRODSSession
  wrong:

  from irodsclient import iRODSSession

  correct:

  from irods.session import iRODSSession

  The main entry point for interaction is within the 'irods.session' submodule, not directly from 'irodsclient'.
• Collection
  wrong:

  from irods.collection import Collection

  correct:

  from irods.collection import iRODSCollection

  The class name for collections is iRODSCollection.
• DataObject
  wrong:

  from irods.data_object import DataObject

  correct:

  from irods.data_object import iRODSDataObject

  The class name for data objects is iRODSDataObject.

Quickstart

This quickstart demonstrates how to establish a session with an iRODS server using environment variables for credentials and then list the contents of the user's home collection. It uses `iRODSSession` as the main entry point for all interactions and showcases basic collection traversal.

import os
from irods.session import iRODSSession

# Configure iRODS connection parameters using environment variables or defaults
host = os.environ.get('IRODS_HOST', 'localhost')
port = int(os.environ.get('IRODS_PORT', '1247'))
zone = os.environ.get('IRODS_ZONE', 'tempZone')
user = os.environ.get('IRODS_USER', 'rods')
password = os.environ.get('IRODS_PASSWORD', 'rods')

try:
    # Establish a session with iRODS
    with iRODSSession(host=host, port=port, zone=zone, user=user, password=password) as session:
        print(f"Successfully connected to iRODS zone: {session.zone} as user: {session.user}")

        # Example: List the contents of the user's home collection
        home_collection_path = f'/{session.zone}/home/{session.user}'
        print(f"\nListing contents of: {home_collection_path}")
        
        try:
            collection = session.collections.get(home_collection_path)
            for item in collection.data_objects:
                print(f"  Data Object: {item.name} (size: {item.size})")
            for sub_collection in collection.subcollections:
                print(f"  Sub-Collection: {sub_collection.name}")
        except Exception as e:
            print(f"  Could not retrieve collection {home_collection_path}: {e}")

except Exception as e:
    print(f"An error occurred during iRODS connection or operation: {e}")
    print("Please ensure your iRODS server is running and credentials are correct.")