Line-by-line:

1. @lru_cache(maxsize=128) wraps the function with an LRU cache.
2. circle_area accepts a Circle instance; since Circle is frozen, it's hashable and usable as a cache key.
3. Calling circle_area(c) repeatedly reuses cached value; significant if the computation is costly.

• Be mindful of memory: caches keep references alive; choose appropriate maxsize.
• Use functools.cache (Python 3.9+) or lru_cache(maxsize=None) for unlimited cache (use responsibly).

Using pathlib with dataclasses: Clean File Operations

Pathlib provides an expressive, cross-platform API for filesystem paths. Combining pathlib with dataclasses creates clear models for file metadata or file-backed objects.

Example: FileRecord dataclass that reads content lazily

from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional
@dataclass
class FileRecord:
    path: Path
    _content: Optional[str] = field(default=None, repr=False, init=False)
    def read(self) -> str:
        """Read file content lazily and cache it."""
        if self._content is None:
            self._content = self.path.read_text(encoding="utf-8")
        return self._content
    def write(self, content: str) -> None:
        self.path.write_text(content, encoding="utf-8")
        self._content = content

Explanation:

• path: Path stores a pathlib.Path object; callers can pass strings or Path objects (Path("file.txt")).
• _content is a cached content attribute; set repr=False to avoid printing large content in reprs, init=False to exclude from __init__.
• read lazily loads data via Path.read_text(), caching it to avoid repeated I/O.
• write updates the file and resets the cache.

• File not found raises FileNotFoundError from read_text. Consider wrapping I/O with try/except and returning a controlled error or default.

• Use Path operations (exists, is_file, parent.mkdir(parents=True, exist_ok=True)) for robust file handling.

Real-World Example: Building a Minimal FastAPI Microservice Using Dataclasses

Scenario: Create a microservice that receives a dataclass-based request describing a file operation, reads the file, computes a metric (e.g., word count), and returns a result. We'll show how dataclasses can be used, how to integrate caching for repeated computations, and how to containerize with Docker.

Important note: FastAPI prefers Pydantic models for request validation. You can:

• Convert dataclasses to dicts and then to models;
• Use Pydantic models directly for request bodies; or
• Use Pydantic's dataclass integration (pydantic.dataclasses.dataclass) to get runtime validation.

app.py:

# app.py
from dataclasses import dataclass, asdict
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from pathlib import Path
from typing import Optional
from functools import lru_cache
app = FastAPI()
class FileQuery(BaseModel):
    path: str
@dataclass(frozen=True)
class FileRequest:
    path: Path
@lru_cache(maxsize=256)
def word_count_for_file(req: FileRequest) -> int:
    p = req.path
    if not p.exists() or not p.is_file():
        raise FileNotFoundError(str(p))
    text = p.read_text(encoding="utf-8")
    # simple metric: number of words separated by whitespace
    return len(text.split())
@app.post("/wordcount")
def wordcount(query: FileQuery):
    try:
        req = FileRequest(Path(query.path))
        count = word_count_for_file(req)
        return {"path": str(req.path), "words": count}
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail="File not found")

Line-by-line explanation:

1. FileQuery is a Pydantic model for input validation: ensures the body has a path string.
2. FileRequest is a frozen dataclass, making it hashable to be used with lru_cache.
3. word_count_for_file is cached; repeated requests for the exact same Path reuse cached results.
4. In the endpoint, we convert validated input to a FileRequest dataclass and call the cached function.
5. Errors (file not found) map to an HTTP 404.

• Start FastAPI via uvicorn app:app --reload.
• POST to /wordcount with JSON {"path":"/tmp/data.txt"}.

FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml poetry.lock /app/  # if using poetry, otherwise requirements.txt
RUN pip install fastapi uvicorn pydantic
COPY . /app
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "80"]

Notes on scaling:

• Caching inside a single container is per-process; in a multi-replica deployment, each instance maintains its own cache. Use external caches (Redis) for shared caching across services.
• For production you'd include proper dependency management, logging, and security headers.

Advanced Patterns

1. Validation in post-init:

1. Inheritance:

1. Mix dataclasses with Protocol/Interfaces:

1. Conversion to/from other systems:

1. Using dataclasses.replace:

Example: safe updates with replace:

from dataclasses import dataclass, replace
@dataclass(frozen=True)
class Config:
    host: str
    port: int
c1 = Config("localhost", 8080)
c2 = replace(c1, port=9090)  # returns a new instance

Common Pitfalls and How to Avoid Them

• Mutable default values: Always prefer default_factory for lists/dicts/sets.
• Assuming type hints are runtime checks: They are not — use validators or Pydantic for runtime validation.
• Hashing mutable fields: Frozen dataclasses with mutable fields can lead to surprising behavior if the contained mutable object is mutated.
• Using dataclasses for behavioral classes: Dataclasses are best for data containers; classes with lots of behavior may be better expressed as normal classes or with composition.

Performance Considerations

• Dataclasses add tiny overhead for the class creation time (auto-generating methods), but the runtime per-instance cost is negligible.
• For very performance-sensitive scenarios, microbenchmark attributes access vs. plain classes — usually attribute access is the same.
• Caching expensive operations (functools.lru_cache) can give large speedups. Be mindful of memory consumption and invalidation strategies.

Best Practices Summary

• Use dataclasses for plain data containers and DTOs (Data Transfer Objects).
• Prefer frozen=True when instances represent immutable values or are used as keys.
• Use field(default_factory=...) to avoid shared mutable defaults.
• Keep heavy validation in a dedicated layer (Pydantic, validators, or explicit checks in __post_init__).
• Combine pathlib for robust file handling and functools for caching to compose performant, readable code.
• When exposing dataclasses through FastAPI, either convert to/from Pydantic models or use pydantic.dataclasses if you want validation.

Example: Putting It All Together

A small example showing dataclasses + pathlib + lru_cache and safe serialization:

from dataclasses import dataclass, asdict
from pathlib import Path
from functools import lru_cache
import json
@dataclass(frozen=True)
class Document:
    path: Path
    def to_serializable(self):
        # Convert to JSON-friendly dict
        d = asdict(self)
        d['path'] = str(self.path)
        return d
@lru_cache(maxsize=128)
def word_count(doc: Document) -> int:
    p = doc.path
    if not p.exists():
        raise FileNotFoundError(str(p))
    text = p.read_text(encoding="utf-8")
    return len(text.split())
Usage
doc = Document(Path("/tmp/sample.txt"))
try:
    count = word_count(doc)
    print(json.dumps({"doc": doc.to_serializable(), "words": count}))
except FileNotFoundError:
    print("File missing")

Explanation:

• to_serializable ensures JSON-friendly types (Path -> str).
• Cached word_count reduces repeated I/O for the same file path.

Further Reading and Tools

• dataclasses official docs: https://docs.python.org/3/library/dataclasses.html
• functools docs (lru_cache): https://docs.python.org/3/library/functools.html#functools.lru_cache
• pathlib docs: https://docs.python.org/3/library/pathlib.html
• FastAPI docs and examples: https://fastapi.tiangolo.com
• For richer validation: Pydantic — https://pydantic-docs.helpmanual.io

Conclusion