Generics in Python: A Beginner's Guide
Learn the fundamentals of generics in Python, how they enhance code flexibility and type safety, and practical examples to get you started.
Before we jump into the world of generics, let’s first understand why typing is important in Python.
- Introduction
- What Are Generics?
- How to Implement Generics in Python
- Why Was There a Need to Have Generics? What Problem Does It Solve?
- Two Ways to Instantiate Generic Classes in Python 3.12+
- Advanced Generics Unveiled (Python 3.12+)
- Conclusion
Introduction
Have you ever written a Python function or a class that works for multiple types — like a list of numbers or strings? Generics let you tell Python: “This works for any type — but keep track of which one.” In this post, we’ll break down how that works in plain English.
💡 Did You Know? Built-in Generics Aren’t Special
Type hints like list[str] and dict[str, int] are generic types — they accept type parameters.
Behind the scenes, these are also defined as generic types.
🧩 Here’s the cool part:
You can define your own generics` — just like Python’s built-ins.
This allows for clean, reusable, and type-safe code.
Let’s continue the journey and see how this works in practice!
What Are Generics?
Generics let you write one piece of code that can work with many different types — without losing track of what type it’s actually working with. Think of it like a “template” or a “blueprint” that adapts depending on the type you give it.
Simple Analogy: Containers with Labels
Imagine you have many containers — boxes, bags, jars.
- Each container can hold anything: books, phones, clothes.
- But each container has a label that tells you what’s inside.
For example:
- A box labeled “Books” means it holds books.
- Another labeled “Phones” holds phones.
The container itself doesn’t change — same shape and size —
only the label (the type) changes.
Generics are like those labeled containers:
- The code (container) stays the same,
- but the type (label) changes depending on what you want to store or work with.
How to Implement Generics in Python
Python supports writing generic code in two main ways, depending on the version you’re using.
Old Way (Python < 3.12)
Before Python 3.12, to write generic classes, you needed to:
- Define a type variable using
TypeVar. is like creating a placeholder or label- This spot can be filled with any type you want, but once you pick a type, stay consistent with it throughout
- Make your class inherit from
Genericwith that type variable.it is like telling a class- “I’m building a container that uses this labeled placeholder, so remember what type it holds and keep it consistent everywhere inside this container.”
For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
from typing import TypeVar, Generic
T = TypeVar('T') # Define a type variable (a placeholder for any type)
class Box(Generic[T]):
def __init__(self, content: T):
self.content = content
def get_content(self) -> T:
return self.content
def echo(item: T) -> T: # here `T` is typevar instance already defined
return item
New Way (Python 3.12+)
Starting with Python 3.12, writing generics has become much cleaner and more intuitive thanks to PEP 695.
Instead of importing and defining TypeVar, and inheriting from Generic, you can now declare the type parameter directly in the class or function definition.
1
2
3
4
5
6
7
8
9
10
11
# Python 3.12+
class Box[T]:
def __init__(self, content: T):
self.content = content
def get_content(self) -> T:
return self.content
def foo[A](value:A)->A:
print("value accepted")
return value
Note : we can use any letter
TorAor etc. but it should follow the proper syntax
ℹ️ Info: we will be continuing with python version 3.12+
Why Was There a Need to Have Generics? What Problem Does It Solve?
Let’s take a simple example: returning the first element of a list.
At first, this looks easy — just write a function and return the first item.
But once you bring in type annotations (especially when using tools like MyPy), a few important questions show up:
- What should be the return type of this function?
- What if the input list contains any type — an
int,str,float, or even a custom object? - How can we make sure the return type is accurate and flexible at the same time?
The Problem Without Generics
Here’s a basic implementation:
1
2
def return_first_element(input_ls: list) -> int | str | float:
return input_ls[0]
Problems with This Approach
What if the list contains a custom object, a
bool, or adict?
The return type won’t be correct.You have to manually list all possible types in the return annotation.
The function is not reusable, not fully type-safe, and hard to maintain as the codebase grows.
The Generic-Based Solution
Here’s the same function rewritten using generics:
1
2
3
4
5
6
from typing import TypeVar, List
T = TypeVar('T')
def return_first_element(input_ls: List[T]) -> T:
return input_ls[0]
What Problem Does This Solve?
The function now works for any list: List[int], List[str], List[float], List[CustomType], etc.
The return type matches whatever type the list contains.
No need to hardcode all possible types.
The code is now clean, type-safe, reusable, and future-proof.
Type checkers like MyPy can now verify type correctness automatically.
1
2
3
return_first_element([1, 2, 3]) # return type: int
return_first_element(["a", "b", "c"]) # return type: str
return_first_element([{"x": 1}, {"y": 2}]) # return type: dict[str, int]
⚡ Note: Generics primarily shine in classes, where most of their power is used.
Two Ways to Instantiate Generic Classes in Python 3.12+
With Python 3.12’s updated syntax, you can create generic class instances in two main ways.
1. Implicit Generic Instantiation (Type Inference from Constructor)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class Box[T]:
def __init__(self, value: T):
self.value = value
def get_item(self) -> T:
return self.value
def change_item(self, value: T) -> None:
self.value = value
# Create an instance of Box, passing an integer 12
# Python infers T = int because 12 is an int
obj = Box(12) # obj is treated as Box[int]
obj.change_item(12) # ✅ Allowed: 12 matches inferred type int
obj.change_item("123") # ❌ Type checker error: str is not compatible with int
🔍 How Does This Work?
- When you call
Box(12), Python infers the typeTasintbecause12is an integer. - Internally, the object behaves like a
Box[int]. - Type checkers like MyPy use this inferred type to:
- Ensure you’re using the class consistently.
- Catch any type mismatches during static analysis.
💡 Key point:
- The constructor argument acts as a clue to Python and static analyzers to “fill in” the generic type automatically.
- If the constructor doesn’t use
T(or any generic letter), Python can’t infer or enforce the type implicitly
2. Explicit Generic Instantiation (Manually Specify Type Parameter)
Sometimes, you might want to explicitly specify the type parameter when creating an instance:
1
2
3
4
5
6
# Explicitly telling Python that T should be int
obj_int = Box[int](123)
# Explicitly telling Python that T should be str
obj_str = Box[str]("hello")
obj_bad = Box[str](123) # ❌ This will be caught by mypy
Advanced Generics Unveiled (Python 3.12+)
1. Bounded Type Variables — Ensuring Constraint Compliance
Rather than allowing any type, bounded type variables constrain generics to only those that meet specific criteria.
This improves both type safety and code clarity.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Using classic (old-style) TypeVar constraints for context—verbose and less Pythonic:
# T = TypeVar("T", bound=int | float) # <-- This is old style and more verbose
# New-style syntax (Python 3.12+): cleaner and built-in generic declaration
class Container[T: int | float]:
def __init__(self, value: T):
self.items = value
def change_item(self, v: T) -> None:
self.items = v
# Implicit inference: T inferred as int
obj = Container(12)
obj.change_item(100) # OK: both ints
obj.change_item(12.1) # MyPy ERROR: float not assignable to T (inferred as int)
# Explicit generic instantiation for float
obj_float = Container[float](10.29) # OK: float matches T
# Invalid: str not allowed by constraint
obj_str = Container[str]("12") # MyPy ERROR: "str" is not one of the allowed types for T
# Invalid: inference fails due to unsupported type
obj_mixed = Container("12") # MyPy ERROR: cannot infer T; "str" not allowed
🔍 Example:
T: int | floatensures thatTis constrained to eitherintorfloat, allowing static type checkers like MyPy to catch incorrect usage.
This inline syntax is part of PEP 695 — introduced in Python 3.12+ — which brings simpler and more powerful generics to Python.
Why It’s Useful
- Ensures your generic class only works with specific, compatible types.
- Catches misuse (like passing a
str) before runtime. - Makes your code cleaner, self-documenting, and future-proof.
- Encourages better design by making type expectations explicit.
2. Multiple Type Parameters — Flexible Multi-Type Containers
In Python 3.12+, you can define classes that accept multiple type parameters directly.
1
2
3
4
5
6
7
8
9
10
11
class Pair[K, V]:
def __init__(self, first: K, second: V):
self.first = first
self.second = second
pair = Pair(1, "one") # ✅ Type inferred: Pair[int, str]
pr_explicit = Pair[int, str](2, "two") # ✅ Explicit type declaration
pr_invalid = Pair[int](2, "two") # ❌ ERROR: Missing second type argument (V)
print(pair.first) # Output: 1
print(pair.second) # Output: one
How It Works
KandVare type placeholders, introduced inline using the new generic syntax.- They represent the types of
firstandsecond, respectively — allowing full control over multiple type parameters.
3. Generics in Inheritance: Simplified and Typed (Python 3.12+)
a. Generic Base Classes
Define a base class that’s parameterized with a generic type, and then subclass it with a concrete type:
1
2
3
4
5
6
7
8
9
10
11
12
class Repository[T]:
def __init__(self, item: T):
self.item = item
def get(self) -> T:
return self.item
class IntRepository(Repository[int]):
pass
repo = IntRepository(123)
value: int = repo.get() # Type-safe: value is an int
Why this matters:
- Less boilerplate and clearer inheritance.
- The T placeholder makes the base class generic and flexible.
b. Enforcing Method Signatures in Subclasses
When overriding generic methods, re-declaring the specialized types ensures consistent static analysis:
1
2
3
4
5
6
7
8
9
class A[T]:
def process(self, item: T) -> str:
return f"Processed {item}"
class B(A[int]):
def process(self, item: int) -> str: # signature type mentioned
return super().process(item)
result: str = B().process(42) # Correctly typed as str
4. Generic Protocols — Duck Typing Meets Type Safety
Protocols let you say:
“I don’t care what type you are, as long as you have these methods.”
Now combine that with generics, and you get flexible yet type-safe interfaces.
Example: Saver[T] Protocol
1
2
3
4
5
6
from typing import Protocol, TypeVar
T = TypeVar("T")
class Saver(Protocol[T]):
def save(self, item: T) -> None: ...
Saver[T] is a generic protocol.
Any class that implements a save(item: T) method will be treated as a Saver[T].
No need for explicit inheritance — this is structural subtyping (aka duck typing).
1
2
3
4
5
6
7
class FileSaver:
def save(self, item: str) -> None:
print(f"Saving text: {item}")
class DbSaver:
def save(self, item: dict) -> None:
print(f"Saving to DB: {item}")
These classes don’t inherit from Saver, but MyPy recognizes them as valid because they implement the expected save(item: T) method.
Generic Function Using the Protocol
1
2
3
4
5
def store_item(saver: Saver[T], item: T):
saver.save(item)
store_item(FileSaver(), "Hello") # Valid: item is str
store_item(DbSaver(), {"id": 1}) # Valid: item is dict
Why It Matters
Loose coupling: You don’t force classes to inherit — they just need the right shape.
Strong typing: Static checkers still verify everything.
Generic flexibility: Saver[T] works for any T.
Protocols + Generics = The best of both dynamic and static typing worlds!
Conclusion
Generics in Python — especially with the new Python 3.12+ syntax — bring clarity, reusability, and type safety to your code. Whether you’re writing flexible data structures, reusable functions, or protocols that enforce interface contracts, generics help you express intent while catching bugs early.
They aren’t just for libraries or advanced use cases — they’re for anyone writing code that works with multiple types.
As Python evolves, mastering generics is a step toward writing cleaner, more maintainable, and future-proof code.
Happy typing!