Skip to main content

Type annotations for Pandas

Project description

Logo

Pandas Stubs

Collection of pandas stub files initially generated using stubgen, fixed when necessary and then partially completed.

CI PyPi version PyPI Downloads Conda Downloads Python support License
VirtusLab PyPI package PyPI download month PyPI download month PyPI pyversions GitHub license

Motivation

Provide rudimentary coverage of pandas code by static type checking, to alleviate problems mentioned in the following issues 14468, 26766. This approach was taken to achieve accelerated development - compared to refactoring existing Pandas codebase creating stub files is relatively uninhibited.

Due to extensive pandas API, quality of the proposed annotations is, for the most part, not suitable for integration into original codebase, but they can be very useful as a way of achieving some type safety during development.

Installation

The easiest way is using PyPI. This will add .pyi files to pandas package location, which will be removed when uninstalling:

pip install pandas-stubs

Another way to install is using Conda:

conda install -c conda-forge pandas-stubs 

Alternatively, if you want a cleaner PYTHONPATH or wish to modify the annotations, manual options are:

  • cloning the repository along with the files, or
  • including it as a submodule to your project repository,

and then configuring a type checker with the correct paths.

Usage

Let’s take this example piece of code in file round.py

import pandas as pd

decimals = pd.DataFrame({'TSLA': 2, 'AMZN': 1})
prices = pd.DataFrame(data={'date': ['2021-08-13', '2021-08-07', '2021-08-21'],
                            'TSLA': [720.13, 716.22, 731.22], 'AMZN': [3316.50, 3200.50, 3100.23]})
rounded_prices = prices.round(decimals=decimals)

Mypy won't see any issues with that, but after installing pandas-stubs and running it again:

mypy round.py

we get the following error message:

round.py:6: error: Argument "decimals" to "round" of "DataFrame" has incompatible type "DataFrame"; expected "Union[int, Dict[Union[int, str], int], Series]"

And after confirming with the docs we can fix the code:

decimals = pd.Series({'TSLA': 2, 'AMZN': 1})

Version Compatibility

The aim of the current release is to cover the most common parts of the 1.2.0 API, however it can provide partial functionality for other version as well. Future versions will cover new Pandas releases.

Versioning

The versions follow a pattern MAJOR.MINOR.PATCH.STUB_VERSION where the first three parts correspond to a specific pandas API version, while STUB_VERSION is used to distinguish between the versions of the stubs themselves.

Type checkers

As of now mypy is the only type checker the stubs were tested with.

Development

Testing using tox

Tox will automatically run all types of tests mentioned further. It will create isolated temporary environments for each declared version of Python and install pandas-stubs like it would normally be installed when using pip or conda.

Usage is as simple as:

tox

Last few lines of the output should look like this (assuming all Python versions are available):

  pep8: commands succeeded
  py36: commands succeeded
  py37: commands succeeded
  py38: commands succeeded
  py39: commands succeeded

Partial testing

Test the stub files internal consistency:

mypy --config-file mypy.ini third_party/3/pandas

Test the stub files against actual code examples (this will use the stubs from the third_party/3/pandas dir):

mypy --config-file mypy.ini tests/snippets

Test the installed stub files against actual code examples. You'll need to install the library beforehand - the .pyi files from your env will be used:

mypy --config-file mypy_env.ini tests/snippets

Test if the code examples work, when actually ran with pandas:

pytests tests/snippets

Disclaimer

This project provides additional functionality for pandas library. Pandas is available under it's own license.

This project is not owned, endorsed, or sponsored by any of AQR Capital Management, NumFOCUS, LLC, Lambda Foundry, Inc. and PyData Development Team.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pandas-stubs-1.2.0.24.tar.gz (92.7 kB view details)

Uploaded Source

Built Distribution

pandas_stubs-1.2.0.24-py3-none-any.whl (159.1 kB view details)

Uploaded Python 3

File details

Details for the file pandas-stubs-1.2.0.24.tar.gz.

File metadata

  • Download URL: pandas-stubs-1.2.0.24.tar.gz
  • Upload date:
  • Size: 92.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.22.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.10

File hashes

Hashes for pandas-stubs-1.2.0.24.tar.gz
Algorithm Hash digest
SHA256 a756c5cf2100c176478d31563ac54f7f6e3d9f33926d6ffa420e4d5aa4f3c2e4
MD5 3e245d5556082fda32174c7679d48ae5
BLAKE2b-256 a02acc4fbcae3f4ea034bb034963daf4d4f6482eed81a3edadfc1401a8578261

See more details on using hashes here.

Provenance

File details

Details for the file pandas_stubs-1.2.0.24-py3-none-any.whl.

File metadata

  • Download URL: pandas_stubs-1.2.0.24-py3-none-any.whl
  • Upload date:
  • Size: 159.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.22.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.10

File hashes

Hashes for pandas_stubs-1.2.0.24-py3-none-any.whl
Algorithm Hash digest
SHA256 e35cda46b4ca044c984dd40169bc3387c81da4c28e96183ffd238f0e343b87b2
MD5 0784fa39cceba9c092102bc27efeeafc
BLAKE2b-256 f9abebae3f43147ced1220fe012a0e9d898485cb435625e64dd3f1f057a82448

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page