Build a Python Library with Advanced Features

Building a Python library means packaging reusable code so others can install it, import it, and rely on it. This article walks through creating a small but complete library that demonstrates the advanced Python features covered throughout this section: descriptors for validated attributes, metaclasses for class registration, type hints for API clarity, and proper project structure for distribution.

The library we will build is a simple validation framework called validable. It lets users define data classes with typed, validated fields, and it automatically registers every model class for serialization. It is small enough to understand in one sitting but demonstrates real patterns used in production libraries.

Project structure and pyproject.toml

A modern Python library starts with a clean project layout. The package code lives in a directory named after the package. A pyproject.toml file declares metadata, dependencies, and build configuration.

plaintext

validable/
    pyproject.toml
    src/
        validable/
            __init__.py
            models.py
            fields.py
            errors.py
    tests/
        test_models.py

The init file exports the public API names that users should import. Everything the user needs should come directly from the top-level package name without navigating into internal submodules.

python

from validable import Model, Field, ValidationError

Keeping the public API small and predictable is the most important design decision. Every name you export is a commitment.

Custom exceptions

Libraries should define their own exception hierarchy. This lets callers catch library-specific errors without accidentally catching unrelated exceptions.

python

class ValidableError(Exception):
    pass
 
class ValidationError(ValidableError):
    def __init__(self, field, value, reason):
        self.field = field
        self.value = value
        self.reason = reason
        super().__init__(f"{field}: {reason} (got {value!r})")
 
class RegistryError(ValidableError):
    pass

Callers can catch ValidableError for any library error or ValidationError specifically for field validation failures. Custom exceptions carry structured data about the error, not just a message string.

Descriptors for validated fields

The Field descriptor, covered in the article on Python descriptors, handles type checking and validation at the attribute level. Each Field instance manages storage for its attribute across all model instances.

python

class Field:
    def __init__(self, field_type, validators=None):
        self.field_type = field_type
        self.validators = validators or []
        self.storage = {}
 
    def __set_name__(self, owner, name):
        self.name = name
 
    def __get__(self, instance, owner):
        if instance is None:
            return self
        return self.storage.get(id(instance))
 
    def __set__(self, instance, value):
        if not isinstance(value, self.field_type):
            raise ValidationError(
                self.name, value,
                f"expected {self.field_type.__name__}"
            )
        for validator in self.validators:
            validator(self.name, value)
        self.storage[id(instance)] = value

The descriptor validates type on every assignment. Additional validators can enforce domain-specific rules like positivity or string length. Storage per instance uses the id-based dictionary pattern.

Metaclass for model registration

A metaclass, covered in the article on Python metaclasses, automatically registers every class that inherits from Model. This enables discovery without explicit registration calls.

python

class ModelMeta(type):
    registry = {}
 
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        if name != "Model":
            mcs.registry[name] = cls
        return cls
 
class Model(metaclass=ModelMeta):
    pass

Any class that inherits from Model is automatically added to the registry. Users never call a register function. The library discovers models at import time.

Putting it together: the user experience

With the infrastructure in place, the user-facing API is clean and declarative. Users define models by subclassing Model and declaring Fields as class attributes.

python

class User(Model):
    name = Field(str)
    age = Field(int)
 
user = User()
user.name = "Maya"
user.age = 30
print(user.name, user.age)

The fields enforce types automatically on every attribute assignment. Trying to assign a string value to the age field raises a ValidationError with a clear and descriptive error message.

text

Maya 30

Assigning a value of the wrong type shows what the descriptor actually does on a bad assignment, instead of only describing it.

python

try:
    user.age = "thirty"
except ValidationError as e:
    print(e)

The descriptor's set method catches the type mismatch before the bad value ever reaches storage, and the exception reports exactly which field failed and what it received.

text

age: expected int (got 'thirty')

The registry contains every model class defined in the application. This enables serialization, form generation, and schema introspection without additional configuration.

python

print(list(ModelMeta.registry.keys()))

Each model appears in the registry by its class name. This enables discovery by other parts of the application without any explicit registration code or decorators on the model classes.

text

['User']

What makes this a real library

This small library demonstrates the pattern behind larger frameworks. The public API is three names: Model, Field, and ValidationError. Each serves a clear purpose and the user never touches internal details.

The descriptors encapsulate attribute storage and validation. The metaclass handles class registration transparently. Type hints throughout the code let IDEs and type checkers provide autocompletion and catch mistakes.

The same architecture scales to real libraries. SQLAlchemy uses descriptors for column definitions and a metaclass for model registration, and Django uses descriptors for field management and a metaclass for model setup. Understanding the patterns in this small library prepares you to read and contribute to those larger codebases.

The article on writing Pythonic code covers the style and design principles that make a library feel natural to Python developers.