From b3786eef866c4d925f6c16f91649b8025c4b777a Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Thu, 11 Dec 2025 18:10:11 +0530 Subject: [PATCH 1/6] Clarify purpose of repository in README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8bc02d48..43eb7df2 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ For conversations that are more suitable to a chat platform, you can use one of ## Repository Content -This GitHub repository is used for several things: +This GitHub repository serves multiple purposes related to Python's static type system: + - The documentation at [typing.python.org](https://typing.python.org/) is maintained in the [docs directory](./docs). This includes the From 684f40e5be43781a240c0c7adf29cd5e23915125 Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Fri, 12 Dec 2025 22:35:34 +0530 Subject: [PATCH 2/6] Add introductory description to typing specification index --- docs/spec/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/spec/index.rst b/docs/spec/index.rst index 30210227..a4ca4b98 100644 --- a/docs/spec/index.rst +++ b/docs/spec/index.rst @@ -1,6 +1,11 @@ Specification for the Python type system + ======================================== +This section provides the official specification for Python’s static type system. +It defines the rules, terminology, and behaviors that type checkers and typing-related tools are expected to follow. + + .. toctree:: :maxdepth: 2 :caption: Contents: From e685406ee7fe9a09929cb364701ebeaaff8e4e9d Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Fri, 12 Dec 2025 22:45:34 +0530 Subject: [PATCH 3/6] Add practical example demonstrating usage of Literal types --- docs/spec/literal.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/spec/literal.rst b/docs/spec/literal.rst index 7b0015ca..993c1248 100644 --- a/docs/spec/literal.rst +++ b/docs/spec/literal.rst @@ -24,6 +24,24 @@ concrete value. For example, if we define some variable ``foo`` to have type ``Literal[3]``, we are declaring that ``foo`` must be exactly equal to ``3`` and no other value. +Example +^^^^^^^ + +Literal types are most useful when a function accepts only a fixed set of +allowed constant values. Type checkers can then verify that callers provide +only those values. + +.. code-block:: python + + from typing import Literal + + def set_mode(mode: Literal["fast", "slow"]) -> None: + print(f"Running in {mode} mode") + + set_mode("fast") # OK + set_mode("other") # Type checker error + + Given some value ``v`` that is a member of type ``T``, the type ``Literal[v]`` is a subtype of ``T``. For example, ``Literal[3]`` is a subtype of ``int``. From 06cb232c5437b66d71b2fb35aa5da41fc00e9436 Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Sat, 13 Dec 2025 13:56:05 +0530 Subject: [PATCH 4/6] Fix Gitter link to use HTTPS --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 19117d05..60d8e3b3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,7 +69,7 @@ Discussions and Support ======================= * `User help forum `_ -* `User chat on Gitter `_ +* `User chat on Gitter `_ * `Developer forum `_ * `Developer mailing list (archived) `_ From 8dcf0fe4d117f5a958a3f398c7cba7d30b820ca5 Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Sat, 13 Dec 2025 14:14:27 +0530 Subject: [PATCH 5/6] Clarify PEP 586 context for Literal types --- docs/spec/literal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/literal.rst b/docs/spec/literal.rst index 993c1248..6ada9cb9 100644 --- a/docs/spec/literal.rst +++ b/docs/spec/literal.rst @@ -8,7 +8,7 @@ Literals ``Literal`` ----------- -(Originally specified in :pep:`586`.) +(Originally specified in :pep:`586`, which introduced ``Literal`` types.) Core Semantics From bedc17ffac384625786ad5d3bfa7cc10819c1697 Mon Sep 17 00:00:00 2001 From: u-harshitha007 Date: Sun, 14 Dec 2025 17:20:17 +0530 Subject: [PATCH 6/6] Clarify allowed precision of Literal arithmetic inference --- docs/spec/literal.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/spec/literal.rst b/docs/spec/literal.rst index 6ada9cb9..7b01f9ae 100644 --- a/docs/spec/literal.rst +++ b/docs/spec/literal.rst @@ -50,6 +50,9 @@ literal type. So, if we have some variable ``foo`` of type ``Literal[3]`` it’s safe to do things like ``foo + 5`` since ``foo`` inherits ``int``’s ``__add__`` method. The resulting type of ``foo + 5`` is ``int``. +The specification does not mandate the level of precision required for such inference, and type checkers may choose to infer a more precise ``Literal`` result where possible. + + This "inheriting" behavior is identical to how we :ref:`handle NewTypes `.