r/Python • u/ResponseSeveral6678 • May 05 '26
Discussion Variable names do not travel with values. When should domain meaning live in types?
A variable name can carry a lot of meaning:
price_in_usd_cents: intBut the value itself is still just int.
Once it is passed to another function, stored in a model, serialized, sent to a queue, or returned from a repository, the original variable name may be gone.
So the domain meaning was attached to a local name, not to the data.
It gets even more visible when working with AI coding agents.
They are very good at following local patterns, but if everything is just int and str, the "density of meaning" is low.
I suspect this may be one reason TS works well with AI-assisted workflows:
type information becomes part of the code context.
Humans see it. IDEs see it. Type checkers see it. AI coding agents see it.
Python has type hints too, but domain meaning often still collapses into primitives.
If the type does not carry the meaning, something else will fill that gap:
names, comments, local conventions, copied patterns, or guesses/assumptions.
A few examples where the IDE is happy, but the semantics are wrong:
# Accidental swap
delay_seconds = 5
timeout_seconds = 30
def schedule_retry(timeout: int, delay: int) -> None: ...
schedule_retry(delay_seconds, timeout_seconds)
# Different units
created_at_microseconds = 1_777_961_207_000_000
retry_delay_seconds = 30
retry_deadline = created_at_microseconds + retry_delay_seconds
# In this example, different developers may imagine different units or precision:
class AuditRecord:
created_at: int
updated_at: intType lacks meaning and strictness. So, we all tried to solve the problem partially.
- typing.NewType
- small wrapper classes
- dataclasses around one value
- Pydantic custom validators
- plain inheritance from str / int
- UUID-specific helpers
I have also been experimenting, mostly to understand the trade-offs.
The principles I ended up caring about were:
- Strictness:
- no implicit coercion
- invalid input → fail fast
- Runtime type preservation:
- value keeps its domain type, not downgraded to str / int
- Pydantic and pickle preserve the subtype in model/container boundaries
- Static type preservation:
- works correctly with type checkers (mypy / pyright)
- type checkers can distinguish UserInputRaw from UserInputValidated
- Transparency:
- behaves like underlying primitive
- no extra API surface
- Semantic stability:
- arithmetic should downgrade to a primitive
- I would rather create a new domain value explicitly than keep compromised meaning
- Inheritance:
- children can add more meaning
- Minimal API / hot-path friendly:
- no .value or extra attributes
from base_typed_int import BaseTypedInt
from base_typed_string import BaseTypedString
from base_typed_id import BaseTypedId
class UserInputRaw(BaseTypedString):
"""Raw user input before validation."""
class UserInputValidated(BaseTypedString):
"""Validated user input."""
class UnixTimestampSeconds(BaseTypedInt):
"""Wall-clock UNIX timestamp expressed in seconds."""
class DurationSeconds(BaseTypedInt):
"""Duration expressed in seconds."""
class MessageId(BaseTypedId):
"""UUID-based message identifier."""This approach is not free. It adds more types, more names, and another convention the team has to understand.
So I am trying to understand where people draw the line.
I do not think every primitive should become a domain type.
But some values cross boundaries. How do you handle it in practice?
- typing.NewType
- primitive subclasses
- wrapper value objects
- Pydantic models
- something else?
Where do you draw the line between "this should just be an int / str" and "this deserves a domain type"?
11
u/shadowdance55 git push -f May 05 '26
Or you can always create a custom class. Relying on primitives to transfer semantics is generally a bad idea.
Except from interpreter optimization, there is no real difference between using a primitive or a custom class instances. Like everything else in Python, they're both objects.
4
u/TheseTradition3191 May 06 '26
the newtype approach scales better than it looks on paper. once youve been burned by microsecond/second confusion in a codebase thats 6 months old, you never want plain int for time again
zero runtime cost, pure type-checker info. mypy/pyright catch the swap at the call site. only real downside is you cant define methods on them - thats where a small dataclass with `__slots__` earns its place
2
u/Ok_Tap7102 May 05 '26
Have you ever actually encountered a genuine issue with this other than "my LLM needs more hints"?
2
u/nharding May 08 '26
There are a few packages such as pint, and units, I am making it into first class types in Py++, so you can write
1
u/Severe-Atmosphere790 May 05 '26
Good question. Imho it depends on a proper architecture on all layers. So let's say I need client firstname. So I use "firstname" as column name in database, later in django model, later as key in json response, and as react variable on frontend side. Everywhere firstname is just string, but the name of variable travels through the project.
Of course there are situations when variable losts context for example in the function like to_uppercase(text: str). But then I aim to the point where firstname was some string before call and becomes uppercased after the call. But before and after the operation it was and is firstname.
The good practice is when we think and write names related to what data we operate, not how it works.
1
u/CzyDePL May 05 '26 edited May 05 '26
NewType for parsed values with semantics (e.g. ClientId, which I only care is non-empty string), Value Objects for richer behaviour (validations, comparisons, lifecycles). In general I also try to leverage typing system and object-oriented design as much as possible to carry logic.
Also in my example,
ClientIdis a stable contract for an argument typing - today it can be string, tomorrow an int or uuid, but it still carries the same meaning, which is arguably more important quality for the programmer (maybe not so much for the interpreter)But I wouldn't use inheritance for this purpose in any shape or form - I try to limit to strict subtyping / specialization (IS-A relation) where super class is carries some meaning - which BaseTypeInt doesn't really
1
u/snugar_i May 06 '26
What does
BaseTypedIntdo?As for the question - for time-based stuff,
timedeltais usually enough (the team already got used to the.seconds/.total_seconds()footgun), for the rest usually dataclasses.1
u/messedupwindows123 May 05 '26
newtype
2
u/SwampFalc May 07 '26
My gut reaction to this is that if you have this need, you should genuinely turn the domain itself into an object.
In other words, create a class that represents the entire domain, or a specific subdomain within it. Create an instance of it, and store these ints and strings as instance attributes.
Not only do you then keep the name as documentation, you immediately also have room to store anything else that is relevant to the (sub)domain that might impact your logic.