Merge branch 'release/0.20.0'

Author: RKrahl

.rtd-require

@@ -1,4 +1,4 @@
 setuptools_scm
-suds-jurko
+suds-community
 PyYAML
 lxml

CHANGES.rst

@@ -2,6 +2,42 @@ Changelog
 =========
 
 
+0.20.0 (2021-10-29)
+~~~~~~~~~~~~~~~~~~~
+
+New features
+------------
+
++ `#86`_, `#89`_: allow SQL functions to be used on the attributes in
+  the arguments to :meth:`icat.query.Query.setOrder` and
+  :meth:`icat.query.Query.addConditions`.
+
+Incompatible changes and new bugs
+---------------------------------
+
++ `#94`_: the implementation of `#89`_ changed the internal data
+  structures in :attr:`icat.query.Query.conditions` and
+  :attr:`icat.query.Query.order`.  These attributes are considered
+  internal and are deliberately not documented, so one could argue
+  that this is not an incompatible change.  But the changes also have
+  an impact on the return value of :meth:`icat.query.Query.__repr__`
+  such that it is not suitable to recreate the query object.
+
+Bug fixes and minor changes
+---------------------------
+
++ `#90`_, `#91`_, `#95`_: :attr:`icat.query.Query.join_specs` was not
+  taken into account in :meth:`icat.query.Query.copy` and
+  :meth:`icat.query.Query.__repr__`.
+
+.. _#86: https://github.com/icatproject/python-icat/issues/86
+.. _#89: https://github.com/icatproject/python-icat/pull/89
+.. _#90: https://github.com/icatproject/python-icat/issues/90
+.. _#91: https://github.com/icatproject/python-icat/issues/91
+.. _#94: https://github.com/icatproject/python-icat/issues/94
+.. _#95: https://github.com/icatproject/python-icat/pull/95
+
+
 0.19.0 (2021-07-20)
 ~~~~~~~~~~~~~~~~~~~
 

README.rst

@@ -178,7 +178,9 @@ Bugs and limitations
 
 + There are issues with ICAT server 4.8.0 and older when using
   suds-community, see `Issue #72`_ for details.  Use suds-jurko when
-  you need to talk to those older ICAT servers.
+  you need to talk to those older ICAT servers.  On the other hand,
+  suds-jurko does can not be installed with setuptools 58.0.0 and
+  newer.
 
 + If supported by the ICAT server (icat.server 4.9.0 and newer), the
   icat.config module queries the server for information on available
@@ -192,6 +194,11 @@ Bugs and limitations
   configuration variables and thus command line arguments are
   effective then those shown by the generic help message.
 
++ The return value of the formal string representation operator of
+  class Query can not be used to recreate another query object with
+  the same value as required by Python standards, see `Issue #94`_ for
+  details.
+
 + For Python 2, the return value of the string representation operator
   of class Query may be a Unicode object if any of the conditions
   contains Unicode.  This violates the specification that requires the
@@ -251,6 +258,7 @@ permissions and limitations under the License.
 .. _Read the Docs site: https://python-icat.readthedocs.io/
 .. _GitHub repository: https://github.com/icatproject/python-icat
 .. _Issue #72: https://github.com/icatproject/python-icat/issues/72
+.. _Issue #94: https://github.com/icatproject/python-icat/issues/94
 .. _PEP 440: https://www.python.org/dev/peps/pep-0440/
 .. _Semantic Versioning: https://semver.org/
 .. _Apache License: https://www.apache.org/licenses/LICENSE-2.0

doc/src/tutorial-search.rst

@@ -183,6 +183,40 @@ We may also include related objects in the search results::
      visitId = "1.1-N"
    }]
 
+python-icat supports the use of some JPQL functions when specifying
+which attribute a condition should be applied to.  Consider the
+following query::
+
+  >>> query = Query(client, "Investigation", conditions={"LENGTH(title)": "= 18"})
+  >>> print(query)
+  SELECT o FROM Investigation o WHERE LENGTH(o.title) = 18
+  >>> client.search(query)
+  [(investigation){
+     createId = "simple/root"
+     createTime = 2021-10-05 14:09:57+00:00
+     id = 430
+     modId = "simple/root"
+     modTime = 2021-10-05 14:09:57+00:00
+     doi = "00.0815/inv-00601"
+     endDate = 2010-10-12 15:00:00+00:00
+     name = "10100601-ST"
+     startDate = 2010-09-30 10:27:24+00:00
+     title = "Ni-Mn-Ga flat cone"
+     visitId = "1.1-N"
+   }, (investigation){
+     createId = "simple/root"
+     createTime = 2021-10-05 14:09:58+00:00
+     id = 431
+     modId = "simple/root"
+     modTime = 2021-10-05 14:09:58+00:00
+     doi = "00.0815/inv-00409"
+     endDate = 2012-08-06 01:10:08+00:00
+     name = "12100409-ST"
+     startDate = 2012-07-26 15:44:24+00:00
+     title = "NiO SC OF1 JUH HHL"
+     visitId = "1.1-P"
+   }]
+
 The conditions in a query may also be put on the attributes of related
 objects.  This allows rather complex queries.  Let us search for the
 datasets in this investigation that have been measured in a magnetic
@@ -668,6 +702,27 @@ dataset parameter, ordered by parameter type name (ascending), units
         }
    }]
 
+In a similar way as for `conditions`, we may use JPQL functions also
+in the `order` argument to :class:`~icat.query.Query`.  Let's search
+for user sorted by the length of their name, from longest to
+shortest::
+
+  >>> query = Query(client, "User", conditions={"fullName": "IS NOT NULL"}, order=[("LENGTH(fullName)", "DESC")])
+  >>> print(query)
+  SELECT o FROM User o WHERE o.fullName IS NOT NULL ORDER BY LENGTH(o.fullName) DESC
+  >>> for user in client.search(query):
+  ...     print("%d: %s" % (len(user.fullName), user.fullName))
+  ...
+  19: Rudolph Beck-Dülmen
+  19: Jean-Baptiste Botul
+  16: Nicolas Bourbaki
+  13: Aelius Cordus
+  11: User Office
+  10: Arnold Hau
+  10: IDS reader
+  8: John Doe
+  4: Root
+
 We may limit the number of returned items.  Search for the second to
 last dataset to have been finished::