Python-icat

~~~~~~~~~~~~~~~~~~

+ Add a module :mod:`icat.eval` that is intended to be run using the
``-m`` command line switch to Python. It allows to evaluate Python
expressions within an ICAT session as one liners directly from the
command line, as for example::

get all Dataset ids
$ python -m icat.eval -e 'client.search("Dataset.id")' -s root
[102284L, 102288L, 102289L, 102293L]

+ Fix an issue in the error handling in the IDS client that caused an
:exc:`urllib2.HTTPError` to be raised instead of an
:exc:`icat.exception.IDSServerError` in the case of an error from
the IDS server and thus the loss of all details about the error
reported in the reply from the server.

+ Add specific exception classes for the different error codes raised
by the IDS server.

+ Fix compatibility issue with Python 3.3 that caused the HTTP method
to be set to :const:`None` in some IDS methods, which in turn caused
an internal server error to be raised in the IDS server.

+ Fix compatibility issues with Python 3.4: some methods have been
removed from class :class:`urllib.request.Request` which caused an
:exc:`AttributeError` in the :class:`icat.ids.IDSClient`.

+ Fix: failed to connect to an ICAT server if it advertises a version
number having a trailing "-SNAPSHOT" in
:meth:`icat.client.Client.getApiVersion`. For compatibility, a
trailing "-SNAPSHOT" will be replaced by "a1" in the
client.apiversion attribute.

+ Suppress misleading context information introduced with Python 3
(PEP 3134) from the traceback in some error messages.
Unfortunately, the fix only works for Python 3.3 and newer.

+ Make example files compatible across Python versions without
modifications, such as running 2to3 on them.


.. _changes-0_5_0:

~~~~~~~~~~~~~~~~~~

+ Integrate an IDS client in the ICAT client.

+ Improved :ref:`icatdump` and :ref:`icatrestore <icatingest>`:

- Changed the logical structure of the dump file format which
significantly simplified the scripts. Note that old dump files
are not compatible with the new versions.

- Add support for XML dump files. A XML Schema Definition for the
dump file format is provided in the doc directory.

The scripts are now considered to be legitimate tools (though still
alpha) rather then mere examples. Consequently, they will be
installed into the bin directory.

+ Implicitly set a one to many relation to an empty list if it is
accessed but not present in an :class:`icat.entity.Entity` object
rather then raising an :exc:`AttributeError`. See `ICAT Issue
112`__.

+ Allow setting one to many relationship attributes and deletion of
attributes in :class:`icat.entity.Entity`. Add method
:meth:`icat.entity.Entity.truncateRelations`. Truncate dummy
relations set by the factory in newly created entity objects.

+ Cache the result from :meth:`icat.client.Client.getEntityInfo` in
the client.

+ Add a method :meth:`icat.entity.Entity.__sortkey__` that return a
key that when used as a sorting key in :meth:`list.sort` allows any
list of entity objects to have a well defined order. Sorting is
based on the Constraint attributes. Add a class variable
:attr:`icat.entity.Entity.SortAttrs` that overrides this and will be
set as a fall back for those entity classes that do not have a
suitable Constraint.

.. __: https://github.com/icatproject/icat.server/issues/112


.. _changes-0_4_0:

~~~~~~~~~~~~~~~~~~

+ Add support for the jurko fork of Suds and for Python 3.

+ Add a new method :meth:`icat.client.Client.searchUniqueKey`.

+ Add an optional argument `keyindex` to method
:meth:`icat.entity.Entity.getUniqueKey` that is used as a cache of
previously generated keys. Remove the argument `addbean`. It had
been documented as for internal use only, so this is not considered
an incompatible change.

+ Add a new exception :exc:`icat.exception.DataConsistencyError`.
Raise this in :meth:`icat.entity.Entity.getUniqueKey` if a relation
that is required in a constraint is not set.

+ Rename :exc:`icat.exception.SearchResultError` to
:exc:`icat.exception.SearchAssertionError`. SearchResultError was a
misnomer here, as this exception class is very specific to
:meth:`icat.client.Client.assertedSearch`. Add a new generic
exception class :exc:`icat.exception.SearchResultError` and derive
:exc:`icat.exception.SearchAssertionError` from it. This way, the
change should not create any compatibility problems in client
programs.

+ Add a check in :mod:`icat.icatcheck` that the
:exc:`icat.exception.ICATError` subclasses are in sync with
`icatExceptionType` as defined in the schema.

+ Bugfix: The code dealing with exceptions raised by the ICAT server
did require all attributes in IcatException sent by the server to be
set, although some of these attributes are marked as optional in the
schema.

+ Do not delete the Suds cache directory in
:meth:`icat.client.Client.cleanup`.

+ Installation: python-icat requires Python 2.6 or newer. Raise an
error if `setup.py` is run by a too old Python version.

+ Move some internal routines in a separate module :mod:`icat.helper`.

+ Greatly improved example scripts :ref:`icatdump` and
:ref:`icatrestore <icatingest>`.


.. _changes-0_3_0:

~~~~~~~~~~~~~~~~~~

+ Add support for ICAT 4.3.1. (Compatibility with ICAT 4.3.2 has also
been tested but did not require any changes.)

+ Implement alias names for entity attributes. This facilitates
compatibility of client programs to different ICAT versions. E.g. a
client program may use `rule.grouping` regardless of the ICAT
version, for ICAT 4.2.* this is aliased to `rule.group`.

+ Add a method :meth:`icat.client.Client.assertedSearch`.

+ Add a method :meth:`icat.entity.Entity.getUniqueKey`.

+ Add entity methods :meth:`Group.getUsers` and
:meth:`Instrument.getInstrumentScientists`.

+ WARNING, incompatible change!

Changed entity methods :meth:`Instrument.addInstrumentScientist` and
:meth:`Investigation.addInvestigationUser` to not to create the
respective user any more, but rather expect a list of existing users
as argument. Renamed :meth:`Group.addUser`,
:meth:`Instrument.addInstrumentScientist`, and
:meth:`Investigation.addInvestigationUser` to :meth:`addUsers`,
:meth:`addInstrumentScientists`, and :meth:`addInvestigationUsers`
(note the plural "s") respectively.

In the client code, replace::

pi = investigation.addInvestigationUser(uid, fullName=userName,
search=True,
role="Principal Investigator")

by ::

pi = client.createUser(uid, fullName=userName, search=True)
investigation.addInvestigationUsers([pi], role="Principal Investigator")

+ Work around a bug in the way SUDS deals with datetime values: set
the local time zone to ``UTC``.

+ Add example scripts :ref:`icatdump` and :ref:`icatrestore <icatingest>`.


.. _changes-0_2_0:

~~~~~~~~~~~~~~~~~~

+ Rework internals of :mod:`icat.config`.

+ Bugfix: :class:`icat.config.Config` required a password to be set
even if prompt for password was requested.

+ Add support for configuration via environment variables.

+ Add support of HTTP proxy settings. [Suggested by Alistair Mills]

+ WARNING, incompatible change!
The configuration read by :mod:`icat.config` is not stored as
attributes on the :class:`icat.config.Config` object itself, but
rather :meth:`icat.config.Config.getconfig` returns an object with
these attributes set. This keeps the configuration values cleanly
separated from the attributes of the :class:`icat.config.Config`
object.

In the client code, replace::

conf = icat.config.Config()
conf.getconfig()

by ::

config = icat.config.Config()
conf = config.getconfig()

+ Move :exc:`ConfigError` from :mod:`icat.config` to
:mod:`icat.exception`.

+ Move :exc:`GenealogyError` from :mod:`icat.icatcheck` to
:mod:`icat.exception`.

+ Review export of symbols. Most client programs should only need to
import :mod:`icat` and :mod:`icat.config`.


.. _changes-0_1_0:

~~~~~~~~~~~~~~~~~~

+ Initial version