Httpx: Private module names

[tomchristie]

I've noticed a couple of projects lately which use private module names inside the package...

• https://github.com/python-hyper/h11/tree/master/h11
• https://github.com/oremanj/tricycle/tree/master/tricycle

I'd initially found it an odd style, but actually it's a really smart approach, that helps you enforce that only the top-level API that you're exposing is actually public API.

For example, right now users might do something like...

from httpx.config import SSLConfig
from httpx.models import Origin
from httpx.auth import FunctionAuth

None of which are actually considered public API by us, but that's not immediately obvious to the user.

We've mentioned in chat or elsewher (I don't recall) that we really want to ensure our users are only ever using import httpx or from httpx import <SOMETHING>, and yes we could simply mention that in our documentation. But actually it'd be far clearer if we actually used private module names, and enforced that users would be aware if they choose to import and use non-public API.

This isn't strictly a breaking API change, but we would only want to make it on a median version bump (0.12.0 or 1.0.0), since it's likely that at least some of our users are currently using sub-module import styles.

We'd also want to update our test cases so that we're using public API wherever possible, and so that it's clearer where there are cases that we're using private API (which would either indicate unit-testing to an extent, or that we've got some part of API that we're planning to expose, but haven't yet finalised on.)

I think we might also want to do a bit of rejigging of how we handle __all__ with this too. We probably don't actually want to support from httpx import *.

Somewhat related to this is that we've got a bunch of methods on classes that we don't document, aren't treating as public API, and probably ought to move into private methods. (Eg. on the Client everything "below" .build_request and .send should probably be private API.) However, let's treat that as a seperate issue to be discussed.

[florimondmanca]

💯 yes to this! Agreed that we can start with private modules/sub-packages, and then review methods on public classes later.

[tomchristie]

💯 yes to this!

Fantastic! I think this would be a good enough motivation to release a 0.12.0, where we start bolting down our public API. 👍

[lepture]

Can you make ByteStream and AsyncDispatcher public? We need them in https://github.com/lepture/authlib/pull/209/files