Merge branch 'release/0.21.0'

Author: RKrahl

CHANGES.rst

@@ -2,6 +2,23 @@ Changelog
 =========
 
 
+0.21.0 (2022-01-28)
+~~~~~~~~~~~~~~~~~~~
+
+New features
+------------
+
++ `#100`_: Add read only attributes
+  :attr:`icat.query.Query.select_clause`,
+  :attr:`icat.query.Query.join_clause`,
+  :attr:`icat.query.Query.where_clause`,
+  :attr:`icat.query.Query.order_clause`,
+  :attr:`icat.query.Query.include_clause`, and
+  :attr:`icat.query.Query.limit_clause` to access the respective
+  clauses of the query string.
+
+.. _#100: https://github.com/icatproject/python-icat/pull/100
+
 0.20.1 (2021-11-04)
 ~~~~~~~~~~~~~~~~~~~
 

README.rst

@@ -26,11 +26,13 @@ The latest release version can be found `Python Package Index (PyPI)`__.
 System requirements
 -------------------
 
-Python:
+Python
+......
 
 + 2.7 or 3.3 and newer.
 
-Required Library packages:
+Required library packages
+.........................
 
 + Suds.  The original version by Jeff Ortel is not maintained anymore
   since very long time and not recommended.  There are several forks
@@ -41,8 +43,21 @@ Required Library packages:
 
 .. __: `suds-jurko`_
 
-Optional library packages, only needed to use certain extra features,
-not required to install or use python-icat itself:
+Conflicts with other packages
+.............................
+
++ `setuptools`_ >= 58.0
+
+  There is a breaking change in setuptools 58.0 that affects all
+  python-icat releases older than upcoming 1.0.  You must either not
+  install setuptools at all or at least downgrade it to 57.5 or older
+  in order to install python-icat.
+
+Optional library packages
+.........................
+
+These packages are only needed to use certain extra features.  They
+are not required to install or use python-icat itself:
 
 + `PyYAML`_
 
@@ -230,7 +245,7 @@ when it is incompatible with PEP 440.
 Copyright and License
 ---------------------
 
-Copyright 2013–2021
+Copyright 2013–2022
 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
 
 Licensed under the `Apache License`_, Version 2.0 (the "License"); you
@@ -247,6 +262,7 @@ permissions and limitations under the License.
 .. _PyPI site: https://pypi.org/project/python-icat/
 .. _suds-jurko: https://bitbucket.org/jurko/suds
 .. _suds-community: https://github.com/suds-community/suds
+.. _setuptools: https://github.com/pypa/setuptools
 .. _PyYAML: https://github.com/yaml/pyyaml
 .. _lxml: https://lxml.de/
 .. _Requests: https://requests.readthedocs.io/

doc/src/conf.py

@@ -11,7 +11,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'python-icat'
-copyright = ('2013–2021, '
+copyright = ('2013–2022, '
              'Helmholtz-Zentrum Berlin für Materialien und Energie GmbH')
 author = 'Rolf Krahl'
 

icat/query.py

@@ -129,11 +129,11 @@ def __init__(self, client, entity,
         if isinstance(entity, basestring):
             self.entity = self.client.getEntityClass(entity)
         elif issubclass(entity, icat.entity.Entity):
-            if (entity in self.client.typemap.values() and 
+            if (entity in self.client.typemap.values() and
                 entity.BeanName is not None):
                 self.entity = entity
             else:
-                raise EntityTypeError("Invalid entity type '%s'." 
+                raise EntityTypeError("Invalid entity type '%s'."
                                       % entity.__name__)
         else:
             raise EntityTypeError("Invalid entity type '%s'." % type(entity))
@@ -155,6 +155,7 @@ def __init__(self, client, entity,
         self.setOrder(order)
         self.setLimit(limit)
         self._init = None
+        self._subst = None
 
     def _attrpath(self, attrname):
         """Follow the attribute path along related objects and iterate over
@@ -170,12 +171,12 @@ def _attrpath(self, attrname):
             if rclass is None:
                 # Last component was not a relation, no further components
                 # in the name allowed.
-                raise ValueError("Invalid attrname '%s' for %s." 
+                raise ValueError("Invalid attrname '%s' for %s."
                                  % (attrname, self.entity.BeanName))
             attrInfo = rclass.getAttrInfo(self.client, attr)
             if attrInfo.relType == "ATTRIBUTE":
                 rclass = None
-            elif (attrInfo.relType == "ONE" or 
+            elif (attrInfo.relType == "ONE" or
                   attrInfo.relType == "MANY"):
                 rclass = self.client.getEntityClass(attrInfo.type)
             else:
@@ -225,6 +226,14 @@ def _split_db_functs(self, attr):
             raise ValueError("Invalid attribute '%s'" % attr)
         return m.group(2,1)
 
+    def _get_subst(self):
+        if self._subst is None:
+            joinattrs = ( set(self.order.keys()) |
+                          set(self.conditions.keys()) |
+                          set(self.attributes) )
+            self._subst = self._makesubst(joinattrs)
+        return self._subst
+
     def setAttributes(self, attributes):
         """Set the attributes that the query shall return.
 
@@ -244,6 +253,7 @@ def setAttributes(self, attributes):
             :meth:`setAttribute` to :meth:`setAttributes` (in the
             plural).
         """
+        self._subst = None
         self.attributes = []
         if attributes:
             if isinstance(attributes, str):
@@ -343,6 +353,7 @@ def setOrder(self, order):
         .. versionchanged:: 0.20.0
             allow a JPQL function in the attribute.
         """
+        self._subst = None
         # Note: with Python 3.7 and newer we could simplify this using
         # a standard dict() rather then an OrderedDict().
         self.order = OrderedDict()
@@ -359,7 +370,7 @@ def setOrder(self, order):
                 if isinstance(obj, tuple):
                     obj, direction = obj
                     if direction not in ("ASC", "DESC"):
-                        raise ValueError("Invalid ordering direction '%s'" 
+                        raise ValueError("Invalid ordering direction '%s'"
                                          % direction)
                 else:
                     direction = None
@@ -433,6 +444,7 @@ def _cond_value(rhs, func):
             else:
                 return "%%s %s" % (rhs)
         if conditions:
+            self._subst = None
             for k in conditions.keys():
                 if isinstance(conditions[k], basestring):
                     conds = [conditions[k]]
@@ -463,7 +475,7 @@ def addIncludes(self, includes):
                 for (pattr, attrInfo, rclass) in self._attrpath(iobj):
                     pass
                 if rclass is None:
-                    raise ValueError("%s.%s is not a related object." 
+                    raise ValueError("%s.%s is not a related object."
                                      % (self.entity.BeanName, iobj))
             self.includes.update(includes)
 
@@ -479,36 +491,15 @@ def setLimit(self, limit):
                 raise TypeError("limit must be a tuple of two elements.")
             self.limit = limit
         else:
-            self.limit = None            
-
-    def __repr__(self):
-        """Return a formal representation of the query.
-        """
-        return ("%s(%s, %s, attributes=%s, aggregate=%s, order=%s, "
-                "conditions=%s, includes=%s, limit=%s, join_specs=%s)"
-                % (self.__class__.__name__,
-                   repr(self.client), repr(self.entity.BeanName),
-                   repr(self.attributes), repr(self.aggregate),
-                   repr(self.order), repr(self.conditions),
-                   repr(self.includes), repr(self.limit),
-                   repr(self.join_specs)))
+            self.limit = None
 
-    def __str__(self):
-        """Return a string representation of the query.
+    @property
+    def select_clause(self):
+        """The SELECT clause of the query.
 
-        Note for Python 2: the result will be an unicode object if any
-        of the conditions in the query contains unicode.  This
-        violates the specification of the string representation
-        operator that requires the return value to be a string object.
-        But it is the *right thing* to do to get queries with
-        non-ascii characters working.  So this operator favours
-        usefulness over formal correctness.  For Python 3, there is no
-        distinction between Unicode and string objects anyway.
+        .. versionadded:: 0.21.0
         """
-        joinattrs = ( set(self.order.keys()) |
-                      set(self.conditions.keys()) |
-                      set(self.attributes) )
-        subst = self._makesubst(joinattrs)
+        subst = self._get_subst()
         if self.attributes:
             attrs = []
             for a in self.attributes:
@@ -528,40 +519,115 @@ def __str__(self):
             else:
                 for fct in reversed(self.aggregate.split(':')):
                     res = "%s(%s)" % (fct, res)
-        base = "SELECT %s FROM %s o" % (res, self.entity.BeanName)
-        joins = ""
+        return "SELECT %s FROM %s o" % (res, self.entity.BeanName)
+
+    @property
+    def join_clause(self):
+        """The JOIN clause of the query.
+
+        .. versionadded:: 0.21.0
+        """
+        subst = self._get_subst()
+        joins = []
         for obj in sorted(subst.keys()):
             js = self.join_specs.get(obj, "JOIN")
-            joins += " %s %s" % (js, self._dosubst(obj, subst))
+            joins.append("%s %s" % (js, self._dosubst(obj, subst)))
+        if joins:
+            return " ".join(joins)
+        else:
+            return None
+
+    @property
+    def where_clause(self):
+        """The WHERE clause of the query.
+
+        .. versionadded:: 0.21.0
+        """
+        subst = self._get_subst()
         if self.conditions:
             conds = []
             for a in sorted(self.conditions.keys()):
                 attr = self._dosubst(a, subst, False)
                 for c in self.conditions[a]:
                     conds.append(c % attr)
-            where = " WHERE " + " AND ".join(conds)
+            return "WHERE " + " AND ".join(conds)
         else:
-            where = ""
+            return None
+
+    @property
+    def order_clause(self):
+        """The ORDER BY clause of the query.
+
+        .. versionadded:: 0.21.0
+        """
+        subst = self._get_subst()
         if self.order:
             orders = []
             for a in self.order.keys():
                 orders.append(self.order[a] % self._dosubst(a, subst, False))
-            order = " ORDER BY " + ", ".join(orders)
+            return "ORDER BY " + ", ".join(orders)
         else:
-            order = ""
+            return None
+
+    @property
+    def include_clause(self):
+        """The INCLUDE clause of the query.
+
+        .. versionadded:: 0.21.0
+        """
         if self.includes:
             subst = self._makesubst(self.includes)
             includes = set(self.includes)
             includes.update(subst.keys())
             incl = [ self._dosubst(obj, subst) for obj in sorted(includes) ]
-            include = " INCLUDE " + ", ".join(incl)
+            return "INCLUDE " + ", ".join(incl)
         else:
-            include = ""
+            return None
+
+    @property
+    def limit_clause(self):
+        """The LIMIT clause of the query.
+
+        .. versionadded:: 0.21.0
+        """
         if self.limit:
-            limit = " LIMIT %s, %s" % self.limit
+            return "LIMIT %s, %s" % self.limit
         else:
-            limit = ""
-        return base + joins + where + order + include + limit
+            return None
+
+    def __repr__(self):
+        """Return a formal representation of the query.
+        """
+        return ("%s(%s, %s, attributes=%s, aggregate=%s, order=%s, "
+                "conditions=%s, includes=%s, limit=%s, join_specs=%s)"
+                % (self.__class__.__name__,
+                   repr(self.client), repr(self.entity.BeanName),
+                   repr(self.attributes), repr(self.aggregate),
+                   repr(self.order), repr(self.conditions),
+                   repr(self.includes), repr(self.limit),
+                   repr(self.join_specs)))
+
+    def __str__(self):
+        """Return a string representation of the query.
+
+        Note for Python 2: the result will be an unicode object if any
+        of the conditions in the query contains unicode.  This
+        violates the specification of the string representation
+        operator that requires the return value to be a string object.
+        But it is the *right thing* to do to get queries with
+        non-ascii characters working.  So this operator favours
+        usefulness over formal correctness.  For Python 3, there is no
+        distinction between Unicode and string objects anyway.
+        """
+        clauses = filter(None, (
+            self.select_clause,
+            self.join_clause,
+            self.where_clause,
+            self.order_clause,
+            self.include_clause,
+            self.limit_clause,
+        ))
+        return " ".join(clauses)
 
     def copy(self):
         """Return an independent clone of this query.