{"id":10162,"library":"python-irodsclient","title":"iRODS Python Client","description":"python-irodsclient is a Python API for interacting with iRODS (integrated Rule-Oriented Data System) servers. It provides programmatic access to iRODS data objects, collections, metadata, and authentication mechanisms. The library is currently at version 3.3.0 and typically releases new versions quarterly, incorporating new iRODS features and Python compatibility updates.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/irods/python-irodsclient","tags":["irods","data management","client","data fabric","scientific data"],"install":[{"cmd":"pip install python-irodsclient","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Build-time and runtime utilities","package":"setuptools","optional":false},{"reason":"JSON parsing utility","package":"json-stream","optional":false},{"reason":"CFFI bindings for core iRODS communication","package":"python-irodsclient-cffi","optional":false}],"imports":[{"note":"The main entry point for interaction is within the 'irods.session' submodule, not directly from 'irodsclient'.","wrong":"from irodsclient import iRODSSession","symbol":"iRODSSession","correct":"from irods.session import iRODSSession"},{"note":"The class name for collections is iRODSCollection.","wrong":"from irods.collection import Collection","symbol":"Collection","correct":"from irods.collection import iRODSCollection"},{"note":"The class name for data objects is iRODSDataObject.","wrong":"from irods.data_object import DataObject","symbol":"DataObject","correct":"from irods.data_object import iRODSDataObject"}],"quickstart":{"code":"import os\nfrom irods.session import iRODSSession\n\n# Configure iRODS connection parameters using environment variables or defaults\nhost = os.environ.get('IRODS_HOST', 'localhost')\nport = int(os.environ.get('IRODS_PORT', '1247'))\nzone = os.environ.get('IRODS_ZONE', 'tempZone')\nuser = os.environ.get('IRODS_USER', 'rods')\npassword = os.environ.get('IRODS_PASSWORD', 'rods')\n\ntry:\n    # Establish a session with iRODS\n    with iRODSSession(host=host, port=port, zone=zone, user=user, password=password) as session:\n        print(f\"Successfully connected to iRODS zone: {session.zone} as user: {session.user}\")\n\n        # Example: List the contents of the user's home collection\n        home_collection_path = f'/{session.zone}/home/{session.user}'\n        print(f\"\\nListing contents of: {home_collection_path}\")\n        \n        try:\n            collection = session.collections.get(home_collection_path)\n            for item in collection.data_objects:\n                print(f\"  Data Object: {item.name} (size: {item.size})\")\n            for sub_collection in collection.subcollections:\n                print(f\"  Sub-Collection: {sub_collection.name}\")\n        except Exception as e:\n            print(f\"  Could not retrieve collection {home_collection_path}: {e}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during iRODS connection or operation: {e}\")\n    print(\"Please ensure your iRODS server is running and credentials are correct.\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project uses Python 3.9 or newer. Upgrade your Python environment if necessary.","message":"Python 2 compatibility was removed in v3.0.0. All subsequent versions require Python 3.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.9 or newer. The library will not function on older Python 3 releases.","message":"Support for Python versions older than 3.9 was removed in v3.1.0.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"Avoid using `IRODS_VERSION`. If you need to check the server version, use `session.server_version` after establishing a connection.","message":"The `IRODS_VERSION` variable has been deprecated. It may be removed in a future release.","severity":"deprecated","affected_versions":">=3.3.0"},{"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.","message":"The iRODS authentication framework was fully ported and updated in v3.1.0. Older authentication configurations or client certificates might require adjustments.","severity":"gotcha","affected_versions":">=3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `python-irodsclient` is installed (`pip install python-irodsclient`). Imports should typically be from submodules like `from irods.session import iRODSSession`.","cause":"Attempting to import from the top-level 'irods' module, or the package was not installed correctly.","error":"ModuleNotFoundError: No module named 'irods'"},{"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.","cause":"Incorrect username, password, zone, or host details provided during session initialization, or issues with `irods_environment.json`.","error":"irods.exception.iRODSAuthError: [CAT_AUTHENTICATION_ERROR] user authentication error"},{"fix":"Update your code to use `session.acls` instead of `session.permissions` when managing access control lists.","cause":"In v2.0.0, the `permissions` attribute was renamed to `acls` for clarity and consistency with iRODS terminology.","error":"AttributeError: 'iRODSSession' object has no attribute 'permissions'"},{"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.","cause":"The installed `python-irodsclient` version requires Python 3.9 or newer, but an older Python version is being used.","error":"RuntimeError: unsupported Python version"}]}