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/5] 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/5] 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 From 60166e3fefb2f809b311e6756ab8a7c896ea1245 Mon Sep 17 00:00:00 2001 From: d-w-moore Date: Wed, 9 Sep 2026 12:04:01 -0400 Subject: [PATCH 3/5] fixes to README --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d3d96619..b15c06d3 100644 --- a/README.md +++ b/README.md @@ -48,17 +48,21 @@ 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: +```python >>> from irods.helpers import make_session >>> session = make_session() +``` It is also possible to use the constructor form directly, passing connection and authentication options within the call parameter list: +```python >>> from irods.session import iRODSSession >>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: +``` Once created, an instance can be managed with an application-appropriate choice -from a couple of possible patterns. Either the programmer can simply manage +from a couple of possible patterns. Firstly, the instance can be managed the instance quite naturally, allowing reference counting to let it pass out-of-scope and destruct its server connection(s) at the proper time: @@ -84,10 +88,10 @@ with make_session() as session: # the end of it, session.cleanup() is implicitly called. ``` -Either way, the instance remains available for further such use afterward, +Either way, the instance remains available for further use afterward, until destructed. -We should, of course, be careful how many still-connected `iRODSSession` +We should, of course, be mindful of 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. From 39d592f78f063243b33c57cfc279bd7c35dfcecd Mon Sep 17 00:00:00 2001 From: d-w-moore Date: Thu, 10 Sep 2026 08:36:47 -0400 Subject: [PATCH 4/5] fix order of mention for methods of iRODSSession construction --- README.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index b15c06d3..e10b8c8a 100644 --- a/README.md +++ b/README.md @@ -42,23 +42,20 @@ 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 a client environment via `iinit`, is by using a simple `make_session` -call: +APIs can be invoked. One can create the object using constructor form directly, +passing connection and authentication options within the call parameter list: ```python ->>> from irods.helpers import make_session ->>> session = make_session() +>>> from irods.session import iRODSSession +>>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: ``` -It is also possible to use the constructor form directly, passing -connection and authentication options within the call parameter list: +Another way to create the session object, assuming one has already successfully +set up a client environment via `iinit`, is by using the convenience function `make_session`: ```python ->>> from irods.session import iRODSSession ->>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: +>>> from irods.helpers import make_session +>>> session = make_session() ``` Once created, an instance can be managed with an application-appropriate choice From 210502ff7e04212e1051cc36c265817de5fc6b5d Mon Sep 17 00:00:00 2001 From: d-w-moore Date: Thu, 10 Sep 2026 08:52:47 -0400 Subject: [PATCH 5/5] rewording, hopefully for the better --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index e10b8c8a..b35cd242 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ passing connection and authentication options within the call parameter list: ```python >>> from irods.session import iRODSSession >>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: +... # Any number of operations using the 'session' variable can go here. ``` Another way to create the session object, assuming one has already successfully @@ -58,10 +59,10 @@ set up a client environment via `iinit`, is by using the convenience function `m >>> session = make_session() ``` -Once created, an instance can be managed with an application-appropriate choice -from a couple of possible patterns. Firstly, the instance can be managed -the instance quite naturally, allowing reference counting to -let it pass out-of-scope and destruct its server connection(s) at the +Once created, the `iRODSSession` instance can be managed from a choice between two +possible patterns. Firstly, one can allow references to the instance to persist as +is natural for the application. This allows Python interpreter's reference counting to +let the object pass out of scope and destroy the underlying server connection(s) at the proper time: ```python @@ -69,29 +70,28 @@ home_coll = session.collections.get(f'/tempZone/home/{session.username}') # (... Further instances of calls to the server through 'session' may follow.) ``` -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. +This casual approach usually ends up being optimal choice in terms efficiency, since +connections are expensive to create and destroy, and any given connection to the iRODS +server can be employed consecutively and for disparate purposes without incident. -Alternatively, a context manager may be employed, forcing connections to be -temporarily cleared from the session object once a given block of code has +Alternatively a context manager may be used, thus forcing connections to be +provisionally 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. + # We can have further usage of 'session' in this code block. At the end + # of it, session.cleanup() is implicitly called to remove any idle connections. ``` -Either way, the instance remains available for further use afterward, -until destructed. +Either way, the instance remains available for further use afterward, until +destructed. We should, of course, be mindful of 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. +the system can support database connections for can result in the spurious failure +of new connections. Finer points in connecting to the iRODS server ----------------------------------------------