Define protocols for connection type overrides

Author: Mark Edwards

Diff for: pyproject.toml

@@ -31,6 +31,7 @@ packages = [
 [tool.poetry.dependencies]
 python = "^3.6"
 graphql-core = "^3.0"
+typing-extensions = { version = "^3.6.2", python = "<3.8" }
 
 [tool.poetry.dev-dependencies]
 pytest = "^5.3"

Diff for: setup.py

@@ -29,7 +29,10 @@
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: Implementation :: PyPy",
     ],
-    install_requires=["graphql-core>=3.0.0"],
+    install_requires=[
+        "graphql-core>=3.0.0",
+        "typing-extensions>=3.6.2,<4; python_version < '3.8'",
+    ],
     python_requires=">=3.6,<4",
     packages=find_packages("src"),
     package_dir={"": "src"},

Diff for: src/graphql_relay/connection/arrayconnection.py

@@ -6,9 +6,13 @@
 from .connectiontypes import (
     Connection,
     ConnectionArguments,
+    ConnectionConstructor,
     ConnectionCursor,
+    ConnectionType,
     Edge,
+    EdgeConstructor,
     PageInfo,
+    PageInfoConstructor,
 )
 
 __all__ = [
@@ -24,10 +28,10 @@
 def connection_from_array(
     data: Sequence,
     args: ConnectionArguments = None,
-    connection_type: Any = Connection,
-    edge_type: Any = Edge,
-    page_info_type: Any = PageInfo,
-) -> Connection:
+    connection_type: ConnectionConstructor = Connection,
+    edge_type: EdgeConstructor = Edge,
+    page_info_type: PageInfoConstructor = PageInfo,
+) -> ConnectionType:
     """Create a connection object from a sequence of objects.
 
     Note that different from its JavaScript counterpart which expects an array,
@@ -54,10 +58,10 @@ def connection_from_array(
 def connection_from_list(
     data: Sequence,
     args: ConnectionArguments = None,
-    connection_type: Any = Connection,
-    edge_type: Any = Edge,
-    pageinfo_type: Any = PageInfo,
-) -> Connection:
+    connection_type: ConnectionConstructor = Connection,
+    edge_type: EdgeConstructor = Edge,
+    pageinfo_type: PageInfoConstructor = PageInfo,
+) -> ConnectionType:
     """Deprecated alias for connection_from_array.
 
     We're now using the JavaScript terminology in Python as well, since list
@@ -84,10 +88,10 @@ def connection_from_array_slice(
     slice_start: int = 0,
     array_length: int = None,
     array_slice_length: int = None,
-    connection_type: Any = Connection,
-    edge_type: Any = Edge,
-    page_info_type: Any = PageInfo,
-) -> Connection:
+    connection_type: ConnectionConstructor = Connection,
+    edge_type: EdgeConstructor = Edge,
+    page_info_type: PageInfoConstructor = PageInfo,
+) -> ConnectionType:
     """Create a connection object from a slice of the result set.
 
     Note that different from its JavaScript counterpart which expects an array,
@@ -162,13 +166,13 @@ def connection_from_array_slice(
 def connection_from_list_slice(
     list_slice: Sequence,
     args: ConnectionArguments = None,
-    connection_type: Any = Connection,
-    edge_type: Any = Edge,
-    pageinfo_type: Any = PageInfo,
+    connection_type: ConnectionConstructor = Connection,
+    edge_type: EdgeConstructor = Edge,
+    pageinfo_type: PageInfoConstructor = PageInfo,
     slice_start=0,
     list_length=0,
     list_slice_length=None,
-) -> Connection:
+) -> ConnectionType:
     """Deprecated alias for connection_from_array_slice.
 
     We're now using the JavaScript terminology in Python as well, since list

Diff for: src/graphql_relay/connection/connectiontypes.py

@@ -1,4 +1,8 @@
 from typing import Any, Dict, List, NamedTuple, Optional
+try:
+    from typing import Protocol
+except ImportError:
+    from typing_extensions import Protocol  # type: ignore
 
 __all__ = ["Connection", "ConnectionArguments", "ConnectionCursor", "Edge", "PageInfo"]
 
@@ -7,6 +11,25 @@
 ConnectionCursor = str
 
 
+class PageInfoType(Protocol):
+    @property
+    def startCursor(self) -> Optional[ConnectionCursor]: ...
+    def endCursor(self) -> Optional[ConnectionCursor]: ...
+    def hasPreviousPage(self) -> Optional[bool]: ...
+    def hasNextPage(self) -> Optional[bool]: ...
+
+
+class PageInfoConstructor(Protocol):
+    def __call__(
+        self,
+        *,
+        startCursor: Optional[ConnectionCursor],
+        endCursor: Optional[ConnectionCursor],
+        hasPreviousPage: Optional[bool],
+        hasNextPage: Optional[bool],
+    ) -> PageInfoType: ...
+
+
 class PageInfo(NamedTuple):
     """A type designed to be exposed as `PageInfo` over GraphQL."""
 
@@ -16,13 +39,40 @@ class PageInfo(NamedTuple):
     hasNextPage: Optional[bool]
 
 
+class EdgeType(Protocol):
+    @property
+    def node(self) -> Any: ...
+    @property
+    def cursor(self) -> ConnectionCursor: ...
+
+
+class EdgeConstructor(Protocol):
+    def __call__(self, *, node: Any, cursor: ConnectionCursor) -> EdgeType: ...
+
+
 class Edge(NamedTuple):
     """A type designed to be exposed as a `Edge` over GraphQL."""
 
     node: Any
     cursor: ConnectionCursor
 
 
+class ConnectionType(Protocol):
+    @property
+    def edges(self): List[EdgeType]: ...
+    @property
+    def pageInfo(self): PageInfoType: ...
+
+
+class ConnectionConstructor(Protocol):
+    def __call__(
+        self,
+        *,
+        edges: List[EdgeType],
+        pageInfo: PageInfoType,
+    ) -> ConnectionType: ...
+
+
 class Connection(NamedTuple):
     """A type designed to be exposed as a `Connection` over GraphQL."""