diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 66d545a0de6e9e..3ec505998fde0d 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -612,6 +612,54 @@ Alternatively, you can install the ``grep`` and ``xargs`` commands via the `MinGW `__ toolchain, and it will allow you to run the commands above. +.. _contributing.import-formatting: + +Import Formatting +~~~~~~~~~~~~~~~~~ +*pandas* uses `isort `__ to standardise import +formatting across the codebase. + +A guide to import layout as per pep8 can be found `here `__. + +A summary of our current import sections ( in order ): + +* Future +* Python Standard Library +* Third Party +* ``pandas._libs``, ``pandas.compat``, ``pandas.util._*``, ``pandas.errors`` (largely not dependent on ``pandas.core``) +* ``pandas.core.dtypes`` (largely not dependent on the rest of ``pandas.core``) +* Rest of ``pandas.core.*`` +* Non-core ``pandas.io``, ``pandas.plotting``, ``pandas.tseries`` +* Local application/library specific imports + +Imports are alphabetically sorted within these sections. + + +As part of :ref:`Continuous Integration ` checks we run:: + + isort --recursive --check-only pandas + +to check that imports are correctly formatted as per the `setup.cfg`. + +If you see output like the below in :ref:`Continuous Integration ` checks: + +.. code-block:: shell + + Check import format using isort + ERROR: /home/travis/build/pandas-dev/pandas/pandas/io/pytables.py Imports are incorrectly sorted + Check import format using isort DONE + The command "ci/code_checks.sh" exited with 1 + +You should run:: + + isort pandas/io/pytables.py + +to automatically format imports correctly. This will modify your local copy of the files. + +The `--recursive` flag can be passed to sort all files in a directory. + +You can then verify the changes look ok, then git :ref:`commit ` and :ref:`push `. + Backwards Compatibility ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1078,6 +1126,8 @@ or a new keyword argument (`example