Python-icat

:meth:`icat.client.Client.getEntityInfo` also lists `createId`,
`createTime`, `modId`, and `modTime` as attributes. This need to be
taken into account in :mod:`icat.icatcheck`.

+ The last fix in 0.8.0 on the string representation operator
:meth:`icat.query.Query.__str__` was not complete, the operator
still had unwanted side effects.

+ Fix a bug in the handling of errors raised from the ICAT or the IDS
server. This bug affected only Python 3.

+ Add proper type checking and conversion for setting an attribute
that corresponds to a one to many relationship in class
:class:`icat.entity.Entity`. Accept any iterable of entities as
value.

+ `9`_: :ref:`icatingest` with `duplicate=CHECK` may fail when
attributes are not strings. Note that this bug was only present in
an alpha version, but not in any earlier release version.

+ Source repository moved to Git. This gives rise to a few tiny
changes. To name the most visible ones: python2_6.patch is now auto
generated by comparing two source branches and must be applied with
`-p1` instead of `-p0`, the format of the icat module variable
:attr:`icat.__revision__` has changed.

+ Review default exports of modules. Mark some helper functions as
internal.

.. _1: https://github.com/icatproject/python-icat/issues/1
.. _3: https://github.com/icatproject/python-icat/issues/3
.. _4: https://github.com/icatproject/python-icat/issues/4
.. _5: https://github.com/icatproject/python-icat/issues/5
.. _6: https://github.com/icatproject/python-icat/issues/6
.. _9: https://github.com/icatproject/python-icat/issues/9
.. _10: https://github.com/icatproject/python-icat/issues/10


.. _changes-0_8_0:

- Add :meth:`icat.ids.IDSClient.getDatafileIds` and
:meth:`icat.ids.IDSClient.getPreparedDatafileIds` calls.

- :meth:`icat.ids.IDSClient.getStatus` allows `sessionId` to be
None.

+ Add new exception class
:exc:`icat.exception.ICATNotImplementedError` that is supposed to be
raised by the upcoming version 4.6.0 of icat.server.

Bug fixes and minor changes
---------------------------

+ `13`_: :meth:`icat.client.Client.searchChunked` raises exception if
the query contains a percent character.

+ `15`_: :ref:`icatdump` raises
:exc:`icat.exception.DataConsistencyError` for
`DataCollectionParameter`.

+ `14`_: :meth:`icat.entity.Entity.__sortkey__` may raise
:exc:`RuntimeError` "maximum recursion depth exceeded".

+ Allow a :class:`icat.ids.DataSelection` to be created from (almost)
any Iterator, not just a :class:`Sequence`. Store the object ids in
:class:`icat.ids.DataSelection` internally in a :class:`set` rather
then a :class:`list`.

+ Add optional arguments `objindex` to
:meth:`icat.dumpfile.DumpFileReader.getobjs` and `keyindex` to
:meth:`icat.dumpfile.DumpFileWriter.writedata` to allow the caller
to control these internal indices.

+ Add optional argument `chunksize` to
:meth:`icat.dumpfile.DumpFileWriter.writedata`.

+ The constructor of class :class:`icat.query.Query` checks the
version of the ICAT server and raises an error if too old.

+ The :meth:`icat.ids.IDSClient.getIcatUrl` call checks the version of
the IDS server.

+ Some changes in the test suite, add more tests.

.. _13: https://github.com/icatproject/python-icat/issues/13
.. _14: https://github.com/icatproject/python-icat/issues/14
.. _15: https://github.com/icatproject/python-icat/issues/15


.. _changes-0_9_0:

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

New features
------------

+ `143`_, `144`_: Make it easier to configure XSLT files to use for
processing the input in custom versions of
:class:`icat.ingest.IngestReader`.

+ `148`_, `149`_: Inject an additional element with environment
information into the input data in :class:`icat.ingest.IngestReader`.

+ `146`_, `147`_, `151`_: Better error handling in
:class:`icat.ingest.IngestReader`.

Incompatible changes
--------------------

+ `144`_: Drop class attribute
:attr:`icat.ingest.IngestReader.XSLT_name` in favour of
:attr:`icat.ingest.IngestReader.XSLT_Map`.

Note that :mod:`icat.ingest` has been declared experimental for now.

Bug fixes and minor changes
---------------------------

+ `141`_, `142`_, `150`_: Review documentation.

+ `145`_: Review build tool chain.

.. _141: https://github.com/icatproject/python-icat/issues/141
.. _142: https://github.com/icatproject/python-icat/pull/142
.. _143: https://github.com/icatproject/python-icat/issues/143
.. _144: https://github.com/icatproject/python-icat/pull/144
.. _145: https://github.com/icatproject/python-icat/pull/145
.. _146: https://github.com/icatproject/python-icat/issues/146
.. _147: https://github.com/icatproject/python-icat/pull/147
.. _148: https://github.com/icatproject/python-icat/issues/148
.. _149: https://github.com/icatproject/python-icat/pull/149
.. _150: https://github.com/icatproject/python-icat/pull/150
.. _151: https://github.com/icatproject/python-icat/pull/151


.. _changes-1_2_0:

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

New features
------------

+ `125`_, `140`_: Add support to link datasets with samples in
:mod:`icat.ingest`.

+ `122`_, `133`_: Allow referencing related objects by reference key
in object references in XML ICAT data file format.

Incompatible changes
--------------------

+ `138`_, `139`_: Fix the input that :mod:`icat.ingest` generates on
the fly to be valid according to the ICAT data file schema. This
also affects the input that the module accepts: the order of
subelements of `data` need to be changed such that
`datasetTechnique` comes before `datasetInstrument`.

Note that :mod:`icat.ingest` has been declared experimental for now.

Bug fixes and minor changes
---------------------------

+ `131`_, `135`_: Fix :meth:`icat.ids.IDSClient.getApiVersion` to
yield correct results for ids.server 2.0.0 and newer.

+ `132`_, `136`_: Fix a spurious :exc:`AttributeError` on cleanup
after connecting to an invalid url.

+ `130`_, `137`_: Review test suite.

.. _122: https://github.com/icatproject/python-icat/issues/122
.. _125: https://github.com/icatproject/python-icat/issues/125
.. _130: https://github.com/icatproject/python-icat/issues/130
.. _131: https://github.com/icatproject/python-icat/issues/131
.. _132: https://github.com/icatproject/python-icat/issues/132
.. _133: https://github.com/icatproject/python-icat/pull/133
.. _135: https://github.com/icatproject/python-icat/pull/135
.. _136: https://github.com/icatproject/python-icat/pull/136
.. _137: https://github.com/icatproject/python-icat/pull/137
.. _138: https://github.com/icatproject/python-icat/issues/138
.. _139: https://github.com/icatproject/python-icat/pull/139
.. _140: https://github.com/icatproject/python-icat/pull/140


.. _changes-1_1_0:

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

New features
------------

+ `113`_, `123`_: Add module :mod:`icat.ingest`.

+ `124`_: Add an optional keyword argument `keepInstRel` to
:meth:`icat.entity.Entity.truncateRelations`.

Bug fixes and minor changes
---------------------------

+ `126`_, `127`_: Update outdated documentation.

+ `112`_, `118`_: Extend icatdata XSD adding extra attributes to
reference objects.

+ `111`_, `121`_: Change the type of
:attr:`icat.client.Client.Register` to
:class:`weakref.WeakValueDictionary`, fixing a memory leak.

+ `119`_, `120`_: Remove `_config` attribute from
:class:`icat.config.Configuration`.

+ `115`_, `116`_: Fix the test suite to work if either PyYAML or
lxml is not available.

+ `128`_: Return an empty list from
:func:`icat.dump_queries.getDataPublicationQueries` when talking to
an ICAT server older than 5.0.

+ `117`_: Fixed deprecation warnings from upcoming Python 3.12.

+ `129`_: Review the build of the documentation at Read the Docs.

.. _111: https://github.com/icatproject/python-icat/issues/111
.. _112: https://github.com/icatproject/python-icat/issues/112
.. _113: https://github.com/icatproject/python-icat/issues/113
.. _115: https://github.com/icatproject/python-icat/issues/115
.. _116: https://github.com/icatproject/python-icat/pull/116
.. _117: https://github.com/icatproject/python-icat/pull/117
.. _118: https://github.com/icatproject/python-icat/pull/118
.. _119: https://github.com/icatproject/python-icat/issues/119
.. _120: https://github.com/icatproject/python-icat/pull/120
.. _121: https://github.com/icatproject/python-icat/pull/121
.. _123: https://github.com/icatproject/python-icat/pull/123
.. _124: https://github.com/icatproject/python-icat/pull/124
.. _126: https://github.com/icatproject/python-icat/issues/126
.. _127: https://github.com/icatproject/python-icat/pull/127
.. _128: https://github.com/icatproject/python-icat/pull/128
.. _129: https://github.com/icatproject/python-icat/pull/129


.. _changes-1_0_0:

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

New features
------------

+ `73`_, `106`_: Add support for the ICAT schema 5.0 extensions.

+ `102`_, `104`_: Make the `obj` argument to
:meth:`icat.client.Client.new` case insensitive.

+ `77`_, `103`_: Add a keyword argument `preset` to allow directly
passing configuration values to the constructor of class
:class:`icat.config.Config`.

+ `66`_, `75`_: Add pathlib support: methods that take a file name
argument also accept a :class:`pathlib.Path` object. Internal
representation of file system paths are changed to use
:class:`pathlib.Path` where appropriate. The predefined
configuarion variable `configFile` now supports tilde expansion.
Note incompatible changes below.

+ `74`_: :class:`icat.ids.DataSelection` also accepts
`DataCollection` as argument.

Incompatible changes and deprecations
-------------------------------------

+ The order and arrangement of data objects in the dump file created
by :ref:`icatdump` has been changed. In some cases, older versions
of :ref:`icatingest` will fail to read dump files written by new
versions of :ref:`icatdump`.

+ As a consequence of switching to pathlib for file system paths some
return values and variables are now :class:`pathlib.Path` objects
rather then :class:`str`. This affects:

- the return value of :func:`icat.config.cfgpath`,
- the predefined configuarion variable `configFile`,
- the module variable :data:`icat.config.cfgdirs`.

+ Drop support for Python 2 and Python 3.3.

+ Drop keyword argument `attribute` and method
:meth:`icat.query.Query.setAttribute` from class
:class:`icat.query.Query`, deprecated in 0.18.0.

+ Drop module :mod:`icat.cgi`, deprecated in 0.13.0.

+ Drop module :mod:`icat.icatcheck` and exception
:exc:`icat.exception.GenealogyError`, deprecated in 0.17.0.

+ Drop methods :meth:`icat.ids.IDSClient.resetPrepared`,
:meth:`icat.ids.IDSClient.getPreparedDatafileIds`,
:meth:`icat.ids.IDSClient.getPreparedData`,
:meth:`icat.ids.IDSClient.getPreparedDataUrl`,
:meth:`icat.client.Client.getPreparedData`, and
:meth:`icat.client.Client.getPreparedDataUrl`, deprecated in 0.17.0.

+ Drop the predefined configuration variable `configDir`, deprecated
in 0.13.0.

+ Drop helper function :func:`icat.exception.stripCause`, deprecated
in 0.14.0.

+ Deprecate :data:`icat.config.defaultsection`. Use the new `preset`
keyword argument to :class:`icat.config.Config` instead.

Bug fixes and minor changes
---------------------------

+ `98`_, `105`_: Review build tool chain. Add a helper class
:class:`icat.helper.Version`.

+ `101`_: Fix tests failing with PyYAML 6.0.

+ Some (more) example scripts now require ICAT 4.4.0 or newer.

.. _66: https://github.com/icatproject/python-icat/issues/66
.. _73: https://github.com/icatproject/python-icat/issues/73
.. _74: https://github.com/icatproject/python-icat/issues/74
.. _75: https://github.com/icatproject/python-icat/pull/75
.. _77: https://github.com/icatproject/python-icat/issues/77
.. _98: https://github.com/icatproject/python-icat/issues/98
.. _101: https://github.com/icatproject/python-icat/pull/101
.. _102: https://github.com/icatproject/python-icat/issues/102
.. _103: https://github.com/icatproject/python-icat/pull/103
.. _104: https://github.com/icatproject/python-icat/pull/104
.. _105: https://github.com/icatproject/python-icat/pull/105
.. _106: https://github.com/icatproject/python-icat/pull/106


.. _changes-0_21_0: