# Dynamic vs Static

So what is typing? For many Python developers, this can feel new, because most classic languages such as C, Java, Rust, and many others were originally designed as statically typed languages. But what does that mean? Let’s look at a small C example:

int sum(int a, int b) {
    return a + b;
}

int main() {
    printf("%d\n", sum(10, 20));

    // printf("%d\n", sum("10", 20));
}

This code works and prints 30. But note that the last line is commented out. If we uncomment it and compile again, we will get an error log like this:

error: passing argument 1 of ‘sum’ makes integer from pointer without cast
   10 |     printf("%d\n", sum("10", 20));
      |                        ^~~~
      |                        |
      |                        char *
note: expected ‘int’ but argument is of type ‘char *’

The log says that the function parameter expected int but got char * (for simplicity, think of it as a string). At first glance, this may not look surprising for Python developers, because this Python code would also fail:

def sum(a, b):
    return a + b

print(sum("10", 20)) # TypeError

So what is the difference? Let’s tweak both examples in C and Python, and call sum with two strings:

print(sum("10", "20")) # > 1020

Here we get no error, because polymorphism works and string addition is valid. But what happens in C?

int main() {
    printf("%d\n", sum("10", "20"));
}

You cannot even compile this program. You get the same error log as before. Notice how we defined sum in C: we explicitly set input argument types to int. That means arguments of any other type cannot be passed into this function. This is static typing. Static typing also requires a type for each variable and prevents changing variable types after declaration. In other words, the type is fixed.

The second group is dynamically typed languages: Python, Lua, JavaScript, and others. In those languages, the variable type is not strictly fixed and can change during execution.

# Benefits of Typing

Now to the question: why do we need typing if Python already works well without it? First, speed. At a low level (whatever representation you use), types are always needed. If we do not write them explicitly, it only means someone else does that for us (for example, a virtual machine), which requires resources. That is reflected in language speed rankings:

In this rating, Python is at the bottom. Will typed Python fix that? Unfortunately, no. Python was not and still is not a statically typed language. Type annotations in Python remain optional. You can omit them, and the Python interpreter does not enforce them at runtime.

This brings us to the second benefit of types: code quality.

“The goal of typing in Python is to help development tools find errors in Python code bases through static analysis, without running code tests.”

Luciano Ramalho, “Fluent Python”

Extending this idea, typing goals are:

• Early error detection, before runtime and before production failures.
• “Test extraction”: correct typing can reduce the number of tests, which are often harder to write and maintain than types. Tests can then focus on business logic, not primitive mismatches.
• Better readability: PEP 20 says “Explicit is better than implicit.” When reading code, function signatures are often enough without diving into implementation.
• Better IDE workflow with more hints and warnings.
• Better architecture quality: types force cleaner abstractions.

# How to Write Typed Code

Before code, let’s separate three important concepts: interface, abstract class, and protocol. What is the difference?

• Interface is a class where all methods are abstract, with no implementation details.
• Abstract class is a class with both abstract and implemented methods.
• Protocol is an implicit interface.

The first two are straightforward. Let’s focus on the last one. In Python, an interface pattern is usually implemented through inheritance: a class implementing an interface inherits from that interface class. A class implementing a protocol does not have to inherit from it and may not even know about it.

## Primitives

Let’s finally look at how to write typed code. Start with a simple function that repeats a string n times.

def multi_string(string, n):
    return string * n

print(multi_string("cat", 3)) # > catcatcat

This function takes a string and a number and returns a string built by concatenating the original string with itself n times. Now type it:

def multi_string(string: str, n: int) -> str:
    return string * n

Syntax is simple: input parameter types go after a colon, output type goes after an arrow. Your IDE can now highlight errors if inputs are wrong or if returned values are handled incorrectly.

You can annotate all common primitives this way: str, int, bytes, float, Decimal, bool.

## Union Types

In real code there are more complex cases where a function should accept multiple types, but not arbitrary ones. In those cases use unions:

def normalize(data: str | bytes) -> str:
    if isinstance(data, bytes):
        return data.decode("utf-8")
    return data

Here normalize accepts either a string or bytes and always returns a UTF-8 string. With union (|), you can list multiple types, but you should use this carefully. If you feel like writing a long union of ten types, pause and reconsider. We will cover ways to handle such cases below.

Unions are also valid for return types, but mostly for optional results. Example:

def parse_int(value: str) -> int | None:
    if not value.isdigit():
        return None
    return int(value)

This means the function result is optional. It may return int, or may not return one if parsing fails. But annotating returns as int | str or other unrelated combinations is usually bad practice. It becomes unclear how to process the result. In practice, return either a concrete type with known methods/attributes, or None. Breaking this rule tends to complicate code.

## Collection Specification

Besides primitives, you can and should annotate collections. Avoid plain data: list; specify element types too. Use square brackets:

def format_user(user: tuple[str, int]) -> str:
    name, score = user
    return f"{name}: {score} points"

def average(values: list[float]) -> float:
    if len(values) == 0:
        return 0
    return sum(values) / len(values)

def total_count(counters: dict[str, int]) -> int:
    return sum(counters.values())

Of course, this does not cover all production scenarios. In TypedDict, NamedTuple, and Dataclass, we extend this toolkit.

## Mapping and MutableMapping

Mapping and MutableMapping are abstract base classes for dict-like structures. Mapping guarantees read-only behavior (keys, values, iteration), while MutableMapping says the object is mutable.

from collections.abc import Mapping, MutableMapping

def read_config(cfg: Mapping[str, str]) -> str:
    return cfg["DATABASE_URL"]

def patch_config(cfg: MutableMapping[str, str]) -> None:
    cfg["DEBUG"] = "1"

If a function only reads data, use Mapping. If it mutates data, use MutableMapping. This is a small but important signal for readers and type checkers.

## NamedTuple

When you need a fixed set of fields while keeping tuple behavior, NamedTuple is useful. It is immutable and indexable, but also lets you access fields by name.

from typing import NamedTuple

class User(NamedTuple):
    id: int
    username: str
    score: int

def print_user(user: User) -> str:
    return f"{user.username} ({user.id}) = {user.score}"

NamedTuple is good for compact data structures that should not change after creation. If you need mutability and richer behavior, prefer dataclass or a regular class.

## TypedDict

If your structure is a dictionary and you want typed keys and values, use TypedDict. It describes dictionary shape and works at static analysis level.

from typing import TypedDict

class User(TypedDict):
    id: int
    username: str
    email: str | None

def send_email(user: User) -> None:
    ...

This is especially useful when data comes from JSON or another dynamic source but you still want a strict key contract. If some keys are optional, define that explicitly to keep type checks meaningful.

## Dataclass

dataclass is a convenient way to define a data container with initializer, comparisons, and readable repr. This class is mutable by default and works well for domain objects and DTOs.

from dataclasses import dataclass

@dataclass
class User:
    id: int
    username: str
    email: str | None = None

def normalize(user: User) -> User:
    user.username = user.username.lower()
    return user

dataclass is a good fit when you need mutable structure and clear data modeling. If an object must be immutable, use @dataclass(frozen=True).

## Enum

Enum helps define a closed set of values. This is useful when a field has a strict list of allowed options and you do not want random strings in your code.

from enum import Enum

class Status(Enum):
    NEW = "new"
    DONE = "done"
    FAILED = "failed"

def is_done(status: Status) -> bool:
    return status is Status.DONE

This approach is practical for statuses, roles, flags, modes, and other enumerable domain values.

## Custom Classes

The type system can specify not only primitives but also your own or library classes. For example:

class User:
    id: int
    username: str
    email: str
    friends: list[User]

def hand_shake(user1: User, user2: User) -> None:
    user1.friends.append(user2)
    user2.friends.append(user1)

## Abstract Classes

Python has an excellent module, collections.abc. It already defines a large set of abstract classes that cover most practical needs. They are useful when you want to describe behavior, not a concrete implementation. What is available there?

collections.abc.ABCMeta
collections.abc.AsyncGenerator
collections.abc.AsyncIterable
collections.abc.AsyncIterator
collections.abc.Awaitable
collections.abc.Buffer
collections.abc.ByteString
collections.abc.Callable
collections.abc.Collection
collections.abc.Container
collections.abc.Coroutine
collections.abc.EllipsisType
collections.abc.FunctionType
collections.abc.Generator
collections.abc.GenericAlias
collections.abc.Hashable
collections.abc.ItemsView
collections.abc.Iterable
collections.abc.Iterator
collections.abc.KeysView
collections.abc.Mapping
collections.abc.MappingView
collections.abc.MutableMapping
collections.abc.MutableSequence
collections.abc.MutableSet
collections.abc.Reversible
collections.abc.Sequence
collections.abc.Set
collections.abc.Sized
collections.abc.ValuesView

As you can see, there are many abstract classes. Most describe a property of a collection. Using them in annotations lets you express wider polymorphic input boundaries for your functions:

from collections.abc import Iterable

def total(values: Iterable[int]) -> int:
    return sum(values)

total([1, 2, 3])
total((1, 2, 3))
total({1, 2, 3})

Sometimes you still see imports from typing like from typing import Iterable, Sequence. In practice, those are re-exports from collections.abc. Today it is better to import these ABCs directly from collections.abc.

## Sequence and Iterable

These two are often confused. Iterable only guarantees that an object can be iterated in a loop. No indexing, length, or ordering is promised. Sequence guarantees iteration plus indexing and length, that is __getitem__ and __len__. This leads to a practical difference in what operations are safe.

from collections.abc import Iterable, Sequence

def sum_any(values: Iterable[int]) -> int:
    total = 0
    for v in values:
        total += v
    return total

def head(values: Sequence[int]) -> int:
    return values[0]

sum_any accepts a list, tuple, or generator. head cannot accept a generator, because it has no indexing and you cannot do values[0]. So, if you only need iteration, use Iterable; if you rely on indexing or length, use Sequence.

## Callable

Callable is used when a function accepts another function. This is especially important for callbacks, event handlers, and higher-order functions.

from collections.abc import Callable

def apply(values: list[int], fn: Callable[[int], int]) -> list[int]:
    return [fn(v) for v in values]

If the signature is unknown in advance, you can use Callable[..., ReturnType], but this should be a last resort.

## Generics

Generics are parameterized types. In simple terms, these are types that accept other types. This matters when you want to preserve the relation between input and output instead of losing it to Any. For example, first returns the same item type as inside the input collection:

from collections.abc import Sequence
from typing import TypeVar

T = TypeVar("T")

def first(items: Sequence[T]) -> T:
    return items[0]

Without generics, you would write Sequence[Any] and lose output type. With generics, the analyzer knows that if input is Sequence[str], the result is str. This is especially important for collections, factories, and repositories where one implementation handles multiple types.

It is also useful to know that TypeVar has a bound parameter that restricts which types can be used in a generic:

from collections.abc import Hashable, Iterable
from typing import TypeVar

HashableT = TypeVar("HashableT", bound=Hashable)
def mode(data: Iterable[HashableT]) -> HashableT:
    ...

## Literal

Literal lets you fix exact allowed values, not just a base type. This is useful when a parameter has a closed set of modes, statuses, or keys.

from typing import Literal

def export_report(format: Literal["csv", "json"]) -> bytes:
    ...

The signature above defines the contract clearly: no third format exists here. This makes APIs clearer and lets type checkers catch typos such as "jsno" before runtime.

## Static Analyzers

Now it is time to discuss what makes typing practical in Python: static analyzers. They read annotations, compare them with actual code, and report problems before runtime.

• mypy is the classic static type checker for gradual typing. Strength: plugin ecosystem and precise per-module strictness tuning. Weakness: without tuning it can be either too soft or too noisy.
• pyright is a fast and clear checker. Strength: good diagnostics and fast feedback. Weakness: plugin-style extensibility is weaker than in mypy.
• pyrefly is a new fast Rust analyzer. Strength: high speed and LSP integration. Weakness: still young, so some behavior may change.
• ty is a new Rust tool by Astral (currently beta). Strength: speed and modern architecture. Weakness: pre-release stage; feature set is still catching up to mature checkers.

You can install and run them with uv:

uv tool install mypy
uv tool install pyright
uv tool install pyrefly
uv tool install ty

uvx mypy .
uvx pyright .
uvx pyrefly check
uvx ty check

Here is a business-oriented example with intentional typing mistakes:

from dataclasses import dataclass
from typing import NewType

UserId = NewType("UserId", int)

@dataclass
class User:
    id: UserId
    email: str
    is_active: bool

def discount(total: int, percent: int) -> int:
    return total - total * (percent / 100)

def send_invoice(user: User, amount: int) -> str:
    if not user.is_active:
        return None
    return f"invoice for {user.email}: {amount}"

def main() -> None:
    user = User(id=42, email=123, is_active="yes")
    total = discount("1000", 10)
    send_invoice(user, "500")

Running pyright on this file will produce messages roughly like:

error: Type "float" is not assignable to return type "int"
error: Type "None" is not assignable to return type "str"
error: "Literal[42]" is not assignable to "UserId"
error: "Literal[123]" is not assignable to "str"
error: "Literal['yes']" is not assignable to "bool"
error: "Literal['1000']" is not assignable to "int"
error: "Literal['500']" is not assignable to "int"

What matters in this output:

• Errors in discount and send_invoice show function contract violations: the signature promises one thing, implementation does another.
• Errors in main show boundary-layer issues (input/DTO) passing wrong types into domain logic.
• The UserId error demonstrates why NewType is useful in business code: a user identifier cannot be accidentally replaced by a plain int without an explicit decision.

## Stub Files (.pyi)

Sometimes you want typing for code you cannot or should not edit. Examples: generated code, third-party library code, or your own module where you do not want to mix typing and implementation. That is what stub files with .pyi extension are for.

A .pyi file contains type signatures only and no implementation. Static analyzers look for these files near source code or in dedicated types-* packages. Example:

calc.py:

def add(a, b):
    return a + b

calc.pyi:

def add(a: int, b: int) -> int: ...

This way you can keep typing separate from implementation, sometimes even without access to source code.

## TypeAlias

When a type gets complex, move it into an alias to keep signatures readable. This is especially useful for business terms like UserId, Currency, or Payload.

from typing import TypeAlias

UserId: TypeAlias = int
Payload: TypeAlias = dict[str, str | int | float]

Then you can write:

def send(user_id: UserId, payload: Payload) -> None:
    ...

In Python 3.12+, you can use the type statement instead:

type UserId = int
type Payload = dict[str, str | int | float]

This is the same alias, just shorter and easier to read.

## TypeAlias vs NewType

TypeAlias is just a type synonym, it does not create a new type. NewType creates a distinct type at static-checking level, even though at runtime it is just a wrapper function. This is useful when you have logically different values of the same base type, for example UserId and OrderId.

from typing import NewType, TypeAlias

UserId: TypeAlias = int
OrderId = NewType("OrderId", int)

def get_user(user_id: UserId) -> None:
    ...

def get_order(order_id: OrderId) -> None:
    ...

UserId and int are treated as the same type. OrderId is not compatible with int without explicit conversion.

# How to Use Typing Correctly

Set the right expectation first. Like tests, the purpose of types is to fail when the code is wrong. If they never fail, they are not doing useful work. The less forgiving your typing setup is, the better it protects your code. Strict typing (like strict tests) catches bugs, but only if checks can actually fail.

Writing truly correct typed code is hard. It is a separate skill that grows the same way architecture and testing skills grow. So start small and increase strictness gradually.

## Returning None

Also consider the case where a function returns nothing:

def print_weather(weather: Weather):
    print("Weather:")
    for date, data in weather.by_days().items():
        print(date)
        print(f"\t{data.temperature}")
        print(f"\t{data.humidity}")
        print(f"\t{data.wind_speed}")
        print("========")

tmp = print_weather(Weather()) + 1

In Python, if a function has no return, it returns None. Static analyzers know this too. For example, pyright on this intentionally broken code will show:

error:
    Operator "+" not supported for types "None" and "Literal[1]"

This shows that pyright understands the return type as None. Does that mean you can skip return annotations? No. First, PEP 20 says explicit is better than implicit. Second, consider developer experience (DX) in Python. Everyone knows typing is optional, so missing return annotation is ambiguous. When you see a function signature without return type, you cannot tell whether the author skipped typing or the function really returns None. You resolve that only by reading implementation details, which slows code navigation.

## Function Input vs Output

Continuing the return-type topic: avoid using abstract classes from collections.abc, or custom abstract classes, for function return types. They are better suited for input types where you want broad polymorphism. Return values should be concrete so it is clear how to use the result.

Important

A function should be more explicit about what concrete type it returns than what it accepts.

If you want to go deeper, here are useful resources to configure your tools and understand Python typing in detail:

• FastAPI type hints guide (helpful for web developers)
• RealPython, Type Checking Guide
• Exercises

So, where does any contribution begin? Ideally, with a problem. A problem can be called anything, including a lack of new features, missing or incomplete documentation pages on a specific topic, some question, or simply trivial bugs that exist everywhere. You personally will not confuse a problem with anything else, because it will be accompanied by an itchy feeling that “something is annoying.” But will this be a problem for other users and developers? In order to understand this and synchronize your perception with the team’s perception, an issue exists.

CONTRIBUTION.md

Every project has its own established rules on how to participate in it. These rules are described either in README.md in a separate “Contribution” paragraph, or in a special CONTRIBUTION.md file. Be sure to read it at the very beginning. This file has the highest priority. That is, even if you understand that some practices deviate from the correct scheme that we will consider below, you should still follow them. Some large projects, such as Postgres or linux-kernel, still work entirely via mailing lists. One should respect the traditions that have formed in the repository, even if they now look like legacy.

# 1. Issue

An issue is a ticket that is stored in the repository. Anyone who comes to the repository can create it. But I recommend that before rushing to describe your problem, you make several attempts to search for similar issues, so as not to burden the repository maintainers with unnecessary work. Let’s see how this can be done:

gh issue list --search "app crashed"

This and all further examples will use the official gh utility. It allows you to perform all basic GitHub operations from the console. I recommend using it for simple operations to speed up your workflow.

The search parameter allows you to add various search filters directly inside it. Let’s try to add them:

gh issue list --search "app crashed is:open label:bug created:>2024-01-01"

It is quite possible, especially in large projects, that this will allow you to find an already created ticket for your problem and even find a solution or answer in it. If not, then do not hesitate to open a new issue. The following scheme will help structure it in the best way:

  graph LR
    A[Excepted] ---> B("Action (run/click/etc)")
    B ---> C[Got]

In large projects, there are issue templates that will help you format an issue according to the standards adopted in that project. You can create an issue with the command:

gh issue create

Another excellent practice is providing a Docker image in which the entire environment is configured and the problem is guaranteed to be reproducible. Or at least provide a log. A professional approach would also be to localize the problem as much as possible. For example, you received an error in the following file:

import fruits
import logistic

a = fruits.Apple()
basket = fruits.MakeBasket()
basket.put(a)
logistic.send(basket)

Of course, you could write exactly this in the issue. But it would be even better to independently experiment with this code and understand what exactly is wrong. For example, check whether the apple was successfully added to the basket:

basket.put(a)
print(basket.content())

Perhaps the problem is that we are trying to send an empty basket, which would mean a bug in the put method. Or perhaps the problem is in the send method after all. In this way, we cut off the unnecessary, leaving the essence of the problem in the issue message.

Remember that even the fact of successfully creating an issue—for example, proposing a valuable feature or discovering a real bug or vulnerability—is already a contribution to the project, and that is already a success. A failure, on the other hand, would be creating a duplicate issue or overloading maintainers with unnecessary context.

# 2. Fork

When you understand which problem you are solving and are convinced that it is really a problem, you can move on to solving it. To do this, you should first fork the repository. This will be valuable support for you if, for example, you are testing CI or simply getting far ahead of the original repository, and it will also allow you to send pull requests, since you most likely do not have permission to make changes to the original repository:

gh repo fork <OWNER>/<REPO>

After cloning the fork locally, make changes in a separate branch, which it will be more convenient to name after the issue number you are trying to close. Why? Because in a short, concise branch name it is far from always possible to express the essence of the problem, which may have taken several months of discussion in the ticket. Therefore, it is much more convenient to simply refer to it by the issue number:

git switch -c 42

In GitHub flow, we do not create a complex branch structure where each branch has its own meaning. Instead, we have a master branch into which only changes that have passed all checks are merged. These changes come there from many so-called feature branches, which we propose to tie to specific issues. And from time to time, we release a version from the master branch. As a result, we get a fairly concise structure:

  %%{init: {
  "gitGraph": {
    "tagLabelColor": "#ffffff",
    "tagLabelBackground": "#d73a49"
  }
}}%%
gitGraph
    commit
    commit
    branch "42"
    checkout "42"
    commit
    commit
    checkout main
    merge "42"
    commit tag: "🚩 v1.1.23"

    branch "44"
    checkout "44"
    commit
    commit
    commit
    checkout main
    merge "44"
    commit tag: "🚩 v1.2.0"

Also, do not forget to synchronize your fork so as not to lose connection with the original project:

gh repo sync <your-username>/<fork-repo> --branch main

# 3. Pull request

When the changes are made and committed, you can send a pull request. The most convenient way is to simply stay on your branch and run the command below. gh will form a suitable pull request itself:

gh pr create

After creating the PR, checks may automatically start if CI is configured in the repository. And this is great. Because checks simplify and speed up the review process. You can immediately see, for example, that your code does not pass style checks, or that you did not write tests for your code and because of this the code coverage failed. Do not ignore this, but make new commits in the same branch, and after pushing them they will automatically be added to the PR and the checks will be restarted. The repository maintainer will not even begin reviewing your PR until all checks in it turn green. You can check the status of the pull request with the command:

gh pr status

Also try to make a neat commit history in the pull request to simplify the review process. Squash commits will help you with this.

When you have broken through all automated checks, do not hesitate to contact the repository architect and ask for a review. He will either review your PR himself or delegate it to someone from the team. On GitHub, this is done simply via a tag: @username. Often, notifications that a new pull request has arrived may be disabled, and moreover, the architect will not know when you have made all the fixes to pass CI. Therefore, modesty here may lead to the fact that your pull request will simply not be seen by anyone. This, by the way, also applies to issues.

If you understand that your pull request completely closes the issue you were solving, then in the PR messages you can specify Close #49, and then the issue will be automatically closed after the pull request is merged.

# 4. Merge

So, when you have passed all automated checks and manual review, your code will get into the master branch of the repository, and you can consider yourself a full-fledged contributor to this project. Keep it up!

Also pay attention to an interesting practice that, in my opinion, is very professional. Imagine that you discovered and reported some bug in an issue. This is already a contribution to the repository. Next, it is proposed to create a pull request in which you write a test that reproduces this bug. The test, of course, will fail. But you send the pull request, thereby adding this test in a disabled state to the codebase. You can also leave a TODO tag. And this will become an even greater contribution to the repository, since you have added a meaningful test, and this is always very useful. And finally, with a second pull request, you already submit changes that fix the code so that it passes this test. And once again you increase your contribution. Thus, you have left behind a lot of artifacts in the repository: an issue, an enhanced test system, and a fixed bug. This will be an excellent example of implementing the TDD (Test Driven Development) approach.

Thus, you and I have gone through the full cycle from the problem to the contribution to the master branch.:

  flowchart LR
    BUG["Find a bug / feature   "] --> ISSUE["Create Issue  "]
    ISSUE --> DISCUSS["Discussion  "]
    DISCUSS --> PR["Open Pull Request  "]
    PR --> CI["PR Checks with CI 󰦕 "]
    CI --> REVIEW["Reviewer Reviews PR  "]
    REVIEW --> MERGE["Merge PR into main  "]
    MERGE --> BUG

You can test your strength right now by finding a suitable issue using these wonderful services:

• Good First Issue — Issues that are great for beginners.
• Awesome for Beginners — A collection of projects for beginners.
• Up For Grabs — Tasks open for solving across various technologies.
• First Contributions — A repository with a manual and a list of open projects.
• First Timers Only — More similar resources.

Do not forget that you yourself can also register your projects on these resources to attract new developers!

GitHub CLI

If you are interested in productive work with GitHub from the console using the gh utility, pay attention to it documentation. And also for that, that gh supports extensions that you can familiarize yourself with you can use the gh ext browse command or write your own!

Some additional reading:

• Official GitHub guideline
• Pull Requests like a Pro, Navendu Pottekkat
• 10 Common Mistakes to Avoid When Contributing to Open Source Projects
• Open Source for Beginners