Tighten up top-level API to only expose public API

docs/advanced.md

@@ -243,7 +243,7 @@ Proxies can be configured to have different behavior such as forwarding or tunne
 ```python
 proxy = httpx.HTTPProxy(
     proxy_url="https://127.0.0.1",
-    proxy_mode=httpx.HTTPProxyMode.TUNNEL_ONLY
+    proxy_mode="TUNNEL_ONLY"  # May be "TUNNEL_ONLY" or "FORWARD_ONLY". Defaults to "DEFAULT".
 )
 async with httpx.Client(proxies=proxy) as client:
     # This request will be tunneled instead of forwarded.

httpx/__init__.py

@@ -2,23 +2,11 @@
 from .api import delete, get, head, options, patch, post, put, request, stream
 from .auth import BasicAuth, DigestAuth
 from .client import Client
-from .concurrency.asyncio import AsyncioBackend
-from .concurrency.base import BasePoolSemaphore, BaseSocketStream, ConcurrencyBackend
-from .config import (
-    USER_AGENT,
-    CertTypes,
-    PoolLimits,
-    SSLConfig,
-    Timeout,
-    TimeoutConfig,
-    TimeoutTypes,
-    VerifyTypes,
-)
-from .dispatch.base import Dispatcher
-from .dispatch.connection import HTTPConnection
-from .dispatch.connection_pool import ConnectionPool
+from .config import TimeoutConfig  # For 0.8 backwards compat.
+from .config import PoolLimits, Timeout
 from .dispatch.proxy_http import HTTPProxy, HTTPProxyMode
 from .exceptions import (
+    ConnectionClosed,
     ConnectTimeout,
     CookieConflict,
     DecodingError,
@@ -38,23 +26,7 @@
     TooManyRedirects,
     WriteTimeout,
 )
-from .models import (
-    URL,
-    AuthTypes,
-    Cookies,
-    CookieTypes,
-    Headers,
-    HeaderTypes,
-    Origin,
-    QueryParams,
-    QueryParamTypes,
-    Request,
-    RequestData,
-    RequestFiles,
-    Response,
-    ResponseContent,
-    URLTypes,
-)
+from .models import URL, Cookies, Headers, Origin, QueryParams, Request, Response
 from .status_codes import StatusCode, codes
 
 __all__ = [
@@ -71,24 +43,18 @@
     "put",
     "request",
     "stream",
+    "codes",
     "BasicAuth",
     "Client",
     "DigestAuth",
-    "AsyncioBackend",
-    "USER_AGENT",
-    "CertTypes",
     "PoolLimits",
-    "SSLConfig",
     "Timeout",
-    "TimeoutConfig",
-    "VerifyTypes",
-    "HTTPConnection",
-    "BasePoolSemaphore",
-    "ConnectionPool",
+    "TimeoutConfig",  # For 0.8 backwards compat.
     "HTTPProxy",
-    "HTTPProxyMode",
+    "HTTPProxyMode",  # For 0.8 backwards compat.
     "ConnectTimeout",
     "CookieConflict",
+    "ConnectionClosed",
     "DecodingError",
     "HTTPError",
     "InvalidURL",
@@ -106,25 +72,14 @@
     "WriteTimeout",
     "BaseSocketStream",
     "ConcurrencyBackend",
-    "Dispatcher",
     "URL",
-    "URLTypes",
     "StatusCode",
-    "codes",
-    "TimeoutTypes",
-    "AuthTypes",
     "Cookies",
-    "CookieTypes",
     "Headers",
-    "HeaderTypes",
     "Origin",
     "QueryParams",
-    "QueryParamTypes",
     "Request",
-    "RequestData",
     "TimeoutException",
     "Response",
-    "ResponseContent",
-    "RequestFiles",
     "DigestAuth",
 ]

httpx/dispatch/proxy_http.py

@@ -1,5 +1,6 @@
 import enum
 import typing
+import warnings
 from base64 import b64encode
 
 import h11
@@ -25,11 +26,18 @@
 
 
 class HTTPProxyMode(enum.Enum):
+    # This enum is pending deprecation in order to reduce API surface area,
+    # but is currently still around for 0.8 backwards compat.
     DEFAULT = "DEFAULT"
     FORWARD_ONLY = "FORWARD_ONLY"
     TUNNEL_ONLY = "TUNNEL_ONLY"
 
 
+DEFAULT_MODE = "DEFAULT"
+FORWARD_ONLY = "FORWARD_ONLY"
+TUNNEL_ONLY = "TUNNEL_ONLY"
+
+
 class HTTPProxy(ConnectionPool):
     """A proxy that sends requests to the recipient server
     on behalf of the connecting client.
@@ -40,7 +48,7 @@ def __init__(
         proxy_url: URLTypes,
         *,
         proxy_headers: HeaderTypes = None,
-        proxy_mode: HTTPProxyMode = HTTPProxyMode.DEFAULT,
+        proxy_mode: str = "DEFAULT",
         verify: VerifyTypes = True,
         cert: CertTypes = None,
         trust_env: bool = None,
@@ -49,6 +57,15 @@ def __init__(
         backend: typing.Union[str, ConcurrencyBackend] = "auto",
     ):
 
+        if isinstance(proxy_mode, HTTPProxyMode):
+            warnings.warn(
+                "The 'HTTPProxyMode' enum is pending deprecation. "
+                "Use a plain string instead. proxy_mode='FORWARD_ONLY', or "
+                "proxy_mode='TUNNEL_ONLY'."
+            )
+            proxy_mode = proxy_mode.value
+        assert proxy_mode in ("DEFAULT", "FORWARD_ONLY", "TUNNEL_ONLY")
+
         super(HTTPProxy, self).__init__(
             verify=verify,
             cert=cert,
@@ -216,8 +233,8 @@ def should_forward_origin(self, origin: Origin) -> bool:
         tunnel all 'HTTPS' requests.
         """
         return (
-            self.proxy_mode == HTTPProxyMode.DEFAULT and not origin.is_ssl
-        ) or self.proxy_mode == HTTPProxyMode.FORWARD_ONLY
+            self.proxy_mode == DEFAULT_MODE and not origin.is_ssl
+        ) or self.proxy_mode == FORWARD_ONLY
 
     async def send(
         self,

tests/client/test_auth.py

@@ -4,18 +4,9 @@
 
 import pytest
 
-from httpx import (
-    URL,
-    CertTypes,
-    Client,
-    DigestAuth,
-    Dispatcher,
-    ProtocolError,
-    Request,
-    Response,
-    TimeoutTypes,
-    VerifyTypes,
-)
+from httpx import URL, Client, DigestAuth, ProtocolError, Request, Response
+from httpx.config import CertTypes, TimeoutTypes, VerifyTypes
+from httpx.dispatch.base import Dispatcher
 
 
 class MockDispatch(Dispatcher):

tests/client/test_cookies.py

@@ -3,16 +3,9 @@
 
 import pytest
 
-from httpx import (
-    CertTypes,
-    Client,
-    Cookies,
-    Dispatcher,
-    Request,
-    Response,
-    TimeoutTypes,
-    VerifyTypes,
-)
+from httpx import Client, Cookies, Request, Response
+from httpx.config import CertTypes, TimeoutTypes, VerifyTypes
+from httpx.dispatch.base import Dispatcher
 
 
 class MockDispatch(Dispatcher):

tests/client/test_headers.py

@@ -4,17 +4,9 @@
 
 import pytest
 
-from httpx import (
-    CertTypes,
-    Client,
-    Dispatcher,
-    Request,
-    Response,
-    TimeoutTypes,
-    VerifyTypes,
-    __version__,
-    models,
-)
+from httpx import Client, Headers, Request, Response, __version__
+from httpx.config import CertTypes, TimeoutTypes, VerifyTypes
+from httpx.dispatch.base import Dispatcher
 
 
 class MockDispatch(Dispatcher):
@@ -132,7 +124,7 @@ async def test_header_update():
 
 
 def test_header_does_not_exist():
-    headers = models.Headers({"foo": "bar"})
+    headers = Headers({"foo": "bar"})
     with pytest.raises(KeyError):
         del headers["baz"]
 

tests/client/test_proxies.py

@@ -40,7 +40,6 @@ def test_proxies_has_same_properties_as_dispatch():
     pool = client.dispatch
     proxy = client.proxies["all"]
 
-    assert isinstance(pool, httpx.ConnectionPool)
     assert isinstance(proxy, httpx.HTTPProxy)
 
     for prop in [
@@ -101,7 +100,6 @@ def test_dispatcher_for_request(url, proxies, expected):
     dispatcher = client.dispatcher_for_url(httpx.URL(url))
 
     if expected is None:
-        assert isinstance(dispatcher, httpx.ConnectionPool)
         assert dispatcher is client.dispatch
     else:
         assert isinstance(dispatcher, httpx.HTTPProxy)

tests/client/test_queryparams.py

@@ -2,17 +2,9 @@
 
 import pytest
 
-from httpx import (
-    CertTypes,
-    Client,
-    Dispatcher,
-    QueryParams,
-    Request,
-    Response,
-    TimeoutTypes,
-    VerifyTypes,
-)
-from httpx.models import URL
+from httpx import URL, Client, QueryParams, Request, Response
+from httpx.config import CertTypes, TimeoutTypes, VerifyTypes
+from httpx.dispatch.base import Dispatcher
 
 
 class MockDispatch(Dispatcher):

tests/client/test_redirects.py

@@ -5,19 +5,17 @@
 
 from httpx import (
     URL,
-    CertTypes,
     Client,
-    Dispatcher,
     NotRedirectResponse,
     RedirectBodyUnavailable,
     RedirectLoop,
     Request,
     Response,
-    TimeoutTypes,
     TooManyRedirects,
-    VerifyTypes,
     codes,
 )
+from httpx.config import CertTypes, TimeoutTypes, VerifyTypes
+from httpx.dispatch.base import Dispatcher
 
 
 class MockDispatch(Dispatcher):

tests/concurrency.py

@@ -9,7 +9,7 @@
 
 import trio
 
-from httpx import AsyncioBackend
+from httpx.concurrency.asyncio import AsyncioBackend
 from httpx.concurrency.trio import TrioBackend
 
 

tests/conftest.py

@@ -17,7 +17,8 @@
 from uvicorn.config import Config
 from uvicorn.main import Server
 
-from httpx import URL, AsyncioBackend
+from httpx import URL
+from httpx.concurrency.asyncio import AsyncioBackend
 from httpx.concurrency.trio import TrioBackend
 
 ENVIRONMENT_VARIABLES = {