1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
File uploads
============
GQL supports file uploads with the :ref:`aiohttp transport <aiohttp_transport>`, the
:ref:`requests transport <requests_transport>`, the :ref:`httpx transport <httpx_transport>`,
and the :ref:`httpx async transport <httpx_async_transport>`,
using the `GraphQL multipart request spec`_.
.. _GraphQL multipart request spec: https://github.com/jaydenseric/graphql-multipart-request-spec
Single File
-----------
In order to upload a single file, you need to:
* set the file as a variable value in the mutation
* create a :class:`FileVar <gql.FileVar>` object with your file path
* provide the `FileVar` instance to the `variable_values` attribute of your query
* set the `upload_files` argument to True
.. code-block:: python
from gql import client, gql, FileVar
transport = AIOHTTPTransport(url='YOUR_URL')
# Or transport = RequestsHTTPTransport(url='YOUR_URL')
# Or transport = HTTPXTransport(url='YOUR_URL')
# Or transport = HTTPXAsyncTransport(url='YOUR_URL')
client = Client(transport=transport)
query = gql('''
mutation($file: Upload!) {
singleUpload(file: $file) {
id
}
}
''')
query.variable_values = {"file": FileVar("YOUR_FILE_PATH")}
result = client.execute(query, upload_files=True)
Setting the content-type
^^^^^^^^^^^^^^^^^^^^^^^^
If you need to set a specific Content-Type attribute to a file,
you can set the :code:`content_type` attribute of :class:`FileVar <gql.FileVar>`:
.. code-block:: python
# Setting the content-type to a pdf file for example
filevar = FileVar(
"YOUR_FILE_PATH",
content_type="application/pdf",
)
Setting the uploaded file name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To modify the uploaded filename, use the :code:`filename` attribute of :class:`FileVar <gql.FileVar>`:
.. code-block:: python
# Setting the content-type to a pdf file for example
filevar = FileVar(
"YOUR_FILE_PATH",
filename="filename1.txt",
)
File list
---------
It is also possible to upload multiple files using a list.
.. code-block:: python
from gql import client, gql, FileVar
transport = AIOHTTPTransport(url='YOUR_URL')
# Or transport = RequestsHTTPTransport(url='YOUR_URL')
# Or transport = HTTPXTransport(url='YOUR_URL')
# Or transport = HTTPXAsyncTransport(url='YOUR_URL')
client = Client(transport=transport)
query = gql('''
mutation($files: [Upload!]!) {
multipleUpload(files: $files) {
id
}
}
''')
f1 = FileVar("YOUR_FILE_PATH_1")
f2 = FileVar("YOUR_FILE_PATH_2")
query.variable_values = {"files": [f1, f2]}
result = client.execute(query, upload_files=True)
Streaming
---------
If you use the above methods to send files, then the entire contents of the files
must be loaded in memory before the files are sent.
If the files are not too big and you have enough RAM, it is not a problem.
On another hand if you want to avoid using too much memory, then it is better
to read the files and send them in small chunks so that the entire file contents
don't have to be in memory at once.
We provide methods to do that for two different uses cases:
* Sending local files
* Streaming downloaded files from an external URL to the GraphQL API
.. note::
Streaming is only supported with the :ref:`aiohttp transport <aiohttp_transport>`
Streaming local files
^^^^^^^^^^^^^^^^^^^^^
aiohttp allows to upload files using an asynchronous generator.
See `Streaming uploads on aiohttp docs`_.
From gql version 4.0, it is possible to activate file streaming simply by
setting the `streaming` argument of :class:`FileVar <gql.FileVar>` to `True`
.. code-block:: python
transport = AIOHTTPTransport(url='YOUR_URL')
client = Client(transport=transport)
query = gql('''
mutation($file: Upload!) {
singleUpload(file: $file) {
id
}
}
''')
f1 = FileVar(
file_name='YOUR_FILE_PATH',
streaming=True,
)
query.variable_values = {"file": f1}
result = client.execute(query, upload_files=True)
Another option is to use an async generator to provide parts of the file.
You can use `aiofiles`_
to read the files in chunks and create this asynchronous generator.
.. _Streaming uploads on aiohttp docs: https://docs.aiohttp.org/en/stable/client_quickstart.html#streaming-uploads
.. _aiofiles: https://github.com/Tinche/aiofiles
.. code-block:: python
async def file_sender(file_name):
async with aiofiles.open(file_name, 'rb') as f:
while chunk := await f.read(64*1024):
yield chunk
f1 = FileVar(file_sender(file_name='YOUR_FILE_PATH'))
query.variable_values = {"file": f1}
result = client.execute(query, upload_files=True)
Streaming downloaded files
^^^^^^^^^^^^^^^^^^^^^^^^^^
If the file you want to upload to the GraphQL API is not present locally
and needs to be downloaded from elsewhere, then it is possible to chain the download
and the upload in order to limit the amout of memory used.
Because the `content` attribute of an aiohttp response is a `StreamReader`
(it provides an async iterator protocol), you can chain the download and the upload
together.
In order to do that, you need to:
* get the response from an aiohttp request and then get the StreamReader instance
from `resp.content`
* provide the StreamReader instance to the `variable_values` attribute of your query
Example:
.. code-block:: python
# First request to download your file with aiohttp
async with aiohttp.ClientSession() as http_client:
async with http_client.get('YOUR_DOWNLOAD_URL') as resp:
# We now have a StreamReader instance in resp.content
# and we provide it to the variable_values attribute of the query
transport = AIOHTTPTransport(url='YOUR_GRAPHQL_URL')
client = Client(transport=transport)
query = gql('''
mutation($file: Upload!) {
singleUpload(file: $file) {
id
}
}
''')
query.variable_values = {"file": FileVar(resp.content)}
result = client.execute(query, upload_files=True)
|
