A python API for iRODS
Project description
iRODS is an open source distributed data management system. This is a client API implemented in python.
Currently supported:
Establish a connection to iRODS, authenticate
Implement basic Gen Queries (select columns and filtering)
Support more advanced Gen Queries with limits, offsets, and aggregations
Query the collections and data objects within a collection
Execute direct SQL queries
Execute iRODS rules
Support read, write, and seek operations for files
PUT/GET data objects
Create data objects
Delete data objects
Create collections
Delete collections
Rename data objects
Rename collections
Register files and directories
Query metadata for collections and data objects
Add, edit, remove metadata
Replicate data objects to different resource servers
Connection pool management
Implement gen query result sets as lazy queries
Return empty result sets when CAT_NO_ROWS_FOUND is raised
Manage permissions
Manage users and groups
Manage resources
GSI authentication
Unicode strings
Ticket based access
iRODS connection over SSL
Python 2.7, 3.4 or newer
Installing
PRC requires Python 2.7 or 3.4+. To install with pip:
pip install python-irodsclient
or:
pip install git+https://github.com/irods/python-irodsclient.git[@branch|@commit|@tag]
Uninstalling
pip uninstall python-irodsclient
Establishing a connection
Using environment files in ~/.irods/:
>>> import os >>> from irods.session import iRODSSession >>> try: ... env_file = os.environ['IRODS_ENVIRONMENT_FILE'] ... except KeyError: ... env_file = os.path.expanduser('~/.irods/irods_environment.json') ... >>> with iRODSSession(irods_env_file=env_file) as session: ... pass ... >>>
Passing iRODS credentials as keyword arguments:
>>> from irods.session import iRODSSession >>> with iRODSSession(host='localhost', port=1247, user='bob', password='1234', zone='tempZone') as session: ... pass ... >>>
If you’re an administrator acting on behalf of another user:
>>> from irods.session import iRODSSession >>> with iRODSSession(host='localhost', port=1247, user='rods', password='1234', zone='tempZone', client_user='bob', client_zone='possibly_another_zone') as session: ... pass ... >>>
If no client_zone is provided, the zone parameter is used in its place.
Working with collections
>>> coll = session.collections.get("/tempZone/home/rods")
>>> coll.id 45798
>>> coll.path /tempZone/home/rods
>>> for col in coll.subcollections: >>> print col <iRODSCollection /tempZone/home/rods/subcol1> <iRODSCollection /tempZone/home/rods/subcol2>
>>> for obj in coll.data_objects: >>> print obj <iRODSDataObject /tempZone/home/rods/file.txt> <iRODSDataObject /tempZone/home/rods/file2.txt>
Create a new collection:
>>> coll = session.collections.create("/tempZone/home/rods/testdir") >>> coll.id 45799
Working with data objects (files)
Create a new data object:
>>> obj = session.data_objects.create("/tempZone/home/rods/test1") <iRODSDataObject /tempZone/home/rods/test1>
Get an existing data object:
>>> obj = session.data_objects.get("/tempZone/home/rods/test1") >>> obj.id 12345
>>> obj.name test1 >>> obj.collection <iRODSCollection /tempZone/home/rods>
>>> for replica in obj.replicas: ... print replica.resource_name ... print replica.number ... print replica.path ... print replica.status ... demoResc 0 /var/lib/irods/Vault/home/rods/test1 1
Reading and writing files
PRC provides file-like objects
>>> obj = session.data_objects.get("/tempZone/home/rods/test1") >>> with obj.open('r+') as f: ... f.write('foo\nbar\n') ... f.seek(0,0) ... for line in f: ... print line ... foo bar
Working with metadata
>>> obj = session.data_objects.get("/tempZone/home/rods/test1") >>> print obj.metadata.items() []
>>> obj.metadata.add('key1', 'value1', 'units1') >>> obj.metadata.add('key1', 'value2') >>> obj.metadata.add('key2', 'value3') >>> print obj.metadata.items() [<iRODSMeta (key1, value1, units1, 10014)>, <iRODSMeta (key2, value3, None, 10017)>, <iRODSMeta (key1, value2, None, 10020)>]
>>> print obj.metadata.get_all('key1') [<iRODSMeta (key1, value1, units1, 10014)>, <iRODSMeta (key1, value2, None, 10020)>]
>>> print obj.metadata.get_one('key2') <iRODSMeta (key2, value3, None, 10017)>
>>> obj.metadata.remove('key1', 'value1', 'units1') >>> print obj.metadata.items() [<iRODSMeta (key2, value3, None, 10017)>, <iRODSMeta (key1, value2, None, 10020)>]
General queries
>>> import os >>> from irods.session import iRODSSession >>> from irods.models import Collection, DataObject >>> >>> env_file = os.path.expanduser('~/.irods/irods_environment.json') >>> with iRODSSession(irods_env_file=env_file) as session: ... query = session.query(Collection.name, DataObject.id, DataObject.name, DataObject.size) ... ... for result in query.get_results(): ... print '{}/{} id={} size={}'.format(result[Collection.name], result[DataObject.name], result[DataObject.id], result[DataObject.size]) ... /tempZone/home/rods/manager/access_manager.py id=212665 size=2164 /tempZone/home/rods/manager/access_manager.pyc id=212668 size=2554 /tempZone/home/rods/manager/collection_manager.py id=212663 size=4472 /tempZone/home/rods/manager/collection_manager.pyc id=212664 size=4464 /tempZone/home/rods/manager/data_object_manager.py id=212662 size=10291 /tempZone/home/rods/manager/data_object_manager.pyc id=212667 size=8772 /tempZone/home/rods/manager/__init__.py id=212670 size=79 /tempZone/home/rods/manager/__init__.pyc id=212671 size=443 /tempZone/home/rods/manager/metadata_manager.py id=212660 size=4263 /tempZone/home/rods/manager/metadata_manager.pyc id=212659 size=4119 /tempZone/home/rods/manager/resource_manager.py id=212666 size=5329 /tempZone/home/rods/manager/resource_manager.pyc id=212661 size=4570 /tempZone/home/rods/manager/user_manager.py id=212669 size=5509 /tempZone/home/rods/manager/user_manager.pyc id=212658 size=5233
Query with aggregation(min, max, sum, avg, count):
>>> with iRODSSession(irods_env_file=env_file) as session: ... query = session.query(DataObject.owner_name).count(DataObject.id).sum(DataObject.size) ... print next(query.get_results()) {<irods.column.Column 411 D_OWNER_NAME>: 'rods', <irods.column.Column 407 DATA_SIZE>: 62262, <irods.column.Column 401 D_DATA_ID>: 14}
In this case since we are expecting only one row we can directly call query.execute():
>>> with iRODSSession(irods_env_file=env_file) as session: ... query = session.query(DataObject.owner_name).count(DataObject.id).sum(DataObject.size) ... print query.execute() +--------------+-----------+-----------+ | D_OWNER_NAME | D_DATA_ID | DATA_SIZE | +--------------+-----------+-----------+ | rods | 14 | 62262 | +--------------+-----------+-----------+
Specific Queries
>>> import os >>> from irods.session import iRODSSession >>> from irods.models import Collection, DataObject >>> from irods.query import SpecificQuery >>> >>> env_file = os.path.expanduser('~/.irods/irods_environment.json') >>> with iRODSSession(irods_env_file=env_file) as session: ... # define our query ... sql = "select data_name, data_id from r_data_main join r_coll_main using (coll_id) where coll_name = '/tempZone/home/rods/manager'" ... alias = 'list_data_name_id' ... columns = [DataObject.name, DataObject.id] # optional, if we want to get results by key ... query = SpecificQuery(session, sql, alias, columns) ... ... # register specific query in iCAT ... _ = query.register() ... ... for result in query.get_results(): ... print '{} {}'.format(result[DataObject.name], result[DataObject.id]) ... ... # delete specific query ... _ = query.remove() ... user_manager.pyc 212658 metadata_manager.pyc 212659 metadata_manager.py 212660 resource_manager.pyc 212661 data_object_manager.py 212662 collection_manager.py 212663 collection_manager.pyc 212664 access_manager.py 212665 resource_manager.py 212666 data_object_manager.pyc 212667 access_manager.pyc 212668 user_manager.py 212669 __init__.py 212670 __init__.pyc 212671
And more…
Additional code samples are available in the test directory
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python_irodsclient-0.7.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5e43a28c23223f5c37669f24dfb042adf7a078d0f92b48d2d04f13325d5f311b |
|
MD5 | ad8ff4a2e1004e9856114b17dead2ad7 |
|
BLAKE2b-256 | ccb39c6e9a66aba187699246f143880f8be35f5e9368d44a022a0cb88c54919b |