Skip to content

Commit dd88023

Browse files
committed
Improve API reference
1 parent 05b3042 commit dd88023

File tree

1 file changed

+118
-2
lines changed

1 file changed

+118
-2
lines changed

REFERENCE.md

+118-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# API Reference
22

33
- [ObjectType](#ObjectType)
4+
- [MutationType](#MutationType)
45
- [SubscriptionType](#SubscriptionType)
56
- [InputType](#InputType)
67
- [ScalarType](#ScalarType)
@@ -150,6 +151,91 @@ class UsersGroupType(ObjectType):
150151
`DeferredType` makes `UserType` happy about `UsersGroup` dependency, deferring dependency check to `make_executable_schema`. If "real" `UsersGroup` is not provided at that time, error will be raised about missing types required to create schema.
151152

152153

154+
## `MutationType`
155+
156+
Convenience type for defining single mutation:
157+
158+
```python
159+
from ariadne_graphql_modules import MutationType, convert_case, gql
160+
161+
from my_app import create_user
162+
163+
164+
class UserRegisterMutation(MutationType):
165+
__schema__ = gql(
166+
"""
167+
type Mutation {
168+
registerUser(username: String!, email: String!): Boolean!
169+
}
170+
"""
171+
)
172+
173+
@staticmethod
174+
async def resolve_mutation(*_, username: str, email: str):
175+
user = await create_user(
176+
full_name=username,
177+
email=email,
178+
)
179+
return bool(user)
180+
```
181+
182+
Recommended use for this type is to create custom base class for your GraphQL API:
183+
184+
```python
185+
from ariadne_graphql_modules import MutationType, convert_case, gql
186+
187+
188+
class BaseMutation(MutationType):
189+
__abstract__ = True
190+
191+
@classmethod
192+
async def resolve_mutation(cls, _, *args, **kwargs):
193+
try:
194+
return await cls.perform_mutation(cls, *args, **kwargs)
195+
except Exception as e:
196+
return {"errors": e}
197+
198+
@classmethod
199+
def get_error_result(cls, error):
200+
return {"errors": [e]}
201+
```
202+
203+
204+
### `__args__`
205+
206+
Optional attribute that can be used to specify custom mapping between GraphQL schema and Python:
207+
208+
```python
209+
from ariadne_graphql_modules import MutationType, convert_case, gql
210+
211+
from my_app import create_user
212+
213+
214+
class UserRegisterMutation(MutationType):
215+
__schema__ = gql(
216+
"""
217+
type Mutation {
218+
registerUser(
219+
userName: String!,
220+
email: String!,
221+
admin: Boolean,
222+
): Boolean!
223+
}
224+
"""
225+
)
226+
__args__ = {"userName": "username", "admin": "is_admin"}
227+
228+
@staticmethod
229+
async def resolve_mutation(*_, username: str, email: str, is_admin: bool | None):
230+
user = await create_user(
231+
full_name=username,
232+
email=email,
233+
is_admin=bool(is_admin),
234+
)
235+
return bool(user)
236+
```
237+
238+
153239
## `SubscriptionType`
154240

155241
Specialized subclass of `ObjectType` that defines GraphQL subscription:
@@ -722,6 +808,36 @@ class UserType(ObjectType):
722808

723809
Use `__fields_args__ = convert_case` on type to automatically convert field arguments to python case in resolver kwargs:
724810

811+
```python
812+
from ariadne_graphql_modules import DeferredType, ObjectType, convert_case, gql
813+
814+
from my_app.models import Article
815+
816+
817+
class SearchQuery(ObjectType):
818+
__schema__ = gql(
819+
"""
820+
type Query {
821+
search(query: String!, includeDrafts: Boolean): [Article!]!
822+
}
823+
"""
824+
)
825+
__fields_args__ = convert_case
826+
__requires__ = [DeferredType("Article")]
827+
828+
@staticmethod
829+
async def resolve_search(*_, query: str, include_drafts: bool | None):
830+
articles = Article.query.search(query)
831+
if not include_drafts:
832+
articles = articles.filter(is_draft=False)
833+
return await articles.all()
834+
```
835+
836+
837+
#### Converting mutation arguments
838+
839+
Use `__args__ = convert_case` on `MutationType` to automatically convert input fields to python case in resolver kwargs:
840+
725841
```python
726842
from ariadne_graphql_modules import MutationType, convert_case, gql
727843

@@ -736,7 +852,7 @@ class UserRegisterMutation(MutationType):
736852
}
737853
"""
738854
)
739-
__fields_args__ = convert_case
855+
__args__ = convert_case
740856

741857
@staticmethod
742858
async def resolve_mutation(*_, full_name: str, email: str):
@@ -750,7 +866,7 @@ class UserRegisterMutation(MutationType):
750866

751867
#### Converting inputs fields
752868

753-
Use `__args__ = convert_case` on type to automatically convert input fields to python case in resolver kwargs:
869+
Use `__args__ = convert_case` on `InputType` to automatically convert input fields to python case in resolver kwargs:
754870

755871
```python
756872
from ariadne_graphql_modules import InputType, MutationType, convert_case, gql

0 commit comments

Comments
 (0)