Implementing Interfaces in Python: ABCs and Protocols

Defining an ABC-Based Interface

An ABC declares abstract methods using the @abstractmethod decorator from the abc module. Any subclass must implement every abstract method. Otherwise, Python raises an error the moment you try to instantiate the subclass.

Say you need an interface for file readers. Readers for different formats like PDFs and emails will require the same methods but with different internal logic. The shared contract is to load a file from a path and return the extracted text.

Here’s that interface modeled as an ABC:

from abc import ABC, abstractmethod

class FileReaderInterface(ABC):
    """Interface for file readers."""

    @abstractmethod
    def load_file(self, path: str) -> None:
        """Load a file for text extraction."""

    @abstractmethod
    def extract_text(self) -> str:
        """Return text extracted from the loaded file."""

A few things to notice in this code snippet:

• FileReaderInterface inherits from abc.ABC, which sets up the metaclass for you.
• Each abstract method is decorated with @abstractmethod.
• The body of abstract methods can contain a descriptive docstring, a bare pass statement, an ellipsis (...), or raise a NotImplementedError exception.

Now, create two concrete classes, PdfReader and EmailReader, which inherit from FileReaderInterface:

# ...

class PdfReader(FileReaderInterface):
    """Extract text from a PDF."""

    def load_file(self, path: str) -> None:
        """Load a PDF file for text extraction."""
        print(f"Loading PDF from {path}")

    def extract_text(self) -> str:
        """Return text extracted from the loaded PDF."""
        return "Extracted PDF text"

class EmailReader(FileReaderInterface):
    """Extract text from an Email."""

    def load_file(self, path: str) -> None:
        """Load an EML file for text extraction."""
        print(f"Loading email from {path}")

    def extract_email_text(self) -> str:
        """Return text extracted from the loaded email."""
        return "Extracted email text"

PdfReader implements both abstract methods, so it satisfies the interface. EmailReader defines .extract_email_text() instead of the required .extract_text(), so it doesn’t satisfy the contract.

Watch what happens when you try to instantiate these classes:

>>> from readers_abc import PdfReader, EmailReader

>>> pdf_reader = PdfReader()
>>> email_reader = EmailReader()
Traceback (most recent call last):
  ...
TypeError: Can't instantiate abstract class EmailReader
⮑ without an implementation for abstract method 'extract_text'

You can instantiate PdfReader, but you get a TypeError when you try to instantiate EmailReader because this class doesn’t implement the expected method, .extract_text(). That’s the value of using abc.ABC: forgetting a method isn’t a runtime surprise buried deep in your code. The failure happens at instantiation, before anything else runs.

To fix the error, rename .extract_email_text() to .extract_text() in EmailReader, and you’ll be able to instantiate it. Go ahead and give it a try.

interface FileReaderInterface {
    void loadFile(String path);
    String extractText();
}

class PdfReader implements FileReaderInterface {
    public void loadFile(String path) {
        // Code to load the file
    }

    public String extractText() {
        // Code to extract the text
    }
}

class EmailReader implements FileReaderInterface {
    public void loadFile(String path) {
        // Code to load the file
    }

    public String extractText() {
        // Code to extract the text
    }
}

class FileReaderInterface {
    public:
        virtual void loadFile(std::string path) = 0;
        virtual std::string extractText() = 0;
        virtual ~FileReaderInterface() = default;
};

class PdfReader : public FileReaderInterface {
    public:
        void loadFile(std::string path) override;
        std::string extractText() override;
};

class EmailReader : public FileReaderInterface {
    public:
        void loadFile(std::string path) override;
        std::string extractText() override;
};

package main

type fileReaderInterface interface {
    loadFile(path string)
    extractText() string
}

type pdfReader struct {
    // Data goes here ...
}

func (p pdfReader) loadFile(path string) {
    // Method definition ...
}

func (p pdfReader) extractText() string {
    // Method definition ...
}

type emailReader struct {
    // Data goes here ...
}

func (e emailReader) loadFile(path string) {
    // Method definition ...
}

func (e emailReader) extractText() string {
    // Method definition ...
}

Type-Checking ABC Subclasses

Static type checkers verify ABC subclass relationships through inheritance with no extra setup. At runtime, you can explicitly type-check an ABC subclass using the built-in isinstance() and issubclass() functions:

>>> from readers_abc import FileReaderInterface, PdfReader

>>> isinstance(PdfReader(), FileReaderInterface)
True

>>> issubclass(PdfReader, FileReaderInterface)
True

Both functions return True because PdfReader has a direct inheritance relationship with FileReaderInterface.

Registering Virtual Subclasses

Sometimes, you want a Python class to satisfy your interface without actually inheriting from it. Maybe the class comes from a third-party library you can’t modify, or maybe you want to document a structural relationship without changing the inheritance chain. The abc module supports this with virtual subclass registration.

Stepping outside the file-reader example for a moment, here’s how you register the built-in float class as a virtual subclass of a Double interface:

from abc import ABC

class Double(ABC):
    """Double precision floating point number."""

Double.register(float)

Now both issubclass() and isinstance() treat float as a Double subclass:

>>> from virtual_subclass import Double

>>> issubclass(float, Double)
True
>>> isinstance(1.2345, Double)
True

You can also use .register() as a class decorator:

>>> @Double.register
... class Double64:
...     """A 64-bit double-precision floating-point number."""
...

>>> issubclass(Double64, Double)
True

Use registration sparingly, though. Virtual subclasses don’t enforce any method requirements. They just declare a relationship. For shape-based matching that actually inspects methods, reach for typing.Protocol, which you’ll learn about next.

Defining a Protocol-Based Interface

Here’s a FileReaderProtocol class that parallels FileReaderInterface:

from typing import Protocol

class FileReaderProtocol(Protocol):
    """Protocol for file readers."""

    def load_file(self, path: str) -> None:
        """Load a file for text extraction."""
        ...

    def extract_text(self) -> str:
        """Return text extracted from the loaded file."""
        ...

In this example, FileReaderProtocol inherits from typing.Protocol instead of from abc.ABC.

You’ll also notice that each method body ends with ... after the docstring, rather than the docstring-only bodies used in the ABC example. That’s a convention difference: ABCs typically rely on docstrings alone to mark abstract method bodies, while protocols often add an ellipsis after the docstring or use the ellipsis on its own.

A concrete class satisfies the protocol purely by implementing the protocol’s methods:

# ...

class PdfReader:
    """Extract text from a PDF."""

    def load_file(self, path: str) -> None:
        """Load a PDF file for text extraction."""
        print(f"Loading PDF from {path}")

    def extract_text(self) -> str:
        """Return text extracted from the loaded PDF."""
        return "Extracted PDF text"

class EmailReader:
    """Extract text from an Email."""

    def load_file(self, path: str) -> None:
        """Load an EML file for text extraction."""
        print(f"Loading email from {path}")

    def extract_text(self) -> str:
        """Return text extracted from the loaded email."""
        return "Extracted email text"

Notice that PdfReader and EmailReader don’t inherit from FileReaderProtocol. However, static type checkers like mypy still recognize them as valid FileReaderProtocol subtypes because they implement the expected methods with the right signatures.

Type-Checking Protocol Subtypes Statically

Consider the following read() function that expects a reader object as an argument:

def read(reader, path: str) -> str:
    reader.load_file(path)
    return reader.extract_text()

read(PdfReader(), "/reports/report.pdf")
read(EmailReader(), "/mail/message.eml")

Without protocols or inheritance, you won’t have an easy way to type-hint the reader argument. If you declare it as a PdfReader, your static type checker will complain about the second call to read() because EmailReader isn’t a PdfReader.

To fix this, use FileReaderProtocol to annotate the reader parameter:

def read(reader: FileReaderProtocol, path: str) -> str:
    reader.load_file(path)
    return reader.extract_text()

# Accepted by the type checker
read(PdfReader(), "/reports/report.pdf")
read(EmailReader(), "/mail/message.eml")

Now, the static type checker verifies that the argument to read() satisfies the FileReaderProtocol protocol by inspecting its methods and signatures rather than by checking for an inheritance relationship. That’s the practical payoff of structural subtyping.

Type-Checking Protocol Subtypes at Runtime

If you need the type check to happen at runtime through isinstance() and issubclass(), then decorate the Protocol class with @runtime_checkable:

from typing import Protocol, runtime_checkable

@runtime_checkable
class FileReaderProtocol(Protocol):
    # ...

With this addition, you can check types with the isinstance() and issubclass() functions:

>>> from readers_protocol import FileReaderProtocol, PdfReader

>>> isinstance(PdfReader(), FileReaderProtocol)
True

>>> issubclass(PdfReader, FileReaderProtocol)
True

Note that runtime-checkable protocols verify only that methods exist, but they don’t validate their signatures. For full signature-level verification at runtime, reach for a third-party runtime type-checking library like beartype or typeguard.

If you want to see protocols at work in more scenarios, Real Python’s Exploring Protocols in Python course walks through structural subtyping, runtime checks, and common protocol patterns step by step.

Applying Duck Typing

To see duck typing in action, consider these plain reader classes with a common set of methods:

class PdfReader:
    """Extract text from a PDF."""
    def load_file(self, path: str) -> None:
        print(f"Loading PDF from {path}")

    def extract_text(self) -> str:
        return "Extracted PDF text"

class EmailReader:
    """Extract text from an Email."""
    def load_file(self, path: str) -> None:
        print(f"Loading email from {path}")

    def extract_text(self) -> str:
        return "Extracted email text"

def read(reader, path: str) -> str:
    reader.load_file(path)
    return reader.extract_text()

Notice what’s not there: no FileReaderInterface, no FileReaderProtocol, no shared base class. PdfReader and EmailReader have nothing in common type-wise. They just happen to expose the same two methods.

As long as read() gets an object with .load_file() and .extract_text(), it doesn’t care what class that object belongs to:

>>> from readers import PdfReader, EmailReader, read

>>> read(PdfReader(), "/reports/report.pdf")
Loading PDF from /reports/report.pdf
'Extracted PDF text'

>>> read(EmailReader(), "/mail/message.eml")
Loading email from /mail/message.eml
'Extracted email text'

That’s duck typing. The contract is behavior rather than type. Python never checks what reader is, only what it does when you call a method on it.

To see the trade-off in action, rename .extract_text() to .extract_email_text() in EmailReader:

# ...

class EmailReader:
    """Extract text from an Email."""
    def load_file(self, path: str) -> None:
        print(f"Loading email from {path}")

    def extract_email_text(self) -> str:
        return "Extracted email text"

# ...

Now read() calls .extract_text() on an object that no longer provides it, and you get an AttributeError. Restart your Python session and run this code snippet:

>>> from readers import EmailReader, read

>>> read(EmailReader(), "/mail/message.eml")
Loading email from /mail/message.eml
Traceback (most recent call last):
    ...
AttributeError: 'EmailReader' object has no attribute 'extract_text'

The mismatch isn’t caught until read() actually tries to call the missing method at runtime. That’s the trade-off of duck typing: freedom from formal type declarations, but no safety net before you run the code.

Combining Duck Typing With ABCs and Protocols

Duck typing works seamlessly with both ABCs and protocols. When you use duck typing with ABCs, the contract is enforced at instantiation time, so you get an early failure if a class doesn’t meet the requirements. The type checker can also verify the type based on the inheritance relationship:

>>> from readers_abc import FileReaderInterface, PdfReader, EmailReader

>>> def read(reader: FileReaderInterface, path: str) -> str:
...     reader.load_file(path)
...     return reader.extract_text()
...

>>> read(PdfReader(), "/reports/report.pdf")
Loading PDF from /reports/report.pdf
'Extracted PDF text'

>>> read(EmailReader(), "/mail/message.eml")
Loading email from /mail/message.eml
'Extracted email text'

When you use duck typing with protocols, the contract isn’t enforced at instantiation time, but a static type checker can verify it before you run the code. You can revisit the Type-Checking Protocol Subtypes Statically section for a refresher on how this works.

ABCs and protocols layer structure on top of duck typing to make it safer. ABCs enforce the contract at instantiation, and protocols catch missing methods at type-check time.