Merge pull request #16 from graphql-python/1.0

Path to 0.3

Author: syrusakbary

.gitignore

@@ -59,3 +59,5 @@ docs/_build/
 # PyBuilder
 target/
 
+
+/tests/django.sqlite

.travis.yml

@@ -6,9 +6,10 @@ python:
 - 3.4
 - 3.5
 - pypy
+cache: pip
 install:
-- pip install pytest pytest-cov coveralls flake8 six blinker pytest-django
-- pip install -e .[django]
+- pip install --cache-dir $HOME/.cache/pip pytest pytest-cov coveralls flake8 six blinker pytest-django
+- pip install --cache-dir $HOME/.cache/pip -e .[django]
 - python setup.py develop
 script:
 - py.test --cov=graphene

README.md

@@ -1,10 +1,13 @@
-# ![Graphene Logo](http://graphene-python.org/favicon.png) [Graphene](http://graphene-python.org) [![Build Status](https://travis-ci.org/graphql-python/graphene.svg?branch=master)](https://travis-ci.org/graphql-python/graphene) [![Coverage Status](https://coveralls.io/repos/graphql-python/graphene/badge.svg?branch=master&service=github)](https://coveralls.io/github/graphql-python/graphene?branch=master)
+# ![Graphene Logo](http://graphene-python.org/favicon.png) [Graphene](http://graphene-python.org) [![Build Status](https://travis-ci.org/graphql-python/graphene.svg?branch=master)](https://travis-ci.org/graphql-python/graphene) [![PyPI version](https://badge.fury.io/py/graphene.svg)](https://badge.fury.io/py/graphene) [![Coverage Status](https://coveralls.io/repos/graphql-python/graphene/badge.svg?branch=master&service=github)](https://coveralls.io/github/graphql-python/graphene?branch=master)
 
 
 Graphene is a Python library for building GraphQL schemas/types fast and easily.
-* **Easy to use:** It maps the models/fields to internal GraphQL objects without effort.
+* **Easy to use:** Graphene helps you use GraphQL in Python without effort.
 * **Relay:** Graphene has builtin support for Relay
-* **Django:** Automatic [Django models](#djangorelay-schema) conversion. *See an [example Django](https://github.com/graphql-python/swapi-graphene) implementation*
+* **Django:** Automatic *Django model* mapping to Graphene Types. *See an [example Django](https://github.com/graphql-python/swapi-graphene) implementation*
+
+
+*But, what is supported in this Python version?* **Everything**: Interfaces, ObjectTypes, Mutations and Relay (Nodes, Connections and Mutations).
 
 
 ## Installation
@@ -13,29 +16,26 @@ For instaling graphene, just run this command in your shell
 
 ```bash
 pip install graphene
+# Or in case of need Django model support
+pip install graphene[django]
 ```
 
 
-## Usage
-
-Example code of a GraphQL schema using Graphene:
+## Examples
 
-### Schema definition
+Here is one example for get you started:
 
 ```python
-class Character(graphene.Interface):
-    id = graphene.IDField()
-    name = graphene.StringField()
-    friends = graphene.ListField('self')
-
-    def resolve_friends(self, args, *_):
-        return [Human(f) for f in self.instance.friends]
+class Query(graphene.ObjectType):
+    hello = graphene.StringField(description='A typical hello world')
+    ping = graphene.StringField(description='Ping someone',
+                                to=graphene.Argument(graphene.String))
 
-class Human(Character):
-    homePlanet = graphene.StringField()
+    def resolve_hello(self, args, info):
+        return 'World'
 
-class Query(graphene.ObjectType):
-    human = graphene.Field(Human)
+    def resolve_ping(self, args, info):
+        return 'Pinging {}'.format(args.get('to'))
 
 schema = graphene.Schema(query=Query)
 ```
@@ -44,48 +44,20 @@ Then Querying `graphene.Schema` is as simple as:
 
 ```python
 query = '''
-    query HeroNameQuery {
-      hero {
-        name
-      }
+    query SayHello {
+      hello
+      ping(to:'peter')
     }
 '''
 result = schema.execute(query)
 ```
 
-### Relay Schema
-
-Graphene also supports Relay, check the [Starwars Relay example](tests/starwars_relay)!
-
-```python
-class Ship(relay.Node):
-    name = graphene.StringField()
-
-    @classmethod
-    def get_node(cls, id):
-        return Ship(your_ship_instance)
-
-
-class Query(graphene.ObjectType):
-    ships = relay.ConnectionField(Ship)
-    node = relay.NodeField()
-
-```
-
-### Django+Relay Schema
-
-If you want to use graphene with your Django Models check the [Starwars Django example](tests/starwars_django)!
+If you want to learn even more, you can also check the following [examples](examples/):
 
-```python
-class Ship(DjangoNode):
-    class Meta:
-        model = YourDjangoModelHere
-        # only_fields = ('id', 'name') # Only map this fields from the model
-        # exclude_fields ('field_to_exclude', ) # Exclude mapping this fields from the model
+* **Basic Schema**: [Starwars example](examples/starwars)
+* **Relay Schema**: [Starwars Relay example](examples/starwars_relay)
+* **Django model mapping**: [Starwars Django example](examples/starwars_django)
 
-class Query(graphene.ObjectType):
-    node = relay.NodeField()
-```
 
 ## Contributing
 

README.rst

@@ -1,9 +1,16 @@
-Graphene |Build Status| |Coverage Status|
-=========================================
+|Graphene Logo| `Graphene <http://graphene-python.org>`__ |Build Status| |PyPI version| |Coverage Status|
+=========================================================================================================
 
-Graphene is a Python library for creating GraphQL schemas/types easly.
-It maps the models/fields to internal GraphQL objects without effort.
-Including automatic `Django models`_ conversion.
+Graphene is a Python library for building GraphQL schemas/types fast and
+easily. \* **Easy to use:** Graphene helps you use GraphQL in Python
+without effort. \* **Relay:** Graphene has builtin support for Relay \*
+**Django:** Automatic *Django model* mapping to Graphene Types. *See an
+`example Django <https://github.com/graphql-python/swapi-graphene>`__
+implementation*
+
+*But, what is supported in this Python version?* **Everything**:
+Interfaces, ObjectTypes, Mutations and Relay (Nodes, Connections and
+Mutations).
 
 Installation
 ------------
@@ -13,89 +20,49 @@ For instaling graphene, just run this command in your shell
 .. code:: bash
 
     pip install graphene
+    # Or in case of need Django model support
+    pip install graphene[django]
 
-Usage
------
-
-Example code of a GraphQL schema using Graphene:
+Examples
+--------
 
-Schema definition
-~~~~~~~~~~~~~~~~~
+Here is one example for get you started:
 
 .. code:: python
 
-    class Character(graphene.Interface):
-        id = graphene.IDField()
-        name = graphene.StringField()
-        friends = graphene.ListField('self')
-
-        def resolve_friends(self, args, *_):
-            return [Human(f) for f in self.instance.friends]
+    class Query(graphene.ObjectType):
+        hello = graphene.StringField(description='A typical hello world')
+        ping = graphene.StringField(description='Ping someone',
+                                    to=graphene.Argument(graphene.String))
 
-    class Human(Character):
-        homePlanet = graphene.StringField()
+        def resolve_hello(self, args, info):
+            return 'World'
 
-    class Query(graphene.ObjectType):
-        human = graphene.Field(Human)
+        def resolve_ping(self, args, info):
+            return 'Pinging {}'.format(args.get('to'))
 
     schema = graphene.Schema(query=Query)
 
-Querying
-~~~~~~~~
-
-Querying ``graphene.Schema`` is as simple as:
+Then Querying ``graphene.Schema`` is as simple as:
 
 .. code:: python
 
     query = '''
-        query HeroNameQuery {
-          hero {
-            name
-          }
+        query SayHello {
+          hello
+          ping(to:'peter')
         }
     '''
     result = schema.execute(query)
 
-Relay Schema
-~~~~~~~~~~~~
-
-Graphene also supports Relay, check the `Starwars Relay example`_!
-
-.. code:: python
-
-    class Ship(relay.Node):
-        '''A ship in the Star Wars saga'''
-        name = graphene.StringField(description='The name of the ship.')
-
-        @classmethod
-        def get_node(cls, id):
-            return Ship(getShip(id))
+If you want to learn even more, you can also check the following
+`examples <examples/>`__:
 
-
-    class Query(graphene.ObjectType):
-        ships = relay.ConnectionField(Ship, description='The ships used by the faction.')
-        node = relay.NodeField()
-
-        @resolve_only_args
-        def resolve_ships(self):
-            return [Ship(s) for s in getShips()]
-
-Django+Relay Schema
-~~~~~~~~~~~~~~~~~~~
-
-If you want to use graphene with your Django Models check the `Starwars
-Django example`_!
-
-.. code:: python
-
-    class Ship(DjangoNode):
-        class Meta:
-            model = YourDjangoModelHere
-            # only_fields = ('id', 'name') # Only map this fields from the model
-            # excluxe_fields ('field_to_excluxe', ) # Exclude mapping this fields from the model
-
-    class Query(graphene.ObjectType):
-        node = relay.NodeField()
+-  **Basic Schema**: `Starwars example <examples/starwars>`__
+-  **Relay Schema**: `Starwars Relay
+   example <examples/starwars_relay>`__
+-  **Django model mapping**: `Starwars Django
+   example <examples/starwars_django>`__
 
 Contributing
 ------------
@@ -112,11 +79,10 @@ After developing, the full test suite can be evaluated by running:
 
     python setup.py test # Use --pytest-args="-v -s" for verbose mode
 
-.. _Django models: #djangorelay-schema
-.. _Starwars Relay example: tests/starwars_relay
-.. _Starwars Django example: tests/starwars_django
-
+.. |Graphene Logo| image:: http://graphene-python.org/favicon.png
 .. |Build Status| image:: https://travis-ci.org/graphql-python/graphene.svg?branch=master
    :target: https://travis-ci.org/graphql-python/graphene
+.. |PyPI version| image:: https://badge.fury.io/py/graphene.svg
+   :target: https://badge.fury.io/py/graphene
 .. |Coverage Status| image:: https://coveralls.io/repos/graphql-python/graphene/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/graphql-python/graphene?branch=master

bin/convert_documentation

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+pandoc README.md --from markdown --to rst -s -o README.rst

tests/starwars/__init__.py renamed to examples/__init__.py

@@ -0,0 +1,97 @@
+humanData = {}
+droidData = {}
+
+
+def setup():
+    from .schema import Human, Droid
+    global humanData, droidData
+    luke = Human(
+        id='1000',
+        name='Luke Skywalker',
+        friends=['1002', '1003', '2000', '2001'],
+        appears_in=[4, 5, 6],
+        home_planet='Tatooine',
+    )
+
+    vader = Human(
+        id='1001',
+        name='Darth Vader',
+        friends=['1004'],
+        appears_in=[4, 5, 6],
+        home_planet='Tatooine',
+    )
+
+    han = Human(
+        id='1002',
+        name='Han Solo',
+        friends=['1000', '1003', '2001'],
+        appears_in=[4, 5, 6],
+        home_planet=None,
+    )
+
+    leia = Human(
+        id='1003',
+        name='Leia Organa',
+        friends=['1000', '1002', '2000', '2001'],
+        appears_in=[4, 5, 6],
+        home_planet='Alderaan',
+    )
+
+    tarkin = Human(
+        id='1004',
+        name='Wilhuff Tarkin',
+        friends=['1001'],
+        appears_in=[4],
+        home_planet=None,
+    )
+
+    humanData = {
+        '1000': luke,
+        '1001': vader,
+        '1002': han,
+        '1003': leia,
+        '1004': tarkin,
+    }
+
+    threepio = Droid(
+        id='2000',
+        name='C-3PO',
+        friends=['1000', '1002', '1003', '2001'],
+        appears_in=[4, 5, 6],
+        primary_function='Protocol',
+    )
+
+    artoo = Droid(
+        id='2001',
+        name='R2-D2',
+        friends=['1000', '1002', '1003'],
+        appears_in=[4, 5, 6],
+        primary_function='Astromech',
+    )
+
+    droidData = {
+        '2000': threepio,
+        '2001': artoo,
+    }
+
+
+def getCharacter(id):
+    return humanData.get(id) or droidData.get(id)
+
+
+def getFriends(character):
+    return map(getCharacter, character.friends)
+
+
+def getHero(episode):
+    if episode == 5:
+        return humanData['1000']
+    return droidData['2001']
+
+
+def getHuman(id):
+    return humanData.get(id)
+
+
+def getDroid(id):
+    return droidData.get(id)