[#827] Add README text on usage of iRODSSession instances - #832
[#827] Add README text on usage of iRODSSession instances#832d-w-moore wants to merge 5 commits into
Conversation
korydraughn
left a comment
korydraughn
left a comment
There was a problem hiding this comment.
Wording seems good.
Are we encouraging the use of irods.helpers and make_session()?
Are they meant for general usage?
d-w-moore
changed the title
I don't feel we have to encourage it ... if the mention of it as the first option seems like encouraging, perhaps a reorganization is needed. The upshot is: a client environment set up, There is this: |
|
Ok, I think we're now presenting the different instance creation options fairly and on equal ground. |
|
Are new commits on the way? Nothing has changed since I last looked at this PR. |
Yeah, sorry ... concentration lapse. I have just now put in the changes referred to aboe. |
| 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: | ||
|
|
||
| >>> from irods.helpers import make_session | ||
| >>> session = make_session() |
There was a problem hiding this comment.
Cover the constructor form(s) before introducing make_session.
There was a problem hiding this comment.
Would it be preferable to have no mention of make_session at all?
There was a problem hiding this comment.
I think it's fine to mention make_session if it's considered to be a general purpose tool.
That said, make_session is a convenience function, so it should be mentioned after showing the tools which make_session is built on top of.
Thoughts?
There was a problem hiding this comment.
That said,
make_sessionis a convenience function, so it should be mentioned after showing the tools whichmake_sessionis built on top of.
that sounds right.
There was a problem hiding this comment.
Done - and the README can now be reviewed again, since I'm done for now changing things around for the present.
| # (... Further instances of calls to the server through 'session' may follow.) | ||
| ``` | ||
|
|
||
| This casual approach usually ends up being optimal choice in terms efficiency, since |
There was a problem hiding this comment.
| This casual approach usually ends up being optimal choice in terms efficiency, since | |
| This casual approach usually ends up being the optimal choice in terms of efficiency, since |
|
|
||
| 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 can create the object using constructor form directly, |
There was a problem hiding this comment.
| APIs can be invoked. One can create the object using constructor form directly, | |
| APIs can be invoked. One can create the object using the constructor form directly, |
| 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 | ||
| home_coll = session.collections.get(f'/tempZone/home/{session.username}') | ||
| # (... Further instances of calls to the server through 'session' may follow.) | ||
| ``` |
There was a problem hiding this comment.
The code block on line 68 seems out of place in relation to the text on line 62.
Feels like the code block can be removed entirely?
| @@ -41,7 +41,62 @@ Uninstalling | |||
| Establishing a (secure) connection | |||
There was a problem hiding this comment.
This title includes (secure), but SSL/TLS isn't mentioned until the next section.
Consider whether (secure) should be moved or removed?
3 participants
No description provided.