PEP 748: tlslib - context & socket by Julien00859 · Pull Request #4960 · python/peps

Julien00859 · 2026-05-06T23:02:50Z

PEP 748: create_connection and create_server instead of connect

Prior discussions at:

That commit is the solution to my struggle binding an Ipv6 localhost address when I first tested tlslib. At the time the library was always binding the socket using family=AF_INET. The solution we implemented in tlslib is to perform a DNS request on the user-provided address to determine the family to use (family=AF_INET6 in my case).

I'm still unhappy with this API server-side. "connect" is the wrong verb, it should be "bind". It is not obvious if other sockets are supported (e.g. Unix Domain Socket).

create_connection and create_server make so much more sense to me, at least as long as we don't have a wrap_socket function.

PEP 748: shutdown(show: 0|1|2) instead of close(force: bool)

Prior discussions:

Work in progress in siotls:

https://codeberg.org/drlazor8/siotls/pulls/26

The messages I wrote on the forum explain the problems I have with close(force: bool), which mainly boils down to "it feels too TLS 1.2-ish". I spent many days exploring ideas to have a clean API to terminate the TLS connection a way that is safe in both TLS 1.2 (synchronous termination) and TLS 1.3 (asynchronous and IMO better). Reusing socket's shutdown terminology feels right to me. It works well for TLS 1.3 and is fine for TLS 1.2.

There are other things in the current Buffer & Socket spec that I find are leaking openssl's API, and that I expect won't work very well with other TLS libraries (including my own) but I'm not ready at this time to make new proposals.

Ease reading the diff of the next commits.

python-cla-bot · 2026-05-06T23:02:53Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-05-06T23:06:51Z

Documentation build overview

📚 pep-previews | 🛠️ Build #32670054 | 📁 Comparing bc67f9f against latest (c093d5f)

🔍 Preview build

709 files changed · ± 709 modified

± Modified

hugovk · 2026-05-08T12:17:20Z

cc PEP authors @jvdprng and @woodruffw.

jvdprng

Thanks for writing this up!

I feel like this pulls a lot of socket API surface into the PEP. Couldn't we stick to a minimum API surface that leaves a bunch of socket options to the backends? E.g., something like:

  class ClientContext(Protocol):
      def connect(
          self,
          address: tuple[str | None, int],
          *,
          server_hostname: str | None = None,
          timeout: float | None = None,
      ) -> TLSSocket: ...

  class ServerContext(Protocol):
      def create_server(
          self,
          address: tuple[str | None, int],
          *,
      ) -> TLSListener: ...

I'm not sure whether splitting out 'listening sockets' and 'connected sockets' is a good idea, but it would solve some of the current blurriness around listen/accept. In general, I'm hesitant to pull in a bunch of socket stuff without discussing this on the PEP boards first.

If we do want to go down this route, we should probably also specify in the PEP that we want to focus on INET sockets. I've left some comments regarding cleaning up types in that case.

The shutdown changes are definitely needed, but I feel like the current PR overspecifies a little.

jvdprng · 2026-05-12T09:24:44Z

+            self,
+            address: tuple[str | None, int],
+            *,
+            family=AF_INET,


Do we want to set AF_INET as the default here? We could have None that lets the backend choose based on the address?

I only replicated the socket.create_server API which uses family=AF_INET by default. To me it is either we stick precisely to the same signature as socket.create_server, or we use another function name.

jvdprng · 2026-05-12T09:46:36Z

-            received from the other side.
-            In either case, this method should return WantWriteError if sending the
-            close_notify alert currently fails."""
+        def shutdown(self, how: Literal[0, 1, 2]) -> None:


I'm worried that the current shutdown / close descriptions may be overspecified for the PEP. Should we focus on describing the observable behavior?

shutdown(SHUT_WR) gracefully closes the TLS sending side

shutdown(SHUT_RD) and shutdown(SHUT_RDWR) may discard unread peer data and are unsafe unless truncation is not an issue

close() should only fully close the transport when safe, otherwise it should raise WantReadError/WantWriteError as appropriate

Also, should we define a specific enum for how? Using literals might be brittle.

+1 about the over-specification, your shorter text is better indeed

The best would indeed to type how using an enum, but I'm afraid such an enum doesn't exist. The right place for such an enum would be socket, but in socket there already are the three global integers socket.SHUT_RD/WR/RDWR and deprecating those in favor of an enum doesn't seem right to me.

Maybe we can type if using Literal[socket.SHUT_RD, socket.SHUT_WR, socket.SHUT_RDWR] instead of [0, 1, 2]. Not sure how it would render in a sphinx/pdoc documentation though :(

Maybe we can type if using Literal[socket.SHUT_RD, socket.SHUT_WR, socket.SHUT_RDWR] instead of [0, 1, 2]. Not sure how it would render in a sphinx/pdoc documentation though :(

Doesn't work :(

$ uv run ty check src/siotls/socket.py error[invalid-type-form]: Type arguments for `Literal` must be `None`, a literal value (int, bool, str, or bytes), or an enum member --> src/siotls/socket.py:178:44 | 176 | logger.debug('%s/%s bytes sent', out_data_sent, len(out_data)) 177 | 178 | def shutdown(self, how: typing.Literal[socket.SHUT_RDWR]) -> None: | ^^^^^^^^^^^^^^^^ 179 | """ 180 | Shutdown TLS and the underlying socket. | info: rule `invalid-type-form` is enabled by default Found 1 diagnostic

Why should the enum be in socket? I think it's actually better to define something like a TLSShutdownMode enum here, because the first step is to close the TLS connection and the second is to close the socket. Each backend is then free to determine how to close the socket.

I can't help but think we are duplicating the information, would you agree to wait for a third opinion?

I've pushed a shorter docstring for shutdown().

I decided to keep the docstring of close() mostly as it was. That close() raises exceptions in TLSSocket when it does not with regular sockets is gonna be a big surprise to users. I think it warrant a lengthier docstring, and the current one is IMO a good fit.

The commit is in a fixup! because I spent too many hours coming with the original one, that's my way of not loosing my work 🥲. It'll will eventually be squashed don't worry.

jvdprng · 2026-05-12T09:52:36Z

+            backlog=None,
+            reuse_port=False,
+            dualstack_ipv6=False,
+        ) -> TLSSocket:


Do we want stronger typing for the TLS sockets? Both 'listening sockets' and 'connected sockets' are still the same type.

I decided to implement them using stronger types in siotls, but IMO we need not to enforce it in the spec.

The `connect()` function is poorly named server-side as it actually `bind()` the socket. Server-side the function lacks a `family` parameter to support IPv6 without a DNS lookup. Actually all three `connect()`, `bind()` and `listen()` socket function are pretty low-level. The high-level `create_connection` (for `connect`) and `create_server` (for `bind()` + `listen()`) are more pythonic. Wrap the latter and not the former, also to remove the need of a `listen()` method on the created socket (which is useless client-side).

Julien00859 added 2 commits April 28, 2026 23:48

PEP 748: materialize the server context

539e879

Ease reading the diff of the next commits.

PEP 748: server context create_buffer takes no server_hostname

791d34e

Julien00859 requested a review from ncoghlan as a code owner May 6, 2026 23:02

hugovk changed the title ~~PEP748 tlslib - context & socket~~ PEP 748: tlslib - context & socket May 8, 2026

jvdprng suggested changes May 12, 2026

View reviewed changes

Julien00859 added 3 commits May 13, 2026 11:39

PEP 748: shutdown(show: 0|1|2) instead of close(force: bool)

54723e3

fixup! PEP 748: shutdown(show: 0|1|2) instead of close(force: bool)

bc67f9f

Julien00859 force-pushed the Julien00859/tlslib-context branch from 3d40e2f to bc67f9f Compare May 13, 2026 09:39

Uh oh!

Conversation

Julien00859 commented May 6, 2026

Uh oh!

python-cla-bot Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

hugovk commented May 8, 2026

Uh oh!

jvdprng left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

python-cla-bot Bot commented May 6, 2026 •

edited

Loading

read-the-docs-community Bot commented May 6, 2026 •

edited

Loading