Consider 2.0

/cc @Lukasa @sigmavirus24 

What would Requests 2.0 include?
- #1338 
- ...


My 2c:
- support HTTPS proxies
- require an explicit procotol in proxy URLs
- remove the `proxies` parameter, introduce `proxy`. People can use transport adapters (see discussion in #1192)


I agree with @t-8ch's first two points. (It's worth noting that the first point actually requires upstream work.) I'm not really bothered about his third, I'd be happy to leave it as-is.

On top of that, I'd want to consider:
- Provide a `Session.build_request()` function (or equivalent). The biggest problem with preparing `Request`s yourself is that you have to reimplement portions of `Session.request()`. We should make it as easy as possible to not do that.


Personally I'd like to seriously improve the docs for the project before we do another release for any major or minor version.

Also, this isn't a breaking API change but we need to hop back on it: https://github.com/kennethreitz/requests/issues/1155


Perhaps we could also address #1294. It isn't hard to address but I'd like to stop nesting so many exceptions so far down. It seems like each library is capturing and re-raising in a wrapped exception. I understand why, I just don't like it in the slightest. I think we should at least attempt to expose the base message and errno (if any) to the user for greater ease of use.


Also, I've been meaning to take a crack at #1166 and @Lukasa's suggestion to provide `Session.build_request()` would make that much much easier. `mock` makes it nice but making the methods as patchable as possible is also very nice.

For the record, I haven't looked closely at any of the vcr clones, but none of them really work the way I want them too. (Yes I know, that means I should make my own. But time is precious now that I have a real job.)


Let's also add a fix for #1462, including a cleanup of the code in the `RequestsEncodingMixin` (which is pretty spaghetti-like).


The fix I want to make for #1462 will require code that I implemented in #1338. Rather than do something complex with branches of branches, I'll just wait until we merge that. =)


While we're at it #1187 could be re-opened and is certainly valid and is a large breaking change


#1460


We might consider starting a 2.0 branch so we can apply any hotfixes to the 1.x series while we work on 2.0. I for one don't think we should rush too quickly into 2.0. We can maintain the 2.0 branch pulling master in regularly, but send all 2.0 related PRs to that branch instead of master.


+1 for having a branch. =)


Also we should consider one last 1.x release since there are ~70 commits between 1.2.3 and now.


Started a new branch #1509 


https://github.com/kennethreitz/requests/releases/tag/2.0


:heart:


I am currently in the process of adding SOCKS proxy (SOCKS4 and SOCKS5) support to `urllib3`. Afterwards, I would like to submit a pull to get it integrated into `requests` 2.0. It is essentially an extension of the HTTPS proxy support patch. Usage would be as follows: `requests.get(url, proxies={"http": "socks5://localhost:1080"})`, with a scheme of either `socks4://` or `socks5://`.

Just so I'm on board with what everyone wants, does this seem reasonable? Such support is a bit too low-level to be implemented simply as an Adapter, and I think it's something that should be provided by both libraries by default. I also have noticed that people have been requesting SOCKS support for a while now.


I think it is probably reasonable. Getting a huge improvement in proxy support for 2.0 would be fantastic. Make sure you submit your PR to the 2.0 branch and not master.

Thanks @Anorov 
:metal: :cake: :beer: :cactus: 


@sigmavirus24 Yep, I fully agree.

I'd just like to get the go-ahead from @kennethreitz before fully continuing, in the event he thinks it's not deserving of being put into requests core.


If it's in vanilla urllib3, then +1 :)


I've been working on support for setting separate connect, read and total timeout values in urllib3 - would probably require a change to the timeout interface for requests. https://github.com/shazow/urllib3/pull/231


@kevinburke That looks awesome. Great job! It'll resolve some of our open issues, like #1577.

We need to propose our API changes. I really like the current clean form of `timeout`, so I think the best API is to do the following:
- Add a `requests.utils.Timeout` class (which is a simple subclass of the `urllib3` timeout class.
- Extend the `timeout` parameter to be a number or optionally an instance of the `Timeout` class.

@kevinburke, when this gets merged you should let me know, and I can either implement the Requests' side myself or code review your version of it. =)


@kevinburke request:

Allow the Timeout class's `__init__` method to take an instance of itself and handles `None`. If it does, we can always just easily do (on our end):

```
def request(method, url, data=None, ..., timeout=None, ...):
    timeout = Timeout(timeout)
    # ...
```

If you can do that :heart:


@sigmavirus24 The only issue there is that None has a specific meaning for timeouts - it implies never timeout, vs. some sentinel object which signifies "use the system default timeout"


@kevinburke since this is going into 2.0 which do you think is better. Currently I believe we do not operate with any default timeout (i.e., None) so keeping that behaviour would not be a big deal. Using some "system default" (which I frankly wasn't aware existed) would be a breaking API change and would be okay since 2.0 allows for those.

I personally am in favor of keeping the current behaviour but I'm open to arguments for using a system default.


Make timeout universal, or create a new universalTimeout param,
coz there seem to be multiple cases where timeout does not work... :-(
https://github.com/kennethreitz/requests/issues/1617
https://github.com/kennethreitz/requests/issues/1577


Can we move all discussion of timeouts to #1594 please?


Closing this since 2.0 has been released