Very simple exception handling + some doc fixes

Author: honzakral

elasticsearch_dsl/exceptions.py

@@ -0,0 +1,6 @@
+class ElasticsearchDslException(Exception):
+    pass
+
+
+class UnknownDslObject(ElasticsearchDslException):
+    pass

elasticsearch_dsl/filter.py

@@ -9,16 +9,17 @@ def F(name_or_filter, **params):
     # {"term": {...}}
     if isinstance(name_or_filter, dict):
         if params:
-            raise #XXX
+            raise ValueError('F() cannot accept parameters when passing in a dict.')
         if len(name_or_filter) != 1:
-            raise #XXX
+            raise ValueError('F() can only accept dict with a single filter ({"bool": {...}}). '
+                 'Instead it got (%r)' % name_or_filter)
         name, params = name_or_filter.copy().popitem()
         return Filter.get_dsl_class(name)(**params)
 
     # Term(...)
     if isinstance(name_or_filter, Filter):
         if params:
-            raise #XXX
+            raise ValueError('F() cannot accept parameters when passing in a Filter object.')
         return name_or_filter
 
     # 'term', tag='python', ...

elasticsearch_dsl/query.py

@@ -10,16 +10,17 @@ def Q(name_or_query, **params):
     # {"match": {"title": "python"}}
     if isinstance(name_or_query, dict):
         if params:
-            raise #XXX
+            raise ValueError('Q() cannot accept parameters when passing in a dict.')
         if len(name_or_query) != 1:
-            raise #XXX
+            raise ValueError('Q() can only accept dict with a single query ({"match": {...}}). '
+                 'Instead it got (%r)' % name_or_query)
         name, params = name_or_query.copy().popitem()
         return Query.get_dsl_class(name)(**params)
 
     # MatchAll()
     if isinstance(name_or_query, Query):
         if params:
-            raise #XXX
+            raise ValueError('Q() cannot accept parameters when passing in a Query object.')
         return name_or_query
 
     # "match", title="python"

elasticsearch_dsl/search.py

@@ -104,7 +104,7 @@ def __getitem__(self, n):
         if isinstance(n, slice):
             # If negative slicing, abort.
             if n.start and n.start < 0 or n.stop and n.stop < 0:
-                raise #XXX
+                raise ValueError("Search does not support negative slicing.")
             # Elasticsearch won't get all results so we default to size: 10 if
             # stop not given.
             s._extra['from'] = n.start or 0
@@ -113,7 +113,7 @@ def __getitem__(self, n):
         else:  # This is an index lookup, equivalent to slicing by [n:n+1].
             # If negative index, abort.
             if n < 0:
-                raise #XXX
+                raise ValueError("Search does not support negative indexing.")
             s._extra['from'] = n
             s._extra['size'] = 1
             return s
@@ -249,12 +249,15 @@ def doc_type(self, *doc_type):
             s._doc_type = (self._doc_type or []) + list(doc_type)
         return s
 
-    def to_dict(self, count=False):
+    def to_dict(self, count=False, **kwargs):
         """
-        Serialize the search into the dictionary that will be sent over as the request's body.
+        Serialize the search into the dictionary that will be sent over as the
+        request's body.
 
         :arg count: a flag to specify we are interested in a body for count -
             no aggregations, no pagination bounds etc.
+
+        All additional keyword arguments will be included into the dictionary.
         """
         if self.filter:
             d = {
@@ -279,6 +282,7 @@ def to_dict(self, count=False):
 
         if not count:
             d.update(self._extra)
+        d.update(kwargs)
         return d
 
     def using(self, client):

elasticsearch_dsl/utils.py

@@ -2,6 +2,8 @@
 
 from six import iteritems
 
+from .exceptions import UnknownDslObject
+
 def _wrap(val):
     if isinstance(val, dict):
         return AttrDict(val)
@@ -55,7 +57,8 @@ def __getattr__(self, attr_name):
         try:
             return _wrap(self._d_[attr_name])
         except KeyError:
-            raise AttributeError()
+            raise AttributeError(
+                '%r object has no attribute %r' % (self.__class__.__name__, attr_name))
 
     def __getitem__(self, key):
         # don't wrap things whe accessing via __getitem__ for consistency
@@ -143,7 +146,8 @@ def _setattr(self, name, value):
 
     def __getattr__(self, name):
         if name.startswith('_'):
-            raise AttributeError()
+            raise AttributeError(
+                '%r object has no attribute %r' % (self.__class__.__name__, name))
 
         value = None
         try:
@@ -158,7 +162,8 @@ def __getattr__(self, name):
                 elif pinfo.get('hash'):
                     value = self._params.setdefault(name, {})
         if value is None:
-            raise AttributeError()
+            raise AttributeError(
+                '%r object has no attribute %r' % (self.__class__.__name__, name))
 
         # wrap nested dicts in AttrDict for convenient access
         if isinstance(value, dict):
@@ -257,14 +262,14 @@ def get_dsl_type(cls, name):
         try:
             return cls._types[name]
         except KeyError:
-            raise #XXX
+            raise UnknownDslObject('DSL type %s does not exist.' % name)
 
     @classmethod
     def get_dsl_class(cls, name):
         try:
             return cls._classes[name]
         except KeyError:
-            raise #XXX
+            raise UnknownDslObject('DSL class %s does not exist in %s.' % (name, self._type_name))
 
 
 class BoolMixin(object):