{"id":7826,"library":"types-polib","title":"Typing Stubs for polib","description":"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.","status":"active","version":"1.2.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-hints","gettext","i18n","localization"],"install":[{"cmd":"pip install polib types-polib","lang":"bash","label":"Install polib and its stubs"}],"dependencies":[{"reason":"Runtime library for which these stubs provide type hints.","package":"polib","optional":false}],"imports":[{"symbol":"POFile","correct":"from polib import POFile"},{"symbol":"POEntry","correct":"from polib import POEntry"},{"symbol":"pofile","correct":"import polib; po = polib.pofile(...)"}],"quickstart":{"code":"import polib\n\n# Create a new PO file\npofile = polib.POFile()\npofile.metadata = {\n    'Project-Id-Version': 'My Project 1.0',\n    'Report-Msgid-Bugs-To': 'you@example.com',\n    'POT-Creation-Date': '2023-01-01 00:00+0000',\n    'PO-Revision-Date': '2023-01-01 00:00+0000',\n    'Last-Translator': 'Your Name <you@example.com>',\n    'Language-Team': 'English <en@example.com>',\n    'MIME-Version': '1.0',\n    'Content-Type': 'text/plain; charset=utf-8',\n    'Content-Transfer-Encoding': '8bit',\n}\n\n# Add an entry\nentry = polib.POEntry(\n    msgid='Hello world!',\n    msgstr='Hola mundo!',\n    occurrences=[('main.py', '10')],\n    comment='A greeting message'\n)\npofile.append(entry)\n\n# Add another entry with plural forms\nentry_plural = polib.POEntry(\n    msgid='{} item',\n    msgid_plural='{} items',\n    msgstr_plural={0: '{} artículo', 1: '{} artículos'},\n    occurrences=[('items.py', '25')],\n    comment='Number of items'\n)\npofile.append(entry_plural)\n\n# Save the PO file\n# For a real application, replace '/tmp/output.po' with a proper path.\n# Ensure the directory exists or handle FileNotFoundError.\ntry:\n    # Using a temporary file for demonstration purposes\n    import tempfile\n    with tempfile.NamedTemporaryFile(suffix='.po', mode='w', delete=False, encoding='utf-8') as f:\n        temp_po_path = f.name\n    pofile.save(temp_po_path)\n    print(f\"PO file saved to: {temp_po_path}\")\n    # Optionally compile to MO\n    temp_mo_path = temp_po_path.replace('.po', '.mo')\n    pofile.save_as_mofile(temp_mo_path)\n    print(f\"MO file compiled to: {temp_mo_path}\")\nfinally:\n    # Cleanup temporary files (optional, for real use you'd keep them)\n    import os\n    if 'temp_po_path' in locals() and os.path.exists(temp_po_path):\n        os.remove(temp_po_path)\n    if 'temp_mo_path' in locals() and os.path.exists(temp_mo_path):\n        os.remove(temp_mo_path)\n\n# Type checkers will use 'types-polib' to ensure correct usage of polib objects.\n# For example, they will verify that 'append' takes a POEntry and 'msgid' is a string.\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure both `polib` and `types-polib` are installed: `pip install polib types-polib`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.*`).","message":"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.","severity":"breaking","affected_versions":"All versions where `types-polib` and `polib` major/minor versions mismatch."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the actual `polib` library: `pip install polib`.","cause":"The `polib` runtime library is not installed, only its type stubs (`types-polib`) are present.","error":"ModuleNotFoundError: No module named 'polib'"},{"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.","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.","error":"error: Cannot find implementation or library stub for module 'polib' (mypy)"},{"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'`).","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.","error":"error: Library \"polib\" has no attribute \"POFile\" [attr-def] (mypy or other type checker)"}]}