Duck Typing in Python

Python duck typing is the principle that the suitability of an object for a particular piece of code is determined by the methods and attributes the object actually provides, not by its declared type, its position in a class hierarchy, or any interface it claims to implement. The name comes from the old saying: if it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck. In programming terms, if an object has a read method that returns string data, you can treat it as a file, regardless of whether it is actually an instance of the file class, a StringIO object from the standard library, a mock object from a test framework, or a class you wrote yourself that happens to provide a compatible read method. The object's behavior at runtime is what matters, not its declared identity.

Duck typing is the mechanism that makes Python's polymorphism, covered in the previous article, feel natural and unobtrusive. In languages with static type systems, polymorphic code requires shared base classes or explicitly declared interfaces, and the compiler verifies at build time that every object passed to a function satisfies the declared type. In Python, none of that ceremony is required. You write a function that calls a method on whatever it receives. If the object has the method, the call succeeds. If it does not, Python raises an AttributeError at runtime. This approach trades compile-time safety for runtime flexibility, and it is one of the features that gives Python its reputation as a language that lets you write less code to accomplish the same task.

The article on polymorphism in Python explained covered how different classes can share a common interface and be used interchangeably. Duck typing is what makes that possible without inheritance hierarchies. Two classes written by different people at different times, with no shared parent and no coordination, can be used polymorphically as long as they define methods with the same names and compatible behavior. The calling code never knows or cares about the class relationship because Python never checks it.

How duck typing works at runtime

When Python encounters a method call like object.method(), it does not check the type of object first. It looks up the name method on the object, finds the function associated with that name in the object's class, and calls it. If the object's class does not define method anywhere in its inheritance chain, the lookup fails and Python raises an AttributeError. The lookup is purely name-based: Python does not care whether object is a list, a dictionary, a custom class, or a built-in type. If the name exists, the call proceeds. If it does not, the call fails.

This name-based dispatch is the engine behind duck typing. Any object that defines a method with the expected name can be passed to code that calls that method. The following function writes a header and a list of items to what it treats as a file-like object, but it works with any object that has a write method:

python

def write_report(output, title, items):
    output.write(f"Report: {title}\n")
    output.write("-" * 40 + "\n")
    for item in items:
        output.write(f"  - {item}\n")

You can call write_report with an actual file object opened for writing, and the report is written to disk. You can call it with a StringIO object from the io module, and the report is captured in memory as a string. You can call it with a list-like object that defines a write method that appends to an internal buffer. You can call it with a mock object in a unit test that records what was written for later verification. The write_report function has no knowledge of any of these types and no dependency on any particular one. It depends solely on the existence of a write method, which every one of these objects provides.

Duck typing in the Python standard library

The Python standard library embraces duck typing extensively, and understanding where it appears helps you recognize the pattern in your own code. The built-in len() function works with any object that defines a special method for length computation. You can pass a string, a list, a dictionary, a set, or a custom class that implements that method, and len() returns the correct count for each one. The function does not check whether the argument is a sequence or a collection; it simply calls the length method and returns the result.

The file handling ecosystem is another example. Functions that expect a file object do not check for a specific file type. They check for the presence of methods like read, write, and close at the moment those methods are called. The io module provides StringIO and BytesIO classes that behave like files but operate on strings and bytes in memory rather than on disk. Any function written to work with a file object automatically works with StringIO, which makes testing code that performs file I/O straightforward: you pass a StringIO instead of a real file, run the function, and inspect the StringIO's contents afterward without touching the filesystem.

Iteration in Python is built entirely on duck typing. A for loop does not require its target to be a list or a tuple. It requires the target to be iterable, which means the target must implement the iteration protocol by defining a method that returns an iterator. Generators, files, dictionaries, sets, and custom classes that implement the iteration protocol all work in for loops without the loop needing to know which specific type it is iterating over. The loop calls the iteration method, receives an iterator, and calls the iterator's next method until exhaustion. The types involved are irrelevant as long as the protocol is followed.

When duck typing is the right approach

Duck typing is at its best when the interface is small and well-understood. A function that needs an object with a single method like write, read, or process is a good candidate for duck typing because the contract is simple and the risk of passing an incompatible object is low. The caller can easily verify that their object supports the required method, and if they make a mistake, the AttributeError points directly to the line where the method was called with a clear message about what is missing.

Duck typing also shines in internal code, where the same person or team controls both the calling code and the objects being passed. In a closed system, the set of types that will be passed to a function is known and limited, and the flexibility of duck typing allows new types to be added without ceremony. A function that processes data might start by accepting only lists, then be extended to accept generators for memory efficiency, then be extended to accept custom data source objects, all without changing the function's code as long as each new type supports iteration.

When to add explicit checks

The main risk of duck typing is that an error caused by passing an incompatible object surfaces as an AttributeError deep in the calling code, possibly with a confusing message if the method name is generic. If a function expects an object with a close method and receives an object whose close method does something completely different, the program will run without errors but produce incorrect results. The error is not that the method is missing; it is that the method exists but has the wrong semantics, and duck typing cannot detect this kind of mismatch.

When the interface is complex or the consequences of a mismatch are severe, adding explicit checks can make the code more robust. Python provides several tools for this. The hasattr() built-in checks whether an object has a method with a given name before calling it. Abstract base classes in the collections.abc and io modules let you check whether an object implements a full protocol rather than just a single method. Type hints, while not enforced at runtime, serve as documentation and can be checked with external tools like mypy. Each of these approaches adds some of the safety of static typing while preserving the flexibility of duck typing for the cases where it is appropriate.

The article on instance methods in Python covers how methods are defined and called, and duck typing extends those mechanics across unrelated classes. Any object with a method of the right name can participate, regardless of how or where that method was defined.