PEP 3107

PEP 3107
Title	PEP 3107
Author	Guido van Rossum
Status	Final
Type	Standards Track
Created	2009-05-10
Python version	3.0+

PEP 3107

Background

PEP 3107 emerged amid debates in the Python community involving Guido van Rossum, Python Software Foundation, Benny Pinkas, Nick Coghlan, Raymond Hettinger, Larry Wall, Tim Peters, Alex Martelli and contributors from projects like Google, Dropbox (company), Red Hat, Canonical (company), Microsoft, Intel Corporation as developers reconsidered function metadata models used in languages such as Perl, Ruby (programming language), Java, C#, Smalltalk, Lisp, Scheme, Haskell, OCaml, Erlang, Racket, Scala, Kotlin, Swift (programming language), Dart (programming language), Go (programming language), Rust (programming language), PHP, JavaScript, TypeScript, Objective-C, Ada (programming language). This proposal built on precedents from PEP 8, PEP 257, PEP 3105, PEP 318, PEP 3099, PEP 3333, PEP 3124 and discussions on mailing lists hosted by python-dev and archives frequented by members from Stack Overflow, GitHub, Bitbucket, SourceForge.

Specification

The specification describes a syntax for attaching annotations to function parameters and return values, inspired by annotations available in Java, C#, TypeScript, Haskell, Scala (programming language), OCaml, ML (programming language), Ada (programming language), and metadata practices in XML Schema and WSDL. It defines the allowed grammar in terms previously used in PEP 8 and integrates with the CPython parser and bytecode generation used by implementations like PyPy, Jython, IronPython and alternative compilers such as Cython. The PEP prescribes that annotations are stored in a function's __annotations__ attribute as a dictionary mapping parameter names and the special 'return' key to their annotation objects, following conventions familiar from RFC 3339 and namespacing approaches used by XML Namespaces and JSON Schema.

Rationale

The rationale cites interoperability needs encountered by projects such as Django (web framework), Flask (web framework), NumPy, SciPy, Pandas (software), TensorFlow, PyTorch, scikit-learn, Numba, Caffe, Theano, Ansible, SaltStack, Chef (software), and Puppet (software) that required richer function metadata for tools in IDEs like PyCharm, Visual Studio Code, Eclipse, NetBeans, Sublime Text, Vim, Emacs, and analysis tools developed by JetBrains, Microsoft Research, Google Research, Facebook AI Research, OpenAI, Mozilla Foundation, Apache Software Foundation. By providing a lightweight, opt-in mechanism echoing designs from ECMAScript 2015, Java Platform, Standard Edition, .NET Framework, and POSIX extensions, the PEP aimed to avoid the complexity found in type systems of Haskell and MLton while enabling static analysis tools originating from Mypy, Pytype, Pyre (software), TypeScript-style checkers, and language servers such as Language Server Protocol implementations.

Examples

Examples illustrate annotation use in contexts similar to examples in documentation authored by Alex Martelli, David Beazley, Brett Cannon, Raymond Hettinger, Ned Batchelder, Barry Warsaw, Luciano Ramalho, Hynek Schlawack, Armin Ronacher, and tutorials produced by Real Python, O’Reilly Media, Packt Publishing, with patterns drawn from academic sources like MIT Press, O'Reilly Media, Addison-Wesley, Pearson Education, and Springer Science+Business Media. Typical examples show functions annotated with types such as built-in types from Python (programming language), container hints resembling PEP 484 ideas, and custom classes defined in libraries like SQLAlchemy, Pygame, Twisted (software), Celery (software), Requests (software), Beautiful Soup, lxml, OpenCV, Pillow (PIL Fork). Return annotations and parameter annotations are stored under __annotations__ for runtime inspection by frameworks such as Django, Flask, FastAPI, Sanic, Tornado (web server), and RPC systems like gRPC.

Implementation

Implementations in CPython added parser support and mapping to the function object model used by PEP 3154 and bytecode emitters similar to work done for PEP 3102 and PEP 362. Alternative interpreters like PyPy, Jython, and IronPython implemented corresponding storage strategies to remain compatible with projects hosted on GitHub, GitLab, and Bitbucket. Tooling integrations included support in linters and formatters such as flake8, pylint, black (software), isort, and static analyzers from Mypy and Pyre. Build systems and CI services like Travis CI, Jenkins, GitHub Actions, CircleCI adopted tooling to parse annotations for type-checking and documentation generators such as Sphinx (software), Doxygen, Javadoc-style tools, and documentation platforms like Read the Docs.

Adoption and Impact

Adoption spread across ecosystems managed by organizations like NumFOCUS, PSF, Apache Software Foundation, Linux Foundation, KDE, GNOME, Canonical (company), Red Hat, Microsoft, Google, Facebook, Amazon (company), IBM, Oracle Corporation, influencing libraries such as NumPy, Pandas (software), scikit-learn, TensorFlow, PyTorch, FastAPI and frameworks like Django (web framework), Flask (web framework), Pyramid (web framework). The impact included enabling type-hinting ecosystems formalized later by PEP 484 and adoption in documentation tools used by projects maintained by Mozilla Foundation, W3C, IETF, and academic institutions like MIT, Stanford University, Massachusetts Institute of Technology, University of Cambridge, University of Oxford.

Compatibility and Migration Considerations

Migration guidance echoed practices promoted by Python Software Foundation, PEP 3105, PEP 8, PEP 257 and tooling from Mypy, pytype, pyright, pylint, flake8 and continuous integration services like Travis CI and CircleCI. Developers from organizations such as Google, Microsoft, Facebook, Netflix, Red Hat, Canonical (company), Dropbox (company), Instagram (service), Spotify (service) coordinated migration strategies to avoid runtime incompatibilities with older interpreters such as Python 2.x and third-party extensions built for CPython C-API, while promoting gradual typing patterns later standardized in PEP 484.

Category:Python Enhancement Proposals