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)

[RafaelWO]

May I ask why would you want to separate the sync from the async version in terms of PyPI packages? At least that is what I understand from the docs as ahttpx has a separate install instruction.

You could still have different a namespace/package for sync compared to async but keep it in a single shipped package, right?
I feel like splitting it up makes it unnecessary complex, IMO. (I am not actively maintaining httpx so I might be wrong here.)

Also, I can imagine that there are some utility functions which both versions would use - are you thinking about a third "core" package?

[lovelydinosaur]

There's not any great options wrt. handling both async and sync dialects within Python.

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

A direct mirroring using the unasync approach just seems neatest. (PyPI / GitHub)

[RafaelWO]

I am still not fully convinced that splitting sync and async into different packages is a benefit - at least in terms of user experience.

The new tagline of HTTPX is "A complete HTTP toolkit for Python" and I would expect to have access to both sync and async in the package - as it is now 🙂

For me, splitting the toolkit into two packages would be similar to HTTPie having a separate installable package for the commands http and https (which is not the case).

Another example would be elasticsearch-py - a user of unasync. But they bundle both sync and async into one elasticsearch package (see docs and repo).

Nevertheless, I don't have insights into the benefits in terms of developer experience and maintainability. Do you have a short write-up of the rationale and reasons behind splitting the package?

[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.

[lovelydinosaur]

Hiya!

Yep the project could totally have a different PyPI name. Getting that right is the thing ain't it?

I've considered various options here, including having the project be URL instabable and not PyPI installable. Or having strictly pinned package names such as import httpx-1.0.0 as httpx. Those ideas probably take us a little bit too off the standard track, so maybe let's be a little bit boring and conventional and just consider PyPI naming options? (...)

• httpx2 isn't the worst, tho doesn't exactly roll off the tongue. The async variant would be... ahttpx2 ...odd?

The design is enough of an evolution that could have a rename...

• The urllib3 team put a chunk of time into a project hip a few years ago with similar design aims. That's been discontinued since a while back. Might be worth an ask if they'd be up for releasing the PyPI package space.

Open to other options (?...)

[RafaelWO]

httpnext is currently reserved but the last commit to the repo was 10 years ago. You could ask the person in charge whether you can take the name?

[lovelydinosaur]

I don't really want to call it httpnext - that was just a working title.

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'd prefer it if we could avoid httpx2 as the rename since it's a bit unwieldy, tho you might be right.

[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?