Httpx: Blockers for 1.0 release.

[tomchristie]

List of things that I currently think are required for a 1.0 release.

We should try to keep this scope as narrow as possible. Anything related to the external API is fair game, plus any critical level implementation issues.

Anything else that doesn't meet those criteria should be regarded as not strictly required for 1.0.

• [ ] Implement parallel requests. (See #52)
• [x] Make URL support str comparison. (See #113) Easy contributor issue
• [ ] Finesse URL interface, focusing on str vs bytes and escaped vs non-escaped. (eg. nail down questions like - does authority return a string that's idna-escaped or not?)
• [ ] Finesse stream interfaces. (Both upload and download. Eg. response.raw and response.stream are currently a bytes async iterator. I think we probably want it to be a stream interface. Related to #123, #24)
• [x] Review auth and/or retry interface. (We have a dispatcher interface already, but it's overly involved for what we really want here. Requests uses callback hooks for more complex cases here, see https://github.com/encode/httpx/pull/136#discussion_r305946280 but I'm not super keen on that. A simple middleware interface might be appropriate(?) and would be sufficient for both retries and auth requirements. (Related to #295, #345)
• [x] Review potentially critical issue #96
• [ ] I don't think the read/write timeout switchover is quite right yet. (Related to https://github.com/encode/httpx/issues/191)
• [ ] I think we've got some outstanding race conditions if a Client is used w/ multi-threading. asgiref gets it right - need to take the same kind of approach.
• [ ] Finish documentation. Esp "Advanced" section, and API docs. (Related to #343)
• [ ] Ensure alternate concurrency backends are adequately supported. (Not neccessarily in core, but really would like to concretely demonstrate that we're providing adequate API to support that use-case) Refs #120
• [ ] Review exception heirarchy, and any API on exceptions. (Related to #141)
• [ ] Review dispacth interface.

Am I missing anything else that strictly needs to get onto this list?

[sethmlarson]

Do we want to make proxy support a part of 1.0?

[tomchristie]

I think we could probably either take it or leave it.

[sethmlarson]

Also I know you've already got mkdocs setup, but what are your thoughts on switching to Sphinx to get code referencing to work? For example currently you can't click on httpx.Client and go to where it's documented.

We can pull all the styling from the current docs into a template so the look and feel will be the same.

[tomchristie]

Personally, I'd prefer not too. Or at least not unless we're streamlining a whole bunch of related projects under python-http. As long as it's something under encode I'd like to see it in-line with how other projects in this org are being managed - that keeps things simple from my POV.

Instead I'd rather get around to adding better interlinking and API docs generation to mkdocs.

[tomchristie]

May well be that my gauge on that evolves as things go, but that'd be where I'm at right now.

[StephenBrown2]

Re: mkdocs, pydoc-markdown handles the auto-generation of mkdocs pages from docstrings. It's not quite as smart as Sphinx in that it doesn't do cross-references well yet, though that's apparently planned for 3.x. I'd love to see it or mkdocs gain support for that.

[florimondmanca]

Hey, should we make use of milestones to track work left to do for 1.0? And perhaps pin this issue so we can easily find it back/keep focus? :)

Also I think we can tick “Review Auth/retry interface” thanks to middleware?

[tomchristie]

Hey, should we make use of milestones to track work left to do for 1.0?

Probably, yes. There's certainly at the very least a clear distinction between "stuff required for 1.0" and "stuff not stictly required for 1.0", and it'd be good for us to start to narrow in on the target at this point.

[florimondmanca]

I went ahead and pinned this issue, as well as marked a bunch of issues (some of them already closed so we don't feel like everything remains to be done 😄) as part of v1.0: https://github.com/encode/httpx/milestone/1. I also edited the issue description with more related issues so we can better see whether we addressed the various points in the near future.

[tomchristie]

Closing this off as gone-stale.