Review the internal data structures in class Query

CHANGES.rst

@@ -2,6 +2,46 @@ Changelog
 =========
 
 
+.. _changes-2_0_0:
+
+2.0.0 (not yet released)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Modified features
+-----------------
+
++ `#158`_: Review the internal data structures in class
+  :class:`icat.query.Query`.  As a consequence, change the format of
+  the `conditions` argument to :class:`icat.query.Query` and
+  :meth:`icat.query.Query.addConditions` from a mapping to a list of
+  tuples.  The legacy format is still supported, but deprecated.
+  Furthermore drop the restriction that any attribute may only appear
+  once in the `order` argument to :class:`icat.query.Query` and
+  :meth:`icat.query.Query.setOrder`.
+
+Incompatible changes and deprecations
+-------------------------------------
+
++ `#158`_: Deprecate passing a mapping in the `conditions` argument to
+  :class:`icat.query.Query` and :meth:`icat.query.Query.addConditions`.
+  In calling code, change::
+
+    query = Query(client, "Datafile", conditions={
+        "dataset.name": "= 'e208945'",
+        "datafileCreateTime": [">= '2012-01-01'", "< '2013-01-01'" ],
+    })
+
+  to::
+
+    query = Query(client, "Datafile", conditions=[
+        ("dataset.name", "= 'e208945'"),
+        ("datafileCreateTime", ">= '2012-01-01'"),
+        ("datafileCreateTime", "< '2013-01-01'" ),
+    ])
+
+.. _#158: https://github.com/icatproject/python-icat/pull/158
+
+
 .. _changes-1_4_0:
 
 1.4.0 (2024-08-30)

doc/examples/add-job.py

@@ -42,8 +42,10 @@ def makeparam(t, pdata):
     param = client.new(t)
     initobj(param, pdata)
     ptdata = data['parameter_types'][pdata['type']]
-    query = ("ParameterType [name='%s' AND units='%s']"
-             % (ptdata['name'], ptdata['units']))
+    query = Query(client, "ParameterType", conditions=[
+        ("name", "= '%s'" % ptdata['name']),
+        ("units", "= '%s'" % ptdata['units']),
+    ])
     param.type = client.assertedSearch(query)[0]
     return param
 
@@ -78,20 +80,20 @@ def makeparam(t, pdata):
 initobj(inputcollection, jobdata['input'])
 
 for ds in jobdata['input']['datasets']:
-    query = Query(client, "Dataset", conditions={
-        "name":"= '%s'" % ds['name'],
-        "investigation.name":"= '%s'" % ds['investigation']
-    })
+    query = Query(client, "Dataset", conditions=[
+        ("name", "= '%s'" % ds['name']),
+        ("investigation.name", "= '%s'" % ds['investigation']),
+    ])
     dataset = client.assertedSearch(query)[0]
     dcs = client.new("DataCollectionDataset", dataset=dataset)
     inputcollection.dataCollectionDatasets.append(dcs)
 
 for df in jobdata['input']['datafiles']:
-    query = Query(client, "Datafile", conditions={
-        "name":"= '%s'" % df['name'],
-        "dataset.name":"= '%s'" % df['dataset'],
-        "dataset.investigation.name":"= '%s'" % df['investigation']
-    })
+    query = Query(client, "Datafile", conditions=[
+        ("name", "= '%s'" % df['name']),
+        ("dataset.name", "= '%s'" % df['dataset']),
+        ("dataset.investigation.name", "= '%s'" % df['investigation']),
+    ])
     datafile = client.assertedSearch(query)[0]
     dcf = client.new("DataCollectionDatafile", datafile=datafile)
     inputcollection.dataCollectionDatafiles.append(dcf)
@@ -112,13 +114,13 @@ def makeparam(t, pdata):
 initobj(outputcollection, jobdata['output'])
 
 for ds in jobdata['output']['datasets']:
-    query = Query(client, "Investigation", conditions={
-        "name":"= '%s'" % ds['investigation']
-    })
+    query = Query(client, "Investigation", conditions=[
+        ("name", "= '%s'" % ds['investigation']),
+    ])
     investigation = client.assertedSearch(query)[0]
-    query = Query(client, "DatasetType", conditions={
-        "name":"= '%s'" % data['dataset_types'][ds['type']]['name']
-    })
+    query = Query(client, "DatasetType", conditions=[
+        ("name", "= '%s'" % data['dataset_types'][ds['type']]['name'])
+    ])
     dataset_type = client.assertedSearch(query)[0]
     print("Dataset: creating '%s' ..." % ds['name'])
     dataset = client.new("Dataset")
@@ -131,10 +133,10 @@ def makeparam(t, pdata):
 
     for df in ds['datafiles']:
         dff = data['datafile_formats'][df['format']]
-        query = Query(client, "DatafileFormat", conditions={
-            "name":"= '%s'" % dff['name'],
-            "version":"= '%s'" % dff['version'],
-        })
+        query = Query(client, "DatafileFormat", conditions=[
+            ("name", "= '%s'" % dff['name']),
+            ("version", "= '%s'" % dff['version']),
+        ])
         datafile_format = client.assertedSearch(query)[0]
         print("Datafile: creating '%s' ..." % df['name'])
         datafile = client.new("Datafile")
@@ -157,16 +159,16 @@ def makeparam(t, pdata):
     outputcollection.dataCollectionDatasets.append(dcs)
 
 for df in jobdata['output']['datafiles']:
-    query = Query(client, "Dataset", conditions={
-        "name":"= '%s'" % df['dataset'],
-        "investigation.name":"= '%s'" % df['investigation']
-    })
+    query = Query(client, "Dataset", conditions=[
+        ("name", "= '%s'" % df['dataset']),
+        ("investigation.name", "= '%s'" % df['investigation']),
+    ])
     dataset = client.assertedSearch(query)[0]
     dff = data['datafile_formats'][df['format']]
-    query = Query(client, "DatafileFormat", conditions={
-        "name":"= '%s'" % dff['name'],
-        "version":"= '%s'" % dff['version'],
-    })
+    query = Query(client, "DatafileFormat", conditions=[
+        ("name", "= '%s'" % dff['name']),
+        ("version", "= '%s'" % dff['version']),
+    ])
     datafile_format = client.assertedSearch(query)[0]
     print("Datafile: creating '%s' ..." % df['name'])
     datafile = client.new("Datafile")

doc/examples/create-datafile.py

@@ -56,13 +56,13 @@
     raise RuntimeError("datafile %s not found" % df_path)
 
 query = Query(client, "DatasetType",
-              conditions={ "name": "= '%s'" % conf.dst_name })
+              conditions=[ ("name", "= '%s'" % conf.dst_name) ])
 dst = client.assertedSearch(query)[0]
 query = Query(client, "DatafileFormat",
-              conditions={ "name": "= '%s'" % conf.dff_name })
+              conditions=[ ("name", "= '%s'" % conf.dff_name) ])
 dff = client.assertedSearch(query)[0]
 query = Query(client, "Investigation",
-              conditions={ "name": "= '%s'" % conf.investigation })
+              conditions=[ ("name", "= '%s'" % conf.investigation) ])
 investigation = client.assertedSearch(query)[0]
 
 fstats = df_path.stat()

doc/examples/create-investigation.py

@@ -107,8 +107,10 @@ def getUser(client, attrs):
         ip = client.new("InvestigationParameter")
         initobj(ip, pdata)
         ptdata = data['parameter_types'][pdata['type']]
-        query = ("ParameterType [name='%s' AND units='%s']"
-                 % (ptdata['name'], ptdata['units']))
+        query = Query(client, "ParameterType", conditions=[
+            ("name", "= '%s'" % ptdata['name']),
+            ("units", "= '%s'" % ptdata['units']),
+        ])
         ip.type = client.assertedSearch(query)[0]
         investigation.parameters.append(ip)
 if 'shifts' in investigationdata:
@@ -123,10 +125,10 @@ def getUser(client, attrs):
     sd = investigation.startDate or investigation.endDate
     ed = investigation.endDate or investigation.startDate
     if sd and ed:
-        query = Query(client, "FacilityCycle", conditions={
-            "startDate": "<= '%s'" % parse_attr_string(ed, "Date"),
-            "endDate": "> '%s'" % parse_attr_string(sd, "Date"),
-        })
+        query = Query(client, "FacilityCycle", conditions=[
+            ("startDate", "<= '%s'" % parse_attr_string(ed, "Date")),
+            ("endDate", "> '%s'" % parse_attr_string(sd, "Date")),
+        ])
         for fc in client.search(query):
             ifc = client.new("InvestigationFacilityCycle", facilityCycle=fc)
             investigation.investigationFacilityCycles.append(ifc)

doc/examples/dumpinvestigation.py

@@ -75,20 +75,32 @@ def mergesearch(sexps):
 # instruments related to the investigations.  These are independent
 # searches, but the results are likely to overlap.  So we need to
 # search and merge results first.  Similar situation for ParameterType.
-usersearch = [("User <-> InvestigationUser <-> Investigation [id=%d]"),
-              ("User <-> UserGroup <-> Grouping <-> InvestigationGroup "
-               "<-> Investigation [id=%d]"),
-              ("User <-> InstrumentScientist <-> Instrument "
-               "<-> InvestigationInstrument <-> Investigation [id=%d]")]
-ptsearch = [("ParameterType INCLUDE Facility, PermissibleStringValue "
-             "<-> InvestigationParameter <-> Investigation [id=%d]"),
-            ("ParameterType INCLUDE Facility, PermissibleStringValue "
-             "<-> SampleParameter <-> Sample <-> Investigation [id=%d]"),
-            ("ParameterType INCLUDE Facility, PermissibleStringValue "
-             "<-> DatasetParameter <-> Dataset <-> Investigation [id=%d]"),
-            ("ParameterType INCLUDE Facility, PermissibleStringValue "
-             "<-> DatafileParameter <-> Datafile <-> Dataset "
-             "<-> Investigation [id=%d]"), ]
+usersearch = [
+    Query(client, "User", conditions=[
+        ("investigationUsers.investigation.id", "= %d")
+    ]),
+    Query(client, "User", conditions=[
+        ("userGroups.grouping.investigationGroups.investigation.id", "= %d")
+    ]),
+    Query(client, "User", conditions=[
+        ("instrumentScientists.instrument.investigationInstruments."
+         "investigation.id", "= %d")
+    ]),
+]
+ptsearch = [
+    Query(client, "ParameterType", conditions=[
+        ("investigationParameters.investigation.id", "= %d")
+    ], includes=["facility", "permissibleStringValues"]),
+    Query(client, "ParameterType", conditions=[
+        ("sampleParameters.sample.investigation.id", "= %d")
+    ], includes=["facility", "permissibleStringValues"]),
+    Query(client, "ParameterType", conditions=[
+        ("datasetParameters.dataset.investigation.id", "= %d")
+    ], includes=["facility", "permissibleStringValues"]),
+    Query(client, "ParameterType", conditions=[
+        ("datafileParameters.datafile.dataset.investigation.id", "= %d")
+    ], includes=["facility", "permissibleStringValues"]),
+]
 
 # The set of objects to be included in the Investigation.
 inv_includes = { "facility", "type.facility", "investigationInstruments",
@@ -103,42 +115,49 @@ def mergesearch(sexps):
 # list: either queries expressed as Query objects, or queries
 # expressed as string expressions, or lists of objects.  In the first
 # two cases, the seacrh results will be written, in the last case, the
-# objects are written as provided.  We assume that there is only one
-# relevant facility, e.g. that all objects related to the
-# investigation are related to the same facility.  We may thus ommit
-# the facility from the ORDER BY clauses.
-authtypes =   [mergesearch([s % invid for s in usersearch]),
-               ("Grouping ORDER BY name INCLUDE UserGroup, User "
-                "<-> InvestigationGroup <-> Investigation [id=%d]" % invid)]
-statictypes = [("Facility ORDER BY name"),
-               ("Instrument ORDER BY name "
-                "INCLUDE Facility, InstrumentScientist, User "
-                "<-> InvestigationInstrument <-> Investigation [id=%d]"
-                % invid),
-               (mergesearch([s % invid for s in ptsearch])),
-               ("InvestigationType ORDER BY name INCLUDE Facility "
-                "<-> Investigation [id=%d]" % invid),
-               ("SampleType ORDER BY name, molecularFormula INCLUDE Facility "
-                "<-> Sample <-> Investigation [id=%d]" % invid),
-               ("DatasetType ORDER BY name INCLUDE Facility "
-                "<-> Dataset <-> Investigation [id=%d]" % invid),
-               ("DatafileFormat ORDER BY name, version INCLUDE Facility "
-                "<-> Datafile <-> Dataset <-> Investigation [id=%d]" % invid)]
-investtypes = [Query(client, "Investigation",
-                     conditions={"id":"in (%d)" % invid},
-                     includes=inv_includes),
-               Query(client, "Sample", order=["name"],
-                     conditions={"investigation.id":"= %d" % invid},
-                     includes={"investigation", "type.facility",
-                               "parameters", "parameters.type.facility"}),
-               Query(client, "Dataset", order=["name"],
-                     conditions={"investigation.id":"= %d" % invid},
-                     includes={"investigation", "type.facility", "sample",
-                               "parameters", "parameters.type.facility"}),
-               Query(client, "Datafile", order=["dataset.name", "name"],
-                     conditions={"dataset.investigation.id":"= %d" % invid},
-                     includes={"dataset", "datafileFormat.facility",
-                               "parameters", "parameters.type.facility"})]
+# objects are written as provided.
+authtypes = [
+    mergesearch([str(s) % invid for s in usersearch]),
+    Query(client, "Grouping", conditions=[
+        ("investigationGroups.investigation.id", "= %d" % invid)
+    ], order=["name"], includes=["userGroups.user"])
+]
+statictypes = [
+    Query(client, "Facility", order=True),
+    Query(client, "Instrument", conditions=[
+        ("investigationInstruments.investigation.id", "= %d" % invid)
+    ], order=True, includes=["facility", "instrumentScientists.user"]),
+    mergesearch([str(s) % invid for s in ptsearch]),
+    Query(client, "InvestigationType", conditions=[
+        ("investigations.id", "= %d" % invid)
+    ], order=True, includes=["facility"]),
+    Query(client, "SampleType", conditions=[
+        ("samples.investigation.id", "= %d" % invid)
+    ], order=True, includes=["facility"]),
+    Query(client, "DatasetType", conditions=[
+        ("datasets.investigation.id", "= %d" % invid)
+    ], order=True, includes=["facility"]),
+    Query(client, "DatafileFormat", conditions=[
+        ("datafiles.dataset.investigation.id", "= %d" % invid)
+    ], order=True, includes=["facility"]),
+]
+investtypes = [
+    Query(client, "Investigation",
+          conditions=[("id", "in (%d)" % invid)],
+          includes=inv_includes),
+    Query(client, "Sample", order=["name"],
+          conditions=[("investigation.id", "= %d" % invid)],
+          includes={"investigation", "type.facility",
+                    "parameters", "parameters.type.facility"}),
+    Query(client, "Dataset", order=["name"],
+          conditions=[("investigation.id", "= %d" % invid)],
+          includes={"investigation", "type.facility", "sample",
+                    "parameters", "parameters.type.facility"}),
+    Query(client, "Datafile", order=["dataset.name", "name"],
+          conditions=[("dataset.investigation.id", "= %d" % invid)],
+          includes={"dataset", "datafileFormat.facility",
+                    "parameters", "parameters.type.facility"})
+]
 
 with open_dumpfile(client, conf.file, conf.format, 'w') as dumpfile:
     dumpfile.writedata(authtypes)

doc/examples/dumprules.py

@@ -36,7 +36,7 @@
 
 groups = set()
 query = Query(client, "Rule",
-              conditions={"grouping": "IS NOT NULL"},
+              conditions=[("grouping", "IS NOT NULL")],
               includes={"grouping.userGroups.user"})
 for r in client.search(query):
     groups.add(r.grouping)
@@ -45,9 +45,9 @@
     sorted(groups, key=icat.entity.Entity.__sortkey__),
     Query(client, "PublicStep"),
     Query(client, "Rule", order=["what", "id"],
-          conditions={"grouping": "IS NULL"}),
+          conditions=[("grouping", "IS NULL")]),
     Query(client, "Rule", order=["grouping.name", "what", "id"],
-          conditions={"grouping": "IS NOT NULL"},
+          conditions=[("grouping", "IS NOT NULL")],
           includes={"grouping"}),
 ]
 

doc/examples/ingest.py

@@ -83,9 +83,9 @@
 client, conf = config.getconfig()
 client.login(conf.auth, conf.credentials)
 
-query = Query(client, "Investigation", conditions={
-    "name": "= '%s'" % conf.investigation
-})
+query = Query(client, "Investigation", conditions=[
+    ("name", "= '%s'" % conf.investigation),
+])
 investigation = client.assertedSearch(query)[0]