Simon Willison’s Weblog

Comment My comment on encode/httpx: Version 1.0 public call. — GitHub

I'm not thrilled about the 1.0 version changing the design of HTTPX so thoroughly - it looks like it's splitting httpx and ahttpx into entirely separate packages.

Python's single biggest weakness when it comes to dependency management is that it isn't possible to install two different versions of a package in the same environment. This makes backwards-incompatible changes really painful, because they lead to a prolonged period where different third-party dependencies may themselves require conflicting versions of another dependency.

This happened with Pydantic 2 and it was miserable - there was a solid 8-12 month period where depending on Pydantic could actively harm a project if that project also depended on something else that used Pydantic 1 - you couldn't upgrade to 2 until your dependency also upgraded to 2, and if you wanted to depend on libraries X and Y where X depended on Pydantic 1 and Y depended on Pydantic 2 your project just couldn't be built using those libraries!

I fear that an HTTPX breaking change could be even more painful than the Pydantic one was.

Consider two of the most popular libraries for interfacing with LLMs - Anthropic and OpenAI's.

https://github.com/anthropics/anthropic-sdk-python/blob/main/pyproject.toml depends on "httpx>=0.25.0, <1".

https://github.com/openai/openai-python/blob/main/pyproject.toml depends on "httpx>=0.23.0, <1".

There are plenty of other projects that depend on both - anything that attempts to provide an abstraction layer over multiple LLM providers, for example (cough).

Now what happens if HTTPX 1.0 comes out with a breaking API, and Anthropic upgrade to it but OpenAI don't? Any package that depends on both of those underlying packages will be stuck in a no-mans land - it will be forced to stick with HTTPX<1.0 and pin the older version of the Anthropic package, then will be blocked waiting for OpenAI to ship their upgrade.

It's not just LLM packages though. Show me Python software that doesn't use an HTTP client these days! https://github.com/encode/httpx/network/dependents lists 527,282 repositories and 13,654 packages. Will every one of those need to make changes to handle the switch to HTTPX 1.0?

I understand that complaining about a 0.x to 1.0 having breaking changes is distinctly uncool of me. That's the whole point of a pre-1.0 version number, at least for projects that follow SemVer.

I have to admit: I had optimistically hoped that HTTPX wasn't going to follow SemVer given the Python ecosystem's uniquely painful response to breaking changes in major packages that other packages depend on.

If I'd know this was going to happen I would have tried to find some other post-1.0 HTTP library to build all of my stuff around!

Solution: call the package httpx2!

I don't like complaining without offering solutions, so here's the one way I can see that this change could be implemented while avoiding all of that pain: change the package name.

If httpx2 came out with this new design, leaving httpx in place, all of these problems go away.

Some projects can switch tohttpx2 as their client library. Old projects can stick with httpx. If my project needs to mix and match dependencies that don't agree on that version then it's fine - I can have both httpx and httpx2 installed in the same environment at the same time.

Mark httpx as deprecated and no longer supported (and/or offer to keep on patching it in exchange for paid sponsorship of the work). Make httpx2 clearly the better option.

That way projects get to switch to httpx2 - and handle the breaking changes - on their own time and without causing any pain for other projects that depend on them but are not yet ready to upgrade their other uses.

I really, really wish Pydantic had done this with their Pydantic 2 upgrade.

I get that it feels ugly to have a 2 on the end of the name - jinja2 got stuck with that seventeen years ago. But I think that tiny bit of ugliness may be a price to pay for shipping significant breaking changes to a library with 500,000 existing users.