Add Database.create_query() as a shorthand for db=Database();q=Query(db,"")

This is a convenience extension to the C API. I hardly saves any typing, but
let's us automatically free the top-level Database() object when we delete
the Query().

2 files changed, 23 insertions, 0 deletions

diff --git a/cnotmuch/database.py b/cnotmuch/database.py
index cad73c69..c815e440 100644
--- a/cnotmuch/database.py
+++ b/cnotmuch/database.py
@@ -293,6 +293,28 @@ class Database(object):
             raise NotmuchError(STATUS.NULL_POINTER)
         return Tags(tags_p, self)
 
+    def create_query(self, querystring):
+        """Returns a :class:`Query` derived from this database
+
+        This is a shorthand method for doing::
+          # short version
+          # Automatically frees the Database() when 'q' is deleted
+
+          q  = Database(dbpath).create_query('from:"Biene Maja"')
+
+          # long version, which is functionally equivalent but will keep the
+          # Database in the 'db' variable around after we delete 'q':
+
+          db = Database(dbpath)
+          q  = Query(db,'from:"Biene Maja"')
+
+        This function is a python extension and not in the underlying C API.
+        """
+        # Raise a NotmuchError if not initialized
+        self._verify_initialized_db()
+
+        return Query(self._db, querystring)
+
     def __repr__(self):
         return "'Notmuch DB " + self.get_path() + "'"
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6d0d5fa3..e04bc843 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -61,6 +61,7 @@ or::
 
    .. automethod:: get_all_tags
 
+   .. automethod:: create_query
 
    .. attribute:: Database.MODE