{"title":"abc Module","description":"","content":"This lesson digs into the `abc` module itself: the building blocks (`ABC`, `ABCMeta`, `abstractmethod`), how `@abstractmethod` composes with `@property`, `@classmethod`, and `@staticmethod`, what virtual subclasses with `register` do, and which built-in abstract base classes ship in `collections.abc`. The chapter ends with guidance on when to pick each piece, and why a `Protocol` sometimes fits where an `ABC` doesn't.\n\n---\n\n# The Three Building Blocks\n\nThe `abc` module exports a small set of names. Three of them do almost all the work:\n\n\n| Name | What it is | Purpose |\n| --- | --- | --- |\n| `ABCMeta` | A metaclass | Enforces abstractness; rarely used directly |\n| `ABC` | A helper class with `metaclass=ABCMeta` | The modern, readable way to make a class abstract |\n| `abstractmethod` | A decorator | Marks a method as abstract |\n\n\n`ABCMeta` is the engine. It tracks which methods on a class are abstract, and intercepts instantiation to raise `TypeError` when any are still unimplemented. `ABC` is a one-line helper that wires the metaclass in, so the syntax becomes `class Foo(ABC)` instead of `class Foo(metaclass=ABCMeta)`. `abstractmethod` is the marker that tells `ABCMeta` \"subclasses must override this\".\n\n\n```python\nfrom abc import ABC, ABCMeta, abstractmethod\n\n# Modern, recommended style\nclass PaymentProcessor(ABC):\n @abstractmethod\n def charge(self, amount):\n pass\n\n# Equivalent older style, still legal\nclass LegacyProcessor(metaclass=ABCMeta):\n @abstractmethod\n def charge(self, amount):\n pass\n```\n\n\nBoth versions produce identical behavior. The `ABC` form is what almost every codebase written today uses; `metaclass=ABCMeta` is mainly useful when a class already needs a custom metaclass for some other reason and abstractness has to combine with it.\n\nThe `abstractmethod` decorator is a marker. It sets `__isabstractmethod__ = True` on the function. `ABCMeta` reads that flag and acts on it. Applying `@abstractmethod` to a class that doesn't have `ABCMeta` in its metaclass chain makes the decorator documentation with no enforcement:\n\n\n```python\nfrom abc import abstractmethod\n\nclass NotReallyAbstract:\n @abstractmethod\n def charge(self, amount):\n pass\n\n# This works even though charge() is \"abstract\".\nprocessor = NotReallyAbstract()\nprint(\"Created an 'abstract' instance with no error\")\n```\n\n\nThe pattern is always `ABC` plus `abstractmethod`, not one or the other. Pair them, or the decorator has no effect.\n\n---\n\n# How `ABCMeta` Enforces Abstractness\n\nWhen Python builds a class, the metaclass's `__init__` runs. `ABCMeta.__init__` walks the class body, finds every method marked with `__isabstractmethod__`, and stores their names in a frozen set on the class as `__abstractmethods__`. When the class is called to construct an instance, `ABCMeta.__call__` checks whether that set is empty. If it isn't, the result is the `TypeError` that lists the missing methods.\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass PaymentProcessor(ABC):\n @abstractmethod\n def charge(self, amount):\n pass\n\n @abstractmethod\n def refund(self, amount):\n pass\n\nprint(PaymentProcessor.__abstractmethods__)\n```\n\n\nThat frozen set is the registry the metaclass consults. A subclass inherits the parent's abstract methods and removes from the set any that it overrides. Once the set is empty, the subclass is concrete.\n\n\n```python\nclass CreditCardProcessor(PaymentProcessor):\n def charge(self, amount):\n return f\"Charged ${amount:.2f}\"\n\n def refund(self, amount):\n return f\"Refunded ${amount:.2f}\"\n\nprint(CreditCardProcessor.__abstractmethods__)\nprint(CreditCardProcessor() is not None)\n```\n\n\n`CreditCardProcessor` overrode both abstract methods, so its `__abstractmethods__` set is empty, and instantiation works. Overriding only one leaves the other in the set, and instantiation fails:\n\n\n```python\nclass PartialProcessor(PaymentProcessor):\n def charge(self, amount):\n return \"charged\"\n\nprint(PartialProcessor.__abstractmethods__)\nPartialProcessor()\n```\n\n\nThe error message names the class and the methods that are still abstract. That message is generated from the `__abstractmethods__` set; it's not a hand-written check.\n\nThe abstractness check happens once per class definition (to build the set) and once per instantiation (to verify the set is empty). The runtime cost is negligible; the only real cost is that abstract classes can't be used as plain placeholders.\n\n---\n\n# Combining `@abstractmethod` With Other Decorators\n\n`abstractmethod` is the only decorator the `abc` module exposes for marking methods, but it composes with the built-in `property`, `classmethod`, and `staticmethod` decorators. The combinations look a little odd at first because decorator order matters in a way that doesn't usually come up.\n\n### `@abstractmethod` With `@property`\n\nA common contract is \"every implementation must expose this value as a read-only attribute\". Place `@property` on top and `@abstractmethod` underneath:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass Shippable(ABC):\n @property\n @abstractmethod\n def weight(self):\n pass\n\nclass Book(Shippable):\n def __init__(self, title, weight_kg):\n self.title = title\n self._weight = weight_kg\n\n @property\n def weight(self):\n return self._weight\n\nbook = Book(\"Python in Practice\", 0.45)\nprint(f\"{book.title} weighs {book.weight} kg\")\n```\n\n\nDecorators apply bottom-up. `@abstractmethod` runs first and marks the raw function as abstract. `@property` wraps the abstract function as a property descriptor. The result is a property whose getter is tracked in the abstract-method set, which is what `ABCMeta` needs to enforce.\n\nReversing the order breaks the enforcement. `@property` wraps the function first, producing a property object. Then `@abstractmethod` marks that property object, but `ABCMeta` doesn't propagate the abstract flag correctly through a `property` wrapper unless `@abstractmethod` was applied to the raw function. Subclasses can then skip the override without Python flagging the omission.\n\n### `@abstractmethod` With `@classmethod`\n\nA factory method that every subclass must provide. The decorator order is `@classmethod` on top, `@abstractmethod` underneath:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass Importable(ABC):\n @classmethod\n @abstractmethod\n def from_csv_row(cls, row):\n pass\n\nclass Order(Importable):\n def __init__(self, order_id, total):\n self.order_id = order_id\n self.total = total\n\n @classmethod\n def from_csv_row(cls, row):\n order_id, total = row\n return cls(order_id, float(total))\n\norder = Order.from_csv_row([\"ORD-1\", \"49.99\"])\nprint(f\"Order {order.order_id}, total ${order.total:.2f}\")\n```\n\n\nThe same bottom-up rule applies: `@abstractmethod` marks the function, `@classmethod` wraps it as a class method. Subclasses must define their own `from_csv_row` classmethod, and the parent's abstract version blocks instantiation until they do.\n\n### `@abstractmethod` With `@staticmethod`\n\nA static helper that every implementation must provide. Same pattern:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass Validator(ABC):\n @staticmethod\n @abstractmethod\n def is_valid(value):\n pass\n\nclass EmailValidator(Validator):\n @staticmethod\n def is_valid(value):\n return \"@\" in value and \".\" in value\n\nprint(EmailValidator.is_valid(\"alice@example.com\"))\nprint(EmailValidator.is_valid(\"not-an-email\"))\n```\n\n\n`@staticmethod` doesn't receive `self` or `cls`, so the abstract version is a function-shaped contract attached to the class. The bottom-up decorator order still applies.\n\n\n| Combination | Order (top to bottom) | What subclasses must provide |\n| --- | --- | --- |\n| Abstract method | `@abstractmethod` | A method with the same name |\n| Abstract property | `@property`, then `@abstractmethod` | A `@property` with the same name |\n| Abstract classmethod | `@classmethod`, then `@abstractmethod` | A `@classmethod` with the same name |\n| Abstract staticmethod | `@staticmethod`, then `@abstractmethod` | A `@staticmethod` with the same name |\n\n\nThe rule of thumb: `@abstractmethod` goes on the bottom, the role-defining decorator goes on top. Any other order either breaks enforcement or produces a confusing object.\n\n---\n\n# Virtual Subclasses With `ABCMeta.register`\n\n`ABCMeta` has one capability that turns abstract base classes from a \"subclasses must inherit from me\" mechanism into something more flexible: **virtual subclassing**. Calling `Base.register(SomeClass)` tells the ABC machinery to treat `SomeClass` as a subclass of `Base` for the purposes of `isinstance` and `issubclass`, without modifying `SomeClass` and without any actual inheritance.\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass Loggable(ABC):\n @abstractmethod\n def log(self, message):\n pass\n\nclass StdlibLogger:\n \"\"\"A class outside the codebase, maybe from a third-party library.\"\"\"\n def log(self, message):\n print(f\"Logged: {message}\")\n\n# Register StdlibLogger as a virtual subclass of Loggable.\nLoggable.register(StdlibLogger)\n\nlogger = StdlibLogger()\nlogger.log(\"hello\")\nprint(isinstance(logger, Loggable))\nprint(issubclass(StdlibLogger, Loggable))\n```\n\n\n`StdlibLogger` does not inherit from `Loggable` in the normal sense. It has no `Loggable` in its `__mro__`:\n\n\n```python\nprint(StdlibLogger.__mro__)\n```\n\n\nBut `isinstance(logger, Loggable)` returns `True` anyway. The ABC machinery keeps a private set of registered subclasses on each abstract base, and `isinstance` consults that set in addition to the normal inheritance chain. The registered class itself is unchanged.\n\nThis is useful in three situations:\n\n- **Integrating third-party classes.** A library outside the codebase has the right shape but doesn't inherit from a local abstract base. `register` accepts it without a wrapper.\n- **Legacy code.** An existing class hierarchy predates the new abstract base. The abstraction layers on top without changing the existing classes.\n- **Built-in protocols.** Python's own built-ins like `list`, `dict`, and `tuple` are registered as virtual subclasses of the abstract bases in `collections.abc`. That's how `isinstance([], collections.abc.Iterable)` returns `True` even though `list` doesn't inherit from `Iterable` directly.\n\nThe catch is real: `register` does not check that the class has the required methods. It's a promise to Python, not a verification. If `StdlibLogger` were missing `log`, the registration would still succeed, and `isinstance` would still return `True`. The error would only show up at call time, the same way it does with plain duck typing. For verified shape checks, combine `register` with tests or use `typing.Protocol` with `@runtime_checkable`.\n\n\n```mermaid\nflowchart LR\n Code[\"isinstance(obj, Loggable)\"]:::cyan\n Check[\"ABCMeta inspects
both MRO and
registered set\"]:::orange\n MRO[\"MRO check
(inheritance)\"]:::green\n Registered[\"registered
virtual subclasses\"]:::teal\n Yes[\"Returns True\"]:::green\n\n Code --> Check\n Check --> MRO\n Check --> Registered\n MRO --> Yes\n Registered --> Yes\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows where virtual subclasses fit. `isinstance` doesn't only walk the inheritance chain; it also asks the ABC whether the class has been registered. Either route returns `True`.\n\n`register` doesn't enforce method presence. The check happens whenever the method is called, which means a missing or misnamed method on a registered class fails at call time, not at registration. Pair `register` with tests when correctness matters.\n\n---\n\n# Built-in Abstract Base Classes: `collections.abc`\n\nPython ships with a set of pre-defined abstract base classes that describe the protocols built into the language. They live in `collections.abc`, and they're the standard way to type-check or assert \"this object behaves like a sequence\" or \"this object is iterable.\"\n\nThe most common ones:\n\n\n| ABC | Required methods | Examples that satisfy it |\n| --- | --- | --- |\n| `Iterable` | `__iter__` | `list`, `tuple`, `dict`, `set`, generators |\n| `Iterator` | `__iter__`, `__next__` | Generators, file objects, `iter(some_list)` |\n| `Sized` | `__len__` | `list`, `tuple`, `dict`, `set`, `str` |\n| `Container` | `__contains__` | `list`, `tuple`, `dict`, `set`, `str` |\n| `Sequence` | `__getitem__`, `__len__` | `list`, `tuple`, `str` |\n| `MutableSequence` | `Sequence` plus `__setitem__`, `__delitem__`, `insert` | `list` |\n| `Mapping` | `__getitem__`, `__len__`, `__iter__`, plus methods like `keys`, `values`, `items` | `dict` |\n| `MutableMapping` | `Mapping` plus `__setitem__`, `__delitem__` | `dict` |\n| `Set` | `__contains__`, `__iter__`, `__len__` | `set`, `frozenset` |\n| `Hashable` | `__hash__` | Most immutable types |\n| `Callable` | `__call__` | Functions, lambdas, classes with `__call__` |\n\n\nTwo things make these useful. First, they support structural checks:\n\n\n```python\nfrom collections.abc import Iterable, Sized, Mapping\n\nprint(isinstance([1, 2, 3], Iterable))\nprint(isinstance(\"hello\", Sized))\nprint(isinstance({\"a\": 1}, Mapping))\nprint(isinstance(42, Iterable))\n```\n\n\nThe built-in types are all registered as virtual subclasses of the appropriate ABCs, so `isinstance` works without any setup. Custom classes that implement the right methods don't automatically register; they have to inherit from the ABC or call `register` explicitly. (Some ABCs detect their own protocols through `__subclasshook__`, which lets `isinstance` succeed structurally for classes that have the right methods. `Iterable` does this for `__iter__`, for example.)\n\nSecond, inheriting from them brings **mixin methods at no extra cost**. A class that inherits from `collections.abc.Sequence` and implements `__getitem__` and `__len__` gets `__iter__`, `__contains__`, `index`, `count`, `__reversed__`, and `__add__` automatically:\n\n\n```python\nfrom collections.abc import Sequence\n\nclass WishList(Sequence):\n \"\"\"A read-only wishlist that stores product names.\"\"\"\n\n def __init__(self, items):\n self._items = list(items)\n\n def __getitem__(self, index):\n return self._items[index]\n\n def __len__(self):\n return len(self._items)\n\nwishlist = WishList([\"book\", \"mug\", \"shirt\", \"headphones\"])\n\nprint(len(wishlist))\nprint(wishlist[2])\nprint(\"mug\" in wishlist) # __contains__ for free\nprint(wishlist.count(\"book\")) # count() for free\nprint(list(reversed(wishlist))) # __reversed__ for free\n```\n\n\n`WishList` implemented only two methods but got six more methods from the `Sequence` ABC. This is the second job `collections.abc` does: it standardizes what a \"sequence\" or a \"mapping\" or a \"set\" offers, so any class that fits the protocol picks up the common helpers without rewriting them.\n\nThe same pattern applies to `MutableSequence` (add `__setitem__`, `__delitem__`, and `insert`; pick up `append`, `extend`, `pop`, `remove`, `reverse`, `__iadd__` automatically), `Mapping` (pick up `__contains__`, `keys`, `items`, `values`, `get`, `__eq__`, `__ne__`), and others. The list of provided mixin methods for each ABC is in the official `collections.abc` documentation.\n\n\n| Implemented methods | Inherit from | Methods inherited |\n| --- | --- | --- |\n| `__iter__` | `Iterable` | `__iter__` is the only thing in the protocol |\n| `__getitem__`, `__len__` | `Sequence` | `__contains__`, `__iter__`, `__reversed__`, `index`, `count` |\n| `__getitem__`, `__setitem__`, `__delitem__`, `__len__`, `insert` | `MutableSequence` | All the above plus `append`, `extend`, `pop`, `remove`, `reverse`, `__iadd__` |\n| `__getitem__`, `__len__`, `__iter__` | `Mapping` | `__contains__`, `keys`, `items`, `values`, `get`, `__eq__`, `__ne__` |\n| `__getitem__`, `__setitem__`, `__delitem__`, `__iter__`, `__len__` | `MutableMapping` | All the above plus `pop`, `popitem`, `clear`, `update`, `setdefault` |\n\n\nInheriting from `collections.abc.Sequence` instead of building a list-like class from scratch saves work and signals intent. A reader of the code knows that `WishList` is meant to behave like a sequence, and a type checker knows the same thing.\n\n---\n\n# When to Use `abc.ABC` vs `typing.Protocol`\n\nPython has two ways to describe \"an object with these methods\". `abc.ABC` is one. `typing.Protocol` (added in Python 3.8) is the other. This section makes the trade-off concrete with the `abc` machinery in mind.\n\n`ABC` is **nominal**: a class belongs to a type because it inherits from that type (directly or via `register`). The relationship is explicit. Instantiation is checked at runtime. Omitting an abstract method causes `TypeError` the moment an instance of the offending class is created.\n\n`Protocol` is **structural**: a class belongs to a type because it has the right methods, regardless of inheritance. The relationship is implicit. Static type checkers verify the shape at type-check time. There's no runtime enforcement by default; `@runtime_checkable` adds an `isinstance` check that inspects method names only.\n\n\n```python\n# ABC version: explicit inheritance required\nfrom abc import ABC, abstractmethod\n\nclass Notifier(ABC):\n @abstractmethod\n def send(self, message):\n pass\n\nclass EmailNotifier(Notifier):\n def send(self, message):\n print(f\"Email: {message}\")\n\n# Protocol version: no inheritance required\nfrom typing import Protocol\n\nclass NotifierProtocol(Protocol):\n def send(self, message: str) -> None: ...\n\nclass StandaloneNotifier:\n def send(self, message):\n print(f\"Standalone: {message}\")\n\ndef notify(n: NotifierProtocol, message: str) -> None:\n n.send(message)\n\nnotify(EmailNotifier(), \"Hi\")\nnotify(StandaloneNotifier(), \"Hi\")\n```\n\n\nBoth calls work. `EmailNotifier` explicitly inherits from `Notifier`; `StandaloneNotifier` doesn't inherit from anything but still satisfies `NotifierProtocol` because it has a `send` method. A type checker accepts both in the call to `notify`.\n\nThe trade-off in a table:\n\n\n| Aspect | `abc.ABC` | `typing.Protocol` |\n| --- | --- | --- |\n| Style | Nominal (explicit inheritance or `register`) | Structural (shape-based) |\n| Enforced at | Runtime, on instantiation | Type-check time (mypy, pyright) |\n| Runtime `isinstance` | Works automatically | Only with `@runtime_checkable`, names only |\n| Missing method | `TypeError` at instantiation | Type-check warning |\n| Inheritance | Required (or `register`) | Not required |\n| Best fit | Library authors locking down a contract | API surfaces that accept any matching shape |\n\n\nThree rules of thumb cover most cases:\n\n1. The codebase controls the subclasses and needs a runtime guarantee that every implementation is complete. Use `ABC`.\n2. Third-party or legacy classes need to satisfy an interface without modification. Use `Protocol`, optionally with `@runtime_checkable`.\n3. Both apply: a published contract for explicit subclasses and structural typing for everything else. Use `ABC` for the inheritance side and `Protocol` for the type hints. They coexist fine.\n\nThe full reference for `ABC` is at docs.python.org under the `abc` module.\n\n---\n\n# Real-World Patterns\n\n`abc` shows up in a few well-defined patterns. Each one solves a specific problem and provides a template that's easy to recognize in other code.\n\n### Pattern 1: Strategy\n\nAn abstract base defines a single operation; multiple concrete implementations provide different algorithms for that operation. Callers hold a reference typed as the abstract base and pick which strategy to use at runtime:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass DiscountStrategy(ABC):\n @abstractmethod\n def apply(self, price):\n pass\n\nclass PercentageDiscount(DiscountStrategy):\n def __init__(self, percent):\n self.percent = percent\n\n def apply(self, price):\n return price * (1 - self.percent / 100)\n\nclass FlatDiscount(DiscountStrategy):\n def __init__(self, amount):\n self.amount = amount\n\n def apply(self, price):\n return max(0.0, price - self.amount)\n\ndef checkout(price, discount):\n return discount.apply(price)\n\nprint(checkout(100.00, PercentageDiscount(20)))\nprint(checkout(100.00, FlatDiscount(15)))\n```\n\n\n`DiscountStrategy` declares the contract: any discount has an `apply(price)` method. `PercentageDiscount` and `FlatDiscount` are concrete strategies. `checkout` doesn't know or care which one it has; it calls `apply`. Adding a \"buy one get one\" strategy means writing one new class.\n\n### Pattern 2: Template Method\n\nAn abstract base provides a concrete method that orchestrates the work and delegates specific steps to abstract methods that subclasses must implement. Subclasses fill in the specifics; the parent owns the overall flow:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass OrderProcessor(ABC):\n def process(self, order):\n self.validate(order)\n self.charge(order)\n self.confirm(order)\n\n @abstractmethod\n def validate(self, order):\n pass\n\n @abstractmethod\n def charge(self, order):\n pass\n\n def confirm(self, order):\n print(f\"Order {order['id']} confirmed\")\n\nclass StandardOrderProcessor(OrderProcessor):\n def validate(self, order):\n print(f\"Validating order {order['id']}\")\n\n def charge(self, order):\n print(f\"Charging ${order['total']:.2f}\")\n\nprocessor = StandardOrderProcessor()\nprocessor.process({\"id\": \"ORD-1\", \"total\": 49.99})\n```\n\n\n`process` is the template; it defines the flow. `validate` and `charge` are the holes that subclasses fill. `confirm` is a concrete method shared by all subclasses. The pattern guarantees that every implementation runs the same sequence; the variation is in the individual steps.\n\n### Pattern 3: Registry of Implementations\n\nCombined with `register`, an abstract base can act as a hub that knows about a set of related implementations. Useful for plugin systems or extensible APIs:\n\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass FileLoader(ABC):\n @abstractmethod\n def load(self, path):\n pass\n\nclass CsvLoader:\n \"\"\"Existing class that wasn't designed with FileLoader in mind.\"\"\"\n def load(self, path):\n return f\"Loaded CSV from {path}\"\n\nclass JsonLoader:\n def load(self, path):\n return f\"Loaded JSON from {path}\"\n\nFileLoader.register(CsvLoader)\nFileLoader.register(JsonLoader)\n\nloaders = [CsvLoader(), JsonLoader()]\nfor loader in loaders:\n assert isinstance(loader, FileLoader)\n print(loader.load(\"data.txt\"))\n```\n\n\n`CsvLoader` and `JsonLoader` are pre-existing classes that fit the `FileLoader` shape but weren't designed to inherit from anything. Registering them turns them into virtual subclasses, and code elsewhere can do `isinstance(obj, FileLoader)` to confirm membership. The classes themselves are unchanged.\n\n\n| Pattern | What it provides | When to use it |\n| --- | --- | --- |\n| Strategy | Swap algorithms behind one interface | Multiple implementations of \"do X\" |\n| Template Method | Fixed flow with customizable steps | Same orchestration, different specifics |\n| Registry of Implementations | Group existing classes under one ABC | Plugin systems, third-party integration |\n\n\nThese aren't the only patterns `abc` enables, but they cover the situations that come up most often. Each one uses different parts of the `abc` machinery: Strategy and Template Method rely on inheritance and `@abstractmethod`; Registry of Implementations uses `register` to fold in classes from outside the codebase.","pageType":"python"}

abc Module

Get Premium