document new cookie API (and maybe improve it)

The `cookies` member of the `Response` and `Session` objects is no longer a dict, it's a `RequestsCookieJar` that behaves like a dict in some cases. However:
1. You can't take `dict(resp.cookies)`, since iteration over a `CookieJar` gives you the `Cookie` objects, which are not valid keys for the dict interface (it expects string keynames). Even if we added this, the dict cast would map `Cookie` objects to string values, which would be weird and not very useful.
2. In general, `CookieJar`s are quite awkward to work with. In test cases I found myself writing `list(resp.cookies)[0]` a lot. I'm not sure what the ideal way to work with them would be.


It seems reasonable to have cookies.keys return cookie names, and cookies.values return values, so that dict(resp.cookies) returns a name:value dict. The get/set methods would still be available for when it is necessary to get access to the actual cookie objects.


+100. We should define `keys()`, `items()`, and `values()`. Thanks!

Are you interested in writing a patch?


And I should have been using `get()` in the unit tests. One of us should docstring which methods return what.


@slingamn I'll work on a patch for this, if no one else is doing it.


@dhagrow 

> It seems reasonable to have cookies.keys return cookie names, and cookies.values return values (...)

What with cookies with the same name and different domain or path?


@slingamn 
Sorry for not responding earlier. I don't think I'll find the time for this soon. If @joshimhoff is willing, that would be great.

@piotr-dobrogost
I see two use-cases for `RequestsCookieJar`:
- One is the dev interested in a single domain, in which case `dict(res.cookies)` would be sufficient.
- The other is the dev interested in multiple domains, in which case it is necessary to be explicit.

I think I would default to the first case, but force the dev to use the second when necessary to avoid ambiguity. In other words, when using the simple API would cause a conflict, raise an exception.

```
>>> req.cookies['name'] = 'value'
CookieConflictError: There are multiple cookies with the name 'name'
```

I'm not sure if it would be better to raise the exception when more than one domain/path is stored in the jar, or only when there is an actually conflicting cookie. I would say the former to favor explicitness. It doesn't make much sense to have a `dict` of cookies from multiple domains.

The simple API would have `res.cookies` act as a standard `dict` object, including the `.get` method. I would then add a special API for `Cookie` objects:
- `.get_cookie(name, domain, path, ...)` returns a `Cookie` object.
- `.set_cookie(name, value, domain, path, ...)` sets/creates a `Cookie`.
- `.get_dict(domain, path, ...)` returns a `name:value` dict of cookies that match the specified requirements.
- perhaps some useful info methods as well, like `.list_domains`.

Anyway, it's not a simple problem. It's worth some discussion to get it right.


@joshimhoff go for it :-)


@kennethreitz Any opinion on the error handling that @dhagrow mentions? I'm working on a patch, but I don't really think I should make that decision.


There is an alternative API that might be a little less jarring. The `Request` and `Response` objects don't actually need direct access to the full cookiejar, so they could each store just a `dict` of their own relevant cookies. For the `Request`, just the cookies pulled from the cookiejar as it was created. For the `Response`, those same cookies, plus any new ones from a `Set-Cookie` header.

To get access to the full set of cookies you would use `session.cookies`, which would no longer have a `dict` interface, but rather just `.set_cookie`, `.get_cookie`, `.get_dict`, etc..., as in my previous suggestion.

Doing it this way seems a little more user-friendly, but you would have to make sure that anytime `request.cookies` is modified, the `session.cookies` object is updated correctly.