Interfaces for Python

8.2 verified Tue May 12 auth: no python install: verified quickstart: verified

Interfaces are objects that specify (document) the external behavior of objects that 'provide' them. An interface specifies behavior through informal documentation, attribute definitions, and invariants. `zope.interface` provides an implementation of 'object interfaces' for Python, facilitating Design By Contract. It is currently at version 8.2 (as of January 9, 2026) and is actively maintained by the Zope Toolkit project.

pip install zope.interface

Warnings

breaking The `implements` class-level function (e.g., `implements(IInterface)`) was removed in `zope.interface` version 6.0. It must be replaced by the `@zope.interface.implementer(IInterface)` class decorator. ↓

fix Replace `implements(IInterface)` with `@implementer(IInterface)` placed above the class definition.

breaking `zope.interface` frequently drops support for older Python versions. Version 8.0 dropped Python 3.8, and 8.1 dropped Python 3.9. Ensure your Python environment meets the `requires_python` specification (>=3.10 for 8.2). ↓

fix Upgrade your Python interpreter to version 3.10 or newer, or downgrade `zope.interface` to a compatible version.

breaking Starting with `zope.interface` 8.0, `pkg_resources` namespace packages were replaced by PEP 420 native namespace packages. This may affect package discovery, especially in older build systems or environments relying on `pkg_resources`. ↓

fix Ensure your project's packaging and build tools are compatible with PEP 420 namespace packages. For `zc.buildout`, version 5 or newer is required with `zope.interface` 6.0b1 and later.

gotcha When defining methods in an `Interface`, omit the `self` argument from the signature. Interfaces describe how a method is *called*, not how it's implemented in a class. This is a common point of confusion. ↓

fix Define interface methods like `def my_method(arg1: Type, arg2: Type) -> ReturnType:` instead of `def my_method(self, arg1: Type, arg2: Type) -> ReturnType:`.

breaking For Python 3.14 and later, `zope.interface.common.builtins.IByteString` and `zope.interface.common.collections.IByteString` are no longer available from `zope.interface` version 7.2 onwards due to the removal of `collections.abc.ByteString` in Python 3.14. ↓

fix Avoid importing or relying on `IByteString` from `zope.interface.common.builtins` or `zope.interface.common.collections` when using Python 3.14 or newer.

gotcha In `zope.interface` 5.0.0, internal singleton objects returned by APIs like `implementedBy` and `directlyProvidedBy` were made immutable. While this fixed potential 'pathological corner cases,' it might subtly affect highly unusual code that previously mutated these objects. ↓

fix Avoid mutating the objects returned by `implementedBy()`, `directlyProvidedBy()`, and similar introspection APIs, as they are now immutable.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) sdist - 0.02s 19.7M

3.10 alpine (musl) - - 0.03s 19.7M

3.10 slim (glibc) wheel 1.7s 0.01s 20M

3.10 slim (glibc) - - 0.01s 20M

3.11 alpine (musl) sdist - 0.03s 22.0M

3.11 alpine (musl) - - 0.04s 22.0M

3.11 slim (glibc) wheel 1.8s 0.03s 23M

3.11 slim (glibc) - - 0.03s 23M

3.12 alpine (musl) sdist - 0.03s 13.7M

3.12 alpine (musl) - - 0.03s 13.7M

3.12 slim (glibc) wheel 1.6s 0.03s 14M

3.12 slim (glibc) - - 0.03s 14M

3.13 alpine (musl) sdist - 0.02s 13.5M

3.13 alpine (musl) - - 0.03s 13.4M

3.13 slim (glibc) wheel 1.6s 0.02s 14M

3.13 slim (glibc) - - 0.02s 14M

3.9 alpine (musl) sdist - 0.02s 19.2M

3.9 alpine (musl) - - 0.02s 19.2M

3.9 slim (glibc) wheel 2.1s 0.02s 20M

3.9 slim (glibc) - - 0.02s 20M

Imports

Interface
```
from zope.interface import Interface
```
Attribute
```
from zope.interface import Attribute
```
implementer
wrong
```
from zope.interface import implements
```
correct
```
from zope.interface import implementer
```
The 'implements' function was deprecated and removed in zope.interface 6.0; use the '@implementer' decorator instead.
verify
```
from zope.interface import verify
```

Quickstart verified last tested: 2026-04-24

Define an interface by inheriting from `zope.interface.Interface`. Declare attributes using `zope.interface.Attribute` and methods with a standard Python function signature (without `self`). Implement the interface in a class using the `@implementer` decorator. Runtime verification can be done with `zope.interface.verify.verifyObject` to ensure adherence to the interface contract.

from zope.interface import Interface, Attribute, implementer, verify

class IGreeter(Interface):
    """An interface for objects that can greet."""

    name = Attribute("The name of the greeter")

    def greet(message: str) -> str:
        """Returns a greeting message."""

@implementer(IGreeter)
class HelloGreeter:
    def __init__(self, name: str):
        self.name = name

    def greet(self, message: str) -> str:
        return f"Hello, {message} from {self.name}!"

# Instantiate the implementing class
greeter_instance = HelloGreeter("World")

# Verify that the instance provides the interface
verify.verifyObject(IGreeter, greeter_instance)

# Use the object as per the interface
print(greeter_instance.greet("Python"))