Pydantic

The arrival of Python 3.14 marks a symbolic milestone for the language. While the version number invites endless mathematical jokes, the technical upgrades offer substantial quality-of-life improvements for developers across the spectrum. From cleaner syntax to specialized compression, this release focuses on refining the developer experience and expanding the capabilities of the standard library. Streamlined Exception Handling Handling multiple exceptions has always required a specific, somewhat clunky syntax involving parentheses. Python 3.14 eliminates this requirement. You can now catch multiple errors in a single `except` block using a comma-separated list without enclosing them in a tuple. It removes a minor friction point that has persisted for years, allowing for cleaner, more readable error-handling blocks. While seemingly small, it reduces the cognitive load during rapid coding sessions and trims down boilerplate code. Built-in Zstandard Compression The inclusion of Zstandard (zstd) directly into the standard library is a major win for performance-oriented applications. This compression algorithm offers a superior balance between speed and compression ratio compared to legacy tools like GZIP or Bzip2. In practical benchmarks, Zstandard provides significantly smaller file sizes with faster compression times. This makes it the ideal choice for developers managing large log files or high-performance caching systems where disk space and throughput are equally critical. Template Strings and Interpolation Template strings arrive as a sophisticated generalization of f-strings. While f-strings are excellent for direct interpolation, they offer little control over the process. Template strings return a deferred object, allowing developers to define custom behavior for how values are handled. This is transformative for security-sensitive tasks like HTML rendering. By implementing a custom sanitizer, you can automatically escape malicious scripts or sensitive data, moving the responsibility of security from the manual string format to a structured, reusable logic layer. The End of Future Imports for Annotations For years, self-referencing classes required a workaround: the `from __future__ import annotations` statement. Python 3.14 finally makes deferred annotations the default behavior. This change simplifies codebases and removes the need for extra imports just to satisfy the type checker. Coupled with the new `annotationlib` module, which allows for deep inspection of types without immediate evaluation, this update provides a more robust foundation for libraries like FastAPI and Pydantic that rely heavily on code introspection. Python 3.14 isn't just a gimmick based on a number; it is a practical step forward in making the language more efficient and easier to maintain. Whether you are excited about the faster compression or the cleaner syntax, these features ensure that Python remains a top-tier choice for modern development.

Overview Building a production-ready application requires more than just writing code that runs. You must create a structure that scales with the size of the codebase, the complexity of the team, and the diversity of deployment environments. This guide demonstrates a modular architecture for FastAPI projects, focusing on separating cross-cutting concerns from business logic to ensure long-term maintainability. By utilizing modern tooling like uv and Docker, we create a reproducible environment where adding features doesn't necessitate massive refactoring. Prerequisites To follow this tutorial, you should have a solid grasp of **Python 3.10+** and basic asynchronous programming. Familiarity with RESTful API concepts and basic SQLAlchemy or ORM patterns is recommended. You should also have Docker installed for local orchestration. Key Libraries & Tools * **FastAPI:** A modern, high-performance web framework for building APIs. * **Pydantic Settings:** Manages configuration via environment variables with type validation. * **uv:** An extremely fast Python package installer and resolver. * **SQLAlchemy:** The SQL toolkit and Object Relational Mapper for database interactions. * **pytest:** A framework that makes it easy to write simple and scalable test suites. Code Walkthrough 1. Centralized Configuration Using Pydantic Settings allows you to define a schema for your environment variables. This prevents the application from starting if a critical variable is missing. ```python from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): app_name: str = "My Scalable App" database_url: str model_config = SettingsConfigDict(env_file=".env") settings = Settings() ``` 2. The Service Layer (Business Logic) Keep your routes thin. The `UserService` acts as a "business seam," handling database interactions and domain rules. This separation allows you to test logic without triggering HTTP overhead. ```python class UserService: def __init__(self, db_session): self.db = db_session def create_user(self, name: str): # Business logic goes here new_user = User(name=name) self.db.add(new_user) self.db.commit() return new_user ``` 3. Dependency Injection in Routes FastAPI provides a built-in `Depends` mechanism. We use this to inject the database session and the service layer into our endpoints. ```python @router.post("/users/") def create_user(user_data: UserCreate, service: UserService = Depends(get_user_service)): return service.create_user(name=user_data.name) ``` Syntax Notes This project structure leverages **Dependency Inversion**. Instead of a route creating a database connection, it asks for one. Notice the use of **Type Hinting** throughout the service and config layers; this isn't just for readability—it enables Pydantic to perform runtime data validation and FastAPI to generate automatic documentation. Practical Examples Imagine you need to switch from a local PostgreSQL database to an external API for user management. In this architecture, you only modify the `UserService` and the `core/config.py`. The `api/v1/user.py` file remains untouched because it only cares about the service interface, not the persistence implementation. Tips & Gotchas * **Environment Safety:** Never commit your `.env` file. Add it to `.gitignore` to protect sensitive credentials. * **Test Isolation:** Use an in-memory SQLite database for testing. FastAPI allows you to override dependencies in your pytest fixtures, ensuring your tests don't pollute your production data. * **Tooling Efficiency:** Use `uv sync` in your Docker builds. It handles dependency locking more reliably than standard `pip` and significantly speeds up container deployment.

Overview Modern AI development often begins with simple prompts but quickly devolves into unmanageable "spaghetti code" as developers add tools, data pipelines, and multiple model calls. This tutorial demonstrates how to apply classic software design patterns—Chain of Responsibility, Observer, and Strategy—to Python AI agents. By decoupling logic from prompts, you create modular systems that are easier to test, debug, and scale. These patterns transform one-off hacks into professional, maintainable software architectures. Prerequisites To follow this guide, you should have a solid grasp of Python basics, specifically functions and lists. Familiarity with Pydantic for data validation is helpful, along with a baseline understanding of how Large Language Models (LLMs) interact with system prompts and context. Key Libraries & Tools * **Pydantic AI**: A framework for building production-grade agents with built-in validation. * **OpenAI API**: The underlying model provider for generating agent responses. * **Python `typing` module**: Used for defining protocols and callable types to ensure structural typing. Code Walkthrough The Chain of Responsibility This pattern allows a series of specialized agents to process a request sequentially. Each step handles a specific concern—like finding a hotel or booking a flight—and passes the updated context to the next handler. ```python def plan_trip(user_input, deps): context = TripContext() # The Chain: A list of callables executed in sequence chain = [handle_destination, handle_flight, handle_hotel, handle_activities] for handler in chain: handler(user_input, deps, context) return context ``` The Observer Pattern Monitoring agent behavior is critical for debugging. The Observer pattern allows you to attach logging or monitoring tools without polluting your core business logic. ```python class AgentObserver(Protocol): def notify(self, agent_name: str, prompt: str, duration: float): ... def run_with_observers(agent, prompt, observers): start = time.time() output = agent.run(prompt) duration = time.time() - start for obs in observers: obs.notify(agent.name, prompt, duration) return output ``` The Strategy Pattern Use the Strategy pattern to swap agent behaviors or "personalities" dynamically. Instead of hardcoding prompts, you pass a strategy function that returns a preconfigured agent. ```python def run_travel_strategy(strategy_func, prompt): # The strategy_func acts as a pluggable behavior factory agent = strategy_func() return agent.run(prompt) Usage run_travel_strategy(get_budget_agent, "I need a trip to Paris") ``` Syntax Notes We utilize **Protocols** from Python's `typing` module to implement structural subtyping. This allows us to define what an "Observer" looks like without forcing rigid inheritance hierarchies. Additionally, using **Callables** as strategies keeps the implementation functional and lightweight compared to traditional class-heavy patterns. Practical Examples These patterns excel in multi-step workflows such as automated customer support triaging (Chain), real-time performance dashboards (Observer), or persona-driven marketing copy generation (Strategy). Tips & Gotchas Always ensure your context object is passed by reference through the chain to maintain state. A common mistake is failing to handle errors midway through a chain; if the destination agent fails, the flight agent should likely never run. Implement early exits or error-handling strategies within your loop to prevent cascading failures.

Overview Python comes with a batteries-included philosophy, yet many developers immediately install third-party packages for tasks that the Python Standard Library handles natively. Utilizing these built-in tools reduces project bloat, minimizes security risks from external dependencies, and improves performance. This guide showcases how to write cleaner code using powerful, overlooked native modules. Prerequisites To get the most out of this tutorial, you should have a solid grasp of basic Python concepts like decorators, generators, and dictionary manipulation. A environment running Python 3.11 or later is highly recommended, as some modules like `tomllib` are not available in older versions. Key Modules & Tools * `functools`: Utilities for higher-order functions, including caching and partial application. * `heapq`: An implementation of the heap queue algorithm, ideal for priority queues. * `graphlib`: Tools for working with graph-like structures, specifically topological sorting. * `tomllib`: Native parsing for TOML configuration files, introduced in Python 3.11. Code Walkthrough Let's build a quick memoized power function and a dynamic priority queue to see how these standard modules work in practice. Memoization with Functools The `cache` decorator in `functools` optimizes CPU-heavy operations by storing previous inputs and results: ```python from functools import cache, partial @cache def compute_power(base: int, exponent: int) -> int: # Computes power and caches the result automatically return base ** exponent Create a specialized function using partial application square = partial(compute_power, exponent=2) print(square(10)) # Outputs 100 ``` Prioritizing Tasks with Heapq The `heapq` module dynamically orders tasks so that the lowest priority number is always processed first: ```python import heapq tasks = [(2, "Write documentation"), (1, "Fix critical bug")] heapq.heapify(tasks) Dynamic addition heapq.heappush(tasks, (0, "Deploy emergency hotfix")) while tasks: priority, task = heapq.heappop(tasks) print(f"Processing {task} (Priority: {priority})") ``` Syntax Notes Python uses the division slash operator (`/`) in `pathlib` to join file paths gracefully, overriding standard division. When working with `dataclasses`, setting `frozen=True` provides read-only attributes, ensuring object immutability. Practical Examples Native modules shine in system automation. You can use `graphlib.TopologicalSorter` to schedule build pipelines by resolving tasks in sequence, or use `secrets` to generate secure, unguessable password reset tokens. Tips & Gotchas Do not use the standard `random` module for security keys or passwords; it is predictable. Always use `secrets` instead. When caching with `functools.cache`, be aware that it grows infinitely; use `lru_cache(maxsize=...)` for long-running processes to prevent memory leaks.

Overview: Beyond the Chatbot Building AI applications often involves wrestling with unpredictable text outputs. While Large Language Models (LLMs) like GPT-4 are brilliant at reasoning, they lack the structural discipline required for production software. Pydantic AI solves this by extending the popular Pydantic validation library to the world of agents. It allows developers to inject business logic, connect to real-world dependencies like databases, and enforce type-safe outputs that your application can actually trust. This guide demonstrates how to build a healthcare triage assistant that uses these features to assess patient urgency based on live data. Prerequisites To follow this tutorial, you should have a solid grasp of **Python 3.10+**, specifically **asynchronous programming** with `asyncio`. You should also be familiar with **Type Hinting** and the basic concepts of **Pydantic** data validation. Finally, you will need an **OpenAI API Key** to power the agent's reasoning. Key Libraries & Tools * **Pydantic AI**: A framework for building robust AI agents with structured validation. * **Pydantic**: Used for defining data models and validating agent outputs. * **OpenAI GPT-4**: The foundational model used for reasoning and natural language processing. * **Asyncio**: Python's standard library for writing concurrent code using the async/await syntax. Code Walkthrough: The Triage Agent 1. Defining Dependencies and Models First, we establish the scaffolding. We define what the agent needs to know (dependencies) and what it must return (output model). ```python from pydantic import BaseModel, Field from dataclasses import dataclass @dataclass class TriageDependencies: patient_id: int db_conn: "DatabaseConnection" class TriageOutput(BaseModel): response_text: str = Field(description="Message to the patient") escalate: bool = Field(description="Whether to escalate to a human") urgency: int = Field(ge=1, le=10, description="Urgency level") ``` 2. Initializing the Agent We initialize the `Agent` class by specifying the model, dependencies, and the expected output type. ```python from pydantic_ai import Agent triage_agent = Agent( 'openai:gpt-4o', deps_type=TriageDependencies, result_type=TriageOutput, system_prompt="You are a triage assistant assessing patient urgency." ) ``` 3. Injecting Context and Tools Dynamic prompts and tools allow the agent to fetch real-time data. The `@triage_agent.system_prompt` decorator lets you pull patient-specific info, while `@triage_agent.tool` gives the LLM the ability to "call" functions like fetching vitals. ```python @triage_agent.system_prompt async def add_patient_name(ctx: RunContext[TriageDependencies]) -> str: name = await ctx.deps.db_conn.get_patient_name(ctx.deps.patient_id) return f"The patient's name is {name}." @triage_agent.tool async def get_vitals(ctx: RunContext[TriageDependencies]) -> str: return await ctx.deps.db_conn.get_latest_vitals(ctx.deps.patient_id) ``` Syntax Notes: RunContext The `RunContext` is a pivotal generic type in Pydantic AI. It carries your custom dependencies through the agent's lifecycle, ensuring that your tools and dynamic prompts always have access to your database or API clients without relying on global variables. Practical Examples This pattern is ideal for **Financial Risk Assessment**, where an agent must pull a credit score and return a structured 'approve/deny' decision, or **Automated Customer Support**, where the agent queries a shipment database to provide precise tracking updates rather than generic hallucinations. Tips & Gotchas * **Parenthesis Pitfalls**: Code completion tools often struggle with the nested structure of agent definitions; double-check your closing brackets. * **Graph Complexity**: While Pydantic AI supports complex graph-based workflows, start with a single agent. Only move to nodes and edges if your logic is too complex for tools and dynamic prompts.

Functional programming and terminal aesthetics Python's flexibility often hides the fact that its standard library, while robust, has gaps that third-party developers have filled with surgical precision. For developers looking to inject functional programming patterns into their workflow, PyToolz (or Toolz) offers a compelling toolkit. It enables high-performance data manipulation pipelines through functions like `compose` and `partial`. While `functools` provides some of this, PyToolz allows for a cleaner synthesis of operations, such as stripping strings and converting them to uppercase in a single, readable line. However, users should note the current lack of static type annotations, a known limitation for those relying heavily on IDE type-checking. Visualizing data within the console is another area where external libraries shine. Tabulate is the go-to for converting lists of lists into clean, formatted tables for the console, Markdown, or even LaTeX. It is remarkably lightweight, making it ideal for CLI debugging. If you need more visual flair, Rich acts as a high-powered replacement for the standard print function. It handles syntax highlighting, progress bars, and complex tracebacks, turning a drab terminal into a rich data dashboard. Bulletproofing code through properties and settings Testing often feels like a manual chore of defining edge cases like zero, empty strings, or negative integers. Hypothesis shifts this burden by introducing property-based testing. Instead of writing individual test cases, you describe the shape of the data, and the library generates hundreds of edge cases you might never have considered. It is a rigorous way to discover hidden bugs in sorting algorithms or data processing logic. Application configuration is similarly streamlined through Pydantic-settings. Managing environment variables often leads to messy boilerplate code. This extension of the popular Pydantic library allows you to define a configuration model that automatically loads and validates settings from `.env` files. This ensures that your application fails fast if a critical database URL or API key is missing, providing type-safe access to your settings throughout the codebase. Moving beyond requests for modern networking For years, `requests` has been the industry standard for HTTP calls, but it lacks native support for asynchronous programming. HTTPX has emerged as a superior alternative, offering a nearly drop-in compatible API while adding async support and connection pooling. This is essential for modern applications that need to make concurrent requests without blocking the main execution thread. When building APIs with FastAPI, developers often struggle with the boilerplate required for pagination. FastAPI-pagination solves this by providing a structured way to handle page objects and query parameters. It allows for seamless navigation through large datasets by automatically handling skip and limit logic. For event-driven architectures, FastStream simplifies interactions with brokers like Kafka or RabbitMQ, using decorators to manage data streams and Pydantic for message validation. The rise of Python-centric user interfaces One of the most exciting shifts in the ecosystem is the ability to build full-stack user interfaces without writing JavaScript. NiceGUI provides a straightforward way to create web-based interfaces with buttons, charts, and tables using pure Python. For those seeking a more native feel on desktop and mobile, Flet leverages Flutter in the background to deliver high-performance apps. Meanwhile, Reflex caters to those who prefer a React-style declarative component tree, and Textual brings sophisticated interactive UIs directly to the terminal. In the AI sector, LangGraph and PydanticAI are redefining how we build agentic workflows. LangGraph focuses on cyclical, graph-based agent logic, while PydanticAI prioritizes type-safe, validated responses from LLMs. Finally, Marimo offers a reactive alternative to Jupyter notebooks. Unlike standard notebooks, Marimo files are stored as pure Python scripts, making them version-control friendly and eliminating the hidden state issues that often plague interactive data science workflows.

Overview of Python SDK Architecture Constructing a Software Development Kit (SDK) involves more than wrapping HTTP calls in functions. A well-designed SDK provides a Pythonic interface that hides the complexity of headers, JSON parsing, and status code handling from the end user. This guide explores a sophisticated architectural pattern that utilizes Pydantic for data validation, HTTPX for networking, and a strategic use of inheritance and generics to eliminate code duplication across multiple API resources. Prerequisites and Toolkit Before building, ensure you have a firm grasp of Python type hinting and object-oriented programming. You should be familiar with asynchronous concepts, though this tutorial focuses on synchronous implementations for clarity. The following tools are essential: - **Pydantic**: For data modeling and automatic validation of API responses. - **HTTPX**: A modern, feature-rich HTTP client for Python that serves as our network engine. - **TypeVar and Generic**: Standard library components from the `typing` module used to create reusable code that adapts to different resource types. Building the Low-Level HTTP Client The foundation of the SDK is a specialized client that manages authentication and base URL configurations. Instead of repeating authorization headers in every request, we centralize this logic. This client acts as a gateway, providing methods for standard HTTP verbs like `GET`, `POST`, `PUT`, and `DELETE` while ensuring all requests include the necessary bearer tokens. ```python import httpx class APIHTTPClient: def __init__(self, token: str, base_url: str): self.client = httpx.Client( base_url=base_url, headers={"Authorization": f"Bearer {token}"} ) def request(self, method: str, endpoint: str, **kwargs): return self.client.request(method, endpoint, **kwargs) def get(self, endpoint: str): return self.request("GET", endpoint) ``` Implementing the Base API Model with Generics To avoid the "God Class" anti-pattern where a single client object contains hundreds of methods for every possible resource, we move resource-specific logic into the models themselves. By creating a `BaseAPIModel` that inherits from Pydantic's `BaseModel`, we can define standard CRUD operations once and apply them to any resource, such as Users, Invoices, or Products. ```python from typing import TypeVar, Generic, Type, List from pydantic import BaseModel T = TypeVar("T", bound="BaseAPIModel") class BaseAPIModel(BaseModel, Generic[T]): id: int | None = None resource_path: str = "" @classmethod def find(cls: Type[T], client: APIHTTPClient) -> List[T]: response = client.get(cls.resource_path) return [cls(**item) for item in response.json()] def save(self, client: APIHTTPClient): if self.id: client.request("PUT", f"{self.resource_path}/{self.id}", json=self.model_dump()) else: response = client.request("POST", self.resource_path, json=self.model_dump()) self.id = response.json().get("id") ``` Creating Specific Resource Models With the base logic established, creating a new resource becomes trivial. You simply define the fields and the endpoint path. The model automatically gains full CRUD capabilities without any additional boilerplate code. This approach ensures that your SDK remains consistent across different data types, as every resource follows the same method signatures for loading and saving. ```python class User(BaseAPIModel["User"]): resource_path = "users" name: str email: str Usage Example client = APIHTTPClient(token="secret_key", base_url="https://api.example.com") users = User.find(client) new_user = User(name="Alice", email="[email protected]") new_user.save(client) ``` Syntax Notes and Conventions This design relies heavily on **Self-Referential Generics**. By passing the class itself into the `Generic` type, Python's type checkers (like Mypy) can correctly infer that `User.find()` returns a `List[User]` rather than a list of the base class. We also utilize **Dependency Injection** by passing the client instance to the model methods, which facilitates easier unit testing and mocking. Tips and Common Gotchas One frequent mistake is forgetting to set the `resource_path` on the subclass, which results in 404 errors during API calls. Additionally, be mindful of **Tight Coupling**. While inheritance reduces code, it binds your models closely to your HTTP client. If you plan to support both REST and GraphQL, you may need to abstract the communication layer further to maintain flexibility. For large-scale SDKs, consider implementing pagination within the `find` method to prevent memory issues when dealing with thousands of records.