pre-commit install

pre-commit run --files <files you have modified>
pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files

pre-commit run --hook-stage manual --all-files

You may want to periodically run ``pre-commit gc``, to clean up repos
which are no longer used.

If you have conflicting installations of ``virtualenv``, then you may get an
error - see `here <https://github.com/pypa/virtualenv/issues/1875>`_.

Also, due to a `bug in virtualenv <https://github.com/pypa/virtualenv/issues/1986>`_,
you may run into issues if you're using conda. To solve this, you can downgrade
``virtualenv`` to version ``20.0.33``.

If you have recently merged in main from the upstream branch, some of the
dependencies used by ``pre-commit`` may have changed.  Make sure to
:ref:`update your development environment <contributing.update-dev>`.

from pandas.util._decorators import deprecate

deprecate('old_func', 'new_func', '1.1.0')

import warnings
from pandas.util._exceptions import find_stack_level


def old_func():
    """Summary of the function.

    .. deprecated:: 1.1.0
       Use new_func instead.
    """
    warnings.warn(
        'Use new_func instead.',
        FutureWarning,
        stacklevel=find_stack_level(),
    )
    new_func()


def new_func():
    pass

Type imports should follow the ``from typing import ...`` convention.
Your code may be automatically re-written to use some modern constructs (e.g. using the built-in ``list`` instead of ``typing.List``)
by the :ref:`pre-commit checks <contributing.pre-commit>`.

In some cases in the code base classes may define class variables that shadow builtins. This causes an issue as described in `Mypy 1775 <https://github.com/python/mypy/issues/1775#issuecomment-310969854>`_. The defensive solution here is to create an unambiguous alias of the builtin and use that without your annotation. For example, if you come across a definition like

.. code-block:: python

   class SomeClass1:
       str = None

The appropriate way to annotate this would be as follows

.. code-block:: python

   str_type = str

   class SomeClass2:
       str: str_type = None

In some cases you may be tempted to use ``cast`` from the typing module when you know better than the analyzer. This occurs particularly when using custom inference functions. For example

.. code-block:: python

   from typing import cast

   from pandas.core.dtypes.common import is_number

   def cannot_infer_bad(obj: Union[str, int, float]):

       if is_number(obj):
           ...
       else:  # Reasonably only str objects would reach this but...
           obj = cast(str, obj)  # Mypy complains without this!
           return obj.upper()

The limitation here is that while a human can reasonably understand that ``is_number`` would catch the ``int`` and ``float`` types mypy cannot make that same inference just yet (see `mypy #5206 <https://github.com/python/mypy/issues/5206>`_). While the above works, the use of ``cast`` is **strongly discouraged**. Where applicable a refactor of the code to appease static analysis is preferable

.. code-block:: python

   def cannot_infer_good(obj: Union[str, int, float]):

       if isinstance(obj, str):
           return obj.upper()
       else:
           ...

With custom types and inference this is not always possible so exceptions are made, but every effort should be exhausted to avoid ``cast`` before going down such paths.

pandas-specific types

pandas uses `mypy <http://mypy-lang.org>`_ and `pyright <https://github.com/microsoft/pyright>`_ to statically analyze the code base and type hints. After making any change you can ensure your type hints are consistent by running

.. code-block:: shell

    pre-commit run --hook-stage manual --all-files mypy
    pre-commit run --hook-stage manual --all-files pyright
    pre-commit run --hook-stage manual --all-files pyright_reportGeneralTypeIssues
    # the following might fail if the installed pandas version does not correspond to your local git version
    pre-commit run --hook-stage manual --all-files stubtest

in your python environment.

.. warning::

    * Please be aware that the above commands will use the current python environment. If your python packages are older/newer than those installed by the pandas CI, the above commands might fail. This is often the case when the ``mypy`` or ``numpy`` versions do not match. Please see :ref:`how to setup the python environment <contributing.conda>` or select a `recently succeeded workflow <https://github.com/pandas-dev/pandas/actions/workflows/code-checks.yml?query=branch%3Amain+is%3Asuccess>`_, select the "Docstring validation, typing, and other manual pre-commit hooks" job, then click on "Set up Conda" and "Environment info" to see which versions the pandas CI installs.

.. _contributing.ci:

Testing type hints in code using pandas

* pandas is not yet a py.typed library (:pep:`561`)!
  The primary purpose of locally declaring pandas as a py.typed library is to test and
  improve the pandas-builtin type annotations.

All tests should go into the ``tests`` subdirectory of the specific package.
This folder contains many current examples of tests, and we suggest looking to these for
inspiration.

As a general tip, you can use the search functionality in your integrated development
environment (IDE) or the git grep command in a terminal to find test files in which the method
is called. If you are unsure of the best location to put your test, take your best guess,
but note that reviewers may request that you move the test to a different location.

To use git grep, you can run the following command in a terminal:

``git grep "function_name("``

This will search through all files in your repository for the text ``function_name(``.
This can be a useful way to quickly locate the function in the
codebase and determine the best location to add a test for it.

Ideally, there should be one, and only one, obvious place for a test to reside.
Until we reach that ideal, these are some rules of thumb for where a test should
be located.

1. Does your test depend only on code in ``pd._libs.tslibs``?
   This test likely belongs in one of:

   - tests.tslibs

     .. note::

          No file in ``tests.tslibs`` should import from any pandas modules
          outside of ``pd._libs.tslibs``

   - tests.scalar
   - tests.tseries.offsets

2. Does your test depend only on code in ``pd._libs``?
   This test likely belongs in one of:

   - tests.libs
   - tests.groupby.test_libgroupby

3. Is your test for an arithmetic or comparison method?
   This test likely belongs in one of:

   - tests.arithmetic

     .. note::

         These are intended for tests that can be shared to test the behavior
         of DataFrame/Series/Index/ExtensionArray using the ``box_with_array``
         fixture.

   - tests.frame.test_arithmetic
   - tests.series.test_arithmetic

4. Is your test for a reduction method (min, max, sum, prod, ...)?
   This test likely belongs in one of:

   - tests.reductions

     .. note::

         These are intended for tests that can be shared to test the behavior
         of DataFrame/Series/Index/ExtensionArray.

   - tests.frame.test_reductions
   - tests.series.test_reductions
   - tests.test_nanops

5. Is your test for an indexing method?
   This is the most difficult case for deciding where a test belongs, because
   there are many of these tests, and many of them test more than one method
   (e.g. both ``Series.__getitem__`` and ``Series.loc.__getitem__``)

   A) Is the test specifically testing an Index method (e.g. ``Index.get_loc``,
      ``Index.get_indexer``)?
      This test likely belongs in one of:

      - tests.indexes.test_indexing
      - tests.indexes.fooindex.test_indexing

      Within that files there should be a method-specific test class e.g.
      ``TestGetLoc``.

      In most cases, neither ``Series`` nor ``DataFrame`` objects should be
      needed in these tests.

   B) Is the test for a Series or DataFrame indexing method *other* than
      ``__getitem__`` or ``__setitem__``, e.g. ``xs``, ``where``, ``take``,
      ``mask``, ``lookup``, or ``insert``?
      This test likely belongs in one of:

      - tests.frame.indexing.test_methodname
      - tests.series.indexing.test_methodname

   C) Is the test for any of ``loc``, ``iloc``, ``at``, or ``iat``?
      This test likely belongs in one of:

      - tests.indexing.test_loc
      - tests.indexing.test_iloc
      - tests.indexing.test_at
      - tests.indexing.test_iat

      Within the appropriate file, test classes correspond to either types of
      indexers (e.g. ``TestLocBooleanMask``) or major use cases
      (e.g. ``TestLocSetitemWithExpansion``).

      See the note in section D) about tests that test multiple indexing methods.

   D) Is the test for ``Series.__getitem__``, ``Series.__setitem__``,
      ``DataFrame.__getitem__``, or ``DataFrame.__setitem__``?
      This test likely belongs in one of:

      - tests.series.test_getitem
      - tests.series.test_setitem
      - tests.frame.test_getitem
      - tests.frame.test_setitem

      If many cases such a test may test multiple similar methods, e.g.

      .. code-block:: python

           import pandas as pd
           import pandas._testing as tm

           def test_getitem_listlike_of_ints():
               ser = pd.Series(range(5))

               result = ser[[3, 4]]
               expected = pd.Series([2, 3])
               tm.assert_series_equal(result, expected)

               result = ser.loc[[3, 4]]
               tm.assert_series_equal(result, expected)

      In cases like this, the test location should be based on the *underlying*
      method being tested.  Or in the case of a test for a bugfix, the location
      of the actual bug.  So in this example, we know that ``Series.__getitem__``
      calls ``Series.loc.__getitem__``, so this is *really* a test for
      ``loc.__getitem__``.  So this test belongs in ``tests.indexing.test_loc``.

6. Is your test for a DataFrame or Series method?

   A) Is the method a plotting method?
      This test likely belongs in one of:

      - tests.plotting

   B) Is the method an IO method?
      This test likely belongs in one of:

      - tests.io

        .. note::

            This includes ``to_string`` but excludes ``__repr__``, which is
            tested in ``tests.frame.test_repr`` and ``tests.series.test_repr``.
            Other classes often have a ``test_formats`` file.

   C) Otherwise
      This test likely belongs in one of:

      - tests.series.methods.test_mymethod
      - tests.frame.methods.test_mymethod

        .. note::

            If a test can be shared between DataFrame/Series using the
            ``frame_or_series`` fixture, by convention it goes in the
            ``tests.frame`` file.

7. Is your test for an Index method, not depending on Series/DataFrame?
   This test likely belongs in one of:

   - tests.indexes

8) Is your test for one of the pandas-provided ExtensionArrays (``Categorical``,
   ``DatetimeArray``, ``TimedeltaArray``, ``PeriodArray``, ``IntervalArray``,
   ``NumpyExtensionArray``, ``FloatArray``, ``BoolArray``, ``StringArray``)?
   This test likely belongs in one of:

   - tests.arrays

9) Is your test for *all* ExtensionArray subclasses (the "EA Interface")?
   This test likely belongs in one of:

   - tests.extension

Using ``pytest``

def test_really_cool_feature():
    pass

Do not use ``pytest.xfail`` (which is different than ``pytest.mark.xfail``) since it immediately stops the
test and does not check if the test will fail. If this is the behavior you desire, use ``pytest.skip`` instead.

def test_xfail(request):
    mark = pytest.mark.xfail(raises=TypeError, reason="Indicate why here")
    request.applymarker(mark)

with tm.assert_produces_warning(DeprecationWarning, match="the warning message"):
    pd.deprecated_function()

with tm.assert_produces_warning(False):
    pd.no_warning_function()

@pytest.mark.filterwarnings("ignore:msg:category")
def test_thing(self):
    pass

with pytest.raises(ValueError, match="an error"):
    raise ValueError("an error")

def test_something(temp_file):
    pd.DataFrame([1]).to_csv(str(temp_file))

@pytest.mark.network
@pytest.mark.single_cpu
def test_network(httpserver):
    httpserver.serve_content(content="content")
    result = pd.read_html(httpserver.url)

   expected = pd.Series([1, 2, 3], dtype=dtype)
   tm.assert_series_equal(result, expected)

Hypothesis is a library for property-based testing. Instead of explicitly
parametrizing a test, you can describe *all* valid inputs and let Hypothesis
try to find a failing input.  Even better, no matter how many random examples
it tries, Hypothesis always reports a single minimal counterexample to your
assertions - often an example that you would never have thought to test.

See `Getting Started with Hypothesis <https://hypothesis.works/articles/getting-started-with-hypothesis/>`_
for more of an introduction, then `refer to the Hypothesis documentation
for details <https://hypothesis.readthedocs.io/en/latest/index.html>`_.

.. code-block:: python

    import json
    from hypothesis import given, strategies as st

    any_json_value = st.deferred(lambda: st.one_of(
        st.none(), st.booleans(), st.floats(allow_nan=False), st.text(),
        st.lists(any_json_value), st.dictionaries(st.text(), any_json_value)
    ))


    @given(value=any_json_value)
    def test_json_roundtrip(value):
        result = json.loads(json.dumps(value))
        assert value == result

This test shows off several useful features of Hypothesis, as well as
demonstrating a good use-case: checking properties that should hold over
a large or complicated domain of inputs.

To keep the pandas test suite running quickly, parametrized tests are
preferred if the inputs or logic are simple, with Hypothesis tests reserved
for cases with complex logic or where there are too many combinations of
options or subtle interactions to test (or think of!) all of them.

.. _contributing.running_tests:

Running the test suite
----------------------

The tests can then be run directly inside your Git clone (without having to
install pandas) by typing::

    pytest pandas

.. note::

    If a handful of tests don't pass, it may not be an issue with your pandas installation.
    Some tests (e.g. some SQLAlchemy ones) require additional setup, others might start
    failing because a non-pinned library released a new version, and others might be flaky
    if run in parallel. As long as you can import pandas from your locally built version,
    your installation is probably fine and you can start contributing!

Often it is worth running only a subset of tests first around your changes before running the
entire suite.

The easiest way to do this is with::

    pytest pandas/path/to/test.py -k regex_matching_test_name

Or with one of the following constructs::

    pytest pandas/tests/[test-module].py
    pytest pandas/tests/[test-module].py::[TestClass]
    pytest pandas/tests/[test-module].py::[TestClass]::[test_method]

Using `pytest-xdist <https://pypi.org/project/pytest-xdist>`_, which is
included in our 'pandas-dev' environment, one can speed up local testing on
multicore machines. The ``-n`` number flag then can be specified when running
pytest to parallelize a test run across the number of specified cores or auto to
utilize all the available cores on your machine.

.. code-block:: bash

   # Utilize 4 cores
   pytest -n 4 pandas

   # Utilizes all available cores
   pytest -n auto pandas

If you'd like to speed things along further a more advanced use of this
command would look like this

.. code-block:: bash

    pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX

In addition to the multithreaded performance increase this improves test
speed by skipping some tests using the ``-m`` mark flag:

- slow: any test taking long (think seconds rather than milliseconds)
- network: tests requiring network connectivity
- db: tests requiring a database (mysql or postgres)
- single_cpu: tests that should run on a single cpu only

You might want to enable the following option if it's relevant for you:

- arm_slow: any test taking long on arm64 architecture

These markers are defined `in this toml file <https://github.com/pandas-dev/pandas/blob/main/pyproject.toml>`_
, under ``[tool.pytest.ini_options]`` in a list called ``markers``, in case
you want to check if new ones have been created which are of interest to you.

The ``-r`` report flag will display a short summary info (see `pytest
documentation <https://docs.pytest.org/en/4.6.x/usage.html#detailed-summary-report>`_)
. Here we are displaying the number of:

- s: skipped tests
- x: xfailed tests
- X: xpassed tests

The summary is optional and can be removed if you don't need the added
information. Using the parallelization option can significantly reduce the
time it takes to locally run tests before submitting a pull request.

If you require assistance with the results,
which has happened in the past, please set a seed before running the command
and opening a bug report, that way we can reproduce it. Here's an example
for setting a seed on windows

.. code-block:: bash

    set PYTHONHASHSEED=314159265
    pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX

On Unix use

.. code-block:: bash

    export PYTHONHASHSEED=314159265
    pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX

For more, see the `pytest <https://docs.pytest.org/en/latest/>`_ documentation.

Furthermore one can run

.. code-block:: python

   pd.test()

with an imported pandas to run tests similarly.

Running the performance test suite
----------------------------------

Performance matters and it is worth considering whether your code has introduced
performance regressions. pandas is in the process of migrating to
`asv benchmarks <https://github.com/airspeed-velocity/asv>`__
to enable easy monitoring of the performance of critical pandas operations.
These benchmarks are all found in the ``pandas/asv_bench`` directory, and the
test results can be found `here <https://asv-runner.github.io/asv-collection/pandas>`__.

To use all features of asv, you will need either ``conda`` or
``virtualenv``. For more details please check the `asv installation
webpage <https://asv.readthedocs.io/en/latest/installing.html>`_.

To install asv::

    pip install git+https://github.com/airspeed-velocity/asv

If you need to run a benchmark, change your directory to ``asv_bench/`` and run::

    asv continuous -f 1.1 upstream/main HEAD

You can replace ``HEAD`` with the name of the branch you are working on,
and report benchmarks that changed by more than 10%.
The command uses ``conda`` by default for creating the benchmark
environments. If you want to use virtualenv instead, write::

    asv continuous -f 1.1 -E virtualenv upstream/main HEAD

The ``-E virtualenv`` option should be added to all ``asv`` commands
that run benchmarks. The default value is defined in ``asv.conf.json``.

Running the full benchmark suite can be an all-day process, depending on your
hardware and its resource utilization. However, usually it is sufficient to paste
only a subset of the results into the pull request to show that the committed changes
do not cause unexpected performance regressions.  You can run specific benchmarks
using the ``-b`` flag, which takes a regular expression. For example, this will
only run benchmarks from a ``pandas/asv_bench/benchmarks/groupby.py`` file::

    asv continuous -f 1.1 upstream/main HEAD -b ^groupby

If you want to only run a specific group of benchmarks from a file, you can do it
using ``.`` as a separator. For example::

    asv continuous -f 1.1 upstream/main HEAD -b groupby.GroupByMethods

will only run the ``GroupByMethods`` benchmark defined in ``groupby.py``.

You can also run the benchmark suite using the version of ``pandas``
already installed in your current Python environment. This can be
useful if you do not have virtualenv or conda; for the in-place build
you need to set ``PYTHONPATH``, e.g.
``PYTHONPATH="$PWD/.." asv [remaining arguments]``.
You can run benchmarks using an existing Python
environment by::

    asv run -e -E existing

or, to use a specific Python interpreter,::

    asv run -e -E existing:python3.6

This will display stderr from the benchmarks, and use your local
``python`` that comes from your ``$PATH``.

Information on how to write a benchmark and how to use asv can be found in the
`asv documentation <https://asv.readthedocs.io/en/latest/writing_benchmarks.html>`_.

Documenting your code
---------------------

Changes should be reflected in the release notes located in ``doc/source/whatsnew/vx.y.z.rst``.
This file contains an ongoing change log for each release.  Add an entry to this file to
document your fix, enhancement or (unavoidable) breaking change.  Make sure to include the
GitHub issue number when adding your entry (using ``:issue:`1234``` where ``1234`` is the
issue/pull request number). Your entry should be written using full sentences and proper
grammar.

When mentioning parts of the API, use a Sphinx ``:func:``, ``:meth:``, or ``:class:``
directive as appropriate. Not all public API functions and methods have a
documentation page; ideally links would only be added if they resolve. You can
usually find similar examples by checking the release notes for one of the previous
versions.

If your code is a bugfix, add your entry to the relevant bugfix section. Avoid
adding to the ``Other`` section; only in rare cases should entries go there.
Being as concise as possible, the description of the bug should include how the
user may encounter it and an indication of the bug itself, e.g.
"produces incorrect results" or "incorrectly raises". It may be necessary to also
indicate the new behavior.

If your code is an enhancement, it is most likely necessary to add usage
examples to the existing documentation.  This can be done following the section
regarding :ref:`documentation <contributing_documentation>`.
Further, to let users know when this feature was added, the ``versionadded``
directive is used. The sphinx syntax for that is:

.. code-block:: rst

    .. versionadded:: 2.1.0

This will put the text *New in version 2.1.0* wherever you put the sphinx
directive. This should also be put in the docstring when adding a new function
or method (`example <https://github.com/pandas-dev/pandas/blob/v0.20.2/pandas/core/frame.py#L1495>`__)
or a new keyword argument (`example <https://github.com/pandas-dev/pandas/blob/v0.20.2/pandas/core/generic.py#L568>`__).