DEV Community: lihil

Design Patterns You Should Unlearn in Python-Part1

lihil — Sat, 21 Jun 2025 15:50:42 +0000

Search for “design patterns in Python” and you’ll be rewarded with a parade of tutorials showing off how to faithfully re-implement Gang of Four patterns — complete with class diagrams, factory hierarchies, and enough boilerplate to heat a small village. They’ll make you feel like you’re writing “serious” code. Smart. Professional. Enterprise-ready.

But here’s the problem: most of these patterns solve problems Python doesn’t have. They were designed for languages like Java and C++, where you have to jump through hoops just to get basic things done — no first-class functions, no dynamic typing, no modules as namespaces. Of course you’d need a Factory or a Singleton if your language gives you nothing else to work with.

Blindly copying those patterns into Python doesn’t make you clever. It makes your code harder to read, harder to test, and harder to explain to the next poor soul who has to maintain it — possibly you, three months from now.

In this post, we’ll go over a few classic GOF patterns that you should unlearn as a Python developer. For each one, we’ll look at:

How it’s usually (and badly) implemented in Python,
Why it actually made sense back when people were writing Java in 2001,
And what the Pythonic alternative looks like — because yes, there’s almost always a simpler way.

Let’s start with the biggest offender: Creational Patterns — aka, a whole category of solutions to problems Python already solved.

Singleton: When You Want a Global Variable but Make It Look Fancy

Ah yes, the Singleton. The go-to pattern for developers who want global state but still want to feel like they’re writing object-oriented code. In Python, you’ll often see this “smart” implementation using __new__ and a class variable:

class Singleton:
    _instance: "Singleton" | None = None

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

It feels clever — until you try to actually use it.

s1 = Singleton(name="Alice", age=30)
s2 = Singleton(name="Bob", age=25)

print(s1.name)  # 'Alice'
print(s2.name)  # Still 'Alice'!

What happened? Well, it turns out you’re always getting the same instance, no matter what parameters you pass. Your second call to Singleton(name="Bob", age=25) didn’t create anything new — it just silently reused the original object, with its original attributes. No warning. No error. Just quietly wrong.

But things get worse when you try to subclass it:

class DBConnection:
    _instance = None
    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

class MySqlConnection(DBConnection): ...
class PostGresConnection(DBConnection): ...

conn1 = MySqlConnection()
conn2 = PostGresConnection()

You might expect two separate objects, one for each subclass. But nope — both conn1 and conn2 are the same instance. That’s because _instance lives on the base class, not per subclass. So congratulations: you’ve now built the ultimate surprise box. PostGresConnection() might return a MySqlConnection, and MySqlConnection() might give you a PostGresConnection. It all depends on which one you happened to instantiate first.

Hope your app enjoys the roulette.

Why Singleton Made Sense in C++

Let’s be clear: the Singleton pattern didn’t appear out of thin air. It was born in the wild west of C++ — a language with no real module system and only a limited notion of namespaces.

In C++, your code lives in header and source files, all crammed together during compilation. There’s no clean way to say “this is private to this file” or “this global object only exists once” without jumping through hoops. The language gives you global variables, which quickly become a mess if you don’t control their initialization and lifetime carefully.

Because C++ doesn’t have modules (before c++20) or proper package systems, Singleton was a clever hack to guarantee exactly one instance of a class, avoiding the nightmare of duplicate globals and multiple definitions. It’s like the language forced you to invent a pattern to handle what Python solves with a simple module-level object.

// logger.h

#ifndef LOGGER_H
#define LOGGER_H

class Logger {
public:
    void log(const char* msg);
};

extern Logger globalLogger; // Declaration
#endif

// logger.cpp

#include "logger.h"
#include <iostream>

Logger globalLogger; // Definition

void Logger::log(const char* msg) {
    std::cout << msg << std::endl;
}

// main.cpp

#include "logger.h"

int main() {
    globalLogger.log("Starting the app");
    return 0;
}

The globalLogger is defined in one translation unit (logger.cpp), but if you accidentally define it in multiple places, the linker will complain about duplicate symbols. Managing this global state is tricky — and the Singleton pattern wraps this idea into a class that controls its own single instance, so you don’t have to worry about multiple definitions.

So yes, Singleton is basically a band-aid for C++’s lack of modularity and clean global state management — not a holy grail of software design.

The Pythonic Alternative: Just Use Modules (Seriously)

If you want a global, single instance in Python, you don’t need to reinvent the wheel with complicated Singleton classes. Python already gives you everything you need — in the form of modules.

Just create your object at the module level, and it’s guaranteed to be a singleton for as long as that module is imported:

# settings.py
from typing import Final

class Settings: ...

settings: Final[Settings] = Settings() # add typing.Final to settings so type checker would complain if someone is trying to re-assign the settings object.

Want to Delay Creation? Use Closures

Okay, maybe you want to delay creating the object until it’s actually needed — lazy initialization. Still no need for Singleton patterns.

Use a simple function with a closure and an internal variable to store the instance:

def _settings():
    settings: Settings = Settings()

    def get_settings() -> Settings:
        return settings

    def set_settings(value: Settings) -> None:
        nonlocal settings
        settings = value

    return get_settings, set_settings

get_settings, set_settings = _settings()

Example of this pattern from github

This approach is especially useful when your settings object depends on values only available at runtime — for example, the path to an environment file (env_file: Path). With lazy initialization via closure, you can defer creating the Settings instance until you have all the necessary information, instead of forcing it at import time.

Builder Pattern: Overcomplicating Object Creation Like a Boss

If you’ve dabbled in design patterns, you’ve probably seen the Builder pattern praised as the elegant way to construct complex objects step-by-step. In languages like Java or C++, where constructors can’t have default arguments and object immutability is king, this makes some sense.

But in Python? Oh boy. You’ll often find “builders” that look like this:

class CarBuilder:
    def __init__(self):
        self._color = None
        self._engine = None

    def set_color(self, color: str) -> "CarBuilder":
        self._color = color
        return self

    def set_engine(self, engine: str) -> "CarBuilder":
        self._engine = engine
        return self

    def build(self) -> "Car":
        return Car(color=self._color, engine=self._engine)

class Car:
    def __init__(self, color: str, engine: str):
        self.color = color
        self.engine = engine

car = (
    CarBuilder()
    .set_color("red")
    .set_engine("V8")
    .build()
)

This is the kind of code that makes you look like you know what you’re doing... until you realize you just reinvented named arguments with method chaining and extra classes. All that boilerplate, just to avoid using Python’s default arguments or keyword arguments?

Congratulations! You’ve just made a builder to work around a problem Python already solves out of the box.

why Builder pattern is often needed due to lack of default parameter values:

public class Car {
    private final String color;
    private final String engine;

    private Car(Builder builder) {
        this.color = builder.color;
        this.engine = builder.engine;
    }

    public static class Builder {
        private String color;   // no default value
        private String engine;  // no default value

        public Builder setColor(String color) {
            this.color = color;
            return this;
        }

        public Builder setEngine(String engine) {
            this.engine = engine;
            return this;
        }

        public Car build() {
            // You might want to add validation here
            return new Car(this);
        }
    }

    public static void main(String[] args) {
        Car car = new Car.Builder()
            .setColor("Red")
            .setEngine("V8")
            .build();
    }
}

In Java, constructors can’t have default values for parameters, and method overloading quickly becomes cumbersome for many options. The Builder pattern solves this by allowing step-by-step construction with optional parameters.

The Pythonic Alternative: Default Arguments and Factory Functions — No Builders Required

So how do we build complex objects in Python without all the ceremony? Simple: we just use the language like it was meant to be used.

1. Use Default Arguments Like a Normal Human

In Python, we don’t need to chain setters just to create an object. We can give parameters default values right in the constructor — no extra classes needed:

class Car:
    def __init__(self, color: str = "black", engine: str = "V4"):
        self.color = color
        self.engine = engine

car = Car(color="red", engine="V8")

Boom. Readable, concise, and infinitely easier to test. You want a default car? Just call Car(). You want something fancy? Pass in the arguments. Done.

2. Want Something Fancier? Use a Factory Function with Overloads

If you want more control or better editor support (e.g. different argument combos), a factory function with typing.overload gives you flexibility without creating a whole Builder class:

from typing import overload

class Car:
    def __init__(self, color: str, engine: str):
        self.color = color
        self.engine = engine

@overload
def make_car() -> Car: ...
@overload
def make_car(color: str) -> Car: ...
@overload
def make_car(color: str, engine: str) -> Car: ...

def make_car(color: str = "black", engine: str = "V4") -> Car:
    return Car(color=color, engine=engine)

car1 = make_car()
car2 = make_car("red")
car3 = make_car("blue", "V8")

You get clean logic, helpful autocompletion in your IDE, and zero boilerplate. Imagine that — solving the builder problem with just functions and defaults.

Who knew?

I Created a Fullstack template to let you deploy your app on cloud for 0 cost

lihil — Thu, 12 Jun 2025 16:34:08 +0000

I built a fullstack solopreneur project template with free cloud hosting and detailed tutorials

Hey everyone,
I’ve been working on a fullstack template aimed at solo devs or indie hackers who want to build and ship something without spending money on infrastructure. I put a lot of effort into making sure everything works out of the box and included step-by-step guides so you can actually deploy it—even if you’ve never done it before.

What’s in it:

Detailed Tutorials & config template to eploy backend to Vercel and frontend to Cloudflare (both have free tiers)
Supabase for database and auth (also free tier)
Generate frontend client based on backend API
Dashboard with metrics and analytics
User management and role-based access control
Sign up / sign in with OAuth
Task management with full CRUD
Pre-configured dev setup with Docker and hot reload

Task management

User management

it’s meant to be used as a quick project starter for app developed by a single person, It followed solid backend/frontend practices, used modern tools (React 19, TypeScript, Tailwind, OpenAPI, etc.), and tried to keep the architecture clean and easy to extend.

If you’re looking to learn how to actually build and deploy a real app with no cost, this could help. Whether you’re making a SaaS, a side project, or just want to understand the fullstack flow better, I hope this saves you some time.

Still actively improving it, so any feedback is appreciated.

Frontend is based on this great project called shadcn-admin (https://github.com/satnaing/shadcn-admin)

GITHUB

github-fullstack-solopreneur-template

Decorators and Functional Programming in Python

lihil — Thu, 29 May 2025 11:22:19 +0000

I often see people ask how to "do functional programming in Python"—as if it requires special tools or libraries.

But the truth is, many Python developers are already using functional programming techniques without realizing it. One of the clearest examples is the use of decorators.

Decorators are not only a staple of modern Python codebases but also a practical bridge between traditional imperative programming and the functional programming paradigm.

The Essence of Decorators

At their core, decorators are higher-order functions: a fundamental concept in functional programming.

What is a Higher-Order Function?

According to Wikipedia, a higher-order function is a function that either(or both):

Takes one or more functions as arguments
Returns a function as its result.

Let me give a naive example for this

from typing import Callable

def dummy(func: Callable[..., Any]) -> Callable[..., Any]:
    return func

At first glance, this dummy function seems trivial.

it just returns the function it receives without any modification.

However, with a slight adjustment, we can transform it into something more useful:

from typing import ParamSpec, TypeVar

P, R = ParamSpec("P"), TypeVar("R")

def dummy(func: Callable[P, R]) -> Callable[P, R]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        result = func(*args, **kwargs)
        return result
    return wrapper

This is a decorator! In Python, decorators satisfy both criteria:
they take a function as input and often return a new function(in our example, wrapper) with modified behavior.

So, decorators in Python are not just a convenient syntax—they’re a direct, real-world application of higher-order function concepts.

Functions as First-Class Citizens

How can Python support decorators so seamlessly? The answer lies in a foundational language feature: functions are first-class citizens.

This means functions in Python can be:

Assigned to variables we can do inside wrapper

  new_func = func
  result = func(*args, **kwargs)

Passed as arguments This

  @dummy
  def add(a: int, b: int) -> int:
      return a + b

is equivalent to

  add = dummy(add)

when we decorate add with dummy, python would automatically passes add as an argument to dummy

Returned from other functions
Inside dummy, we return wrapper as a value, which is a function defined within dummy.
Stored in data structures like lists or dictionaries
we won't dig deep into this, but when dummy is defined, it is stored within module's global namespace, which is a dict under the hood.

In contrast, in some statically typed or older programming languages(say java before java 8), functions are not first-class.

This would break in pre-java8

public class Example {
    public static void callTwice(Function func) {
        func(); // Error: not a valid function call
        func();
    }

    public static void main(String[] args) {
        callTwice(sayHello); // sayHello isn't a value
    }

    public static void sayHello() {
        System.out.println("Hello");
    }
}

Therefore...

If you've used a decorator like @functools.lru_cache, @app.get, or @login_required, then you've already dipped your toes into functional programming. You’re working with functions that modify or enhance the behavior of other functions—precisely the kind of thing functional programming is all about.

Functional Programming with Decorators

Decorators don't just align with functional programming.

they can enable several important techniques:

1. Function Composition

In functional programming, composition is the idea of building complex behavior by combining simple functions. Decorators can be used to layer transformations or validations around a core function, much like composing small functions into a pipeline.

You can chain multiple decorators to achieve a composition-like behavior, each adding behavior before or after the main function is run.

   @decor1
   @decor2
   @decor3
   def decor(a: int, b: int) -> int: ...

This pattern is powerful, but it comes with some caveats:

Signature incompatibility:
If one decorator modifies the function’s signature (e.g., changes the number or type of arguments), it may break compatibility with other decorators in the chain.For decorators that need to inspect the function signature, if one decorator does not preserve it, the others may break.
Order sensitivity: The order in which decorators are applied matters. For example, using @abc.abstractmethod on a method that has already been wrapped by another decorator may lead to incorrect behavior or errors.
Readability: As the number of decorators grows, it becomes harder to understand what the function actually does at a glance.

#### Example from lihil

In lihil, an endpoint can receive multiple plugins (which are essentially decorators) using a cleaner and more structured syntax:

   @user.post(plugins=[plugin1, plugin2, plugin3])
   async def create_user(): ...

Under the hood, lihil applies these plugins in sequence by decorating the endpoint function:

   for plugin in plugins:
       func = plugin(func)

This approach maintains the core idea of composition while improving clarity and control over the decoration process.

2. Currying

Currying is the process of transforming a function that takes multiple arguments into a sequence of functions that each take a single argument. While Python doesn't support automatic currying like Haskell, you can manually simulate currying using decorators—returning nested functions that capture arguments through closure.

This is especially powerful when writing configuration-like decorators, where parameters are fixed upfront and later used to modify a function's behavior.

Consider the following example:

    def curry(func: Callable[..., R], *curry_args: Any, **curry_kwargs: Any):
        def wrapper(*args: Any, **kwargs: Any) -> R:
            return func(*(curry_args + args), **(curry_kwargs | kwargs))
        return wrapper

Here, curry is a higher-order function that returns a new function (wrapper) with some arguments pre-filled. These pre-filled values are remembered through closure, and the remaining arguments can be supplied later when the returned function is called.

To demonstrate how this works, imagine a simple subtraction function:

   def sub(a: int, b: int) -> int:
       return a - b

   sub_five = curry(sub, b=5)
   assert sub_five(a=8) == 3

We can use curry to fix one of the arguments, say b = 5, creating a new function that subtracts 5 from any input

By pre-binding the second argument b, we've effectively turned sub(a, b) into a function that only needs a. This mirrors the essence of currying in functional programming—progressively transforming a multi-argument function into a chain of single-argument calls.

3. Closures

A closure occurs when a function "remembers" variables from the scope in which it was created, even after that scope has finished executing. This is how decorators store context—whether it's a permission requirement, a configuration flag, or a runtime condition.

Closures are what make decorators stateful, enabling powerful behaviors like caching, logging, or retry logic without modifying the function’s internal logic. They allow decorators to wrap and extend functions while retaining information across calls.

let's take a look at a real-world example: Python’s built-in lru_cache decorator from the functools module.

Internally, it uses a closure to remember the function’s arguments and their corresponding results.

Here's a simplified version of its implementation (based on Python 3.12), with some details omitted to highlight the key point:

    def _lru_cache_wrapper(user_function, maxsize, typed, _CacheInfo):
        # Constants shared by all lru cache instances:
        sentinel = object()          # unique object used to signal cache misses
        make_key = _make_key         # build a key from the function arguments

        cache = {}
        hits = misses = 0

         # case when maxsize is None
         def wrapper(*args, **kwds):
             # Simple caching without ordering or size limit
             nonlocal hits, misses
             key = make_key(args, kwds, typed)
             result = cache_get(key, sentinel)
             if result is not sentinel:
                 hits += 1
                 return result
             misses += 1
             result = user_function(*args, **kwds)
             cache[key] = result
             return result

Here, the inner function wrapper forms a closure over several variables—cache, hits, misses, and make_key(a util function).

These variables live outside the wrapper function, but remain accessible to it even after _lru_cache_wrapper has finished executing. As a result, wrapper is able to remember past function calls and cache results accordingly.

This technique enables powerful optimizations like memoization, all while keeping the decorator’s logic entirely separate from the original function body.

Other Functional Programming Techniques in Python

Beyond decorators, Python supports many functional idioms that align with the same principles:

Comprehensions
list, dict, and set comprehensions are Python’s upgrades to map and filter, expressed in a concise and readable way. They're pure, declarative, and avoid side effects.
Generators
Generators support lazy evaluation, a key technique in functional programming. Using yield, Python functions can produce a sequence of results over time, supporting pipelines and memory-efficient data flows.
Built-in Functions
Python's standard library includes functional tools like map, filter, reduce, any, all, and functools.partial. These utilities operate on data immutably and often use higher-order functions—core values of the functional paradigm.

Turning a Utility into a Decorator

Let's write some functions that illustrate these concepts.

T = TypeVar("T")

def is_even(x: int) -> bool:
    return (x % 2) == 0

def larger_than(x: int, threshold: int) -> bool:
    return x > threshold

Now we define a utility function that checks whether a value satisfies a list of conditions. This uses a generator expression and all() for declarative, short-circuiting evaluation:

def meets_conditions(*conditions: Callable[[T], bool], target: T) -> bool:
    return all(condition(target) for condition in conditions) # generator comprehension

Finally, we wrap everything into a decorator. It accepts multiple conditions and applies them to the result of a function. We also use functools.partial to pre-fill parameters—a form of currying:

def check_result(*conditions: Callable[[T], bool]):
    def decorator(func: Callable[P, T]):
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
            result = func(*args, **kwargs)
            if not meets_conditions(*conditions, target=result):
                raise ValueError("Return value did not meet required conditions")
            return result

        return wrapper

    return decorator

@check_result(is_even, partial(larger_than, threshold=5))
def add(a: int, b: int) -> int:
    return a + b


assert add(3, 5) == 8
add(1, 1) # This would fail
add(4, 3) # This would fail too

This Post is originally from lihil

Lihil — a High-Performance Web Framework for Enterprise Web Development in Python

lihil — Wed, 21 May 2025 00:50:05 +0000

Lihil is a modern web framework built to make Python a serious choice for enterprise backend systems — from monoliths to microservices.

Why Lihil?

Python has long been criticized as “too slow” or “too dynamic” for large-scale applications. But the language and ecosystem have evolved — Python 3.10+ offers a robust type system, and with ongoing advancements like the removal of the Global Interpreter Lock (GIL), Python is ready for high-performance workloads.

Lihil aims to bring together:

High performance rivaling Go and Java frameworks
Scalable architecture that grows from simple apps to distributed systems
Modern developer ergonomics with static typing, auto-injection, and clean API design

GitHub: https://github.com/raceychan/lihil

Docs & tutorials: https://lihil.cc

What Lihil Offers

Performance

Lihil is 50–100% faster than comparable ASGI frameworks with similar functionality.
Benchmark source (reproducible):
https://github.com/raceychan/lhl_bench

Parameter Parsing

Lihil provides a powerful, type-driven parameter parser that handles inputs from all request sources.

Parses from query, path, header, and body

Type-aware conversion

Alias support for headers

Custom decoders via Param(decoder=...)

from typing import Annotated
from lihil.params import Param

@Route("/users/{user_id}")
async def create_user(
    user_id: str,
    name: Annotated[str, Param("query")],
    auth_token: Annotated[str, Param("header", alias="x-auth-token")],
    user_data: UserPayload
):
    ...

Data Validation & Decoding

Using msgspec under the hood, Lihil supports custom decoding and encoding with minimal boilerplate.

from lihil.di import CustomEncoder
from lihil.params import Param

async def create_user(
    user_id: Annotated[MyUserID, Param(decoder=decode_user_id)]
) -> Annotated[MyUserID, CustomEncoder(encode_user_id)]:
    return user_id

Dependency Injection

Lihil’s DI system resolves dependencies via type hints and supports:

Scoped, singleton, and transient lifecycles

Deeply nested dependencies

Lazy initialization

Factory-based injection

async def get_conn(engine: Engine):
    async with engine.connect() as conn:
        yield conn

async def get_users(conn: AsyncConnection):
    return await conn.execute(text("SELECT * FROM users"))

@Route("/users").get
async def list_users(
    users: Annotated[list[User], use(get_users)],
    is_active: bool = True
):
    return [u for u in users if u.is_active == is_active]

Plugin System

Lihil provides a flexible plugin system that allows you to decorate endpoint functions with custom logic — without interfering with parameter parsing or signature analysis.

This is particularly useful for features like logging, metrics, authentication, or request tracing.

You can easily integrate a third party library into lihil within a few lines

from functools import wraps
from lihil.plugins import EndpointSignature, Graph
from typing import Callable, Awaitable
from redis import RedisClient

def redis_plugin(redis: RedisClient, cache_key: str):
    def inner(self, graph: Graph, func: Callable[..., Awaitable[Any]], sig: EndpointSignature[Any]):
        @wraps(func)
        async def wrapped(*args, **kwargs):
            if result := redis.get(kwargs[cache_key]):
                return result
            return await func(*args, **kwargs)
        return wrapped
    return inner

Then apply it to your routes/endpoints

route = Route("/users/{user_id}")

@route.get(plugins=[redis_plugin(RedisClient(), cache_key="user_id")])
async def create_user(user_id: str): ...

Structured Problem Responses

Lihil adopts RFC 7807 to return detailed problem responses for exceptions.


class OutOfStockError(HTTPException[str]):
    __status__ = 422
    def __init__(self, order: Order):
        detail = f"{order} can't be placed, because {order.items} is short in quantity"
        super().__init__(detail)

Client receives:

{
  "type_": "out-of-stock-error",
  "status": 422,
  "title": "The order can't be placed because items are out of stock",
  "detail": "order(id=43, items=[massager]) can't be placed, because [massager] is short in quantity",
  "instance": "/users/ben/orders/43"
}

Event System

Lihil provides a unified event system that supports:

publish (in-process, blocking)

emit (in-process, non-blocking)

sink (integration point for MQ/databases)


from lihil import Route, status
from lihil.plugins.bus import Event, EventBus, bus_plugin
from typing import Annotated
from lihil.params import Param

class TodoCreated(Event):
    name: str
    content: str

async def on_create(created: TodoCreated, ctx):
    ...

bus_route = Route("/bus", listeners=[on_create])

@bus_route.post(plugins=[bus_plugin])
async def create_todo(
    name: str,
    content: str,
    bus: Annotated[EventBus, Param("plugin")]
) -> Annotated[None, status.OK]:
    await bus.publish(TodoCreated(name, content))

Handlers can have dependencies and can even publish new events during execution.

Standards-Driven, Scalable Design

Lihil supports distributed middleware like throttling and event sourcing, and offers guidance for best practices and clean architecture. You can:

Start with a monolith and scale to microservices.
Use strong typing for maintainability.
Follow extensible plugin patterns for observability, persistence, auth, etc.

Who It's For

Lihil is for developers who want:

Enterprise-ready structure and flexibility
Great DX (developer experience) with Python’s readability
True scalability and performance
Strict typing with fast feedback and strong IDE support
Detailed OpenAPI docs for both success and failure cases
First-class support for async patterns, events, streaming, and RPC

Versioning

Lihil is at v0.2.8, already >99% test-covered and strictly typed.

What's Next

Upcoming in v0.2.0+:

v0.2.9 supabase integration

v0.2.10 MCP server

v0.3.0 +

Schema-based async query builder
Out-of-process event bus (e.g., RabbitMQ, Kafka)
Command handlers (HTTP RPC + gRPC)

👉 GitHub: https://github.com/raceychan/lihil
📘 Docs: https://lihil.cc

You're Using HTTP Status Codes Wrong — Here's the solution

lihil — Mon, 05 May 2025 16:27:10 +0000

Question:

How would you choose a status code for an order that could not be processed because the customer's shipping address is outside the delivery zone?

Whether you are struggling to find an appropiate status code, or if you have a specific status code to use, this blog is for you.

What is http status code and why you should care

Status code is popular

Even if you are not a technical guy, it is very likley that you have heard these numbers 404, 502. This is because http status code is so popular that It is literally everywhere on the internet.

HTTP status codes have long been a cornerstone of web application error handling. Defined in RFC 7231, these codes serve as a standardized way for servers to communicate the outcome of a request to the client.
The standard defines several categories of status codes, such as 2xx for success, 4xx for client errors, and 5xx for server errors.
Quote from RFC 7231:

HTTP clients are not required to
understand the meaning of all registered status codes, though such
understanding is obviously desirable. However, a client MUST
understand the class of any status code, as indicated by the first
digit, and treat an unrecognized status code as being equivalent to
the x00 status code of that class

It has become an industrial consensus to check these status codes as a way to quickly determine whether a request was successful or failed. For example, many libraries and frameworks will raise an exception if a request results in an error status. Here's a simple example using Python's requests library:

import requests

response = requests.get("https://api.example.com/data")
response.raise_for_status() # this would raise exception when status code > 400
print("Data retrieved successfully!")

In this example, raise_for_status() automatically raises an HTTPError if the server returns a 4xx or 5xx status code. This is a common pattern in many applications to ensure that only successful requests are processed further.

Why is it difficult to choose a status code for your bussiness error

It's common(but not necessarily correct) to use 4xx codes like 400 Bad Request or 403 Forbidden when something goes wrong. For example, a "premium" user trying to access a feature available only to "pro" users might return a 403 Forbidden status. In such cases, the error is clear, and the status code maps well to the scenario.

But as web applications grow in complexity and deal with more nuanced business rules, things get trickier. Consider a scenario where an order could not be processed because of a mismatch between the customer's shipping address and the delivery zone. How should this issue be represented in terms of HTTP status codes?

There isn't an easy or clear answer. While we could use 400 Bad Request, it doesn't quite capture the specific business rule violation that's occurring. Similarly, a 409 Conflict could work in some cases, but it still doesn’t feel precise enough. As the number of potential issues grows—whether they’re related to payment failures, address mismatches, or resource conflicts—the more apparent it becomes that HTTP status codes are not built to handle the full complexity of modern business logic.

Don'ts

Currently, there are a few ways the industry deals with the problem of handling business logic errors in web applications. These solutions often involve workarounds or generalizations due to the limitations of HTTP status codes. Here are some of the common approaches:

Embedding Custom Status Inside Request Body

One approach is to always return a 200 OK status code, even when the request fails, and include a custom status code in the response body. This method involves returning a business-specific error code along with additional details.

Example:

   {
       "business_code": "CUSTOMIZED_BUSINESS_ERROR",
       "detail": "The shipping address is outside the serviceable delivery zone."
   }

I have personally encountered this solution from my work a several times during my career. when the system contains only a few components, and with detailed documentation, it could work, but as the system grows and additional components (like proxies, API gateways, and logging systems) are added, this keeps creating new problems you wouldn't have to solve otherwise.

self-define 3-digits status code, for example, 6xx means some business rules, 700 means others, etc.

Some solutions attempt to define their own set of status codes beyond the standard 2xx, 4xx, and 5xx categories. For example, 6xx might represent business rules, with specific codes for each scenario (e.g., 700 for some other business logic). While this avoids reading the request body to determine failure, it violates the HTTP standards, meaning many tools might throw errors or not support these codes.
Example:

600: CONNECTION ERROR - This indicates a general connection error
601: INCOMPLETE ERROR - This indicates sever sends an incomplete page/object (as indicated by Content-Length header)
701: ERROR TEXT FOUND - This code is returned if any error text (such as, "Service Unavailable") are found in the main page (frame HTML contents included). Note that the error text must be defined in advance of the test. Error text means if the text is found, this session should be considered a failure.

According to RFC 7231,

New status codes are required to fall under one of the categories
defined in Section 6.

status codes >= 600 are invalid because they fall outside of the defined categories.

Dos

A 4xx status code + Generic Error Message

{
  "status": 400,
  "message": "Something went wrong"
}

A common fallback is to return a 4xx status code (typically 400 Bad Request) and include a generic error message such as "Something went wrong" in the response body. This approach hides the real cause of the business logic failure and lumps all client errors into one vague category. While this might suffice for small-scale applications or early prototypes, it quickly becomes inadequate as the complexity of business rules increases.

Some systems go a step further by returning a one-line reason phrase or a slightly extended message, but still fall short of conveying structured, actionable error details to clients.

Using the Same Status Code for Multiple Business Logic Issues

{
  "status": 400,
  "message": "Payment failed"
}

{
  "status": 400,
  "message": "Invalid shipping address"
}

As business logic errors grow in number and variety, some teams attempt to fit them into a limited set of existing status codes. For instance, both a payment failure due to insufficient funds and a mismatch in shipping address might be returned as 400 Bad Request. While this approach simplifies server-side handling, it severely limits the clarity of error messages, making it hard for clients to distinguish between different types of business failures. This also places unnecessary burden on client-side developers to reverse-engineer the true nature of the error from vague responses.

Best Practice

Structured Error Message + Documentation (With Standards Compliance)

A thoughtful approach to business rule violations is to return an appropriate 4xx status code—ideally one that aligns semantically with the error (for example, 407 Proxy Authentication Required, if applicable)—to indicate that the request was unsuccessful due to a business constraint.

In addition, the response body can include a structured error message based on RFC 9457 (Problem Details for HTTP APIs), which defines fields such as type, title, status, detail, and instance. This format encourages clarity and consistency, making it easier for both developers and automated systems to understand, handle, and trace errors.

Equally important is having each error type clearly documented so that client developers know what an error means and how to address it. Well-maintained documentation enables richer client experiences, reduces guesswork, and helps prevent issues before they arise.

Stripe does an excellent job in this area with their dedicated error code documentation, which provides detailed explanations for a wide range of business-related errors. Their commitment to transparency and developer experience is evident and commendable.

That said, there are a couple of areas where further improvements could enhance the experience even more:

Their structured error format, while clear, doesn’t explicitly follow RFC 9457, and omits fields like instance that can be valuable for debugging.
It’s not clear whether their documentation is automatically generated or manually maintained. If it’s the latter, this could introduce challenges in keeping it fully up to date with evolving APIs.

How lihil solves this problem

Structured Error Messages + Auto-Generated Documentation

lihil tackles the problem by making structured error handling first-class. You can declare rich, type-safe exceptions by subclassing HTTPException[T], where T defines the structure of the error's detail field. These exceptions can then be directly attached to endpoints using the errors= parameter. This not only ensures consistent error responses but also enables lihil to automatically generate OpenAPI documentation for each declared error—including a link to a detailed problem page under the "External documentation" tab.

How you define a structual exception in lihil

from lihil import Empty, Lihil, Resp, Route, status, Meta
from lihil.interface import Base
from lihil.problems import HTTPException

class AddressOutOfScopeProblem(Base):
    current_address: Annotated[str, Meta(examples=["home"])]
    service_radius: Annotated[float, Meta(examples=[3.5])]
    distance: Annotated[float, Meta(examples=4)]

    message: str = ""

    def __post_init__(self):
        self.message = f"Your current address {self.current_address} is {self.distance} miles away and our service radius is {self.service_radius}"

class InvalidOrderError(HTTPException[AddressOutOfScopeProblem]):
    "Address out of service zone"
    __status__ = 422

    instance: Annotated[str, Meta(examples=["2cd20e0c-9ddc-4fdc-8f61-b32f62ac784d"])]
    detail: AddressOutOfScopeProblem


orders = Route("orders")

@orders.post(errors=[InvalidOrderError])
async def create_orders() -> Resp[Empty, status.CREATED]: ...

lhl = Lihil(routes=[orders])

if __name__ == "__main__":
    lhl.run(__file__)

Running the above code and it is automatically documented in your OpenAPI.

What makes it good.

As you might see from the OpenAPI, each of these error response follows the RFC 9457 format, including fields like type, title, status, detail, and instance. You can customize how errors are rendered by registering handlers with @problem_solver, which maps specific exceptions or status codes to structured responses. Specific exception handlers take precedence over status-code-based ones, giving you fine-grained control.

By default, lihil also generates detailed responses for common issues such as missing parameters, returning structured 422 responses for InvalidRequestErrors—complete with field-level information. These responses are not only machine-readable but also fully documented out of the box.

Best of all, all this documentation is automatically synced with your code. There's no need to manually update or maintain a separate error code reference. lihil keeps your API behavior and documentation in perfect alignment.