Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[spec] clarification or change of "`partial\n` in a `py.typed` file"

Open
#2,113 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start by reading the distributing.html section on partial stub packages, then compare the linked mypy, pyright, and ty checks and the referenced discuss.python.org thread. Done means agreeing on the intended matching rule and updating the specification to state it unambiguously, including newline and end-of-file behavior.

Written by the indexing model from the issue text.

Description

topic: typing spec

Reading through https://typing.python.org/en/latest/spec/distributing.html#partial-stub-packages today for unrelated purposes, it struck me that the occurrences of partial\n are ambiguous because it could be interpreted as requiring literally a backslash and an n. Furthermore, assuming \n is actually not to be taken literally (which is reasonable given that other places in the spec use glob stars anyway, although never in something you actually type into a file) it's ambiguous what happens if you use CRLF or CR as line terminators in your file. This also seems to rule out a file that just contains partial and then ends, without a newline character (you're not "supposed to" do this, but it happens).

To keep exactly the current behavior, I think this verbiage should be tweaked to "partial, followed by a newline". Perhaps the linefeed and carriage return characters could be mentioned explicitly, or a mention can be made of universal newlines.

However, I am not sure if the current behavior is actually important to specify, and I think other possibilities make more sense. Other possibilities include "partial on a line by itself", "partial surrounded by any amount of whitespace", and just "partial". "As the sole content of the file" may be added if desired.

A brief survey suggests that:

  • mypy does fscache.read(stub_typed_file).decode().strip() == "partial", which is not quite the same as the specified check
  • pyright does (pyTypedContents.match(/partial\n/) || pyTypedContents.match(/partial\r\n/)), which is certainly a reasonable interpretation of the current spec, especially if you assume that no one ever uses only-CR newlines
  • ty does to_ascii_lowercase().contains("partial") to be deliberately permissive, as explained in a comment

There is a reasonably long discussion about this topic over at https://discuss.python.org/t/pep-561-clarification-regarding-n/32875, but I didn't find it very enlightening.

Dominant language
Python
Stars
1.8k
Forks
302
Avg merge
23h
Merged PRs (30d)
8

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from python/typing

All issues in python/typing

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.