Merge pull request #3 from pandas-dev/master

Sync Fork from Upstream Repo

Author: sthagen

doc/source/development/contributing.rst

@@ -635,6 +635,8 @@ many errors as possible, but it may not correct *all* of them. Thus, it is
 recommended that you run ``cpplint`` to double check and make any other style
 fixes manually.
 
+.. _contributing.code-formatting:
+
 Python (PEP8 / black)
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -656,27 +658,16 @@ apply ``black`` as you edit files.
 You should use a ``black`` version >= 19.10b0 as previous versions are not compatible
 with the pandas codebase.
 
-Optionally, you may wish to setup `pre-commit hooks <https://pre-commit.com/>`_
-to automatically run ``black`` and ``flake8`` when you make a git commit. This
-can be done by installing ``pre-commit``::
-
-   pip install pre-commit
-
-and then running::
-
-   pre-commit install
-
-from the root of the pandas repository. Now ``black`` and ``flake8`` will be run
-each time you commit changes. You can skip these checks with
-``git commit --no-verify``.
+If you wish to run these checks automatically, we encourage you to use
+:ref:`pre-commits <contributing.pre-commit>` instead.
 
 One caveat about ``git diff upstream/master -u -- "*.py" | flake8 --diff``: this
 command will catch any stylistic errors in your changes specifically, but
 be beware it may not catch all of them. For example, if you delete the only
 usage of an imported function, it is stylistically incorrect to import an
 unused function. However, style-checking the diff will not catch this because
 the actual import is not part of the diff. Thus, for completeness, you should
-run this command, though it will take longer::
+run this command, though it may take longer::
 
    git diff upstream/master --name-only -- "*.py" | xargs -r flake8
 
@@ -694,6 +685,8 @@ behaviour as follows::
 This will get all the files being changed by the PR (and ending with ``.py``),
 and run ``flake8`` on them, one after the other.
 
+Note that these commands can be run analogously with ``black``.
+
 .. _contributing.import-formatting:
 
 Import formatting
@@ -716,7 +709,6 @@ A summary of our current import sections ( in order ):
 
 Imports are alphabetically sorted within these sections.
 
-
 As part of :ref:`Continuous Integration <contributing.ci>` checks we run::
 
     isort --recursive --check-only pandas
@@ -740,8 +732,37 @@ to automatically format imports correctly. This will modify your local copy of t
 
 The `--recursive` flag can be passed to sort all files in a directory.
 
+Alternatively, you can run a command similar to what was suggested for ``black`` and ``flake8`` :ref:`right above <contributing.code-formatting>`::
+
+    git diff upstream/master --name-only -- "*.py" | xargs -r isort
+
+Where similar caveats apply if you are on OSX or Windows.
+
 You can then verify the changes look ok, then git :ref:`commit <contributing.commit-code>` and :ref:`push <contributing.push-code>`.
 
+.. _contributing.pre-commit:
+
+Pre-Commit
+~~~~~~~~~~
+
+You can run many of these styling checks manually as we have described above. However,
+we encourage you to use `pre-commit hooks <https://pre-commit.com/>`_ instead
+to automatically run ``black``, ``flake8``, ``isort`` when you make a git commit. This
+can be done by installing ``pre-commit``::
+
+    pip install pre-commit
+
+and then running::
+
+    pre-commit install
+
+from the root of the pandas repository. Now all of the styling checks will be
+run each time you commit changes without your needing to run each one manually.
+In addition, using this pre-commit hook will also allow you to more easily
+remain up-to-date with our code checks as they change.
+
+Note that if needed, you can skip these checks with ``git commit --no-verify``.
+
 Backwards compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/development/roadmap.rst

@@ -129,20 +129,6 @@ Some specific goals include
 * Improve the overall organization of the documentation and specific subsections
   of the documentation to make navigation and finding content easier.
 
-Package docstring validation
-----------------------------
-
-To improve the quality and consistency of pandas docstrings, we've developed
-tooling to check docstrings in a variety of ways.
-https://github.com/pandas-dev/pandas/blob/master/scripts/validate_docstrings.py
-contains the checks.
-
-Like many other projects, pandas uses the
-`numpydoc <https://numpydoc.readthedocs.io/en/latest/>`__ style for writing
-docstrings. With the collaboration of the numpydoc maintainers, we'd like to
-move the checks to a package other than pandas so that other projects can easily
-use them as well.
-
 Performance monitoring
 ----------------------
 

pandas/_config/display.py

@@ -1,6 +1,7 @@
 """
 Unopinionated display configuration.
 """
+
 import locale
 import sys
 
@@ -11,7 +12,7 @@
 _initial_defencoding = None
 
 
-def detect_console_encoding():
+def detect_console_encoding() -> str:
     """
     Try to find the most capable encoding supported by the console.
     slightly modified from the way IPython handles the same issue.

pandas/_config/localization.py

@@ -12,7 +12,7 @@
 
 
 @contextmanager
-def set_locale(new_locale, lc_var=locale.LC_ALL):
+def set_locale(new_locale, lc_var: int = locale.LC_ALL):
     """
     Context manager for temporarily setting a locale.
 
@@ -44,7 +44,7 @@ def set_locale(new_locale, lc_var=locale.LC_ALL):
         locale.setlocale(lc_var, current_locale)
 
 
-def can_set_locale(lc, lc_var=locale.LC_ALL):
+def can_set_locale(lc: str, lc_var: int = locale.LC_ALL) -> bool:
     """
     Check to see if we can set a locale, and subsequently get the locale,
     without raising an Exception.
@@ -58,7 +58,7 @@ def can_set_locale(lc, lc_var=locale.LC_ALL):
 
     Returns
     -------
-    is_valid : bool
+    bool
         Whether the passed locale can be set
     """
 

pandas/_testing.py

@@ -122,9 +122,9 @@ def round_trip_pickle(
     _path = path
     if _path is None:
         _path = f"__{rands(10)}__.pickle"
-    with ensure_clean(_path) as path:
-        pd.to_pickle(obj, _path)
-        return pd.read_pickle(_path)
+    with ensure_clean(_path) as temp_path:
+        pd.to_pickle(obj, temp_path)
+        return pd.read_pickle(temp_path)
 
 
 def round_trip_pathlib(writer, reader, path: Optional[str] = None):

pandas/compat/numpy/function.py

@@ -33,13 +33,26 @@
 
 
 class CompatValidator:
-    def __init__(self, defaults, fname=None, method=None, max_fname_arg_count=None):
+    def __init__(
+        self,
+        defaults,
+        fname=None,
+        method: Optional[str] = None,
+        max_fname_arg_count=None,
+    ):
         self.fname = fname
         self.method = method
         self.defaults = defaults
         self.max_fname_arg_count = max_fname_arg_count
 
-    def __call__(self, args, kwargs, fname=None, max_fname_arg_count=None, method=None):
+    def __call__(
+        self,
+        args,
+        kwargs,
+        fname=None,
+        max_fname_arg_count=None,
+        method: Optional[str] = None,
+    ) -> None:
         if args or kwargs:
             fname = self.fname if fname is None else fname
             max_fname_arg_count = (
@@ -300,7 +313,7 @@ def validate_take_with_convert(convert, args, kwargs):
 )
 
 
-def validate_window_func(name, args, kwargs):
+def validate_window_func(name, args, kwargs) -> None:
     numpy_args = ("axis", "dtype", "out")
     msg = (
         f"numpy operations are not valid with window objects. "
@@ -315,7 +328,7 @@ def validate_window_func(name, args, kwargs):
             raise UnsupportedFunctionCall(msg)
 
 
-def validate_rolling_func(name, args, kwargs):
+def validate_rolling_func(name, args, kwargs) -> None:
     numpy_args = ("axis", "dtype", "out")
     msg = (
         f"numpy operations are not valid with window objects. "
@@ -330,7 +343,7 @@ def validate_rolling_func(name, args, kwargs):
             raise UnsupportedFunctionCall(msg)
 
 
-def validate_expanding_func(name, args, kwargs):
+def validate_expanding_func(name, args, kwargs) -> None:
     numpy_args = ("axis", "dtype", "out")
     msg = (
         f"numpy operations are not valid with window objects. "
@@ -345,7 +358,7 @@ def validate_expanding_func(name, args, kwargs):
             raise UnsupportedFunctionCall(msg)
 
 
-def validate_groupby_func(name, args, kwargs, allowed=None):
+def validate_groupby_func(name, args, kwargs, allowed=None) -> None:
     """
     'args' and 'kwargs' should be empty, except for allowed
     kwargs because all of
@@ -359,16 +372,15 @@ def validate_groupby_func(name, args, kwargs, allowed=None):
 
     if len(args) + len(kwargs) > 0:
         raise UnsupportedFunctionCall(
-            f"numpy operations are not valid with "
-            f"groupby. Use .groupby(...).{name}() "
-            f"instead"
+            "numpy operations are not valid with groupby. "
+            f"Use .groupby(...).{name}() instead"
         )
 
 
 RESAMPLER_NUMPY_OPS = ("min", "max", "sum", "prod", "mean", "std", "var")
 
 
-def validate_resampler_func(method, args, kwargs):
+def validate_resampler_func(method: str, args, kwargs) -> None:
     """
     'args' and 'kwargs' should be empty because all of
     their necessary parameters are explicitly listed in
@@ -385,7 +397,7 @@ def validate_resampler_func(method, args, kwargs):
             raise TypeError("too many arguments passed in")
 
 
-def validate_minmax_axis(axis):
+def validate_minmax_axis(axis: Optional[int]) -> None:
     """
     Ensure that the axis argument passed to min, max, argmin, or argmax is
     zero or None, as otherwise it will be incorrectly ignored.

pandas/core/index.py

@@ -27,4 +27,5 @@
     "pandas.core.index is deprecated and will be removed in a future version.  "
     "The public classes are available in the top-level namespace.",
     FutureWarning,
+    stacklevel=2,
 )