Specifying POST body content-type

I was using requests to submit POST requests to a third-party website when I noticed that the `files` parameter can also accept a three- or four-element tuple that denotes body content-type (and another header?) (https://github.com/kennethreitz/requests/blob/master/requests/models.py#L120) instead of just two as noted in the docs.

Is there a reason this is not yet mentioned in the docs or can I expect this interface may break in future releases?

I'm on Requests version 2.0.1, by the way :).


It's not mentioned in the docs primarily out of laziness. We do talk about it elsewhere, such as on Stack Overflow. I think more generally we're not very happy with that interface, so we're always considering changing it, but I think we'd be happy to accept a docs pull request anyway. =)


Is there any reason you're not happy about it? If not (and if you do plan on keeping it), I could try look into the docs later on :).


It feels unpleasant to me, that's all. Requests' interface is normally very good at being self-describing, and the interface we're talking about now is phenomenally opaque. This is just not a clear way of providing the relevant information:

``` python
files = {'file': ('filename.xls', open('filename.xls'), 'application/vnd.ms-excel', {})}
```

In the past, I've suggested that I'd like to remove all but the most basic multipart file upload functionality from Requests entirely, and provide a 'blessed' third-party module that can do all of the craziness that people often want from their multipart uploads. As of right now there's no plan afoot to do that, so documenting the current solution is OK, but it's possible I'll look into doing it for a 3.0 release.


There's also a secret Class you can use to do your own streamed uploads exactly as you like, to support any format. I never documented it though :)


@Lukasa I personally make great use of Requests' file uploading options (very helpful when debugging and auditing web apps), and would like to see it remain in core if possible. It's features like this (being able to specify a filename, a string or file object, and a content type in any multipart upload) that make Requests far more versatile than urllib2.

A potential API change could be to allow each file to be either a tuple as it is now, or a dict, where the dict can specify any number of parameters as in: `{"name": "filename.xls", "content": open("filename.xls"), "content_type": "application/vnd.ms-excel"}`. This is more verbose, but removes the need to remember where to position each element in the tuple (though unfortunately might cause the need to remember the filename is "name", etc..).


@Anorov I appreciate that the current set of features is highly useful, and I wouldn't dream of stripping it out unless there was a good option for replacing it that had total feature parity. We're a ways away from that right now, so we don't need to worry about it, but your objection is noted. =)

This isn't the kind of decision I get to make anyway, I only get to petition Kenneth.


> I only get to petition Kenneth.

[When I was back there in seminary school, there was a man who put for the proposition that you could petition the Lord with prayer!](https://www.youtube.com/watch?v=PbpRlqqzSD4)

Sorry it just popped into my head. ;)