Quick answer: Python annotations document intended types but are not enforced by the interpreter. An rtype-style runtime validator can check annotated boundaries, while static checking, tests, and value validation remain separate responsibilities. Validate external inputs once and keep internal contracts clear.
In Python, rtype usually means return type. You will often see it in docstrings as :rtype:, where it tells readers what kind of object a function returns.
Modern Python code more often uses return type hints with the arrow syntax, such as def add(a: int, b: int) -> int. Both styles describe the output of a function, but they are used by different tools and documentation systems.
The important idea is simple: callers should know what comes back before they use a function. A clear return type makes code easier to read, test, document, and refactor. It also helps editors show better autocomplete and catch obvious mismatches earlier.
The official Python typing documentation explains modern type hints. For related code quality topics, see Python documentation tools, the Python syntax checker guide, and the Python union of lists guide.
Use rtype In A Docstring
Older Sphinx-style docstrings often describe parameters with :param: and the return type with :rtype:.
def square(number):
"""
Return the square of a number.
:param number: Number to square.
:type number: int
:return: Squared number.
:rtype: int
"""
return number * number
This style is useful when a project already generates documentation from docstrings. It keeps explanatory text and type details in the same place.
Docstring return types are mainly documentation. They are easy for humans to read, but static analysis tools usually prefer real annotations in the function signature.
Use A Return Type Hint
For new Python code, return type hints are usually clearer because tools can read them directly from the function signature.
def square(number: int) -> int:
return number * number
result = square(6)
print(result)
The -> int part means the function is expected to return an integer. Python does not enforce this automatically at runtime, but editors and type checkers can use it.
This makes signatures self-explanatory. A reader can scan the function line and understand the expected input and output without opening the body or reading a long comment first.
Return Collections
Return types can describe containers too. Use list[str], dict[str, int], or similar forms in modern Python.
def normalize_names(names: list[str]) -> list[str]:
cleaned = []
for name in names:
cleaned.append(name.strip().title())
return cleaned
print(normalize_names([" ada ", "grace "]))
This tells readers that the function accepts a list of strings and returns another list of strings.
Collection return types are especially useful in larger functions because they make shape expectations clear. A function that returns one string is different from one that returns a list of strings, even if both are built from the same source data.
Return More Than One Possible Type
When a function can return one type or another, use the union operator in Python 3.10 and newer.
def find_user(user_id: int) -> dict[str, str] | None:
if user_id == 1:
return {"name": "Ada"}
return None
print(find_user(1))
print(find_user(2))
The | None part makes the missing-result case visible. That helps callers remember to handle it.
Without this hint, callers may assume the function always returns a dictionary and then fail later with a TypeError. Making the optional case explicit encourages safer checks.
Return Custom Objects
Return type hints also work with classes. If the class is already defined, use the class name directly.
class Report:
def __init__(self, title: str):
self.title = title
def build_report(title: str) -> Report:
return Report(title)
report = build_report("Daily Check")
print(report.title)
This makes factory functions easier to understand. A reader can see which object comes back without jumping into the function body.
For larger projects, these annotations also help keep module boundaries clear. Functions that build reports, clients, parsers, or response objects can advertise the exact object they return.
Inspect Type Hints
Python stores annotations on functions, and typing.get_type_hints() can resolve them for tools.
from typing import get_type_hints
def add(left: int, right: int) -> int:
return left + right
hints = get_type_hints(add)
print(hints["left"])
print(hints["return"])
This is how documentation tools, validation helpers, and type-aware frameworks can inspect return type information.
Runtime introspection should be used carefully, but it is useful for tooling. Many frameworks read annotations to build schemas, validate inputs, or generate documentation.
rtype vs Type Hints
Use :rtype: when your project already follows Sphinx-style docstrings or needs human-readable documentation in that format. Use return type hints when you want editor support, static analysis, and signatures that explain themselves.
You can use both, but avoid letting them disagree. If the docstring says :rtype: int and the function signature says -> str, readers and tools will get conflicting information.
When updating old code, change the annotation and docstring together. If the function behavior changes from returning a single item to returning a list, update every place that describes the return type.
The reliable pattern is to make the return value obvious in the signature, explain behavior in the docstring, and keep any rtype text aligned with the actual return type. That gives humans and tools the same understanding of the function output.
Annotate The Contract
Type hints make the intended input and output visible to readers and static tools. They do not automatically reject a value at runtime.
def total(values: list[float]) -> float:
return sum(values)
print(total([1.5, 2.5]))
Validate At A Boundary
Runtime checks are most valuable where data enters from a file, request, plugin, or other untrusted boundary. Convert or reject invalid values before internal code relies on the contract.
def require_positive(value: int) -> int:
if not isinstance(value, int) or value <= 0:
raise ValueError("expected a positive integer")
return value
print(require_positive(3))
Keep Static And Runtime Checks Distinct
A static checker catches many annotation mismatches before execution, while runtime validation catches actual values. Use both where the cost and risk justify them instead of assuming one replaces the other.
from typing import get_type_hints
def greet(name: str) -> str:
return f"Hello, {name}"
print(get_type_hints(greet))
Test Values And Behavior
Type checks do not prove ranges, relationships, side effects, or business rules. Add tests for valid values, invalid values, boundary cases, and the behavior that the function promises.
def percentage(value: float) -> float:
if not 0 <= value <= 100:
raise ValueError("percentage out of range")
return value
print(percentage(75.0))
Python’s typing documentation defines annotations, while a runtime validator should be evaluated against its maintained project documentation. Related references include runtime attribute contracts, tests, and typed iteration.
For related contract design, compare runtime attribute checks, tests, and typed iteration when adding validation.
Frequently Asked Questions
What is rtype used for in Python?
An rtype-style tool can validate annotated function inputs or outputs at runtime, depending on the library and configuration.
Are Python type hints enforced automatically?
No. Python annotations are metadata unless a static checker, runtime validator, or framework actively uses them.
Where should runtime validation happen?
Validate at external or untrusted boundaries, then keep internal code simpler once the contract is established.
Can runtime type checking replace tests?
No. It checks type-oriented contracts but not business rules, values, side effects, or integration behavior.
