Typing Stubs for nanoid

2.0.0.20260408 · active · verified Thu Apr 16

types-nanoid is a PEP 561 type stub package that provides static type annotations for the `nanoid` library. It allows type checkers such as MyPy, Pyright, and PyCharm to perform static analysis and type inference on code that uses `nanoid`, ensuring type safety without impacting runtime behavior. This version aims to provide accurate annotations for `nanoid==2.0.0`. It is actively maintained as part of the `typeshed` project, with updates typically correlating to upstream `nanoid` releases or general typeshed improvements.

Common errors

```
Module 'nanoid' has no 'generate' member (no-member)
```
cause The type checker cannot find the `nanoid` runtime library or its associated stubs (`types-nanoid`), or there's a version mismatch.

fix Ensure both `nanoid` and `types-nanoid` are installed in your environment (`pip install nanoid types-nanoid`) and your type checker (e.g., MyPy) is correctly configured to find them. Verify version compatibility between `nanoid` and `types-nanoid`.
```
ModuleNotFoundError: No module named 'nanoid'
```
cause The `nanoid` runtime library is not installed. `types-nanoid` only provides type hints and does not include the actual runnable code.

fix Install the `nanoid` runtime library: `pip install nanoid`.
```
Incompatible types in assignment (expression has type "str", variable has type "None") (Mypy error code: assignment)
```
cause This usually indicates a type checker issue where the return type of `nanoid.generate` (or related functions) is being misinterpreted, often due to an outdated `types-nanoid` stub for a newer `nanoid` version, or vice-versa.

fix Verify that `nanoid` and `types-nanoid` versions are compatible. Upgrade both to their latest compatible versions. If the issue persists, explicitly cast the type or use type ignore comments as a temporary workaround while reporting the issue to the `typeshed` project.

Warnings

breaking Type stub versions should ideally align with the major version of the runtime library they type. A mismatch between `types-nanoid` and the installed `nanoid` version can lead to incorrect type-checking results or errors.
Fix: Ensure `nanoid` and `types-nanoid` are installed with compatible versions. For example, if `types-nanoid` is for `nanoid==2.0.0`, install both as `pip install "nanoid==2.0.0" "types-nanoid==2.0.0.*"`. Consult the `typeshed` repository for specific version compatibility notes.
gotcha There can be confusion with the JavaScript `@types/nanoid` package, which is deprecated because the JS `nanoid` library now includes its own types. In Python, however, `types-nanoid` is still necessary for type checking as the `nanoid` Python package does not typically bundle `py.typed` files for static analysis.
Fix: For Python projects, always install `types-nanoid` explicitly for type checking alongside the `nanoid` runtime library.
gotcha The `nanoid` library offers `non_secure_generate` which uses `random.random` internally. This function is explicitly "not recommended for generating tokens or secrets" due to its weaker cryptographic strength compared to `generate()`. Using it in security-sensitive contexts is a footgun.
Fix: For any security-critical ID generation (e.g., session tokens, API keys), always use `nanoid.generate()`. Reserve `nanoid.non_secure_generate()` only for cases where performance is prioritized over cryptographic strength and security is not a concern (e.g., temporary internal identifiers).

Install

pip install types-nanoid Install only type stubs
pip install nanoid types-nanoid Install runtime and type stubs

Imports

generate
```
from nanoid import generate
```
non_secure_generate
```
from nanoid import non_secure_generate
```

Quickstart

This quickstart demonstrates how to install both the `nanoid` library and its corresponding type stubs, `types-nanoid`. It then shows how to use `nanoid.generate` for secure IDs and `nanoid.non_secure_generate` for performance-critical, non-security-sensitive cases, all while leveraging the type hints provided by `types-nanoid` for static analysis.

import os
from nanoid import generate, non_secure_generate

def create_ids() -> None:
    # Generate a cryptographically strong, URL-friendly unique ID
    secure_id: str = generate()
    print(f"Secure ID: {secure_id}")

    # Generate a non-secure ID (for non-security-critical applications)
    non_secure_id: str = non_secure_generate(size=10)
    print(f"Non-Secure ID (10 chars): {non_secure_id}")

    # Generate with a custom alphabet and size
    custom_alphabet_id: str = generate('1234567890abcdef', 8)
    print(f"Custom Alphabet ID: {custom_alphabet_id}")


if __name__ == "__main__":
    create_ids()

view raw JSON →