Merge pull request graphql-python#54 from graphql-python/releases/0.5.0

Version 0.5.0 reached! Compatible with GraphQL April 2016 spec 😎
JoaRiski · May 4, 2016 · bff187a · bff187a
2 parents 8ea043a + f2175f5
commit bff187a
Show file tree

Hide file tree

Showing 190 changed files with 6,128 additions and 4,306 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -8,18 +8,18 @@ python:
 - pypy
 cache: pip
 install:
-- pip install --cache-dir $HOME/.cache/pip pytest-cov coveralls flake8 import-order gevent==1.1b5 six>=1.10.0
+- pip install --cache-dir $HOME/.cache/pip pytest-cov pytest-mock coveralls flake8 isort==3.9.6 gevent==1.1b5 six>=1.10.0 pypromise>=0.4.0
 - pip install --cache-dir $HOME/.cache/pip pytest>=2.7.3 --upgrade
 - pip install -e .
 script:
 - flake8
-- py.test --cov=graphql tests
+- py.test --cov=graphql graphql tests
 after_success:
 - coveralls
 matrix:
   include:
     - python: "3.5"
       script:
         - flake8
-        - import-order graphql
-        - py.test --cov=graphql tests tests_py35
+        - isort --check-only graphql/ -rc
+        - py.test --cov=graphql graphql tests tests_py35
diff --git a/README.md b/README.md
@@ -1,20 +1,19 @@
 # GraphQL-core
 
-GraphQL for Python
+GraphQL for Python.
+
+*This library is a port of [graphql-js](https://github.com/graphql/graphql-js) to Python.*
+
 
 [![PyPI version](https://badge.fury.io/py/graphql-core.svg)](https://badge.fury.io/py/graphql-core)
 [![Build Status](https://travis-ci.org/graphql-python/graphql-core.svg?branch=master)](https://travis-ci.org/graphql-python/graphql-core)
 [![Coverage Status](https://coveralls.io/repos/graphql-python/graphql-core/badge.svg?branch=master&service=github)](https://coveralls.io/github/graphql-python/graphql-core?branch=master)
 [![Public Slack Discussion](https://graphql-slack.herokuapp.com/badge.svg)](https://graphql-slack.herokuapp.com/)
 
+See more complete documentation at http://graphql.org/ and
+http://graphql.org/docs/api-reference-graphql/.
 
-## Project Status
-
-This library is a port of [graphql-js](https://github.com/graphql/graphql-js) to Python.
-
-We are currently targeting feature parity with `v0.4.18` of the reference implementation, and are currently on `v0.5.0`.
-
-Please see [issues](https://github.com/graphql-python/graphql-core/issues) for the progress.
+For questions, ask [Stack Overflow](http://stackoverflow.com/questions/tagged/graphql).
 
 ## Getting Started
 
@@ -25,31 +24,99 @@ The overview describes a simple set of GraphQL examples that exist as [tests](te
 in this repository. A good way to get started is to walk through that README and the corresponding tests
 in parallel. 
 
-### Using `graphql-core`
+### Using graphql-core
 
 Install from pip:
 
 ```sh
 pip install graphql-core
 ```
 
-### Supported Python Versions
-`graphql-core` supports the following Python versions:
-
-* `2.7.x`
-* `3.3.x`
-* `3.4.x`
-* `3.5.0`
-* `pypy-2.6.1`
+GraphQL.js provides two important capabilities: building a type schema, and
+serving queries against that type schema.
+
+First, build a GraphQL type schema which maps to your code base.
+
+```python
+from graphql import (
+    graphql,
+    GraphQLSchema,
+    GraphQLObjectType,
+    GraphQLField,
+    GraphQLString
+)
+
+schema = GraphQLSchema(
+  query= GraphQLObjectType(
+    name='RootQueryType',
+    fields={
+      'hello': GraphQLField(
+        type= GraphQLString,
+        resolve=lambda *_: 'world'
+      )
+    }
+  )
+)
+```
+
+This defines a simple schema with one type and one field, that resolves
+to a fixed value. The `resolve` function can return a value, a promise,
+or an array of promises. A more complex example is included in the top
+level [tests](graphql/tests) directory.
+
+Then, serve the result of a query against that type schema.
+
+```python
+query = '{ hello }'
+
+result = graphql(schema, query)
+
+# Prints
+# {
+#   "data": { "hello": "world" }
+# }
+print result
+```
+
+This runs a query fetching the one field defined. The `graphql` function will
+first ensure the query is syntactically and semantically valid before executing
+it, reporting errors otherwise.
+
+```python
+query = '{ boyhowdy }'
+
+result = graphql(schema, query)
+
+# Prints
+# {
+#   "errors": [
+#     { "message": "Cannot query field boyhowdy on RootQueryType",
+#       "locations": [ { "line": 1, "column": 3 } ] }
+#   ]
+# }
+print result
+```
 
-### Built-in Concurrency Support
-Support for `3.5.0`'s `asyncio` module for concurrent execution is available via an executor middleware at 
-`graphql.core.execution.middlewares.asyncio.AsyncioExecutionMiddleware`.
+### Executors
 
-Additionally, support for `gevent` is available via 
-`graphql.core.execution.middlewares.gevent.GeventExecutionMiddleware`.
+The graphql query is executed, by default, synchronously (using `SyncExecutor`).
+However the following executors are available if we want to resolve our fields in parallel:
 
-Otherwise, by default, the executor will use execute with no concurrency.
+* `graphql.execution.executors.asyncio.AsyncioExecutor`: This executor executes the resolvers in the Python asyncio event loop.
+* `graphql.execution.executors.asyncio.GeventExecutor`: This executor executes the resolvers in the Gevent event loop.
+* `graphql.execution.executors.asyncio.ProcessExecutor`: This executor executes each resolver as a process.
+* `graphql.execution.executors.asyncio.ThreadExecutor`: This executor executes each resolver in a Thread.
+* `graphql.execution.executors.asyncio.SyncExecutor`: This executor executes each resolver synchronusly (default).
+
+#### Usage
+
+You can specify the executor to use via the executor keyword argument in the `grapqhl.execution.execute` function.
+
+```python
+from graphql.execution.execute import execute
+
+execute(schema, ast, executor=SyncExecutor())
+```
 
 ## Main Contributors
 

diff --git a/graphql/__init__.py b/graphql/__init__.py
@@ -1,5 +1,5 @@
 '''
-GraphQL provides a Python implementation for the GraphQL specification
+GraphQL.js provides a reference implementation for the GraphQL specification
 but is also a useful utility for operating on GraphQL files and building
 sophisticated tools.
 
@@ -14,4 +14,200 @@
 
 This also includes utility functions for operating on GraphQL types and
 GraphQL documents to facilitate building tools.
+
+You may also import from each sub-directory directly. For example, the
+following two import statements are equivalent:
+
+    from graphql import parse
+    from graphql.language.base import parse
 '''
+
+
+# The primary entry point into fulfilling a GraphQL request.
+from .graphql import (
+  graphql
+)
+
+
+# Create and operate on GraphQL type definitions and schema.
+from .type import (  # no import order
+  GraphQLSchema,
+
+  # Definitions
+  GraphQLScalarType,
+  GraphQLObjectType,
+  GraphQLInterfaceType,
+  GraphQLUnionType,
+  GraphQLEnumType,
+  GraphQLInputObjectType,
+  GraphQLList,
+  GraphQLNonNull,
+
+  # Scalars
+  GraphQLInt,
+  GraphQLFloat,
+  GraphQLString,
+  GraphQLBoolean,
+  GraphQLID,
+
+  # Predicates
+  is_type,
+  is_input_type,
+  is_output_type,
+  is_leaf_type,
+  is_composite_type,
+  is_abstract_type,
+
+  # Un-modifiers
+  get_nullable_type,
+  get_named_type,
+)
+
+
+# Parse and operate on GraphQL language source files.
+from .language.base import (  # no import order
+  Source,
+  get_location,
+
+  # Parse
+  parse,
+  parse_value,
+
+  # Print
+  print_ast,
+
+  # Visit
+  visit,
+  ParallelVisitor,
+  TypeInfoVisitor,
+  BREAK,
+)
+
+
+# Execute GraphQL queries.
+from .execution import (  # no import order
+  execute,
+)
+
+
+# Validate GraphQL queries.
+from .validation import (  # no import order
+  validate,
+  specified_rules,
+)
+
+# Create and format GraphQL errors.
+from .error import (
+  GraphQLError,
+  format_error,
+)
+
+
+# Utilities for operating on GraphQL type schema and parsed sources.
+from .utils.base import (
+  # The GraphQL query recommended for a full schema introspection.
+  introspection_query,
+
+  # Gets the target Operation from a Document
+  get_operation_ast,
+
+  # Build a GraphQLSchema from an introspection result.
+  build_client_schema,
+
+  # Build a GraphQLSchema from a parsed GraphQL Schema language AST.
+  build_ast_schema,
+
+  # Extends an existing GraphQLSchema from a parsed GraphQL Schema
+  # language AST.
+  extend_schema,
+
+  # Print a GraphQLSchema to GraphQL Schema language.
+  print_schema,
+
+  # Create a GraphQLType from a GraphQL language AST.
+  type_from_ast,
+
+  # Create a JavaScript value from a GraphQL language AST.
+  value_from_ast,
+
+  # Create a GraphQL language AST from a JavaScript value.
+  ast_from_value,
+
+  # A helper to use within recursive-descent visitors which need to be aware of
+  # the GraphQL type system.
+  TypeInfo,
+
+  # Determine if JavaScript values adhere to a GraphQL type.
+  is_valid_value,
+
+  # Determine if AST values adhere to a GraphQL type.
+  is_valid_literal_value,
+
+  # Concatenates multiple AST together.
+  concat_ast,
+
+  # Comparators for types
+  is_equal_type,
+  is_type_sub_type_of,
+  do_types_overlap,
+
+  # Asserts a string is a valid GraphQL name.
+  assert_valid_name,
+)
+
+__all__ = (
+    'graphql',
+    'GraphQLBoolean',
+    'GraphQLEnumType',
+    'GraphQLFloat',
+    'GraphQLID',
+    'GraphQLInputObjectType',
+    'GraphQLInt',
+    'GraphQLInterfaceType',
+    'GraphQLList',
+    'GraphQLNonNull',
+    'GraphQLObjectType',
+    'GraphQLScalarType',
+    'GraphQLSchema',
+    'GraphQLString',
+    'GraphQLUnionType',
+    'get_named_type',
+    'get_nullable_type',
+    'is_abstract_type',
+    'is_composite_type',
+    'is_input_type',
+    'is_leaf_type',
+    'is_output_type',
+    'is_type',
+    'BREAK',
+    'ParallelVisitor',
+    'Source',
+    'TypeInfoVisitor',
+    'get_location',
+    'parse',
+    'parse_value',
+    'print_ast',
+    'visit',
+    'execute',
+    'specified_rules',
+    'validate',
+    'GraphQLError',
+    'format_error',
+    'TypeInfo',
+    'assert_valid_name',
+    'ast_from_value',
+    'build_ast_schema',
+    'build_client_schema',
+    'concat_ast',
+    'do_types_overlap',
+    'extend_schema',
+    'get_operation_ast',
+    'introspection_query',
+    'is_equal_type',
+    'is_type_sub_type_of',
+    'is_valid_literal_value',
+    'is_valid_value',
+    'print_schema',
+    'type_from_ast',
+    'value_from_ast',
+)