Typing Stubs for polib

1.2.0.20260408 · active · verified Thu Apr 16

types-polib is a PEP 561-compliant type stub package that provides static type annotations for the polib library. polib is a pure Python library designed to manipulate, create, and modify gettext files (.pot, .po, and .mo files) used for internationalization and localization. This types-polib package, part of the larger typeshed project, enables static type checkers like MyPy, Pyright, or PyCharm to verify type correctness in code that uses polib, without altering runtime behavior. The package version 1.2.0.20260408 aims to provide accurate annotations for polib versions 1.2.*. Releases are frequent, reflecting updates from the typeshed project.

Common errors

```
ModuleNotFoundError: No module named 'polib'
```
cause The `polib` runtime library is not installed, only its type stubs (`types-polib`) are present.

fix Install the actual `polib` library: `pip install polib`.
```
error: Cannot find implementation or library stub for module 'polib' (mypy)
```
cause MyPy cannot locate the runtime `polib` package or its corresponding type stubs. This could happen if `polib` is installed but `types-polib` is not, or if your Python environment/MyPy configuration is not correctly set up.

fix Ensure both `polib` and `types-polib` are installed in the active environment. Verify your MyPy configuration (e.g., `mypy.ini` or `pyproject.toml`) and ensure your `PYTHONPATH` or MyPy's environment can find your installed packages.
```
error: Library "polib" has no attribute "POFile" [attr-def] (mypy or other type checker)
```
cause The `polib` library version installed is significantly different from what `types-polib` expects, or the specific attribute/class was removed/renamed in the `polib` version you are using. This typically indicates a version mismatch or an outdated stub.

fix Check the version of your installed `polib` (`pip show polib`). Confirm that `types-polib` supports this version (typically indicated by the first three parts of `types-polib`'s version number). If necessary, upgrade or downgrade `polib` to match the stub's target version (e.g., `pip install 'polib<1.3,>=1.2'`).

Warnings

gotcha This package provides *only* type stubs. It does not contain any runtime code for `polib` itself. You must install the `polib` library separately for your code to run.
Fix: Ensure both `polib` and `types-polib` are installed: `pip install polib types-polib`.
breaking Type stubs are version-specific. The `types-polib` version `1.2.0.20260408` is designed to provide accurate annotations for `polib==1.2.*`. Using `types-polib` with significantly different versions of `polib` (e.g., `polib` 0.x or `polib` 2.x if it ever exists) may lead to incorrect type-checking results or errors.
Fix: Align the `types-polib` version with your installed `polib` version. The `types-polib` version's first three parts typically match the `polib` version it stubs (e.g., `types-polib==1.2.0.*` for `polib==1.2.*`).
gotcha Type stubs are consumed by static type checkers (e.g., MyPy, Pyright, PyCharm) at design time. Installing `types-polib` alone will not provide type checking if you are not running a type checker or your IDE is not configured to use them.
Fix: Integrate a static type checker (e.g., MyPy) into your development workflow. Run `mypy your_module.py` or configure your IDE (e.g., VS Code with Pylance/Pyright) to enable type checking.

Install

pip install polib types-polib Install polib and its stubs

Imports

POFile
```
from polib import POFile
```
POEntry
```
from polib import POEntry
```
pofile
```
import polib; po = polib.pofile(...)
```

Quickstart

This quickstart demonstrates basic usage of the `polib` library to create and manipulate .po files. When `types-polib` is installed alongside `polib`, static type checkers (like MyPy, Pyright, or PyCharm) will automatically use the provided type hints to analyze this code for type consistency and potential errors, without requiring any changes to the import statements.

import polib

# Create a new PO file
pofile = polib.POFile()
pofile.metadata = {
    'Project-Id-Version': 'My Project 1.0',
    'Report-Msgid-Bugs-To': 'you@example.com',
    'POT-Creation-Date': '2023-01-01 00:00+0000',
    'PO-Revision-Date': '2023-01-01 00:00+0000',
    'Last-Translator': 'Your Name <you@example.com>',
    'Language-Team': 'English <en@example.com>',
    'MIME-Version': '1.0',
    'Content-Type': 'text/plain; charset=utf-8',
    'Content-Transfer-Encoding': '8bit',
}

# Add an entry
entry = polib.POEntry(
    msgid='Hello world!',
    msgstr='Hola mundo!',
    occurrences=[('main.py', '10')],
    comment='A greeting message'
)
pofile.append(entry)

# Add another entry with plural forms
entry_plural = polib.POEntry(
    msgid='{} item',
    msgid_plural='{} items',
    msgstr_plural={0: '{} artículo', 1: '{} artículos'},
    occurrences=[('items.py', '25')],
    comment='Number of items'
)
pofile.append(entry_plural)

# Save the PO file
# For a real application, replace '/tmp/output.po' with a proper path.
# Ensure the directory exists or handle FileNotFoundError.
try:
    # Using a temporary file for demonstration purposes
    import tempfile
    with tempfile.NamedTemporaryFile(suffix='.po', mode='w', delete=False, encoding='utf-8') as f:
        temp_po_path = f.name
    pofile.save(temp_po_path)
    print(f"PO file saved to: {temp_po_path}")
    # Optionally compile to MO
    temp_mo_path = temp_po_path.replace('.po', '.mo')
    pofile.save_as_mofile(temp_mo_path)
    print(f"MO file compiled to: {temp_mo_path}")
finally:
    # Cleanup temporary files (optional, for real use you'd keep them)
    import os
    if 'temp_po_path' in locals() and os.path.exists(temp_po_path):
        os.remove(temp_po_path)
    if 'temp_mo_path' in locals() and os.path.exists(temp_mo_path):
        os.remove(temp_mo_path)

# Type checkers will use 'types-polib' to ensure correct usage of polib objects.
# For example, they will verify that 'append' takes a POEntry and 'msgid' is a string.

view raw JSON →