Skip to content

HTTPCore Compatibility

HTTPCOREXYZ is a fork of HTTPCore. While most code can be migrated simply by replacing import httpcore with import httpcorexyz, there are situations where you cannot easily change every dependency — for example, when a third-party library checks isinstance(response, httpcore.Response) internally.

To handle this, importing httpcorexyz automatically registers it under the httpcore name in sys.modules:

import sys
import httpcorexyz

assert sys.modules["httpcore"] is sys.modules["httpcorexyz"]  # True

This means any subsequent import httpcore in the same process will resolve to httpcorexyz, and isinstance checks against httpcore classes will pass for httpcorexyz objects:

import httpcore   # resolves to httpcorexyz after the above
import httpcorexyz

response = httpcorexyz.Response(200, headers=[], content=b"")
assert isinstance(response, httpcore.Response)  # True

Prior art

This pattern — where the installable PyPI name differs from the importable module name, or where a fork registers itself under its predecessor's name — is well-established in the Python ecosystem:

  • Pillow / PIL — The actively maintained fork of the Python Imaging Library. It installs as Pillow on PyPI but exposes the PIL package, so all code written against the original PIL works without modification.
  • opencv-python / cv2 — The PyPI package is opencv-python; the module is cv2.
  • pyyaml / yaml — The PyPI package is pyyaml; the module is yaml.

Important caveat

The aliasing only takes effect if httpcore has not already been imported before httpcorexyz. If both packages are installed and httpcore is imported first, the alias will not be established.

For this reason, ensure that nothing in your codebase (or its dependencies) imports httpcore before httpcorexyz is imported. In practice, the simplest way to guarantee this is to import httpcorexyz early — for example, at the top of your application's entry point — before any other imports that might pull in httpcore.