gh-141838: Add EmptyList, EmptyDict, EmptySet types for empty collection hinting

[a-jean-andreasian]

Feature or enhancement Issue #141838

Proposal:

Proposal: Add Empty Collection Type Hints for Enhanced Type Precision

Problem: The current type system doesn't distinguish between empty and non-empty containers, which can lead to ambiguity in function contracts and require additional code inspection.

Current limitation:

def get_user_data() -> List[Dict[str, str]]:
    # The return type doesn't indicate whether empty results are possible
    if not users_exist:
        return []  # Empty list
    return [{"name": "john"}]

Proposal: We suggest adding special forms for empty collections:

• EmptyList for []
• EmptyDict for {}
• EmptySet for set()
• EmptyTuple for ()

Use cases:

from typing import EmptyList, EmptyDict

# Clearer function contracts
def initialize() -> EmptyDict:
    return {}

# Optional results with precise types
def find_users(query: str) -> List[User] | EmptyList:
    if not query:
        return []
    return [user1, user2]

# Configuration with empty defaults
def load_settings() -> Dict[str, Setting] | EmptyDict:
    if not config_exists():
        return {}
    return parse_config()

Benefits:

• More precise type annotations
• Better communication of function semantics
• Enhanced static analysis capabilities
• Self-documenting code without runtime cost

Implementation consideration: These could be implemented as _SpecialForm instances, similar to existing special types, ensuring no runtime impact.

This would provide developers with additional expressiveness when designing APIs and function interfaces, particularly for cases where empty collections have specific semantic meaning.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

• Issue: Add type hints for empty collections (EmptyList, EmptyDict, EmptySet, EmptyTuple) #141838

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[picnixz]

Closing because this needs a discussion. See #141838 (comment).

[a-jean-andreasian]

Closing because this needs a discussion. See #141838 (comment).

The changes are minimal (+40 -0 lines) and straightforward to review. The implementation follows existing patterns of the module and adds clear value for type hinting empty collections.

The code is runnable and tested. If there are specific technical concerns, I'm happy to address them.

However, requiring extensive community discussion for a small, well-scoped addition seems disproportionate when the implementation work is already complete and follows established patterns.

Kindly regard, to not implement this idea in the future.

[terryjreedy]

Technical comment: PR titles, at least for CPython, are bi-directionally linked to issues as per my edit. The initial post should be much terser (often a single line) and not a repeat of the issue opening, as by default it becomes the commit message. With proper links, the repeat is redundant.

[JelleZijlstra]

The runtime code may be small but objects in typing also need to be supported by type checkers, and it's not all that obvious how these would work in type checkers. If you want this to be part of Python, you'll have to write a detailed specification of how type checkers should handle these and ideally a reference implementation for at least one existing type checker.