Skip to main content

interface-py

interface-py is a lightweight Python package for defining interfaces and concrete implementations with enforced contracts.
It ensures that concrete classes implement all required methods, properties, and fields, including validation for empty or invalid property getters.


Features

  • Define interfaces using the @interface decorator.
  • Enforce that concrete classes implement all interface methods, fields, and properties.
  • Detects and enforces rules for empty, explicit, and invalid getters/setters.
  • Support for fields with four declaration styles:
    1. With annotation only → x: int
    2. With annotation + ... → y: float = ...
    3. Without annotation + ... → z = ...
    4. With direct type assignment → DataModel = dict or any other type/class
  • Ensures that property getters defined explicitly in interfaces always raise an error.
  • Allows defining properties in interfaces with empty bodies (..., pass, or docstring-only`).
  • Enforce getter, setter, and deleter implementation rules for properties.
  • Supports multi-level interface hierarchies with automatic contract aggregation.
  • Prevents runtime errors from missing implementations.
  • Works alongside Python's built-in ABCs.

Installation

pip install interface-py

Usage

Defining an Interface

from interface_py import interface

@interface
class HumanInterface:
    # field definitions
    name: str
    age: int = ...
    nickname = ...
    DataModel = dict  # direct type assignment
    
    def speak(self): ...
    
    @property
    def rank(self): ...
    
    @rank.setter
    def rank(self, value): ...
  • Property definitions in interfaces may have an empty body (..., pass, or docstring-only`).
  • However, explicit getters (e.g. @rank.getter) are not allowed in interfaces, even if their body is empty.

🦆 Duck Typing (Structural Compatibility Checks)

interface-py provides structural compatibility checks via a separate submodule:
interface_py.duck_typing

This module lets you check whether a class or instance matches an interface contract structurally,
even if it doesn’t explicitly inherit from it.


Example

from interface_py import interface
from interface_py.duck_typing import is_duck_subclass, is_duck_instance

@interface
class FlyableInterface:
    def fly(self): ...

class Bird:
    def fly(self):
        print("Flying high!")

class Plane:
    def fly(self):
        print("Taking off!")

# Structural (duck) compatibility check
assert is_duck_subclass(Bird, FlyableInterface)
assert is_duck_instance(Plane(), FlyableInterface)

✅ In this example:

  • Neither Bird nor Plane explicitly inherit from FlyableInterface.
  • However, both provide the required fly() method.
  • Therefore, they are structurally compatible with the interface.
    (“If it flies like a bird, it’s a bird.”)

Notes

  • These checks are opt-in and non-intrusive —
    They don’t affect Python’s built-in issubclass() or isinstance() behavior.
    Instead, you explicitly call is_duck_subclass() or is_duck_instance().
  • Works with:
    • Methods
    • Properties
    • Fields
    • Static methods
    • Class methods
  • This design avoids modifying the MRO or inheritance hierarchy.
  • Future versions may extract this logic into a standalone package for broader reuse.

Import Path

from interface_py.duck_typing import (
    is_duck_subclass,
    is_duck_instance,
)

Multi-level Interface Example

from interface_py import interface, concrete

@interface
class MilitaryHumanInterface(HumanInterface):
    def march(self): ...

@concrete
class Soldier(MilitaryHumanInterface):
    name: str = "John"
    age: int = 25
    nickname = "Eagle"
    
    def speak(self):
        print("Reporting for duty!")

    def march(self):
        print("Marching!")

    @property
    def rank(self):
        return self._rank
    
    @rank.setter
    def rank(self, value):
        self._rank = value
  • MilitaryHumanInterface extends HumanInterface.
  • Soldier implements all required methods, fields, and properties from both interfaces automatically.
  • Multi-level inheritance automatically merges all parent interface contracts.

Field Enforcement Examples

from interface_py import interface, concrete

@interface
class ExampleInterface:
    x: int              # only annotation
    y: float = ...      # annotation with ellipsis
    z = ...             # plain ellipsis
    DataModel = dict    # direct type assignment


# ✅ Correct implementation
@concrete
class GoodImpl(ExampleInterface):
    x: int = 10
    y: float = 3.14
    z = "hello"
    DataModel = dict


# ❌ Incorrect implementation
@concrete
class BadImpl(ExampleInterface):
    x: str = "oops"   # wrong type (expected int)
    # y missing → TypeError
    z = ...           # not allowed to keep ellipsis
    DataModel = list   # wrong type assignment

Method Enforcement Rules

In interfaces, all methods must have an empty body.
Empty bodies are recognized as:

  • pass
  • ...
  • docstring-only functions (for example, a function that only contains a string literal as its body)

In concrete classes, all methods must have a non-empty body.
Methods defined with only pass, ..., or docstring-only are considered unimplemented and raise a TypeError.


Property Enforcement Rules

  • A property can be declared in an interface as:

    @property
    def data(self): ...
    
  • The above is valid and treated as a contract placeholder.

  • However, the following is invalid and raises an error:

    @property
    def data(self):
        pass
    
    @data.getter
    def data(self):
        ...
    
  • Concrete classes must implement the getter, and if defined in the interface, also the setter and deleter.


Validation

  • Instantiating a concrete class that does not implement all interface methods/fields/properties raises a TypeError.
  • Ensures consistent interface contracts across your project.
  • The decorator @interface automatically enforces the interface behavior without requiring any base class.
  • The decorator @concrete ensures that at least one parent of the concrete class is an interface.

Why Use interface-py?

  • Provides contract enforcement in dynamically typed Python.
  • Detects incomplete or empty implementations early.
  • Helps structure large codebases with clear interface and implementation separation.
  • Avoids runtime errors from missing or placeholder methods.
  • Enforces correctness while remaining Pythonic.

License

MIT License

Metadata

Release files for interface-py 1.5.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for interface-py 1.5.4
File Size Uploaded Provenance Actions
interface_py-1.5.4.tar.gz 9.2 kB Without provenance Details for interface_py-1.5.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for interface-py 1.5.4
File Interpreter ABI Platform Actions
interface_py-1.5.4-py3-none-any.whl Python 3 none any Details for interface_py-1.5.4-py3-none-any.whl

Total release size: 16.8 kB

Release files / interface_py-1.5.4.tar.gz

Download URL interface_py-1.5.4.tar.gz
Size 9.2 kB
Tags Source
SHA-256 checksum
How to use checksums
8009612fd5062f975877bc6591ba7928bd1ae750f060ed21def81ec422324c35
BLAKE2b-256 checksum
How to use checksums
1c6ee43ea15dc050e8906e70093e39464602afe670fb3a7cdf1fb7369d5eac7f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / interface_py-1.5.4-py3-none-any.whl

Download URL interface_py-1.5.4-py3-none-any.whl
Size 7.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ec6dbb72176475c48bb1108252964576b91f3642952f225537b05dda6753f44
BLAKE2b-256 checksum
How to use checksums
f0657ec00207bbff2dc16047f297d81ebf35a82f213801ea0c5046ec5e2067ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for interface-py 1.5.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page