The Session: creating and managing connections

Before performing any operation on an iRODS server, the Python API needs a Session.
A Session represents an authenticated connection and is used by all functions that interact with iRODS.
It reads your irods_environment.json file, just like the GUI and CLI, and establishes a secure connection.

There are two main ways to create a Session:

• interactive authentication
  
• non‑interactive authentication

Both return a connected Session object, but they differ in how they obtain the password and how they integrate with the CLI configuration.

interactive_auth

The function interactive_auth is designed for situations where entering a password is acceptable or preferred.

from ibridges.authenticate import interactive_auth

session = interactive_auth()

This function:

• looks for an irods_environment.json file
• checks whether a cached password exists in ~/.irods/.irodsA
  
• if the cached password is unavailable or outdated, it will ask you to type your password
  
• after successful authentication, it stores an obfuscated password for future use

You can specify a different environment file:

session = interactive_auth(irods_env_path="/path/to/irods_environment.json")

If you want to ignore the cached password and force reauthentication, for example if your cached password is due to expire soon, you can create a session with:

session = interactive_auth(reauthenticate=True)

The interactive authentication is useful when you are working interactively in python, for example in a Jupyter notebook.

non_interactive_auth

The function non_interactive_auth is designed for automated workflows where you do not want to type a password.
It never prompts for a password.
Instead, it relies entirely on the cached password created earlier by:

• the CLI or GUI
  
• interactive_auth
  
• a previous successful authentication attempt

Example:

from ibridges.authenticate import non_interactive_auth

session = non_interactive_auth()

You can also specify an alias or an environment file:

session = non_interactive_auth(ienv_path_or_alias="surf")

or

session = non_interactive_auth(ienv_path_or_alias="/path/to/irods_environment.json")

This method is ideal for scheduled jobs, automated pipelines, and reproducible workflows where no user interaction is possible. To ensure that a cached password is available, you should use the interactive_auth, the CLI or the GUI before starting your job. The workflow will authenticate the session from that password.

If no cached password exists, authentication will fail rather than prompting for a password.

Choosing between interactive and non‑interactive authentication

Use interactive_auth when:

• you are working in a notebook or terminal
• you want to authenticate manually once and reuse the cached password
• you are teaching or demonstrating iBridges

Use non_interactive_auth when:

• you run automated workflows
  
• you schedule jobs on a cluster
  
• you build reproducible pipelines
  
• you want zero user interaction
  
• you rely on CLI aliases to select environments

Using Sessions as context managers

Both authentication functions return a Session object that can be used as a context manager.
This ensures that connections are closed cleanly, even if an error occurs.

from ibridges.authenticate import interactive_auth, non_interactive_auth

with interactive_auth() as session:
    session.home

with non_interactive_auth() as session:
    session.home

If you do not use a with statement, you must close the session manually:

session.close()

Session attributes

A Session contains useful information about your connection and user identity:

print(session.username)
print(session.default_resc)
print(session.zone)
print(session.server_version)
print(session.get_user_info())
print(session.home)
print(session.cwd)

These values correspond to fields in your environment file and information retrieved from the iRODS server.