Python Type Annotations: From Guessing Games to Clear Programming

Python does not require specifying variable types, which is both an advantage and sometimes a source of trouble. Have you ever encountered the frustration of looking at a function you wrote months ago and completely forgetting what parameters to pass? Or when calling someone else’s function, you can only guess what parameters to provide? I used to waste a lot of time in this “guessing game.” Since there is a problem, there must be a corresponding solution. Let’s see what Type Hints offers as a solution.

What are Type Annotations?

In simple terms, type annotations are type specifications added to variables, function parameters, and return values. For example:



1
2
3
4
5
6
7


# Previously written like this - like playing a guessing game
def process_data(data):
    return len(data)
 
# Now it can be written like this - clear and straightforward
def process_data(data: list) -> int:
    return len(data)

Looking at the second piece of code, you can immediately understand: this function takes a list and returns an integer. No more guessing!

Why is it Needed?

Python is known for its flexibility, but its dynamic typing can sometimes lead to issues:

Poor Code Readability

Code without type annotations is like traveling without a map:



1
2
3


def calculate(items, count):
    # What are items? Should count be a number?
    return sum(items) * count

Hidden Bugs

Type errors may only surface at runtime:



1
2
3


def connect_database(host, port):
    # If port is passed as the string "3306", it may only raise an error at connection time
    pass

Low Development Efficiency

Without accurate code suggestions from the IDE, you have to frequently consult the documentation.

Three Major Benefits of Type Annotations:

• Improved Readability: The intent of the code is clear at a glance
• Early Error Detection: Captures type issues before runtime
• Enhanced Development Experience: IDEs provide smart suggestions and autocompletion

Basic Usage: It’s Quite Simple

Variable Annotations

Starting from Python 3.6, you can directly add type annotations to variables:



1
2
3
4
5
6
7
8
9


# Basic type annotations
name: str = "Zhang San"           # String
age: int = 25                      # Integer
is_valid: bool = True              # Boolean
price: float = 19.99               # Float
 
# Container type annotations
scores: list = [90, 85, 95]        # List
config: dict = {"key": "value"} # Dictionary

Function Annotations

Functions are the most important application scenario for type annotations:



1
2
3
4
5
6


def greet(name: str, times: int = 1) -> str:
    """Greet someone a specified number of times"""
    return " ".join([f"Hello, {name}!"] * times)
 
# When called, the IDE will suggest parameter types and return value types
result = greet("Bob", 3)  # Correct usage

Annotation Interpretation:

• name: str→ Parameter name should be a string
• times: int = 1→ Parameter times is an integer, default value is 1
• -> str→ The function returns a string

Handling Complex Situations

Precise Container Type Annotations

Sometimes knowing it’s a list is not enough; you also want to know what the list contains:



1
2
3
4
5
6
7


from typing import List, Dict, Tuple, Set 
 
# Precise container type annotations
umbers: List[int] = [1, 2, 3]                    # List of integers
student_scores: Dict[str, float] = {"Alice": 95.5} # Dictionary: string keys, float values
coordinates: Tuple[float, float] = (1.5, 2.3)      # Tuple: two floats
tags: Set[str] = {"python", "programming"}         # Set of strings

Optional and Union Types

Handling cases that may be None or multiple types:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15


from typing import Optional, Union 
 
# Optional type: may be a string or None
def find_user(username: str) -> Optional[str]:
    users = {"alice": "user123"}
    return users.get(username)  # Returns a string or None 
 
# Union type: may be one of several types
def process_data(data: Union[str, int, list]) -> None:
    if isinstance(data, str):
        print(f"Processing string: {data}")
    elif isinstance(data, int):
        print(f"Processing integer: {data}")
    elif isinstance(data, list):
        print(f"Processing list: {data}")

This way, the caller knows to handle the None case.

Practical Application: Using Tools to Check Type Errors

Writing annotations is not enough; we need tools to check if types are correct. The one I use most often is mypy.

Installation and Usage



1


pip install mypy

Assuming there is a file namedtest.py:



1
2
3
4
5


def add_numbers(a: int, b: int) -> int:
    return a + b 
 
# Intentionally passing the wrong type
result = add_numbers(10, "20")  # The second parameter should be a number

Run the check:



1


mypy test.py

mypy will tell you:



1


test.py:5: error: Argument 2 to "add_numbers" has incompatible type "str"; expected "int"

This way, you can discover errors before running the program, rather than waiting for it to crash.

Usage Experience

Don’t Try to Do It All at Once

At first, don’t try to add type annotations to all your code; it will be painful. Here’s how I do it:

1. Annotate All New Code: Add type annotations to all new functions
2. Prioritize Important Functions: Start with functions that are core to business logic
3. Gradual Improvement: Each time you modify old code, add type annotations as well

Where is it Most Worth Adding?

In my experience, these areas are the most cost-effective for adding type annotations:

• Public Interface Functions: Functions that will be called by others
• Complex Data Processing Functions: Functions with complex parameter and return value types
• Functions Prone to Errors: Functions that have historically had type-related bugs

Real Case Study

In our project, we had a price calculation function that originally looked like this:



1
2
3


def calculate_price(quantity, price, tax_rate):
    # Various calculation logic...
    pass

People often passed tax_rate as the string “0.1” instead of the number 0.1. After adding type annotations:



1
2
3


def calculate_price(quantity: int, price: float, tax_rate: float) -> float:
    # Same logic...
    pass

This type of error has never occurred again, and newcomers can quickly understand how to use this function.

Some Practical Tips

Handling Third-Party Libraries Without Annotations

Some older libraries do not have type annotations; you can handle them like this:



1
2
3
4
5


from typing import Any
import some_old_library 
 
# Temporarily use Any type, indicating no type checking
result: Any = some_old_library.some_function()

IDE Support

Modern IDEs have excellent support for type annotations:

• VS Code and PyCharm provide code completion based on types
• Type errors will have red wavy line indications
• Hovering shows function signatures

My Missteps

At first, I also found type annotations cumbersome, thinking: “Python is dynamically typed; isn’t adding these redundant?”

But after several projects, I found:

• Debugging Time is Reduced: Type errors can be discovered during coding
• Code is Easier to Maintain: Looking back at the code after six months, I can still understand it quickly
• Team Collaboration is Smoother: Newcomers can quickly get up to speed with the code

Especially as projects grow larger and more people get involved, the value of type annotations becomes even more apparent.

Recommendations

If you haven’t used type annotations yet, I suggest starting like this:

1. Try it on One Function First: Choose a function you are familiar with and add type annotations to experience it
2. Install mypy: Experience the effects of type checking
3. Use in New Code: From now on, add type annotations to all new functions

There is no need to switch to type annotations all at once; gradual improvement is key.

Type annotations are not a silver bullet, but they have indeed made my programming life much easier. At least, I no longer have to play the guessing game of “what type should this variable be?”

Have you used type annotations in your projects? Or do you have any questions about type annotations? Feel free to discuss!

Recommended Reading:

Python with keyword: Make your resource management easier

Don’t let Python eat your memory: Understand memory management at once

When to use is? When to use ==? Why does Python design it this way?

✨Follow me, to get more Python learning resources, practical projects, and industry trends! Reply “python learning” in the public account backend to get Python learning e-books!