{"id":2677,"library":"pyarrow-stubs","title":"pyarrow-stubs","description":"pyarrow-stubs provides type annotations for the Apache Arrow Python library (PyArrow). Its purpose is to enable static type checking tools like MyPy and Pyright to analyze code that uses PyArrow, improving code quality and catching potential errors at development time. The current version is 20.0.0.20251215, with releases typically aligning with PyArrow's development, and ongoing discussions about potentially integrating stubs directly into the main Apache Arrow project.","status":"active","version":"20.0.0.20251215","language":"en","source_language":"en","source_url":"https://github.com/zen-xu/pyarrow-stubs","tags":["type-stubs","pyarrow","apache-arrow","type-checking","mypy","pyright"],"install":[{"cmd":"pip install pyarrow-stubs","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Provides the runtime library for which these stubs offer type annotations.","package":"pyarrow","optional":false}],"imports":[{"note":"Type annotations are automatically picked up by type checkers when 'pyarrow' is imported. You do not import directly from 'pyarrow-stubs'.","symbol":"Table","correct":"import pyarrow as pa\n# Usage: pa.Table"},{"note":"Type annotations are automatically picked up by type checkers when 'pyarrow' is imported. You do not import directly from 'pyarrow-stubs'.","symbol":"Array","correct":"import pyarrow as pa\n# Usage: pa.Array"}],"quickstart":{"code":"import pyarrow as pa\nfrom typing import List\n\ndef create_arrow_table(names: List[str], ages: List[int]) -> pa.Table:\n    \"\"\"Creates a PyArrow Table from names and ages.\"\"\"\n    if not (len(names) == len(ages)):\n        raise ValueError(\"Lengths of names and ages must match.\")\n    \n    # Create PyArrow Arrays\n    name_array = pa.array(names, type=pa.string())\n    age_array = pa.array(ages, type=pa.int64())\n    \n    # Create a PyArrow Table\n    table = pa.table({'name': name_array, 'age': age_array})\n    return table\n\nif __name__ == \"__main__\":\n    my_names = [\"Alice\", \"Bob\", \"Charlie\"]\n    my_ages = [30, 24, 35]\n    \n    # This call would be type-checked by tools like MyPy/Pyright\n    person_table: pa.Table = create_arrow_table(my_names, my_ages)\n    \n    print(\"Created PyArrow Table:\")\n    print(person_table)\n\n    print(f\"\\nFirst person's name: {person_table.column('name')[0].as_py()}\")","lang":"python","description":"This example demonstrates creating a PyArrow Table with explicit type hints. When `pyarrow-stubs` is installed, a type checker like MyPy or Pyright will use these stubs to validate the types in your code, for example, ensuring that `create_arrow_table` returns a `pa.Table`."},"warnings":[{"fix":"Install `pyarrow-stubs` in the same environment as `pyarrow` using `pip install pyarrow-stubs`.","message":"Type checkers like MyPy and Pyright will report 'Stub file not found for \"pyarrow\"' or 'Skipping analyzing \"pyarrow\": module is installed, but missing library stubs or py.typed marker' if `pyarrow-stubs` is not installed alongside `pyarrow`. Ensure `pyarrow-stubs` is present in your environment for proper static analysis.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For type errors, consider using `typing.cast` or `typing.Any` as a temporary workaround. Consult the `pyarrow` and `pyarrow-stubs` GitHub issues and discussions for the latest updates on type completeness.","message":"Due to PyArrow's underlying C++/Cython implementation and dynamic nature, some parts of its API may have incomplete or less precise type hints within `pyarrow-stubs`. You might encounter situations where explicit type casting (`typing.cast`) or `typing.Any` is necessary, especially for complex or dynamically generated types. The PyArrow community is actively working on improving type coverage, including discussions about integrating stubs directly into the main project.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate your code to use `pyarrow.ExtensionType` instead of `pyarrow.PyExtensionType`. Refer to the `pyarrow` documentation and security advisories for detailed migration steps.","message":"A security vulnerability (CVE-2023-47248) in `pyarrow` related to `pyarrow.PyExtensionType` led to the `pyarrow-hotfix` package. If your code uses `pyarrow.PyExtensionType` (e.g., for custom extension types in Parquet files) and `pyarrow-hotfix` is active, your workloads might fail. The recommended fix is to migrate to `pyarrow.ExtensionType`.","severity":"breaking","affected_versions":"pyarrow < 14.0.1 (addressed by pyarrow-hotfix)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}