pandas-stubs

Warnings

• breaking The current 3.0.x releases of pandas-stubs may not fully support all new features introduced in pandas 3.0. This can lead to unexpected type errors or missing type information for newer APIs.
  Fix: Consult the official pandas-stubs GitHub issue tracker (specifically issue #1654 and #1641) for ongoing compatibility updates and known limitations when working with pandas 3.0 and newer.
• gotcha pandas-stubs provides a 'narrower' set of type annotations compared to what pandas itself might allow, prioritizing recommended best practices and soundness over complete API coverage. This means some valid pandas code, especially less common patterns, might still raise type errors.
  Fix: When encountering unexpected type errors, first review the pandas documentation for the recommended usage. If the code is intentionally flexible, consider adding `type: ignore` comments for specific lines or sections, or consult the pandas-stubs philosophy documentation.
• gotcha The typing goals for `pandas` itself (internal consistency) and `pandas-stubs` (public API usage) differ. This can occasionally lead to inconsistencies or divergences in type definitions between the two projects. While a long-term goal is to merge them, they remain separate for now.
  Fix: For type checking your application code, prioritize the types provided by `pandas-stubs`. If encountering discrepancies, refer to the `pandas-stubs` repository for public API typing.
• gotcha Changes in pandas API or updates to pandas-stubs (e.g., how methods like `itertuples()` are typed) can introduce new type checker errors in existing code that previously passed without issue.
  Fix: After updating `pandas` or `pandas-stubs`, run your type checker and review any new errors. Adjust your code to align with the updated type signatures or, if necessary, use type ignores (`# type: ignore`) for known legitimate patterns that the stubs might not yet fully cover.

Install

• pip install pandas-stubs PyPI

Imports

• pandas

  import pandas as pd

  pandas-stubs is a stub-only package (PEP 561). Its `.pyi` files are automatically discovered and used by type checkers like MyPy when `pandas` is imported; direct imports from `pandas_stubs` are not intended for runtime use.

Quickstart

To use `pandas-stubs`, first install `pandas`, `pandas-stubs`, and a type checker like `mypy`. Then, write your pandas code as usual. Run `mypy your_script.py` to check for type errors. The example demonstrates a common DataFrame operation and comments out an incorrect usage of `DataFrame.round()` that `pandas-stubs` would catch, along with its correct version.

import pandas as pd

def analyze_data(df: pd.DataFrame) -> pd.Series:
    # This operation is correctly typed
    total_sales = df['sales'].sum()
    print(f"Total sales: {total_sales}")
    
    # Example that would cause a type error with pandas-stubs
    # pandas.DataFrame.round expects a Series or int for 'decimals', not another DataFrame.
    # This line is commented out to allow the script to run without runtime error, 
    # but a type checker would flag it.
    # decimals_df = pd.DataFrame({'price': 2})
    # df_rounded = df.round(decimals=decimals_df)

    # Correct usage for .round() method
    decimals_series = pd.Series({'price': 2, 'quantity': 0})
    df['price'] = df['price'].round(decimals=decimals_series.get('price', 0))
    return df['price']

if __name__ == "__main__":
    data = {'item': ['A', 'B', 'C'], 'sales': [100.5, 150.2, 200.0], 'price': [10.234, 5.678, 12.345], 'quantity': [10, 20, 15]}
    sales_df = pd.DataFrame(data)
    processed_prices = analyze_data(sales_df)
    print(processed_prices)