DEV Community: Prajwal M

Help Needed: Type Hint for wrapper class in python

Prajwal M — Sat, 07 Jun 2025 16:39:53 +0000

Help! Why don't I get any type hints here?#pythonlearning pic.twitter.com/rLsgvCk0qb
— Prajwal M (@glitch_guy0) June 7, 2025

🧠 From Chaos to Clarity: How I Designed a Structured Logging System for My Application

Prajwal M — Sun, 01 Jun 2025 15:12:11 +0000

Logging is deceptively tricky. When I started building my app, I assumed logging would be simple — just add logger.info() or logger.error() where needed. But as the app grew, so did the problems:

Inconsistent logs from different layers
Inability to trace what failed and why
Unstructured logs that Fluent Bit couldn’t reliably parse
Missing context (like response time, request ID) in error logs

I had questions. A lot of them. Here's how I answered them — and built a logging system that’s clean, structured, and future-ready.

🤯 1. My First Realization: Logging Is Closely Tied to Exceptions

Doubt: “Logging needs all details at the end (status code, time taken, etc.), but most of those are only known at the response stage. Should I log in request and response both?”

Answer:

✅ Logging once — at the response/finalization stage — makes more sense. You get the complete picture: time taken, status code, route, etc.

❌ Logging both request and response separately introduces duplication and inconsistency.

🔍 2. Then I Asked: How Do I Get Debug Details from Inside the Library?

Doubt: “If I log inside the library, I miss outer context like time taken. But if I don't log there, I lose debug info.”

Insight:

I realized exceptions are the bridge — I can raise exceptions from deep inside the code, carrying debug metadata with them. Then, at the top-level (e.g., middleware), I catch and log the whole thing.

🏗️ 3. My First Design Attempt: Logging + Exception Carrying Details

class AppException(Exception):
    def __init__(self, message, level="error", details=None):
        super().__init__(message)
        self.level = level
        self.details = details or {}

💡 Now I could raise exceptions with structured metadata. I made sure every exception had a level and details dict — which the logger could later use.

📤 4. I Wanted JSON Logs for Fluent Bit

Doubt: “How do I send structured logs to Fluent Bit, and will all logs have the same JSON format?”

Answer:

I used Python's logging.config.dictConfig() with a JSON formatter (e.g., json-log-formatter or structlog). Now every log has fields like level, message, request_id, time_taken, etc.

🧪 5. Then I Faced: Should Exceptions Decide Log Level?

Doubt: “Wait, does the exception decide if this is info, debug, or error? Or does the logger?”

Answer:

✅ I let exceptions carry the log level as an enum (DEBUG, INFO, ERROR, etc.).

Then my logger dynamically calls logger.debug(), logger.info(), etc. based on that.

🧵 6. Then the Real Design Emerged: Middleware-Level Logging

I moved all logging to the final response handler:

If there’s no exception, log INFO with full context (status, duration, etc.)
If there's a custom exception, log using its level and details
If it's unhandled, log as ERROR with traceback

Example final logger:

def log_exception(exc, request_context):
    if isinstance(exc, AppException):
        getattr(logger, exc.level)(exc.args[0], extra={**exc.details, **request_context})
    else:
        logger.error("Unhandled exception", exc_info=exc, extra=request_context)

🛑 7. I Also Asked: What About `DEBUG` Logs?

Doubt: “Do debug logs bubble up to middleware too?”

Answer:

✅ If debug details are important, I attach them as details in exceptions.

🚫 I don’t emit low-level debug logs directly — instead, I raise them with exceptions if they matter for observability.

🧠 8. I Realized: Logs and Exceptions Are Loosely Coupled, But Work Together

Insight:

Exceptions carry structured data, but they don't log themselves. The logger does that, at a single point, using info from the exception.

I even thought about creating a single field like log_level and one details dict — now the logger only looks at two fields, making it future-proof and decoupled.

💥 9. Final Problem: FastAPI’s `HTTPException` Doesn’t Work for This

Doubt: “I'm using FastAPI. Should I subclass HTTPException or replace it?”

Answer:

✅ I wrapped HTTPException into a custom LoggedException, adding level and details

✅ Middleware logs and re-raises it as usual

🚫 I never log inside business logic — I only raise with metadata

📦 Final Architecture

lib code
│
├── raises AppException("user not found", level="info", details={...})
│
controller
│
└── catches exception
    └── logs once with log level and details (JSON)
    └── returns response

🛠 Tools I Considered or Used

Tool	Use
`logging` + `dictConfig`	Core logger setup
`json-log-formatter`	JSON formatter for structured logs
`structlog`	More advanced context-based structured logging
`contextvars`	Track request-specific info like trace_id
`Fluent Bit`	Ship logs to log storage
`Elasticsearch`, `Loki`, `Sentry`	Log & error analysis

🧵 Key Takeaways

Raise structured exceptions with log metadata
Log once, centrally, with all context (request ID, time taken, etc.)
Use JSON format for compatibility with log collectors
Let exceptions carry log level, but log only at the final point
Avoid scattered logs — treat logs as events, not prints

📝 Written on 2025-06-01

The Stateless Struggle: Authlib, Starlette, and My Quest for a Stateless FastAPI Authentication

Prajwal M — Wed, 28 May 2025 15:33:24 +0000

As I embark on building a robust and scalable API with FastAPI, authentication using OpenID Connect (OIDC) is a crucial piece of the puzzle. My initial foray into this involved exploring the well-regarded authlib library. Given its solid reputation and support for various authentication flows, it seemed like a natural starting point. However, my experience, particularly when considering its integration with Starlette (often a precursor or related ecosystem to FastAPI), has led me down a frustrating path, highlighting a seemingly inherent stateful design that clashes with my need for a purely stateless architecture.

My exploration with authlib for OIDC within the Starlette context quickly revealed a fundamental dependency: session management. The library, by default, heavily relies on storing authentication state within server-side sessions. This became evident as I delved into its registration process and observed its internal use of .session to persist state. While authlib admirably handles the intricacies of the OIDC specification under the hood, this forced stateful approach presents a significant hurdle for those of us aiming for stateless APIs.

The documentation, while present, often lacks the clarity needed to deviate from this default stateful behavior. It feels like the library nudges you towards session-based authentication, making the path to a stateless implementation feel like an uphill battle requiring deep dives into internal workings. This lack of explicit guidance on achieving statelessness, coupled with the inherent complexity of managing sessions in a distributed environment, becomes a significant concern.

My notes reflect this growing frustration. The need to manage authentication state externally if one wishes to avoid session middleware is explicitly mentioned. This begs the question: Why does authlib's Starlette integration so strongly favor a stateful model? For applications demanding scalability and adherence to stateless API design principles, this feels like an unnecessary constraint.

The desire for statelessness in modern APIs is often driven by factors like:

Scalability: Stateless services are inherently easier to scale horizontally as they don't rely on shared session storage.
Decoupling: Statelessness promotes better decoupling between the client and server.
Simplified Architecture: Removing the complexities of session management can lead to a cleaner and more maintainable architecture.

While authlib undoubtedly provides a powerful abstraction over authentication protocols, its seemingly rigid stance on session management within the Starlette ecosystem creates a significant impedance mismatch for developers targeting stateless FastAPI applications. The effort required to circumvent this default behavior and implement a truly stateless solution using authlib feels excessive, potentially outweighing the benefits of the library itself.

This journey has led me to question whether authlib in this context is the most suitable tool for my specific needs. The lack of straightforward guidance on stateless implementation, the forced reliance on sessions, and the need to potentially wrestle with internal logic to achieve a stateless design all point towards a potential mismatch.

My point is clear: authlib's strong coupling with session management in its Starlette integration presents a significant challenge for developers aiming for stateless APIs, particularly those building with FastAPI. While the library excels in handling authentication protocols, its default stateful nature necessitates considerable effort to achieve a stateless architecture, potentially making it less ideal for this common API design pattern.

The quest for a truly stateless authentication solution for my FastAPI application continues. Perhaps there are alternative libraries or strategies that offer a more aligned approach. The experience with authlib has been a valuable learning curve, highlighting the importance of choosing tools that align with the fundamental architectural principles of the application being built.

And a crucial question to the community: If I'm misunderstanding something, or if there's a well-documented and straightforward way to achieve stateless OIDC authentication with authlib for Starlette/FastAPI that avoids session middleware, please enlighten me! I'm eager to learn and correct my understanding. Any guidance, examples, or pointers to relevant documentation would be incredibly appreciated.

DEV Community: Prajwal M

Help Needed: Type Hint for wrapper class in python

🧠 From Chaos to Clarity: How I Designed a Structured Logging System for My Application

🤯 1. My First Realization: Logging Is Closely Tied to Exceptions

🔍 2. Then I Asked: How Do I Get Debug Details from Inside the Library?

🏗️ 3. My First Design Attempt: Logging + Exception Carrying Details

📤 4. I Wanted JSON Logs for Fluent Bit

🧪 5. Then I Faced: Should Exceptions Decide Log Level?

🧵 6. Then the Real Design Emerged: Middleware-Level Logging

🛑 7. I Also Asked: What About DEBUG Logs?

🧠 8. I Realized: Logs and Exceptions Are Loosely Coupled, But Work Together

💥 9. Final Problem: FastAPI’s HTTPException Doesn’t Work for This

📦 Final Architecture

🛠 Tools I Considered or Used

🧵 Key Takeaways

The Stateless Struggle: Authlib, Starlette, and My Quest for a Stateless FastAPI Authentication

🛑 7. I Also Asked: What About `DEBUG` Logs?

💥 9. Final Problem: FastAPI’s `HTTPException` Doesn’t Work for This