Create Request.links_multi and utils function for properly parsing Link headers

The current `Request.links` property has a few problems: it assumes there will only be a single link for a given relation type, and that each link has only a single relation type (see [RFC 5988](http://tools.ietf.org/html/rfc5988)); and the `utils.parse_header_links()` function it relies on does not properly parse inputs containing commas or semicolons within quoted strings. However, since I'm not sure of the proper way to fix either function without breaking backwards compatibility, I've instead created `Requests.links_multi` and `utils.parse_header_links_full`, if only to solicit feedback on the logic itself; the factoring can be changed in any way the maintainers prefer.

Specifically, `parse_header_links_full` returns a list of the new `Link` `namedtuple`s with `uri` and `attrs` attributes. Internally, it delegates to a new `tokenize` function, which splits a string into a list of tokens (identifiers, "specials", and quoted strings) according to the rules in [RFC 2616](http://tools.ietf.org/html/rfc2616#section-2.2), which makes the parsing itself quite straightforward with some application of `itertools`. In addition, `parse_header_links` is reimplemented in terms of this, to at least properly handle quoted delimiters.

`Request.links_multi`, in turn, returns a `CaseInsensitiveDict` keyed on the relation type (`Request.links` has been updated to do this as well), whose values are a list of all the links with that relation type. If a link has multiple relation types (e.g. `rel="foo bar"`), it will be added to the lists for each relation type.


Wow, this is a serious chunk of work: thankyou!

I have to get around to reviewing this, which I haven't done yet, but it seems like it's a good enhancement. I'm not going to speculate on how @kennethreitz will want to handle the API change: whether he'll want extra properties or to hold off until Semver lets us make this backwards incompatible change.


I actually have no review feedback: assuming the API design is acceptable to Kenneth, I'm happy with this. =) It's going to confuse the hell out of anyone not familiar with `itertools`, but that's just an excuse for them to learn it. :+1: This is just outstanding work.


I haven't looked at this at all and don't have any opinion yet. I just think the important context here is that (if I remember correctly) @kennethreitz was explicit in his desire to only handle the case where there's a single link for a given relation type. I'll have to find the corresponding issues/PRs to double check though. 

In general I'm always :+1: for conforming to RFCs. As a side note, if this is rejected, I would be more than happy to accept this as a feature for the [toolbelt](/sigmavirus24/toolbelt).


What's the status of this PR? I'm starting a new job soon, and will have less time to support languishing PRs like this. Still willing to make changes, however.


@alekstorm Kenneth's hugely busy, and so sizeable pull requests will tend to sit on the pile for a while until he has time to look at them. We're not a project in a rush, so don't worry, this won't be lost, and we won't be pressuring you to make fast changes. =)

Congrats on the new job, btw! 


@alekstorm also there's no rush. If needed, @Lukasa can improve the PR on a branch of our own (using all of your work as a base). And congratulations on the new job! I hope it treats you well :)


Could you make this API function like the current one, but using a MultiDict, perhaps?


@alekstorm if you can't finish this up, let me know and I'll take over the work for you.


ppppppppiiiiiiing :)


Sorry about the delay. How do I go about using a MultiDict? It looks like the discussion stalled in https://github.com/kennethreitz/requests/issues/1155, but urllib3 recently gained an `HTTPHeaderDict`, which looks like it provides the functionality we need, but using it for something other than HTTP headers feels... hacky.

Assuming we find a MultiDict implementation, do you want me to nix `links_multi` in favor of changing `links`?


Hah, when I originally wrote `HTTPHeaderDict` it was called `CaseInsensitiveMultiDict`. We ended up changing it because the `__getitem__` implementation joins all values for the key together with a comma which is something fairly peculiar to HTTP headers and means that it can only really work on string values. Due to this it might fall somewhat short for your needs. This is also opposed to e.g Werkzeug's `MultiDict` which just gives you back the first value.

I'm open to any changes/feedback you might suggest for it to be more useful to you. Personally I think the `getlist` method needs to be changed to just go over the values because `set-cookie` headers can contain commas. If that is done it's really only the `__getitem__` behavior that keeps it from being a general `CaseInsensitiveMultiDict`.


Closing due to lack of activity.