Do you have any recommendations for articles or example projects of what a good Python project (that isn't django based) looks like in 2025? Seeing things like pydantic derived types leak everywhere seems wrong from my Java background.

Ooh, great question. I don't have a good link. I would say that most of the concepts that I'm expressing come from personal experience and an interest in optimizing my own codebases for maintainability.

Pydantic is often misunderstood, and developers who aren't familiar with typesafe-python love to try to raise criticisms of it. But the way that you should think about it is that it's essentially a replacement for a built-in type system in the context of data like a dataclass. However, Pydantic takes it further by giving you serialization and deserialization that is customizable and has integrations with, for example, SQL Alchemy where you can serialize directly from your ORM. One of the major benefits that I find is that it provides common, repeatable interfaces for validation or data formatting.

Essentially, it has become incredibly popular because it provides a consistent interface that developers understand for accomplishing these common patterns.

When it comes to "leaking" derived types through things like OpenAPI specs and documentation, they don't really expose the underlying object's functionality, but they do expose the object's structure so that you can easily generate documentation that includes the expected response bodies and expected return bodies. Whether those get serialized into JSON or something else, the parameters and types and optionality of each of those is formally defined by Pydantic in a way that's straightforward for the documentation generation to interpret.

In most cases you'll disable the generated documentation links from FastAPI in production.

pydantic types are designed to be shipped. Just make sure you strip any security stuff or PII. Pydantic and JSON work very very well together.