From 8bbf70c33bb68c591fccfe0bee2a94070921dee4 Mon Sep 17 00:00:00 2001 From: d-w-moore Date: Fri, 4 Sep 2026 08:06:06 -0400 Subject: [PATCH 1/2] README section for iRODSSession instance usage --- README.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d136657b..70fc4e39 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,39 @@ Uninstalling Establishing a (secure) connection ---------------------------------- -One way of starting a session is to pass iRODS credentials as keyword +An `iRODSSession` instance is the interface object through which iRODS server +APIs can be invoked. One way to create the session object, assuming one has +already successfully set up an client environment via `iinit`, is by using a +simple `make_session` call: + +```python +from irods.helpers import make_session +sess1 = make_session() + +# Possible patterns include: +# 1. keeping a ready reference to the session. + +sess1.collections.get(f'/tempZone/home/{session.username}') +# (... Further instances of calls to the server through sess1 may follow.) + +# or: +# 2. using the session object with a context manager. + +with make_session() as sess2: + my_user = sess2.users.get(ses.username) + # Here, we can have other statements using sess2, and at end + # of code block, sess2.cleanup() is implicitly called. + +# sess1 retains an idle but reusable connection whereas sess2 does not; i.e. +# sess1.pool.idle has length 1, and sess2.pool.idle is an empty set. +# However, both sessions are equally open for further server interactions. +``` + +Of course, we should be careful how many still-connected `iRODSSession` objects we retain +references to in an application, as having more of them than the system can support +database connections for can result in spurious failure of iRODS client connections. + +Another way of starting a session is to pass iRODS credentials as keyword arguments: ```python From 92f3da2ffad81bed129af56b24a5f5bc2a4e37c5 Mon Sep 17 00:00:00 2001 From: d-w-moore Date: Tue, 8 Sep 2026 08:31:07 -0400 Subject: [PATCH 2/2] beef up explanation, and don't present make_session as the 'main' choice --- README.md | 68 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 70fc4e39..d3d96619 100644 --- a/README.md +++ b/README.md @@ -42,38 +42,60 @@ Establishing a (secure) connection ---------------------------------- An `iRODSSession` instance is the interface object through which iRODS server -APIs can be invoked. One way to create the session object, assuming one has -already successfully set up an client environment via `iinit`, is by using a -simple `make_session` call: +APIs can be invoked. -```python -from irods.helpers import make_session -sess1 = make_session() +One way to create the session object, assuming one has already successfully +set up a client environment via `iinit`, is by using a simple `make_session` +call: -# Possible patterns include: -# 1. keeping a ready reference to the session. +>>> from irods.helpers import make_session +>>> session = make_session() -sess1.collections.get(f'/tempZone/home/{session.username}') -# (... Further instances of calls to the server through sess1 may follow.) +It is also possible to use the constructor form directly, passing +connection and authentication options within the call parameter list: -# or: -# 2. using the session object with a context manager. +>>> from irods.session import iRODSSession +>>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: -with make_session() as sess2: - my_user = sess2.users.get(ses.username) - # Here, we can have other statements using sess2, and at end - # of code block, sess2.cleanup() is implicitly called. +Once created, an instance can be managed with an application-appropriate choice +from a couple of possible patterns. Either the programmer can simply manage +the instance quite naturally, allowing reference counting to +let it pass out-of-scope and destruct its server connection(s) at the +proper time: -# sess1 retains an idle but reusable connection whereas sess2 does not; i.e. -# sess1.pool.idle has length 1, and sess2.pool.idle is an empty set. -# However, both sessions are equally open for further server interactions. +```python +home_coll = session.collections.get(f'/tempZone/home/{session.username}') +# (... Further instances of calls to the server through 'session' may follow.) ``` -Of course, we should be careful how many still-connected `iRODSSession` objects we retain -references to in an application, as having more of them than the system can support -database connections for can result in spurious failure of iRODS client connections. +This casual approach usually ends up being the most efficient, as connection +pooling will allow potentially disparate uses of a server connection to happen +consecutively without harm, and without the need for disposing of or +interrupting the connection. + +Alternatively, a context manager may be employed, forcing connections to be +temporarily cleared from the session object once a given block of code has +executed: + +```python +with make_session() as session: + my_user = session.users.get(session.username) + # Here, we can have further usage of 'session' in this code block, and at + # the end of it, session.cleanup() is implicitly called. +``` + +Either way, the instance remains available for further such use afterward, +until destructed. + +We should, of course, be careful how many still-connected `iRODSSession` +objects we retain references to in an application, as having more of them than +the system can support database connections for can result in spurious failure +of iRODS client connections. + +Finer points in connecting to the iRODS server +---------------------------------------------- -Another way of starting a session is to pass iRODS credentials as keyword +iRODS credentials may also be passed as keyword arguments: ```python