Emphasize client

[cwaldbieser]

Based on a conversation with Glyph in PR #76, I reverted the changes from that PR and instead updated the examples and documentation to emphasize that client code may interact with treq.client.HTTPClient directly. In fact this should be the way to customize the behavior of the client. The various treq request functions are just shortcuts.

[codecov-io]

Current coverage is 96.30%

Merging #109 into master will decrease coverage by -0.01% as of 8aba93c

@@            master   #109   diff @@
=====================================
  Files           19     19       
  Stmts         1601   1595     -6
  Branches       121    120     -1
  Methods          0      0       
=====================================
- Hit           1542   1536     -6
  Partial         19     19       
  Missed          40     40       

Review entire Coverage Diff as of 8aba93c

Powered by Codecov. Updated on successful CI builds.

[glyph]

@cwaldbieser thanks for this update! I just merged another PR that conflicts with this, unfortunately; do you want to remove the agent parameter first? @hynek - what do you think?

[hynek]

I’m confused why it removes the custom agent test?

I’m also not a fan of replacing treq by a http_client in all examples TBH. It should be documented but this is excessive.

[cwaldbieser]

The custom_agent test was reverted along as part of the change that added
passing agent as a parameter to the shortcut functions. The test is no
longer valid.

I could put all the examples back except the one specific to docs on how
you customize the underlying agent. Would that be better?

Thanks,
Carl

On Thu, Jul 30, 2015 at 2:51 AM, Hynek Schlawack notifications@github.com
wrote:

I’m confused why it removes the custom agent test?

I’m also not a fan of replacing treq by a http_client in all examples TBH.
It should be documented but this is excessive.

—
Reply to this email directly or view it on GitHub
#109 (comment).

[cwaldbieser]

I merged the recent change to master back into this branch.
I removed all traces of passing the custom agent as a parameter to the treq.(get|post|put|delete|...) methods. Instead, I updated the docs to explain how you should just use treq.client.HTTPClient directly, as this was not particularly clear until @glyph pointed this out.
I also reverted the other examples back to using treq.get() etc., as @hynek is right-- it did feel like overkill to just bind an additional name in all the examples that don't use a custom agent.

[glyph]

Oh no, more conflicts :-(. This is actually looking pretty good though, can you resolve the conflicts again and perhaps we can land it?

[cwaldbieser]

I corrected the conflict and pulled out the code that would allow you to pass a custom agent to the short cut functions in api.py. The docs explain that the way to customize the client behavior is to instantiate an HTTPClient directly and not use the short cuts.

[glyph]

@cwaldbieser - I was ready to merge this after resolving conflicts... but then I saw you broke compatibility by removing the agent= functionality. That is at the very least a separate change :-. Sorry about the ridiculous review latency on Treq, we have not had a good process to encourage people to look over pull requests.

[glyph]

I feel bad about asking you to do something about this only every 6 months and then not merging it, so I've taken over the work in #129 .

[glyph]

Closing so as not to have a duplicate, but your work is appreciated :).