graphene/UPGRADE-v2.0.md

391 lines
8.0 KiB
Markdown
Raw Normal View History

2017-07-12 09:52:24 +03:00
# v2.0 Upgrade Guide
2017-07-12 06:33:03 +03:00
2017-07-24 06:12:54 +03:00
`ObjectType`, `Interface`, `InputObjectType`, `Scalar` and `Enum` implementations
have been quite simplified, without the need to define a explicit Metaclass for each subtype.
2017-07-27 10:10:22 +03:00
It also improves the field resolvers, [simplifying the code](#simpler-resolvers) the
developer has to write to use them.
2017-07-24 06:12:54 +03:00
2017-07-27 10:13:12 +03:00
**Deprecations:**
2017-07-24 06:12:54 +03:00
* [`AbstractType`](#abstracttype-deprecated)
* [`resolve_only_args`](#resolve_only_args)
2017-07-27 06:08:30 +03:00
* [`Mutation.Input`](#mutationinput)
2017-07-24 06:12:54 +03:00
2017-07-27 10:13:12 +03:00
**Breaking changes:**
* [`Simpler Resolvers`](#simpler-resolvers)
2017-07-24 06:12:54 +03:00
* [`Node Connections`](#node-connections)
2017-07-27 10:13:12 +03:00
**New Features!**
2017-07-24 06:12:54 +03:00
* [`InputObjectType`](#inputobjecttype)
2018-12-04 20:56:25 +03:00
* [`Meta as Class arguments`](#meta-as-class-arguments) (_only available for Python 3_)
2017-07-24 06:12:54 +03:00
> The type metaclasses are now deleted as they are no longer necessary. If your code was depending
> on this strategy for creating custom attrs, see an [example on how to do it in 2.0](https://github.com/graphql-python/graphene/blob/v2.0.0/graphene/tests/issues/test_425.py).
2017-07-12 06:33:03 +03:00
## Deprecations
2017-07-24 06:12:54 +03:00
### AbstractType deprecated
2017-07-12 06:33:03 +03:00
2017-07-24 06:12:54 +03:00
AbstractType is deprecated in graphene 2.0, you can now use normal inheritance instead.
2017-07-12 06:33:03 +03:00
2017-07-24 06:12:54 +03:00
Before:
2017-07-12 06:33:03 +03:00
2017-07-24 06:12:54 +03:00
```python
class CommonFields(AbstractType):
name = String()
2017-07-12 06:33:03 +03:00
2017-07-24 06:12:54 +03:00
class Pet(CommonFields, Interface):
pass
```
2017-07-24 06:12:54 +03:00
With 2.0:
2017-07-24 06:12:54 +03:00
```python
class CommonFields(object):
name = String()
2017-07-24 06:12:54 +03:00
class Pet(CommonFields, Interface):
pass
```
### resolve\_only\_args
2017-07-27 13:00:21 +03:00
`resolve_only_args` is now deprecated as the resolver API has been simplified.
2017-07-24 06:12:54 +03:00
Before:
```python
class User(ObjectType):
name = String()
@resolve_only_args
def resolve_name(self):
return self.name
```
With 2.0:
```python
class User(ObjectType):
name = String()
2017-07-27 13:00:21 +03:00
def resolve_name(self, info):
2017-07-24 06:12:54 +03:00
return self.name
```
2017-07-27 05:44:17 +03:00
### Mutation.Input
`Mutation.Input` is now deprecated in favor of using `Mutation.Arguments` (`ClientIDMutation` still uses `Input`).
2017-07-27 05:44:17 +03:00
Before:
```python
class User(Mutation):
class Input:
name = String()
```
With 2.0:
```python
class User(Mutation):
class Arguments:
name = String()
```
## Breaking Changes
2017-07-27 10:13:12 +03:00
### Simpler resolvers
2017-08-07 22:28:18 +03:00
All the resolvers in graphene have been simplified.
Prior to Graphene `2.0`, all resolvers required four arguments: `(root, args, context, info)`.
Now, resolver `args` are passed as keyword arguments to the function, and `context` argument dissapeared in favor of `info.context`.
2017-07-27 10:13:12 +03:00
Before:
```python
my_field = graphene.String(my_arg=graphene.String())
def resolve_my_field(self, args, context, info):
my_arg = args.get('my_arg')
return ...
```
With 2.0:
```python
my_field = graphene.String(my_arg=graphene.String())
2017-08-07 22:28:18 +03:00
def resolve_my_field(self, info, my_arg):
2017-07-27 10:13:12 +03:00
return ...
```
**PS.: Take care with receiving args like `my_arg` as above. This doesn't work for optional (non-required) arguments as stantard `Connection`'s arguments (first, before, after, before).**
You may need something like this:
```python
def resolve_my_field(self, info, known_field1, known_field2, **args): ## get other args with: args.get('arg_key')
```
2017-08-07 22:28:18 +03:00
And, if you need the context in the resolver, you can use `info.context`:
2017-07-27 10:13:12 +03:00
```python
my_field = graphene.String(my_arg=graphene.String())
2017-08-07 22:28:18 +03:00
def resolve_my_field(self, info, my_arg):
context = info.context
2017-07-27 10:13:12 +03:00
return ...
```
2017-07-24 06:12:54 +03:00
### Node Connections
Node types no longer have a `Connection` by default.
In 2.0 and onwards `Connection`s should be defined explicitly.
Before:
```python
class User(ObjectType):
class Meta:
interfaces = [relay.Node]
name = String()
2017-07-24 09:16:51 +03:00
2017-07-24 06:12:54 +03:00
class Query(ObjectType):
user_connection = relay.ConnectionField(User)
```
With 2.0:
```python
class User(ObjectType):
class Meta:
interfaces = [relay.Node]
name = String()
class UserConnection(relay.Connection):
class Meta:
node = User
2017-07-24 06:12:54 +03:00
class Query(ObjectType):
user_connection = relay.ConnectionField(UserConnection)
```
2017-07-28 06:06:48 +03:00
## Node.get_node
The method `get_node` in `ObjectTypes` that have `Node` as interface, changes its API.
2017-07-28 06:06:48 +03:00
From `def get_node(cls, id, context, info)` to `def get_node(cls, info, id)`.
```python
class MyObject(ObjectType):
class Meta:
interfaces = (Node, )
@classmethod
def get_node(cls, id, context, info):
return ...
```
To:
```python
class MyObject(ObjectType):
class Meta:
interfaces = (Node, )
@classmethod
def get_node(cls, info, id):
return ...
```
2017-07-27 12:51:25 +03:00
## Node.get_node_from_global_id
The parameters' order of `get_node_from_global_id` method has changed. You may need to adjust your [Node Root Field](http://docs.graphene-python.org/en/latest/relay/nodes/#node-root-field) and maybe other places that uses this method to obtain an object.
Before:
```python
class RootQuery(object):
...
node = Field(relay.Node, id=ID(required=True))
def resolve_node(self, args, context, info):
node = relay.Node.get_node_from_global_id(args['id'], context, info)
return node
```
Now:
```python
class RootQuery(object):
...
node = Field(relay.Node, id=ID(required=True))
def resolve_node(self, info, id):
node = relay.Node.get_node_from_global_id(info, id)
return node
```
2017-07-27 12:51:25 +03:00
## Mutation.mutate
2018-05-24 02:20:55 +03:00
Now only receives (`self`, `info`, `**args`) and is not a @classmethod
Before:
```python
class SomeMutation(Mutation):
...
@classmethod
def mutate(cls, instance, args, context, info):
...
```
With 2.0:
```python
class SomeMutation(Mutation):
...
def mutate(self, info, **args):
...
```
With 2.0 you can also get your declared (as above) `args` this way:
```python
class SomeMutation(Mutation):
class Arguments:
first_name = String(required=True)
last_name = String(required=True)
...
def mutate(self, info, first_name, last_name):
...
```
2017-07-27 12:51:25 +03:00
## ClientIDMutation.mutate_and_get_payload
2017-07-28 06:06:48 +03:00
Now only receives (`root`, `info`, `**input`)
2017-07-27 12:51:25 +03:00
### Middlewares
If you are using Middelwares, you need to some adjustments:
Before:
```python
class MyGrapheneMiddleware(object):
def resolve(self, next_mw, root, args, context, info):
## Middleware code
return next_mw(root, args, context, info)
```
With 2.0:
```python
class MyGrapheneMiddleware(object):
def resolve(self, next_mw, root, info, **args):
context = info.context
## Middleware code
info.context = context
       return next_mw(root, info, **args)```
```
## New Features
### InputObjectType
2017-07-24 06:12:54 +03:00
If you are using `InputObjectType`, you now can access
its fields via `getattr` (`my_input.myattr`) when resolving, instead of
the classic way `my_input['myattr']`.
And also use custom defined properties on your input class.
Example. Before:
```python
class UserInput(InputObjectType):
2017-07-27 06:12:15 +03:00
id = ID(required=True)
2017-07-27 06:12:15 +03:00
def is_valid_input(input):
return input.get('id').startswith('userid_')
class Query(ObjectType):
2017-07-24 09:10:15 +03:00
user = graphene.Field(User, input=UserInput())
@resolve_only_args
def resolve_user(self, input):
user_id = input.get('id')
2017-07-27 06:12:15 +03:00
if is_valid_input(user_id):
return get_user(user_id)
```
With 2.0:
```python
class UserInput(InputObjectType):
2017-07-27 06:12:15 +03:00
id = ID(required=True)
@property
2017-07-27 06:12:15 +03:00
def is_valid(self):
2017-07-24 06:12:54 +03:00
return self.id.startswith('userid_')
class Query(ObjectType):
2017-07-24 09:10:15 +03:00
user = graphene.Field(User, input=UserInput())
2017-07-28 06:06:48 +03:00
def resolve_user(self, info, input):
2017-07-27 06:12:15 +03:00
if input.is_valid:
return get_user(input.id)
2017-07-24 06:12:54 +03:00
```
### Meta as Class arguments
Now you can use the meta options as class arguments (**ONLY PYTHON 3**).
2017-07-24 06:12:54 +03:00
Before:
```python
class Dog(ObjectType):
class Meta:
interfaces = [Pet]
name = String()
```
With 2.0:
```python
class Dog(ObjectType, interfaces=[Pet]):
name = String()
```
2017-07-25 09:15:47 +03:00
2017-07-27 05:44:17 +03:00
### Abstract types
Now you can create abstact types super easily, without the need of subclassing the meta.
```python
class Base(ObjectType):
class Meta:
abstract = True
2017-07-27 05:44:17 +03:00
id = ID()
2017-07-27 13:00:21 +03:00
def resolve_id(self, info):
2017-07-27 05:44:17 +03:00
return "{type}_{id}".format(
type=self.__class__.__name__,
id=self.id
)
```
2017-07-25 09:15:47 +03:00
### UUID Scalar
In Graphene 2.0 there is a new dedicated scalar for UUIDs, `UUID`.