Version 1.0 public call. 👋🏼

[lovelydinosaur]

Hiya team,

We're quickly narrowing in on a Version 1.0 release. ☺️ 🎉
I'd like to schedule a video call for interested parties in order to get some visibility onto...

• The Version 1.0 release plan, and deciding what will and will not make the cut.
• Outlining the project roadmap.
• Talking through sponsorship, contributions, and encode / project documentation.

If you'd be interested in joining a call could you comment against this issue and indicate availability...

• 9:00 am UTC, Weds 16th Oct. (a)
• 12:30 pm UTC, Weds 16th Oct. (b)
• 9:00 am UTC, Thurs 17th Oct. (c)
• 12:30 pm UTC, Thurs 17th Oct. (d)
• 9:00 am UTC, Fri 18th Oct. (e)
• 12:30 pm UTC, Fri 18th Oct. (f)

I'll update the ticket sometime on monday with a selected time and video link.

Thanks so much everyone for all your hard work and support. ✨🍰 ✨

(Paging @encode/maintainers & everyone else also.)

[RobertCraigie]

@tomchristie FYI the Version 1.0 release link is broken, it's pointing to this discussion instead of #3319

[lovelydinosaur]

😅 Resolved.

[lovelydinosaur]

(a,b,c,d,e,f)

[alexgmin]

(a,b,c,d,e,f)

Automatic time conversion to the viewer's timezone:
https://time.is/compare/0900_16_Oct_2024_in_UTC/ (a)
https://time.is/compare/1230_16_Oct_2024_in_UTC/ (b)
https://time.is/compare/0900_17_Oct_2024_in_UTC/ (c)
https://time.is/compare/1230_17_Oct_2024_in_UTC/ (d)
https://time.is/compare/0900_18_Oct_2024_in_UTC/ (e)
https://time.is/compare/1230_18_Oct_2024_in_UTC/ (f)

[RobertCraigie]

(a,b,c,d,e,f)

[ahopkins]

a, b, c, d

[RafaelWO]

d, f - but I cannot guarantee that I'll be able to attend

P.S. I'm not a contributor (yet) but I'm a happy and inspired user 🙂

[zanieb]

I can only do 12:30 slots, i.e. b, d, f with a preference for b, d.

I don't think it's a high priority for me to join, but interested in helping out.

[DarkPhily]

(e, f)

[alexgmin]

Since there are no updates I'm assuming it's not today?

[lovelydinosaur]

Hi all...

Let's have a public call tomorrow, Thursday 17th... 12:30 UTC

https://time.is/compare/1230_17_Oct_2024_in_UTC/

On this meeting link...

https://meet.google.com/dst-jytb-mbe

[Kludex]

Can you record it? I don't think I'll be able to attend.

[lovelydinosaur]

I'm not planning on recording this session, tho I'll keep it in mind for the future.
Will aim on taking more open calls, really helps to connect.
Perhaps see ya next time?

[zanieb]

I took some notes from the call — they're not perfect.

• Introductions
  • Tom Christie
  • Hugo
  • Alex Gomez Martin
  • Rafael
  • Zanie Blue
• 1.0 release
  • Announcement pull request for the release
    • Needs changelog
    • Context on why breaking changes are being made, e.g, the SSL API changes
    • Getting this further should help decisions on the changes
  • Is the SSL API correct?
    • In the current version we have the same interface as requests
    • We got rid of accepting various types and require an SSLContext specificially
    • It makes things like switching to truststore easier
    • It makes the API more coherent
    • Should the parameter be named ssl or ssl_context?
    • Should the parameter be named verify and take a bool still?
      • Would simplify migrations for users
  • Should we include more features based on a messaging perspective?
    • Usually it's no big deal to delay adding features but while we're
      making an announcement it could help encourage people to switch from requests
    • e.g., a full request timeout
  • Decreased dependency footprint
    • The async dependencies automatically install anyio and sniffio,
      but we don't need those by default
    • There's a pull request moving this to httpx[asyncio] or
      httpx[trio]
    • We should drop idna as a mandatory dependency
    • The entire dependency should be httpcore, certify, and,
      indirectly, h11
    • We should make httpcore and certify soft dependencies so they are
      only imported when they're used
    • Then httpx can be installed on platforms without SSL support i.e.
      javascript platforms
  • Stricter type checking
    • We're following the requests API in a bunch of places but we could
      constrain the types and support the same functionality
    • e.g., the proxy parameter can be a string, Url, or Proxy instance
    • e.g., the timeout parameter can be a float, tuple[float, ..], or a Timeout instance
    • e.g., the auth and headers parameters too
  • Should system proxies be on by default?
    • Always on by default right now, requires opt-out to disable
    • Should we make it opt-in instead?
  • We can be explicit about using semantic version
    • We can explicitly suggest 1.*
  • We should suggest style for imports
    • e.g., import httpx rather than from httpx import ...
    • Ensure that httpx modules are private so it's clear you shouldn't import them
• Feedback?
  • Alex
    • The main use-case is to set a simple timeout which should be easy to
      do, i.e., with an int or float
  • Hugo
    • Having a timeout at all is really important
    • I don't think there's any rush to release 1.0 but it seems like you're
      close
    • I think it's nice that the API is drop-in for main use-cases
  • Zanie
    • Maybe you use GitHub code search to see how people are using the
      verify parameter to guide that decision
    • An overall timeout seems really nice but I'd be wary of expanding
      scope of the releasesince the team is
      small
      • Actually, if you frame it as a breaking change for the default
        timeout behavior I think it makes more sense to put into 1.0 (as
        opposed to just a bigger announcement with more features)
      • Rust's lib has a overall timeout by default: https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.timeout
      • They don't have a write timeout which is tough for us: Add option to set write timeout seanmonstar/reqwest#2403
    • It's not clear that tightening the API types is a better user experience and could cause churn
• Project process
  • e.g., someone asks for something -> it's implemented
  • Prefer to start with a discussion still
  • Design-led process
  • Behavioral changes should be led by documentation
  • Allows focus on behavior changes rather than implementation changes
• Sponsorships
  • Django Fellowships have a good model
  • We should have transparency about how money is spent
  • Target incomes for developers
  • Create part-time positions
• Overall project aims
  • How can we reduce the complexity of the stack?
    • Less different ways to do things
    • Minimal footprints to the stack you're working with
  • When you drop into lower-level aspects it should be consistent
  • HTTP toolkit not just a client
  • It'd be nice to have a punchy tagline that differentiates it from other
    libraries

[RafaelWO]

It'd be nice to have a punchy tagline that differentiates it from other
libraries

What do you think about "Your all-in-one Python HTTP toolkit"? Or "The" instead of "Your".

[zanieb]

A few things we didn't talk about but probably should

1. Are we going to do pre-releases? Betas?
2. Are we going to write a specific migration guide?
3. Are we adding warnings to a pre-1.0 release that explains the upcoming migration?

[mcosta74]

Hello all, any ETA for v1.0 ?

[lovelydinosaur]

Hey y'all...

I've been working away on 1.0, and there's enough in place that I'm happy to show how the project's looking right now.
Little bit of a change here... I've been working privately on this for a change.

Here's the docs as they currently stand... https://www.encode.io/httpnext/

(Currently bit heavy on the tech details, just needed to get it across the line)

[T-256]

@RafaelWO IIUC, you need to have both sync/async in single package to use them? Can you describe your use cases of using both modes at same time in single codebase?

Nevertheless, I don't have insights into the benefits in terms of developer experience and maintainability

If your concern is about maintainability/contribution to that project, by what I understood, that going to be under one repository and duplicated works validated by unasync, and CI will show errors if anything wrong.

Also, for installation experience, AFAICT, httpx-v1.0 will be published under single name httpx in pypi and installs two packages to site-packages of your environment. IMO, this is a win for python app bundlers (e.g. pyinstaller).

[RafaelWO]

@T-256 One example of using both sync/async in a single package would be the following. You maintain a package to abstract some REST API that uses HTTPX under the hood. But not all of your users are using your async API. Perhaps you initially provided only a sync API to your users, and now you want to migrate to an async approach. For compatibility reasons, you want to support both sync and async.

Of course, one might argue that this also works if HTTPX is split into two packages. But as a user, remembering and using one package is always easier than two.

If your concern is about maintainability/contribution to that project, by what I understood, that going to be under one repository and duplicated works validated by unasync, and CI will show errors if anything wrong.

That is also how I understood the integration of unasync. But this does not force you to publish two packages.

Also, for installation experience, AFAICT, httpx-v1.0 will be published under single name httpx in pypi and installs two packages to site-packages of your environment. IMO, this is a win for python app bundlers (e.g. pyinstaller).

That would be new to me. According to the pre-release docs, you have to install them separately. At least separate pip install commands are currently listed:

pip install --pre httpx
# or
pip install --pre ahttpx

But if you are right regarding the bundling, the main difference is the root namespace (import httpx vs import ahttpx), correct?

---

Overall, my gut feeling is that splitting the package would mainly cause unnecessary pain. But as I said previously, others who built this awesome package (mainly Kim and the other contributors) for sure have more insights and better arguments for a split. Happy to read and understand more about the reasons and to revise my opinion 🙂

[RobertCraigie]

Hey, maintainer of openai-python and anthropic-python here - it looks like splitting the packages into sync and async variants would be very painful for us.

Would splitting the packages result in duplicates of all the common classes? e.g. httpx.Headers? If so, this would be very bad, it would make writing any sort of generic code over the sync / async versions very awkward.

We could package them together, tho there's plenty of namespace awkwardness to be had there. Eg. the current httpx.Client / httpx.AsyncClient proliferation.

For what its worth, I never found this split to be awkward, in fact we even have a similar setup ourselves with OpenAI() and AsyncOpenAI()! To me, entirely separate packages is much more awkward.

[lovelydinosaur]

Okay, that's really helpful feedback. Thank you.

[RobertCraigie]

Glad I could help! I'd be happy to help with anything else as well :)

[simonw]

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.

[Wauplin]

Hi there 👋 I'm a co-maintainer of huggingface_hub, the Python SDK to interact with the Hugging Face Hub (https://huggingface.co/). And a big fan of your work for the Python web ecosystem 🙏

I ended up on this thread as we are actively looking into switching from using requests+aiohttp to using httpx instead. We have several reasons for this (HTTP/2 support), but the main one is to provide a consistent experience whether users are using our sync or async methods. Reading this thread, I totally relate to @simonw's concerns around supporting versions of httpx that are deeply incompatible. As our library is meant to be integrated into other tools, we cannot pin httpx version ourselves without blocking our dependents. We were not directly impacted by pydantic's upgrade but I witnessed it and don't want to fall into this pit either 😄

I genuinely don't have options to suggest other than @simonw 's "httpx2". I really enjoy using httpx in my other projects so I’d love to integrate it into huggingface_hub as well, as long as we can be confident the API will stay stable over time.

[hugovk]

If HTTPX 1.0 is released as httpx2, will HTTPX 2.0 be released as httpx3?

Or is the hope that breaking changes in subsequent major releases won't be as significant and it can continue as httpx2?

[agronholm]

Why do the async/sync clients even have to have different top-level package names? All other projects seem to handle that without such shenanigans.

[bunny-therapist]

If it is httpx 1.0, why not call it httpx1 to keep the numbers in sync?

[CarliJoy]

I have another idea.

What if we introduce a httpx.v1.* namespace and keep a copy of the existing implementation within httpx, but mark it as deprecated?

Under this approach, we could define that the legacy API is removed in version 1.1, or—if we adhere strictly to semantic versioning—removed in 1.0.

The core idea is to allow both the old and the new APIs to coexist within the same package for a defined transition period, while clearly deprecating the old one. This avoids breaking downstream projects that cannot migrate immediately and do not update all dependencies simultaneously.

This approach eliminates the need for additional PyPI package names and remains future-proof with respect to a potential v2 API.

This also reduces cognitive overhead. Introducing a new PyPI package name forces users to reason about multiple packages and their relationship. Keeping both APIs in a single distribution provides a clearer upgrade path and allows users to migrate incrementally without having to adopt or understand a parallel package.

Having to type three extra characters in imports is a small price to pay for a stable, upgradeable API.

[Ravencentric]

I want to echo what @RobertCraigie said. The reason I moved away from requests is that httpx offered a single, unified interface for both sync and async in one package. This made it easy for me to do the same and provide both FooBarClient and AsyncFooBarClient without juggling multiple dependencies. Python does not have a concept of optional extras that can be removed, so a package like mine, which relies on httpx to provide both client variants, would be forced to pick a default.

Consider this scenario:

foobar depends on httpx and provides both FooBarClient and AsyncFooBarClient. Now imagine httpx 1.0 splits async into a separate ahttpx package. My options are:

1. Require both httpx and ahttpx for everyone, even though almost no one needs both.
2. Pick a default, for example sync, and move async to an async extra. Users who want async clients cannot avoid depending on the sync client. They must install both httpx and ahttpx even if they will never use the sync client.
3. Ship a broken package that forces users to install either foobar[httpx] or foobar[ahttpx] just to get a working client.

Essentially, a package like mine will be forced to depend on both one way or another. You could argue this is the case today, since httpx ships both and users do not get a choice, but separating it into multiple packages will inherently make things more complicated.

[KalleDK]

While i do agree with you about not splitting them up, I also wanna mention that a solution could be foobar and afoobar... and possible foobar, afoobar and sfoobar... I don't know if it's a good solution, but I understand it.

[KalleDK]

Hi @lovelydinosaur thanks for all your work!

I have a few note to the middleware (which I don't find a lot of info about)

As I understand, the Idea is to have functions like FollowRedict, Cookies and Auth nested in transport?!
So one might do
Client -> Auth -> FollowRedirect -> Cookies -> Transport
Is there any thoughts on how the layers might be able to communicate?

• User might want to always FollowRedict (except in a few calls)
• User might want to alwayt FollowRedict, but the Auth layer might need to not do that.
• How would Auth access the Cookies in the CookiesLayer (and also the users access to it)

This stems from some Auth libraries that I'm making, that would be used by multiple other libraries (that I don't control).
So how would I conway that if you use my Auth middleware, then you need to have a cookiestore and keep it below me / above me?

And a bonus question, this would mean that the Auth aproach with yielding is to be changed to a Transport?