py-typewriter-cli 1.1.0

A CLI tool for generating type annotations.

Typewriter

Overview

Typewriter is a Python Typer CLI built on LibCST that normalizes None-related type annotations in Python source code. It can be used to automatically rewrite type annotations to use Optional instead of Union when None is involved, and to ensure Optional is used for variable and parameter annotations when the default value is None.

What it rewrites (default mode, Python 3.9-compatible):

Union[T, None] -> Optional[T]

Union[T1, T2, None] -> Optional[Union[T1, T2]]

x: T = None -> x: Optional[T] = None

def f(x: T = None) -> def f(x: Optional[T] = None)

With --target-version 3.10 (PEP 604 mode):

Union[T, None] -> T | None

Optional[T] -> T | None

Union[T1, T2] -> T1 | T2

Union[T1, T2, None] -> T1 | T2 | None

x: T = None -> x: T | None = None

def f(x: T = None) -> def f(x: T | None = None)

Additional notes:

• x: Any = None stays unchanged.
• Qualified typing references are preserved.
• Import statements are added as needed and deduplicated.
• Unused Union and Optional imports are cleaned up after rewriting.

Quick Start

Installation for PyPI

pip install py-typewriter-cli # Python 3.10-3.13

Usage

Typewriter exposes one subcommand: run. Consider example.py with contents:

from typing import Any, Union

count: int = None
name: str = None
payload: Any = None

def greet(user_id: int = None, msg: Union[str, None] = None) -> Union[str, None]:
    if user_id is None:
        return None
    return f"hello-{user_id}\n{msg}"

To see what would change without writing files, run with --check:

typewriter run path/to/example.py --check

Would transform path/to/example.py
--- path/to/example.py
+++ path/to/example.py
@@ ...
-old line
+new line

In --check mode, Typewriter prints a unified diff of its proposed changes to stdout and provides the following Exit codes:

• 0: no changes needed
• 1: changes would be made
• 2: error

To apply the detected changes, run without --check:

typewriter run path/to/example.py

Additional features:

To run recursively on all *.py files in a directory:

typewriter run examples # Non-`.py` files are rejected.

To transform an in-memory string and return the result to stdout, use --code:

typewriter run --code "var: int = None\\n"

PEP 604 mode

To emit T | None style unions instead of Optional[T], pass --target-version 3.10 (or any Python 3.10+ version):

typewriter run path/to/example.py --target-version 3.10

In this mode, existing Optional[...] and Union[...] annotations are normalized to PEP 604 syntax too. The default output remains Python 3.9-compatible (Optional[T]).

Skip configuration

To skip additional files or directories by glob pattern, use --ignore (repeatable):

typewriter run myproject --ignore "test_*" --ignore "generated"

Patterns are matched against both the bare file/directory name and the relative path from the scanned root. The built-in skip set (.git, .venv, __pycache__, build, dist, etc.) is always active regardless of extra patterns.

To also honor the nearest .gitignore at or above the scanned directory:

typewriter run myproject --respect-gitignore

Additional Details:

• PATH and --code are mutually exclusive.
• Literal \\n sequences in --code input are interpreted as newlines.
• When a directory is provided as PATH, Typewriter will ignore non-.py files and common non-source subdirectories such as .git, .venv, venv, __pycache__, build, and dist.
• PEP 604 syntax (T | None) is opt-in via --target-version 3.10 and is not used by default.

Versioning

The package version is the single source of truth. The documentation version in docs/source/conf.py is derived automatically from typewriter.__version__, which reads the distribution metadata for py-typewriter-cli.

Motivation

Typewriter was created to resolve issue #2303 in microsoft/playwright-python.

The issue highlighted a common inconsistency in the codebase where type annotations involving None were not standardized, leading to confusion and maintenance challenges. Specifically, some type annotations used Union[T, None] while others used Optional[T], and there were cases where variable and parameter annotations did not use Optional even when the default value was None. This made it difficult to maintain a consistent style and to leverage static analysis tools effectively.

Surely, other developers have encountered similar inconsistencies in their codebases, and Typewriter can be a useful tool for anyone looking to standardize a common inconsistency and correct a common issue related to the use of None in type annotations. By using Typewriter, developers can ensure that their codebase adheres to PEP 484 proposal of requiring optional types to be made explicit.

Contributing

Contributions to Typewriter are welcome! Please follow the fork-and-pull request workflow:

1. Fork the repository and create a new branch for your feature or bug fix.
2. Make your changes and commit them with clear messages.
3. Push your branch to your fork and open a pull request against the main branch of the original repository.