From c3c1831b825cc88d390de3d015965429ccfb3a48 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 27 Feb 2022 21:48:36 -0800 Subject: [PATCH 1/3] DOC: Move general utility functions to better locations --- .pre-commit-config.yaml | 2 +- doc/source/reference/arrays.rst | 105 ++++++++++++--- doc/source/reference/general_functions.rst | 7 - .../reference/general_utility_functions.rst | 127 ------------------ doc/source/reference/index.rst | 3 +- doc/source/reference/options.rst | 20 +++ doc/source/reference/testing.rst | 57 ++++++++ pandas/_libs/tslibs/np_datetime.pyx | 2 + scripts/pandas_errors_documented.py | 2 +- 9 files changed, 172 insertions(+), 153 deletions(-) delete mode 100644 doc/source/reference/general_utility_functions.rst create mode 100644 doc/source/reference/options.rst create mode 100644 doc/source/reference/testing.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6f91c885bf1e8..2c58ccb52f9e5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -178,7 +178,7 @@ repos: language: python files: ^pandas/core/generic\.py$ - id: pandas-errors-documented - name: Ensure pandas errors are documented in doc/source/reference/general_utility_functions.rst + name: Ensure pandas errors are documented in doc/source/reference/testing.rst entry: python scripts/pandas_errors_documented.py language: python files: ^pandas/errors/__init__.py$ diff --git a/doc/source/reference/arrays.rst b/doc/source/reference/arrays.rst index 5d40541f1d37b..1b8e0fdb856b5 100644 --- a/doc/source/reference/arrays.rst +++ b/doc/source/reference/arrays.rst @@ -6,6 +6,10 @@ pandas arrays, scalars, and data types ====================================== +******* +Objects +******* + .. currentmodule:: pandas For most data types, pandas uses NumPy arrays as the concrete @@ -40,8 +44,8 @@ stored in a :class:`Series`, :class:`Index`, or as a column in a :class:`DataFra .. _api.arrays.datetime: -Datetime data -------------- +Datetimes +--------- NumPy cannot natively represent timezone-aware datetimes. pandas supports this with the :class:`arrays.DatetimeArray` extension array, which can hold timezone-naive @@ -161,8 +165,8 @@ If the data are timezone-aware, then every value in the array must have the same .. _api.arrays.timedelta: -Timedelta data --------------- +Timedeltas +---------- NumPy can natively represent timedeltas. pandas provides :class:`Timedelta` for symmetry with :class:`Timestamp`. @@ -216,8 +220,8 @@ A collection of :class:`Timedelta` may be stored in a :class:`TimedeltaArray`. .. _api.arrays.period: -Timespan data -------------- +Periods +------- pandas represents spans of times as :class:`Period` objects. @@ -284,8 +288,8 @@ Every period in a :class:`arrays.PeriodArray` must have the same ``freq``. .. _api.arrays.interval: -Interval data -------------- +Intervals +--------- Arbitrary intervals can be represented as :class:`Interval` objects. @@ -379,8 +383,8 @@ pandas provides this through :class:`arrays.IntegerArray`. .. _api.arrays.categorical: -Categorical data ----------------- +Categoricals +------------ pandas defines a custom data type for representing data that can take only a limited, fixed set of values. The dtype of a :class:`Categorical` can be described by @@ -444,8 +448,8 @@ data. See :ref:`api.series.cat` for more. .. _api.arrays.sparse: -Sparse data ------------ +Sparse +------ Data where a single value is repeated many times (e.g. ``0`` or ``NaN``) may be stored efficiently as a :class:`arrays.SparseArray`. @@ -469,8 +473,8 @@ and methods if the :class:`Series` contains sparse values. See .. _api.arrays.string: -Text data ---------- +Strings +------- When working with text data, where each valid element is a string or missing, we recommend using :class:`StringDtype` (with the alias ``"string"``). @@ -494,8 +498,8 @@ See :ref:`api.series.str` for more. .. _api.arrays.bool: -Boolean data with missing values --------------------------------- +Nullable Boolean +---------------- The boolean dtype (with the alias ``"boolean"``) provides support for storing boolean data (``True``, ``False``) with missing values, which is not possible @@ -525,3 +529,72 @@ with a bool :class:`numpy.ndarray`. DatetimeTZDtype.tz PeriodDtype.freq IntervalDtype.subtype + +********* +Utilities +********* + +Constructors +------------ +.. autosummary:: + :toctree: api/ + + api.types.union_categoricals + api.types.infer_dtype + api.types.pandas_dtype + +Data type introspection +~~~~~~~~~~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: api/ + + api.types.is_bool_dtype + api.types.is_categorical_dtype + api.types.is_complex_dtype + api.types.is_datetime64_any_dtype + api.types.is_datetime64_dtype + api.types.is_datetime64_ns_dtype + api.types.is_datetime64tz_dtype + api.types.is_extension_type + api.types.is_extension_array_dtype + api.types.is_float_dtype + api.types.is_int64_dtype + api.types.is_integer_dtype + api.types.is_interval_dtype + api.types.is_numeric_dtype + api.types.is_object_dtype + api.types.is_period_dtype + api.types.is_signed_integer_dtype + api.types.is_string_dtype + api.types.is_timedelta64_dtype + api.types.is_timedelta64_ns_dtype + api.types.is_unsigned_integer_dtype + api.types.is_sparse + +Iterable introspection +~~~~~~~~~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: api/ + + api.types.is_dict_like + api.types.is_file_like + api.types.is_list_like + api.types.is_named_tuple + api.types.is_iterator + +Scalar introspection +~~~~~~~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: api/ + + api.types.is_bool + api.types.is_categorical + api.types.is_complex + api.types.is_float + api.types.is_hashable + api.types.is_integer + api.types.is_interval + api.types.is_number + api.types.is_re + api.types.is_re_compilable + api.types.is_scalar diff --git a/doc/source/reference/general_functions.rst b/doc/source/reference/general_functions.rst index dde16fb7fac71..4b2fadcb367a1 100644 --- a/doc/source/reference/general_functions.rst +++ b/doc/source/reference/general_functions.rst @@ -78,10 +78,3 @@ Hashing util.hash_array util.hash_pandas_object - -Testing -~~~~~~~ -.. autosummary:: - :toctree: api/ - - test diff --git a/doc/source/reference/general_utility_functions.rst b/doc/source/reference/general_utility_functions.rst deleted file mode 100644 index ee17ef3831164..0000000000000 --- a/doc/source/reference/general_utility_functions.rst +++ /dev/null @@ -1,127 +0,0 @@ -{{ header }} - -.. _api.general_utility_functions: - -========================= -General utility functions -========================= -.. currentmodule:: pandas - -Working with options --------------------- -.. autosummary:: - :toctree: api/ - - describe_option - reset_option - get_option - set_option - option_context - -.. _api.general.testing: - -Testing functions ------------------ -.. autosummary:: - :toctree: api/ - - testing.assert_frame_equal - testing.assert_series_equal - testing.assert_index_equal - testing.assert_extension_array_equal - -Exceptions and warnings ------------------------ -.. autosummary:: - :toctree: api/ - - errors.AbstractMethodError - errors.AccessorRegistrationWarning - errors.DtypeWarning - errors.DuplicateLabelError - errors.EmptyDataError - errors.InvalidIndexError - errors.IntCastingNaNError - errors.MergeError - errors.NullFrequencyError - errors.NumbaUtilError - errors.OptionError - errors.OutOfBoundsDatetime - errors.OutOfBoundsTimedelta - errors.ParserError - errors.ParserWarning - errors.PerformanceWarning - errors.UnsortedIndexError - errors.UnsupportedFunctionCall - -Data types related functionality --------------------------------- -.. autosummary:: - :toctree: api/ - - api.types.union_categoricals - api.types.infer_dtype - api.types.pandas_dtype - -Dtype introspection -~~~~~~~~~~~~~~~~~~~ -.. autosummary:: - :toctree: api/ - - api.types.is_bool_dtype - api.types.is_categorical_dtype - api.types.is_complex_dtype - api.types.is_datetime64_any_dtype - api.types.is_datetime64_dtype - api.types.is_datetime64_ns_dtype - api.types.is_datetime64tz_dtype - api.types.is_extension_type - api.types.is_extension_array_dtype - api.types.is_float_dtype - api.types.is_int64_dtype - api.types.is_integer_dtype - api.types.is_interval_dtype - api.types.is_numeric_dtype - api.types.is_object_dtype - api.types.is_period_dtype - api.types.is_signed_integer_dtype - api.types.is_string_dtype - api.types.is_timedelta64_dtype - api.types.is_timedelta64_ns_dtype - api.types.is_unsigned_integer_dtype - api.types.is_sparse - -Iterable introspection -~~~~~~~~~~~~~~~~~~~~~~ -.. autosummary:: - :toctree: api/ - - api.types.is_dict_like - api.types.is_file_like - api.types.is_list_like - api.types.is_named_tuple - api.types.is_iterator - -Scalar introspection -~~~~~~~~~~~~~~~~~~~~ -.. autosummary:: - :toctree: api/ - - api.types.is_bool - api.types.is_categorical - api.types.is_complex - api.types.is_float - api.types.is_hashable - api.types.is_integer - api.types.is_interval - api.types.is_number - api.types.is_re - api.types.is_re_compilable - api.types.is_scalar - -Bug report function -------------------- -.. autosummary:: - :toctree: api/ - - show_versions diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index f7c5eaf242b34..b6f2991cc0eb4 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -37,8 +37,9 @@ public functions related to data types in pandas. resampling style plotting - general_utility_functions + options extensions + testing .. This is to prevent warnings in the doc build. We don't want to encourage .. these methods. diff --git a/doc/source/reference/options.rst b/doc/source/reference/options.rst new file mode 100644 index 0000000000000..52ef10cc51305 --- /dev/null +++ b/doc/source/reference/options.rst @@ -0,0 +1,20 @@ +{{ header }} + +.. _api.options: + +==================== +Options and settings +==================== + +API for configuring global behavior. See :ref:`the User Guide ` for more. + +Working with options +-------------------- +.. autosummary:: + :toctree: api/ + + describe_option + reset_option + get_option + set_option + option_context diff --git a/doc/source/reference/testing.rst b/doc/source/reference/testing.rst new file mode 100644 index 0000000000000..2a840ba41cc72 --- /dev/null +++ b/doc/source/reference/testing.rst @@ -0,0 +1,57 @@ +{{ header }} + +.. _api.testing: + +======= +Testing +======= + +.. _api.general.testing: + +Assertion functions +------------------- +.. autosummary:: + :toctree: api/ + + testing.assert_frame_equal + testing.assert_series_equal + testing.assert_index_equal + testing.assert_extension_array_equal + +Exceptions and warnings +----------------------- +.. autosummary:: + :toctree: api/ + + errors.AbstractMethodError + errors.AccessorRegistrationWarning + errors.DtypeWarning + errors.DuplicateLabelError + errors.EmptyDataError + errors.InvalidIndexError + errors.IntCastingNaNError + errors.MergeError + errors.NullFrequencyError + errors.NumbaUtilError + errors.OptionError + errors.OutOfBoundsDatetime + errors.OutOfBoundsTimedelta + errors.ParserError + errors.ParserWarning + errors.PerformanceWarning + errors.UnsortedIndexError + errors.UnsupportedFunctionCall + +Bug report function +------------------- +.. autosummary:: + :toctree: api/ + + show_versions + +Test suite runner +----------------- +.. autosummary:: + :toctree: api/ + + test diff --git a/pandas/_libs/tslibs/np_datetime.pyx b/pandas/_libs/tslibs/np_datetime.pyx index bc03a3e7f885e..b9d06e5f67010 100644 --- a/pandas/_libs/tslibs/np_datetime.pyx +++ b/pandas/_libs/tslibs/np_datetime.pyx @@ -98,6 +98,8 @@ cdef inline bint cmp_scalar(int64_t lhs, int64_t rhs, int op) except -1: class OutOfBoundsDatetime(ValueError): + """Raised when the datetime is outside the range that + can be represented.""" pass diff --git a/scripts/pandas_errors_documented.py b/scripts/pandas_errors_documented.py index 4024cd24c558e..3e5bf34db4fe8 100644 --- a/scripts/pandas_errors_documented.py +++ b/scripts/pandas_errors_documented.py @@ -14,7 +14,7 @@ import sys from typing import Sequence -API_PATH = pathlib.Path("doc/source/reference/general_utility_functions.rst").resolve() +API_PATH = pathlib.Path("doc/source/reference/testing.rst").resolve() def get_defined_errors(content: str) -> set[str]: From d39856c5fff074902615978a48baf217a71c9555 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Mon, 28 Feb 2022 10:27:36 -0800 Subject: [PATCH 2/3] Newline --- pandas/_libs/tslibs/np_datetime.pyx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslibs/np_datetime.pyx b/pandas/_libs/tslibs/np_datetime.pyx index b9d06e5f67010..79a58478d630a 100644 --- a/pandas/_libs/tslibs/np_datetime.pyx +++ b/pandas/_libs/tslibs/np_datetime.pyx @@ -98,8 +98,10 @@ cdef inline bint cmp_scalar(int64_t lhs, int64_t rhs, int op) except -1: class OutOfBoundsDatetime(ValueError): - """Raised when the datetime is outside the range that - can be represented.""" + """ + Raised when the datetime is outside the range that + can be represented. + """ pass From 6d9eedf6181571b0fee8cce5a110289d807e5e4c Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Mon, 28 Feb 2022 10:36:23 -0800 Subject: [PATCH 3/3] Add current module? --- doc/source/reference/options.rst | 1 + doc/source/reference/testing.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/doc/source/reference/options.rst b/doc/source/reference/options.rst index 52ef10cc51305..7316b6e9c72b1 100644 --- a/doc/source/reference/options.rst +++ b/doc/source/reference/options.rst @@ -5,6 +5,7 @@ ==================== Options and settings ==================== +.. currentmodule:: pandas API for configuring global behavior. See :ref:`the User Guide ` for more. diff --git a/doc/source/reference/testing.rst b/doc/source/reference/testing.rst index 2a840ba41cc72..0d702dd4e702d 100644 --- a/doc/source/reference/testing.rst +++ b/doc/source/reference/testing.rst @@ -5,6 +5,7 @@ ======= Testing ======= +.. currentmodule:: pandas .. _api.general.testing: