pandahandler.indexes
====================

.. py:module:: pandahandler.indexes

.. autoapi-nested-parse::

   Tools for working with pandas indexes.



Classes
-------

.. autoapisummary::

   pandahandler.indexes.Index


Functions
---------

.. autoapisummary::

   pandahandler.indexes.is_unnamed_range_index
   pandahandler.indexes.assert_no_nulls
   pandahandler.indexes.unset


Module Contents
---------------

.. py:function:: is_unnamed_range_index(index: pandas.Index) -> bool

   Assert that the index is trivial, i.e. equal to the default RangeIndex.


.. py:function:: assert_no_nulls(index: pandas.Index) -> None

   Assert that the index has no null values.


.. py:function:: unset(df: pandas.DataFrame, require_names: bool = True) -> pandas.DataFrame

   Safely unset the index.

   Details:

   * This is more an "unset" than a "reset" in the sense that it makes the index as trivial as possible. If we
     could totally remove the index of the data frame, that's what this function would do, but the unnamed
     range index is the next closest thing.
   * This is "safe" in the sense that it will not drop any existing data encoded in the index. (We assume that an
     unnamed range index does not count as "data" in this context.) Existing index columns get converted to
     regular columns in the data frame.

   :param df: The data frame to unset the index on.
   :param require_names: Whether to raise an error if the existing index is unnamed:

                         * This setting is ignored whenever the index is an unnamed RangeIndex.
                         * With require_names=False, a unnamed index typically is converted to a new column called "index".
                         * Using require_names=True (default) forces users to declare how to handle an unnamed index. Either:

                           * Call reset_index(drop=True) directly to drop the index instead of calling this function.
                           * Set the name(s) of the index prior to calling this function.

   :raises ValueError: If the data frame column names overlap with the index names.
   :raises ValueError: If all of the following apply:
       - require_names is True (the default)
       - the index is unnamed
       - the index is not a trivial RangeIndex

   :returns: A copy of the input data frame with the index columns reset as regular columns. The new index is
             a simple RangeIndex.


.. py:class:: Index

   A functional wrapper around pandas indexes.

   An instance of this class can be used to simplify the following types of operations:

   * Coercing an input data frame to have a particular index.
   * Enforcing or ensuring various index properties such as monotonicity or uniqueness.
   * Unset and reset indexes cleanly before and after operations that require columnar access to index columns.

   This class applies both for pandas.Index and MultiIndex objects to reduce the amount of special-casing needed based
   on the number of columns in the index.

   .. rubric:: Example

   .. code-block:: python

       # Set an index with sorting
       df = pd.DataFrame({"a": [1, 3, 2], "b": [4, 5, 6]})
       index = Index(names=["a"], sort=True)
       df = index(df)
       assert df.index.tolist() == [1, 2, 3]

       # Switch over to another column as the index


   .. py:attribute:: names
      :type:  pandas.core.indexes.frozen.FrozenList

      The names of the columns of the index.


   .. py:attribute:: allow_null
      :type:  bool

      Whether to allow null values in the index. Applicable only for single-column indexes, since pandas does not
      support null values in a MultiIndex.


   .. py:attribute:: sort
      :type:  bool

      Whether to sort the index.


   .. py:attribute:: require_unique
      :type:  bool

      Whether to require the index to be unique. E.g. if True, raise an error if the index is not unique.


   .. py:method:: __call__(df: pandas.DataFrame, **kwargs: Any) -> pandas.DataFrame

      Set the index on the data frame.

      Any named columns of the current df index that are not part of the new index will be converted to new
      data frame columns.

      :param df: The data frame to set the index on.
      :param \*\*kwargs: Additional arguments to pass to the set_index method.

      :raises ValueError: If the verify_integrity kwarg is inconsistent with the require_unique attribute.
      :raises ValueError: If there is overlap between the existing index column names and the column names.



   .. py:method:: assert_equal_names(index: pandas.Index) -> None

      Assert that names of the provided index match the names of this index.