Text of peps.python.org › pep-0544 as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 544 – Protocols: Structural subtyping (static duck typing) | peps.python.org

PEP 544 – Protocols: Structural subtyping (static duck typing) PEP 544 – Protocols: Structural subtyping (static duck typing) Author : Ivan Levkivskyi <levkivskyi at gmail.com>, Jukka Lehtosalo <jukka.lehtosalo at iki.fi>, Łukasz Langa <lukasz at python.org> BDFL-Delegate : Guido van Rossum <guido at python.org> Discussions-To : Python-Dev list Status : Final Type : Standards Track Topic : Typing Created : 05-Mar-2017 Python-Version : 3.8 Resolution : Typing-SIG message Table of Contents Abstract Rationale and Goals Nominal vs structural subtyping Non-goals Existing Approaches to Structural Subtyping Specification Terminology Defining a protocol Protocol members Explicitly declaring implementation Merging and extending protocols Generic protocols Recursive protocols Self-types in protocols Callback protocols Using Protocols Subtyping relationships with other types Unions and intersections of protocols Type[] and class objects vs protocols NewType() and type aliases Modules as implementations of protocols @runtime_checkable decorator and narrowing types by isinstance() Using Protocols in Python 2.7 - 3.5 Runtime Implementation of Protocol Classes Implementation details Changes in the typing module Introspection Rejected/Postponed Ideas Make every class a protocol by default Protocols subclassing normal classes Support optional protocol members Allow only protocol methods and force use of getters and setters Support non-protocol members Make protocols interoperable with other approaches Use assignments to check explicitly that a class implements a protocol Support isinstance() checks by default Provide a special intersection type construct Prohibit explicit subclassing of protocols by non-protocols Covariant subtyping of mutable attributes Overriding inferred variance of protocol classes Support adapters and adaptation Call structural base types “interfaces” Make protocols special objects at runtime rather than normal ABCs Backwards Compatibility Implementation References Copyright Important This PEP is a historical document: see Protocols and typing.Protocol for up-to-date specs and documentation.

Canonical typing specs are maintained at the typing specs site ; runtime typing behaviour is described in the CPython documentation. × See the typing specification update process for how to propose changes to the typing spec. Abstract Type hints introduced in PEP 484 can be used to specify type metadata for static type checkers and other third party tools. However, PEP 484 only specifies the semantics of nominal subtyping.

In this PEP we specify static and runtime semantics of protocol classes that will provide a support for structural subtyping (static duck typing). Rationale and Goals Currently, PEP 484 and the typing module [typing] define abstract base classes for several common Python protocols such as Iterable and Sized . The problem with them is that a class has to be explicitly marked to support them, which is unpythonic and unlike what one would normally do in idiomatic dynamically typed Python code.

For example, this conforms to PEP 484 : from typing import Sized , Iterable , Iterator class Bucket ( Sized , Iterable [ int ]): ... def __len__ ( self ) -> int : ... def __iter__ ( self ) -> Iterator [ int ]: ... The same problem appears with user-defined ABCs: they must be explicitly subclassed or registered. This is particularly difficult to do with library types as the type objects may be hidden deep in the implementation of the library.

Also, extensive use of ABCs might impose additional runtime costs. The intention of this PEP is to solve all these problems by allowing users to write the above code without explicit base classes in the class definition, allowing Bucket to be implicitly considered a subtype of both Sized and Iterable[int] by static type checkers using structural [wiki-structural] subtyping: from typing import Iterator , Iterable class Bucket : ... def __len__ ( self ) -> int : ... def __iter__ ( self ) -> Iterator [ int ]: ... def collect ( items : Iterable [ int ]) -> int : ... result : int = collect ( Bucket ()) # Passes type check Note that ABCs in typing module already provide structural behavior at runtime, isinstance(Bucket(), Iterable) returns True .

The main goal of this proposal is to support such behavior statically. The same functionality will be provided for user-defined protocols, as specified below. The above code with a protocol class matches common Python conventions much better. It is also automatically extensible and works with additional, unrelated classes that happen to implement the required protocol. Nominal vs structural subtyping Structural subtyping is natural for Python programmers since it matches the runtime semantics of duck typing: an object that has certain properties is treated independently of its actual runtime class.

However, as discussed in PEP 483 , both nominal and structural subtyping have their strengths and weaknesses. Therefore, in this PEP we do not propose to replace the nominal subtyping described by PEP 484 with structural subtyping completely. Instead, protocol classes as specified in this PEP complement normal classes, and users are free to choose where to apply a particular solution. See section on rejected ideas at the end of this PEP for additional motivation.

Non-goals At runtime, protocol classes will be simple ABCs. There is no intent to provide sophisticated runtime instance and class checks against protocol classes. This would be difficult and error-prone and will contradict the logic of PEP 484 . As well, following PEP 484 and PEP 526 we state that protocols are completely optional : No runtime semantics will be imposed for variables or parameters annotated with a protocol class.

Any checks will be performed only by third-party type checkers and other tools. Programmers are free to not use them even if they use type annotations. There is no intent to make protocols non-optional in the future. To reiterate, providing complex runtime semantics for protocol classes is not a goal of this PEP, the main goal is to provide a support and standards for static structural subtyping. The possibility to use protocols in the runtime context as ABCs is rather a minor bonus that exists mostly to provide a seamless transition for projects that already use ABCs.

Existing Approaches to Structural Subtyping Before describing the actual specification, we review and comment on existing approaches related to structural subtyping in Python and other languages: zope.interface [zope-interfaces] was one of the first widely used approaches to structural subtyping in Python. It is implemented by providing special classes to distinguish interface classes from normal classes, to mark interface attributes, and to explicitly declare implementation.

For example: from zope.interface import Interface , Attribute , implementer class IEmployee ( Interface ): name = Attribute ( "Name of employee" ) def do ( work ): """Do some work""" @implementer ( IEmployee ) class Employee : name = 'Anonymous' def do ( self , work ): return work . start () Zope interfaces support various contracts and constraints for interface classes. For example: from zope.interface import invariant def required_contact ( obj ): if not ( obj . email or obj . phone ): raise Exception ( "At least one contact info is required" ) class IPerson ( Interface ): name = Attribute ( "Name" ) email = Attribute ( "Email Address" ) phone = Attribute ( "Phone Number" ) invariant ( required_contact ) Even more detailed invariants are supported.

However, Zope interfaces rely entirely on runtime validation. Such focus on runtime properties goes beyond the scope of the current proposal, and static support for invariants might be difficult to implement. However, the idea of marking an interface class with a special base class is reasonable and easy to implement both statically and at runtime. Python abstract base classes [abstract-classes] are the sta

The rest of this page is on the live site.