Interfaces for Python

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

• pip install zope.interface Install latest stable version

Imports

• Interface

  from zope.interface import Interface

• Attribute

  from zope.interface import Attribute

• implementer

  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

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"))