Metadata-Version: 2.0
Name: python-irodsclient
Version: 0.6.0
Summary: A python API for iRODS
Home-page: https://github.com/irods/python-irodsclient
Author: iRODS Consortium
Author-email: support@irods.org
License: BSD
Keywords: irods
Platform: UNKNOWN
Classifier: License :: OSI Approved :: BSD License
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: PrettyTable (>=0.7.2)

Python iRODS Client (PRC)
=========================

`iRODS <https://www.irods.org>`__ 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
-  Delete data objects
-  Create collections
-  Delete collections
-  Rename data objects
-  Rename collections
-  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
-  Python 2.7, 3.4 or newer

Installing
----------

PRC requires Python 2.7 or 3.4+. To install with pip:

``pip install git+git://github.com/irods/python-irodsclient.git``

Uninstalling
------------

``pip uninstall python-irodsclient``

Establishing a connection
-------------------------

.. code:: python

    >>> from irods.session import iRODSSession
    >>> sess = iRODSSession(host='localhost', port=1247, user='rods', password='rods', zone='tempZone')

If you're an administrator acting on behalf of another user:

.. code:: python

    >>> from irods.session import iRODSSession
    >>> sess = iRODSSession(host='localhost', port=1247, user='rods', password='rods', zone='tempZone', 
               client_user='another_user', client_zone='another_zone')

If no ``client_zone`` is provided, the ``zone`` parameter is used in its
place.

Working with collections
------------------------

.. code:: python

    >>> coll = sess.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:

.. code:: python

    >>> coll = sess.collections.create("/tempZone/home/rods/testdir")
    >>> coll.id
    45799

Working with data objects (files)
---------------------------------

Create a new data object:

.. code:: python

    >>> obj = sess.data_objects.create("/tempZone/home/rods/test1")
    <iRODSDataObject /tempZone/home/rods/test1>

Get an existing data object:

.. code:: python

    >>> obj = sess.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 <http://docs.python.org/2/library/stdtypes.html#file-objects>`__
for reading and writing files

.. code:: python

    >>> obj = sess.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
---------------------

.. code:: python

    >>> obj = sess.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)>]

Performing general queries
--------------------------

.. code:: python

    >>> from irods.session import iRODSSession
    >>> from irods.models import Collection, User, DataObject
    >>> sess = iRODSSession(host='localhost', port=1247, user='rods', password='rods', zone='tempZone')
    >>> results = sess.query(DataObject.id, DataObject.name, DataObject.size, \
    User.id, User.name, Collection.name).all()
    >>> print results
    +---------+-----------+-----------+---------------+--------------------------------+-----------+
    | USER_ID | USER_NAME | D_DATA_ID | DATA_NAME     | COLL_NAME                      | DATA_SIZE |
    +---------+-----------+-----------+---------------+--------------------------------+-----------+
    | 10007   | rods      | 10012     | runDoxygen.rb | /tempZone/home/rods            | 5890      |
    | 10007   | rods      | 10146     | test1         | /tempZone/home/rods            | 0         |
    | 10007   | rods      | 10147     | test2         | /tempZone/home/rods            | 0         |
    | 10007   | rods      | 10148     | test3         | /tempZone/home/rods            | 8         |
    | 10007   | rods      | 10153     | test5         | /tempZone/home/rods            | 0         |
    | 10007   | rods      | 10154     | test6         | /tempZone/home/rods            | 8         |
    | 10007   | rods      | 10049     | .gitignore    | /tempZone/home/rods/pycommands | 12        |
    | 10007   | rods      | 10054     | README.md     | /tempZone/home/rods/pycommands | 3795      |
    | 10007   | rods      | 10052     | coll_test.py  | /tempZone/home/rods/pycommands | 658       |
    | 10007   | rods      | 10014     | file_test.py  | /tempZone/home/rods/pycommands | 465       |
    +---------+-----------+-----------+---------------+--------------------------------+-----------+

Query with aggregation(min, max, sum, avg, count):

.. code:: python

    >>> results = sess.query(DataObject.owner_name).count(DataObject.id).sum(DataObject.size).all()
    >>> print results
    +--------------+-----------+-----------+
    | D_OWNER_NAME | D_DATA_ID | DATA_SIZE |
    +--------------+-----------+-----------+
    | rods         | 10        | 10836     |
    +--------------+-----------+-----------+


