PreparedRequest.dump()

```
>>> r = requests.get('http://httpbin.org/ip')

>>> print r.request.dump()
REQUESTS/2.9.1 GET http://httpbin.org/ip
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.9.1
```


I think `render` is a good name if it was reporting `HTTP/1.1` in the strings. Another name may be more appropriate now. 


I find it entertaining how this showcases just how much we completely disregard header order. 


Thinking of removing Response's render. 


Maybe `dump()`?


@Lukasa hmmm, that works.


This looks exactly like what I was hoping for.

A couple of comments (feel free to disregard and ship anyway, I'm already happy):
1. I'm not sure about the name **render()**. The method feels like a variant of `__str__` but with all the gory details. I expect it to be used mainly for debugging, so maybe just debug() instead?
2. I really would like both of them (Response.render() and Request.render()). For debugging purposes I often need both the sent request and the response. I then take both of them and send them in an e-mail to the one with the server, so they can debug why my requests are not working right. Without a way to render responses I still would have to have my own utility for that.
3. Not that fond of the "REQUESTS/2.9.1" string. Maybe we could do PreparedRequest<[string_here]> as a way to mimic `__repr__`?


@EmilStenstrom `render` has been renamed to `dump`.


dump() works for me!


> Not that fond of the "REQUESTS/2.9.1" string. Maybe we could do PreparedRequest<[string_here]> as a way to mimic **repr**?

I agree with @EmilStenstrom. I don't like that much either. It's confusing and may make some people think we're doing some weird protocol instead of HTTP.


Concrete suggestion of syntax for dump():

``` python
>>> import requests
>>> r = requests.get('http://httpbin.org/ip')
>>> r.request
<PreparedRequest [GET]>
>>> r.request.dump()
<PreparedRequest [
    GET http://httpbin.org/ip
    Connection: keep-alive
    Accept-Encoding: gzip, deflate
    Accept: */*
    User-Agent: python-requests/2.9.1
]>
```


Any rationale for removing Response.dump()? I find it really useful for debugging a remote service in the same way that Request.dump() is useful.


@EmilStenstrom hmm, that's not a bad way to present it! I like it. 

For the record, I'm still not 100% on including this. I'm still tossing the idea back and forth in my mind. This syntax definitely helps, though.

This syntax also helps support the inclusion of `Response.dump`. It just didn't make sense with the other syntax.


@EmilStenstrom updated the syntax. 

```
<PreparedRequest [
    POST http://httpbin.org/post
    User-Agent: python-requests/2.9.1
    Connection: keep-alive
    Accept-Encoding: gzip, deflate
    Accept: */*
    Content-Length: 3447
    Content-Type: multipart/form-data; boundary=bf96155646964bf082b7a30531aa7c7e
]>
```


Using colors to display warning about non string-like content bodies now. I like where this is going. 

<img width="484" alt="screen shot 2016-02-16 at 1 12 22 am" src="https://cloud.githubusercontent.com/assets/119893/13068556/73c11082-d44a-11e5-9650-315aedf0ca21.png">

Things to do:
- [x] disable color output when not a tty
- [x] potentially color the rest of the output, not sure how i feel about that. 


Ooooh, it's so pretty (and cross-platform).

<img width="473" alt="screen shot 2016-02-16 at 1 51 13 am" src="https://cloud.githubusercontent.com/assets/119893/13069150/f9b10c92-d44f-11e5-8da1-079c58f8bb5b.png">

I dig this. 


I'm very happy with how this turned out, and by also including Response.dump() all three of my concerns have been delt with. It's ready to ship in my mind.


@EmilStenstrom as soon as I'm done perfecting `PreparedRequest`, I'll move on to `Response` :)


Two methods are now included, `dump()`, and `dumps()`. 

_dumps_ is for people that want to grab a string representation of the dump and use it programatically. _dump_ prints the dump directly to the screen, in colorful glory. Colors can optionally be disabled by passing `colored=False`.


Reponse is done! 

<img width="420" alt="screen shot 2016-02-16 at 3 13 46 am" src="https://cloud.githubusercontent.com/assets/119893/13070557/69a961d8-d45b-11e5-8eb0-1803fd4bebee.png">

I think this is ready to ship. 


@EmilStenstrom Response is now included (see above). :cake:

Thanks a lot for your help with this, you've been instrumental ;)


@sigmavirus24 @Lukasa last call for comments. Will merge/release tomorrow. 


I have a preference to remove the functionality to dump colours, rather than vendor in two more modules, but otherwise this is fine by me. =)


Yeah. So, I agree with @Lukasa whole-heartedly. I don't think we should be vendoring libraries just for colorizing this output. This feels like a vast step outside the domain of this library - HTTP. That kind of behaviour belongs elsewhere. We also don't even remotely attempt to reflect whether or not the user is attempting to use proxies, which I think will be far more confusing for those users when they expect to see that output here.

To be clear:
- I think we're violating the law of constraints of limiting this library to HTTP
- I think we're doing our users a grave disservice by having this functionality here in such a naive implementation
- I think we're adding more (vendored) dependencies than we should ever rightfully need


If I hear the word _vendored_ from either one of you again, you're fired :)

But in all seriousness, thoughts on colorization noted. I quite like it, and am not 100% on it yet myself (but am leaning towards yes). 

Now, the purpose of these methods are to provide a convenient way to print out the state of a `PreparedRequest` and a `Response` when building applications by hand (I typically resort to printing `PreparedRequest.__dict__`, which is terrible. Proxies are not involved at this point, and no user should expect any proxy information to be present at this point. The output clearly shows that we are representing the `PreparedRequest` object, and they can look that up in the documentation if they get confused. 


> Proxies are not involved at this point, and no user should expect any proxy information to be present at this point. 

I disagree. The usage you showed above (reproduced below for clarity)

``` py
>>> r = requests.get(url)
>>> r.request.dump()
...
```

Is a request that has been sent. Requests has no way to distinguish that, realistically, but the user knows it has been sent and will expect that information. I know it's hard for us to easily distinguish between a PreparedRequest that someone has made using the PreparedRequest flow and one that was already sent, but users tend to not care if we can determine that or not. Introducing this here will open us up to a host of bug reports about not including various pieces of information in the dump.

> If I hear the word vendored from either one of you again, you're fired :)

Yeah, I'm just thinking of two groups of people:
- Developers who closely follow requests development and are constantly looking to pick fights with us over different choices (vendoring, certifi vs system bundles, etc.)
- Downstream redistributors

The former I don't particularly care about because they generally include people whose opinion I already deprioritize (for various reasons). The latter I'm not worried too much about in this case because colorama is almost certainly already packaged in their repositories. What I care about in that case is when someone does `{package-manager-install} python-requests` and suddenly sees a few new dependencies that look completely unrelated to requests. I think the inclusion of those libraries should be a large warning sign.

And now I'll shut up ;)


> Is a request that has been sent. Requests has no way to distinguish that, realistically, but the user knows it has been sent and will expect that information. I know it's hard for us to easily distinguish between a PreparedRequest that someone has made using the PreparedRequest flow and one that was already sent, but users tend to not care if we can determine that or not. Introducing this here will open us up to a host of bug reports about not including various pieces of information in the dump.

That information would be expected to be present in the headers, right? If so, then anyone manually printing `r.request.headers` today would be equally confused. I don't see that to be the case. Perhaps this is just surfacing a bug that `r.request` should include that information (I don't necessarily think that it should). 


@kennethreitz the proxy information is tricky. We have a hacky way of incorporating it into the information in the toolbelt, but I don't think this implementation would have the same ability to determine if a proxy is in use.


I have no concern for proxy representation here, but if you're concerned for user confusion, we can make a special note in the documentation. `PreparedRequests` and `Response` have no information or knowledge of proxies, and the `dump()` of their contents has no need to represent such information.


If we're going to document as notes everything that might confuse a person with these implementations, those notes will probably outweigh the documentation of the feature itself.


I see nothing here that would be confusing to anyone.