Re: [Django] #33757: django.test.Client.post documentation is confusing (was: django.test.Client.post documentation is wrong)
Django
--------------------------------+--------------------------------------
Reporter: bastian-wattro | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 4.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------+--------------------------------------
Changes (by bastian-wattro):
* status: closed => new
* resolution: invalid =>
Old description:
> Following
> [https://docs.djangoproject.com/en/4.0/topics/testing/tools/#django.test.Client.post]
> with Django version 4.0.4 to write my first unit tests, I failed to
> upload a file.
>
> As described there, I tried
> {{{#!python
> with open('mal.csv', 'rb') as fp:
> self.client.post('/post/endpoint/', {'name': 'fred', 'attachment': fp})
> }}}
> And assumed that (as described there)
> > The name attachment here is not relevant; use whatever name your file-
> processing code expects.
>
> This made the test fail. Printing request.FILES returned:
> `<MultiValueDict: {'attachment': [<InMemoryUploadedFile: mal.csv
> (text/csv)>]}>`
>
> What worked was the (way more intuitive)
> {{{#!python
> with open('mal.csv', 'rb') as fp:
> self.client.post('/post/entpoint/', {'name': 'fred', 'attachment': fp})
> # <MultiValueDict: {'fred': [<InMemoryUploadedFile: mal.csv
> (text/csv)>]}>
> }}}
>
> I did not check:
> * since when the documentation is obsolete
> * if this is intended behavior
New description:
Following
[https://docs.djangoproject.com/en/4.0/topics/testing/tools/#django.test.Client.post]
with Django version 4.0.4 to write my first unit tests, I failed to upload
a file under a given keyword *with the *name* / *attachment* pattern*
As described there, I tried to set *name* and *file pointer* like this:
> Submitting files is a special case. To POST a file, you need only
provide the file field name as a key, and a file handle to the file you
wish to upload as a value. For example:
> {{{#!python
with open('mal.csv', 'rb') as fp:
self.client.post('/post/endpoint/', {'name': 'fred', 'attachment': fp})
}}}
> The name *attachment* here is not relevant; use whatever name your file-
processing code expects.
This made me assume that the file given via the filepointer will be
accessible via the keyword `fred`.
This
[test](https://github.com/django/django/blob/d5bc36203057627f6f7d0c6dc97b31adde6f4313/tests/file_uploads/tests.py#L86-L93)
works because the [endpoint being
called](https://github.com/django/django/blob/d5bc36203057627f6f7d0c6dc97b31adde6f4313/tests/file_uploads/views.py#L18)
(contrary to what I would expect) checks the keyword of the file pointer
(`fiel_field` in this case) and the `name` separately.
What I wanted was
{{{#!python
with open('mal.csv', 'rb') as fp:
self.client.post('/post/endpoint/', {'fred': fp})
}}}
as (contraty to what is written in the docs) **name** is not required
Sorry for the confusion and thanks for the quick responses.
--
Comment:
Sorry for the confusion and thanks for the quick responses. I'll try to
clarify:
Following
[https://docs.djangoproject.com/en/4.0/topics/testing/tools/#django.test.Client.post
the docs]
with Django version 4.0.4 to write my first unit tests, I failed to upload
a file under a given keyword ''with the ''name'' / ''attachment''
pattern''
The docs state:
{{{#!python
>>> c = Client()
>>> with open('wishlist.doc', 'rb') as fp:
... c.post('/customers/wishes/', {'name': 'fred', 'attachment': fp})
}}}
> The name *attachment* here is not relevant; use whatever name your file-
processing code expects.
This made me assume that the file given via the file pointer will be
accessible via the keyword `fred`.
This
[https://github.com/django/django/blob/d5bc36203057627f6f7d0c6dc97b31adde6f4313/tests/file_uploads/tests.py#L86-L93
test] works because the
[https://github.com/django/django/blob/d5bc36203057627f6f7d0c6dc97b31adde6f4313/tests/file_uploads/views.py#L18
endpoint being called] (contrary to what I would expect) checks the
keyword of the file pointer (`fiel_field` in this case) and the `name`
separately.
Reading the docs for a third time now I get the meaning.
What I don't understand is why the keyword 'name' is there, and why
doesn't it simply say something like:
----
To submit a file, provide a file handle to the file you wish to upload as
a value. For example:
{{{#!python
>>> c = Client()
>>> with open('wishlist.doc', 'rb') as fp:
... c.post('/customers/wishes/', {'wishes_file': fp})
}}}
will be accessible via `request.FILES['wishes_file']`
----
Again thanks for your time. I get now that this is something that probably
only confuses new comers like my self.
--
Ticket URL: <https://code.djangoproject.com/ticket/33757#comment:3>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.