Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Annotate URLPath protocol parameter with Literal#3285

Merged
Kludex merged 4 commits into
Kludex:mainfrom
Chang-LeHung:refactor/literal-string-type-hints
Jun 10, 2026
Merged

Annotate URLPath protocol parameter with Literal#3285
Kludex merged 4 commits into
Kludex:mainfrom
Chang-LeHung:refactor/literal-string-type-hints

Conversation

@Chang-LeHung

@Chang-LeHung Chang-LeHung commented May 23, 2026

Copy link
Copy Markdown
Contributor
  • Define an ASGIProtocol = Literal["http", "websocket", ""] type alias in starlette/types.py.
  • Replace the plain str annotation on URLPath.__new__ and URLPath.__init__'s protocol parameter with ASGIProtocol, so static type checkers can catch invalid values at analysis time.
  • The existing runtime assert is kept as a safety net for dynamic usage.

Chang-LeHung and others added 2 commits May 23, 2026 16:14
Replace the plain `str` annotation on `URLPath.__new__` and `URLPath.__init__`
with a `ASGIProtocol` Literal type (`"http" | "websocket" | ""`), so static
type checkers can catch invalid values at analysis time. The runtime `assert`
is kept as a safety net.
@Kludex

Kludex commented May 23, 2026

Copy link
Copy Markdown
Owner

Where is empty string passed?

@Chang-LeHung

Chang-LeHung commented May 23, 2026

Copy link
Copy Markdown
Contributor Author

The empty string "" is the default value for the protocol parameter. It's used when callers omit protocol, for example in Mount.url_path_for and Host.url_path_for:

def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
if self.name is not None and name == self.name and "path" in path_params:
# 'name' matches "<mount_name>".
path_params["path"] = path_params["path"].lstrip("/")
path, remaining_params = replace_params(self.path_format, self.param_convertors, path_params)
if not remaining_params:
return URLPath(path=path)
elif self.name is None or name.startswith(self.name + ":"):

def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
if self.name is not None and name == self.name and "path" in path_params:
# 'name' matches "<mount_name>".
path = path_params.pop("path")
host, remaining_params = replace_params(self.host_format, self.param_convertors, path_params)
if not remaining_params:
return URLPath(path=path, host=host)

In these cases the protocol is unknown at that point β€” it gets resolved later when a child route (like Route or WebSocketRoute) provides "http" or "websocket".

@Chang-LeHung

Copy link
Copy Markdown
Contributor Author

The empty string "" is the default value for the protocol parameter. It's used when callers omit protocol, for example in Mount.url_path_for and Host.url_path_for:

def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
if self.name is not None and name == self.name and "path" in path_params:
# 'name' matches "<mount_name>".
path_params["path"] = path_params["path"].lstrip("/")
path, remaining_params = replace_params(self.path_format, self.param_convertors, path_params)
if not remaining_params:
return URLPath(path=path)
elif self.name is None or name.startswith(self.name + ":"):

def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
if self.name is not None and name == self.name and "path" in path_params:
# 'name' matches "<mount_name>".
path = path_params.pop("path")
host, remaining_params = replace_params(self.host_format, self.param_convertors, path_params)
if not remaining_params:
return URLPath(path=path, host=host)

In these cases the protocol is unknown at that point β€” it gets resolved later when a child route (like Route or WebSocketRoute) provides "http" or "websocket".

@Kludex

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 1 file

Re-trigger cubic

@Kludex Kludex changed the title Use Literal type alias for URLPath protocol parameter Annotate URLPath protocol parameter with Literal Jun 10, 2026

@Kludex Kludex left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there's much benefit from this, but I guess it's fine.

@Kludex Kludex enabled auto-merge (squash) June 10, 2026 09:30
@Kludex

Kludex commented Jun 10, 2026

Copy link
Copy Markdown
Owner

Thanks anyway. πŸ™

@Kludex Kludex merged commit 115228f into Kludex:main Jun 10, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants