Bring connection subpackage up to date

Author: Cito

src/graphql_relay/__init__.py

@@ -1,16 +1,19 @@
 from .version import version, version_info, version_js, version_info_js
-from .connection.connection import connection_args, connection_definitions
+from .connection.connectiontypes import (
+    Connection, ConnectionArguments, ConnectionCursor, Edge, PageInfo
+)
+from .connection.connection import (
+    backward_connection_args, connection_args, connection_definitions,
+    forward_connection_args, GraphQLConnectionDefinitions)
 from .connection.arrayconnection import (
-    connection_from_list,
-    connection_from_list_slice,
-    cursor_for_object_in_connection)
+    connection_from_array, connection_from_array_slice,
+    cursor_for_object_in_connection,
+    cursor_to_offset, get_offset_with_default, offset_to_cursor)
+from .mutation.mutation import mutation_with_client_mutation_id
 from .node.node import (
     node_definitions,
-    from_global_id,
-    to_global_id,
-    global_id_field)
+    from_global_id, global_id_field, to_global_id)
 from .node.plural import plural_identifying_root_field
-from .mutation.mutation import mutation_with_client_mutation_id
 
 __version__ = version
 __version_info__ = version_info
@@ -20,17 +23,21 @@
 __all__ = [
     # The graphql-relay and graphql-relay-js version info
     'version', 'version_info', 'version_js', 'version_info_js',
+    # Types for creating connection types in the schema
+    'Connection', 'ConnectionArguments', 'ConnectionCursor', 'Edge', 'PageInfo',
     # Helpers for creating connection types in the schema
-    'connection_args', 'connection_definitions',
+    'backward_connection_args', 'connection_args', 'connection_definitions',
+    'forward_connection_args', 'GraphQLConnectionDefinitions',
     # Helpers for creating connections from arrays
-    'connection_from_list', 'connection_from_list_slice',
-    'cursor_for_object_in_connection',
-    # Helper for creating node definitions
-    'node_definitions',
-    # Utilities for creating global IDs in systems that don't have them
-    'from_global_id', 'to_global_id', 'global_id_field',
+    'connection_from_array', 'connection_from_array_slice',
+    'cursor_for_object_in_connection', 'cursor_to_offset',
+    'get_offset_with_default', 'offset_to_cursor',
     # Helper for creating mutations with client mutation IDs
     'mutation_with_client_mutation_id',
+    # Helper for creating node definitions
+    'node_definitions',
     #  Helper for creating plural identifying root fields
-    'plural_identifying_root_field'
+    'plural_identifying_root_field',
+    # Utilities for creating global IDs in systems that don't have them
+    'from_global_id', 'global_id_field', 'to_global_id',
 ]

src/graphql_relay/connection/arrayconnection.py

@@ -1,150 +1,138 @@
 import binascii
+from typing import Any, Collection, Optional, TypeVar
 
 from ..utils.base64 import base64, unbase64
-from .connectiontypes import Connection, PageInfo, Edge
+from .connectiontypes import (
+    Connection, ConnectionArguments, ConnectionCursor, Edge, PageInfo)
 
+__all__ = [
+    'connection_from_array', 'connection_from_array_slice',
+    'cursor_for_object_in_connection', 'cursor_to_offset',
+    'get_offset_with_default', 'offset_to_cursor'
+]
 
-def connection_from_list(
-        data, args=None,
-        connection_type=None, edge_type=None, pageinfo_type=None):
-    """
-    A simple function that accepts an array and connection arguments, and returns
-    a connection object for use in GraphQL. It uses array offsets as pagination,
-    so pagination will only work if the array is static.
+T = TypeVar('T')
+
+
+def connection_from_array(
+        data: Collection, args: ConnectionArguments) -> Connection:
+    """Create a connection argument from a collection.
+
+    A simple function that accepts a collection (e.g. a Python list) and connection
+    arguments, and returns a connection object for use in GraphQL. It uses array
+    offsets as pagination, so pagination will only work if the array is static.
     """
-    _len = len(data)
-    return connection_from_list_slice(
-        data,
-        args,
-        connection_type=connection_type,
-        edge_type=edge_type,
-        pageinfo_type=pageinfo_type,
+    return connection_from_array_slice(
+        data, args,
         slice_start=0,
-        list_length=_len,
-        list_slice_length=_len,
+        array_length=len(data),
     )
 
 
-def connection_from_list_slice(
-        list_slice, args=None,
-        connection_type=None, edge_type=None, pageinfo_type=None,
-        slice_start=0, list_length=0, list_slice_length=None):
-    """
-    Given a slice (subset) of an array, returns a connection object for use in
-    GraphQL.
-    This function is similar to `connectionFromArray`, but is intended for use
+def connection_from_array_slice(
+        array_slice: Collection, args: ConnectionArguments,
+        slice_start: int, array_length: int
+        ) -> Connection:
+    """Given a slice of a collection, returns a connection object for use in GraphQL.
+
+    This function is similar to `connection_from_array`, but is intended for use
     cases where you know the cardinality of the connection, consider it too large
-    to materialize the entire array, and instead wish pass in a slice of the
+    to materialize the entire collection, and instead wish pass in a slice of the
     total result large enough to cover the range specified in `args`.
     """
-    connection_type = connection_type or Connection
-    edge_type = edge_type or Edge
-    pageinfo_type = pageinfo_type or PageInfo
-
-    args = args or {}
-
     before = args.get('before')
     after = args.get('after')
     first = args.get('first')
     last = args.get('last')
-    if list_slice_length is None:
-        list_slice_length = len(list_slice)
-    slice_end = slice_start + list_slice_length
-    before_offset = get_offset_with_default(before, list_length)
+    slice_end = slice_start + len(array_slice)
+    before_offset = get_offset_with_default(before, array_length)
     after_offset = get_offset_with_default(after, -1)
 
-    start_offset = max(
-        slice_start - 1,
-        after_offset,
-        -1
-    ) + 1
-    end_offset = min(
-        slice_end,
-        before_offset,
-        list_length
-    )
+    start_offset = max(slice_start - 1, after_offset, -1) + 1
+    end_offset = min(slice_end, before_offset, array_length)
+
     if isinstance(first, int):
-        end_offset = min(
-            end_offset,
-            start_offset + first
-        )
+        if first < 0:
+            raise ValueError("Argument 'first' must be a non-negative integer.")
+
+        end_offset = min(end_offset, start_offset + first)
     if isinstance(last, int):
-        start_offset = max(
-            start_offset,
-            end_offset - last
-        )
+        if last < 0:
+            raise ValueError("Argument 'last' must be a non-negative integer.")
+
+        start_offset = max(start_offset, end_offset - last)
 
     # If supplied slice is too large, trim it down before mapping over it.
-    _slice = list_slice[
+    trimmed_slice = array_slice[
         max(start_offset - slice_start, 0):
-        list_slice_length - (slice_end - end_offset)
+        len(array_slice) - (slice_end - end_offset)
     ]
+
     edges = [
-        edge_type(
-            node=node,
-            cursor=offset_to_cursor(start_offset + i)
+        Edge(
+            node=value,
+            cursor=offset_to_cursor(start_offset + index)
         )
-        for i, node in enumerate(_slice)
+        for index, value in enumerate(trimmed_slice)
     ]
 
     first_edge_cursor = edges[0].cursor if edges else None
     last_edge_cursor = edges[-1].cursor if edges else None
     lower_bound = after_offset + 1 if after else 0
-    upper_bound = before_offset if before else list_length
+    upper_bound = before_offset if before else array_length
 
-    return connection_type(
+    return Connection(
         edges=edges,
-        page_info=pageinfo_type(
-            start_cursor=first_edge_cursor,
-            end_cursor=last_edge_cursor,
-            has_previous_page=isinstance(last, int) and start_offset > lower_bound,
-            has_next_page=isinstance(first, int) and end_offset < upper_bound
+        pageInfo=PageInfo(
+            startCursor=first_edge_cursor,
+            endCursor=last_edge_cursor,
+            hasPreviousPage=isinstance(last, int) and start_offset > lower_bound,
+            hasNextPage=isinstance(first, int) and end_offset < upper_bound
         )
     )
 
 
 PREFIX = 'arrayconnection:'
 
 
-def offset_to_cursor(offset):
-    """
-    Creates the cursor string from an offset.
-    """
-    return base64(PREFIX + str(offset))
+def offset_to_cursor(offset: int) -> ConnectionCursor:
+    """Create the cursor string from an offset."""
+    return base64(f"{PREFIX}{offset}")
 
 
-def cursor_to_offset(cursor):
-    """
-    Rederives the offset from the cursor string.
-    """
+def cursor_to_offset(cursor: ConnectionCursor) -> Optional[int]:
+    """Rederive the offset from the cursor string."""
     try:
         return int(unbase64(cursor)[len(PREFIX):])
     except binascii.Error:
         return None
 
 
-def cursor_for_object_in_connection(data, _object):
-    """
-    Return the cursor associated with an object in an array.
-    """
-    if _object not in data:
+def cursor_for_object_in_connection(data: Collection, obj: T) -> Optional[Any]:
+    """Return the cursor associated with an object in a collection."""
+    try:
+        # noinspection PyUnresolvedReferences
+        offset = data.index(obj)  # type: ignore
+    except AttributeError:  # collection does not have an index method
+        for offset, value in data:
+            if value == obj:
+                return offset
+        return None
+    except ValueError:
         return None
+    else:
+        return offset_to_cursor(offset)
 
-    offset = data.index(_object)
-    return offset_to_cursor(offset)
 
+def get_offset_with_default(cursor: ConnectionCursor = None, default_offset=0) -> int:
+    """Get offset from a given cursor and a default.
 
-def get_offset_with_default(cursor=None, default_offset=0):
-    """
-    Given an optional cursor and a default offset, returns the offset
-    to use; if the cursor contains a valid offset, that will be used,
+    Given an optional cursor and a default offset, return the offset to use;
+    if the cursor contains a valid offset, that will be used,
     otherwise it will be the default.
     """
     if not isinstance(cursor, str):
         return default_offset
 
     offset = cursor_to_offset(cursor)
-    try:
-        return int(offset)
-    except (TypeError, ValueError):
-        return default_offset
+    return default_offset if offset is None else offset

src/graphql_relay/connection/connection.py

@@ -1,9 +1,12 @@
-from typing import Any
+from typing import Any, NamedTuple
 
 from graphql.type import (
     GraphQLArgument,
+    GraphQLArgumentMap,
     GraphQLBoolean,
     GraphQLField,
+    GraphQLFieldMap,
+    GraphQLFieldResolver,
     GraphQLInt,
     GraphQLList,
     GraphQLNonNull,
@@ -12,24 +15,59 @@
     Thunk
 )
 
-connection_args = {
-    'before': GraphQLArgument(GraphQLString),
+__all__ = [
+    'connection_definitions',
+    'forward_connection_args', 'backward_connection_args', 'connection_args',
+    'GraphQLConnectionDefinitions'
+]
+
+
+# Returns a GraphQLArgumentMap appropriate to include on a field
+# whose return type is a connection type with forward pagination.
+forward_connection_args: GraphQLArgumentMap = {
     'after': GraphQLArgument(GraphQLString),
     'first': GraphQLArgument(GraphQLInt),
+}
+
+# Returns a GraphQLArgumentMap appropriate to include on a field
+# whose return type is a connection type with backward pagination.
+backward_connection_args: GraphQLArgumentMap = {
+    'before': GraphQLArgument(GraphQLString),
     'last': GraphQLArgument(GraphQLInt),
 }
 
+# Returns a GraphQLArgumentMap appropriate to include on a field
+# whose return type is a connection type with bidirectional pagination.
+connection_args = {
+    **forward_connection_args, **backward_connection_args
+}
+
+
+class GraphQLConnectionDefinitions(NamedTuple):
+    edge_type: GraphQLObjectType
+    connection_type: GraphQLObjectType
+
 
 def resolve_maybe_thunk(thing_or_thunk: Thunk) -> Any:
     return thing_or_thunk() if callable(thing_or_thunk) else thing_or_thunk
 
 
 def connection_definitions(
-        name, node_type,
-        resolve_node=None, resolve_cursor=None,
-        edge_fields=None, connection_fields=None):
+        node_type: GraphQLObjectType,
+        name: str = None,
+        resolve_node: GraphQLFieldResolver = None,
+        resolve_cursor: GraphQLFieldResolver = None,
+        edge_fields: Thunk[GraphQLFieldMap] = None,
+        connection_fields: Thunk[GraphQLFieldMap] = None
+        ) -> GraphQLConnectionDefinitions:
+    """Return GraphQLObjectTypes for a connection with the given name.
+
+    The nodes of the returned object types will be of the specified type.
+    """
+    name = name or node_type.name
     edge_fields = edge_fields or {}
     connection_fields = connection_fields or {}
+
     edge_type = GraphQLObjectType(
         name + 'Edge',
         description='An edge in a connection.',
@@ -60,7 +98,7 @@ def connection_definitions(
             ),
             **resolve_maybe_thunk(connection_fields)})
 
-    return edge_type, connection_type
+    return GraphQLConnectionDefinitions(edge_type, connection_type)
 
 
 # The common page info type used by all connections.