extra docs and typing info

docs/coding/predicates.rst

@@ -2,10 +2,10 @@
 Predicates
 ==========
 
-Predicates are functions that take something and return a boolean about truthfulness
-of given statement. Satella contains a bunch of functions to produce these predicates.
+By a predicate Satella understands a function of a single argument and a single return values.
+Satella's API drastically simplifies writing lambda.
 
-Satella lets you express predicates in a Pythonic way, eg:
+Satella lets you express lambdas in a Pythonic way, eg:
 
     ::
 
@@ -23,7 +23,6 @@ which due to Python limitations (namely __len__ being allowed to return an int o
 via it's method .length(), eg:
 
 
-
     ::
 
         p = x.length() == 2
@@ -72,6 +71,7 @@ Or check whether an instance is of provided type
         p = x.instanceof(int)
         assert p(2)
 
+
 Only take care for x to be the first argument in all operators you use. For example,
 don't do this:
 
@@ -79,3 +79,5 @@ don't do this:
 
         p = 2 < x < 6
 
+
+Because Python will compare first 2 with x using int's __gt__, which will fail.

satella/coding/predicates.py

@@ -44,29 +44,29 @@ class Predicate:
     def __call__(self, v):
         return self.operation(v)
 
-    def has_keys(self, *keys):
+    def has_keys(self, *keys) -> 'Predicate':
         """
         Return a predicate checking whether this value has provided keys
         """
         return make_operation_two_args(_has_keys)(self, keys)
 
-    def one_of(self, *values):
+    def one_of(self, *values) -> 'Predicate':
         """
         Return a predicate checking if x is amongst values
         """
         return make_operation_two_args(_one_of)(self, values)
 
-    def inside(self, value):
+    def inside(self, value: tp.Container) -> 'Predicate':
         """
         Return a predicate checking if x is inside value
         """
         return make_operation_two_args(operator.contains)(self, value)
 
-    def instanceof(self, instance):
+    def instanceof(self, class_descriptor) -> 'Predicate':
         """
         Return a predicate checking whether this value is an instance of instance
         """
-        return make_operation_two_args(isinstance)(self, instance)
+        return make_operation_two_args(isinstance)(self, class_descriptor)
 
     length = make_operation_single_arg(len)
 
@@ -88,10 +88,6 @@ class Predicate:
     __neg__ = make_operation_single_arg(lambda y: -y)
     __invert__ = make_operation_single_arg(operator.invert)
     __abs__ = make_operation_single_arg(abs)
-    __int__ = make_operation_single_arg(int)
-    __float__ = make_operation_single_arg(float)
-    __complex__ = make_operation_single_arg(complex)
-    __str__ = make_operation_single_arg(str)
     __truediv__ = make_operation_two_args(operator.__truediv__)
     __floordiv__ = make_operation_two_args(operator.floordiv)
     __mod__ = make_operation_two_args(operator.mod)