Fix docstrings and imports.

graphql_compiler/compiler/blocks.py

@@ -407,9 +407,16 @@ def __init__(self):
         self.validate()
 
     def validate(self):
-        """OutputSource blocks are always valid in isolation."""
+        """Ensure that the OutputSource block is valid.
+
+        OutputSource blocks are always valid in isolation.
+        """
         pass
 
     def to_gremlin(self):
-        """OutputSource blocks have no explicit Gremlin representation."""
+        """Return the unicode representation of this BasicBlock.
+
+        The correct Gremlin representation of OutputSource blocks is an empty string.
+        Their effect is applied during code generation and optimization passes.
+        """
         return u''

graphql_compiler/compiler/emit_match.py

@@ -6,7 +6,7 @@
 
 
 def _get_vertex_location_name(location):
-    """Helper to get the location name from a location that is expected to point to a vertex."""
+    """Get the location name from a location that is expected to point to a vertex."""
     mark_name, field_name = location.get_location_name()
     if field_name is not None:
         raise AssertionError(u'Location unexpectedly pointed to a field: {}'.format(location))

graphql_compiler/compiler/filters.py

@@ -13,11 +13,11 @@
 def scalar_leaf_only(operator):
     """Ensure the filter function is only applied to scalar leaf types."""
     def decorator(f):
-        """Decorator function applied to the inner function "f"."""
+        """Decorate the supplied function with the "scalar_leaf_only" logic."""
         @wraps(f)
         def wrapper(schema, current_schema_type, ast, context,
                     directive, parameters, *args, **kwargs):
-            """Wrapper function for the decorator."""
+            """Check that the type on which the operator operates is a scalar leaf type."""
             if 'operator' in kwargs:
                 current_operator = kwargs['operator']
             else:
@@ -38,11 +38,11 @@ def wrapper(schema, current_schema_type, ast, context,
 def takes_parameters(count):
     """Ensure the filter function has "count" parameters specified."""
     def decorator(f):
-        """Decorator function applied to the inner function "f"."""
+        """Decorate the supplied function with the "takes_parameters" logic."""
         @wraps(f)
         def wrapper(schema, current_schema_type, ast, context,
                     directive, parameters, *args, **kwargs):
-            """Wrapper function for the decorator."""
+            """Check that the supplied number of parameters equals the expected number."""
             if len(parameters) != count:
                 raise GraphQLCompilationError(u'Incorrect number of parameters, expected {} got '
                                               u'{}: {}'.format(count, len(parameters), parameters))

graphql_compiler/compiler/helpers.py

@@ -87,7 +87,7 @@ def get_uniquely_named_objects_by_name(object_list):
 
 
 def safe_quoted_string(value):
-    """Return the provided string, surrounded by single quotes. Unsafe strings cause exceptions!"""
+    """Return the provided string, surrounded by single quotes. Unsafe strings cause exceptions."""
     validate_safe_string(value)
     return u'\'{}\''.format(value)
 

graphql_compiler/compiler/ir_lowering_common.py

@@ -6,7 +6,7 @@
 from .blocks import (Backtrack, CoerceType, ConstructResult, Filter, MarkLocation, OutputSource,
                      QueryRoot, Recurse, Traverse)
 from .expressions import (BinaryComposition, ContextField, ContextFieldExistence, FalseLiteral,
-                          Literal, NullLiteral, TrueLiteral)
+                          NullLiteral, TrueLiteral)
 from .helpers import validate_safe_string
 
 

graphql_compiler/schema.py

@@ -187,7 +187,7 @@
 
 
 def _unused_function(*args, **kwargs):
-    """Function placeholder for functions that are required but aren't used."""
+    """Must not be called. Placeholder for functions that are required but aren't used."""
     raise NotImplementedError(u'The function you tried to call is not implemented, args / kwargs: '
                               u'{} {}'.format(args, kwargs))