Notes:

- move the multi-index formatting logic into
  PandasMultiIndexingAdapter._repr_inline_
- inline repr: check for _repr_inline_ implementation first

See pydata#5691

Not totally yet: need to refactor set_index / reset_index

Avoid re-creating the indexes for dimension variables. Collect then
directly instead.

Note: the change here is working for building new Datasets but I haven't
checked other cases like merging different objects, etc. So I'm not sure
this is the right approach.

- Index.query must now return a mapping of {dim_name:
positional_indexer} as indexes may be based on several coordinates with
different dimensions

- Added `group_coords_by_index` utility function (not used yet, not sure
we'll need it)

TODO:

- Update DataArray selection
- Update .loc and other places using remap_label_indexers
- Fix selection of multi-index that returns only scalar coordinates

Multi-index level variables now return the scalar value that corresponds
to the level instead of the multi-index tuple element (all levels).

Also get rid of PandasMultiIndexingAdapter.__getitem__ cache
optimization, which doesn't work with level scalar values and was
premature optimization anyway.

Fixed renamed dimension in the case of multi-index -> single index

Updated DataArray._overwrite_indexes

Dirty fix for alignment (not tested yet)

Created QueryResult and MergedQueryResults classes for convenience.

When level is not None:

- if result is another adapter: propagate it properly
- if result is a numpy adapter: use level values

Make the fix in pydata#3153 specific to pandas indexes (i.e., do not apply it
to other, custom indexes). See pydata#5697 for details.

This should also fix pydata#5700 although no test has been added yet (we need
to refactor set_index first).

- Use a dataclass for QueryResult

- Pass Variables and DataArrays indexers un-normalized to Index.query().
  Indexes have the responsibility of returning the expected types for
  positional (dimension) indexers by adding back dimensions and
  coordinates if needed.

- Typing fixes and tweaks

Related to pydata#1366

Still needs tests

Also need to address the problem of multi-index level coordinates (data
adapters currently not updated). We'll probably need for
`Index.rename()` to also return new index variables?

Still need to address default indexes internal checks (these are
disabled for now).

- Refactor reset_index
- Improve creating new xarray indexes from pandas indexes with proper
  propagation of variable metadata (dtype, attrs, encoding)

Closes pydata#4542

..instead of dropping those coordinates

Closes pydata#1408 once tests are fixed/updated

Some changes:

Multi-indexes are created only if the
stacked dimensions each have a single coordinate index. In the other
cases, multi-indexes are not created, which means that it is an
irreversible operation (unstack will not work)

Multi-indexes are created from the stacked coordinate variables and not
anymore from the unstacked dimension indexes (level product). There's a
significant decrease in performance but it is probably acceptable since
it's now possible to avoid the creation of multi-indexes.

It is possible to stack a dimension with a multi-index, but it drops the
index. Otherwise it would make it hard for unstack() to figure out
what's going on. It makes it clear that this is an irreversible
operation.

It is more robust and allows creating a multi-index from
non-default (non-dimension) coordinates, as long as there's one and only
one 1-d indexed coordinate for each dimension to stack.

This removes some ugly & duplicate patterns.

stack: revert to old way of creating multi-index

unstack: support non-default (non-dimension) multi-index (as long as
there is exactly one multi-index per specified dimension)

Refactored utils.multiindex_from_product_levels utility function
into a new PandasMultiIndex classmethod.

Use the good old way as we still support py37

make sure the stacked dataset used has a multi-index

Fixes pydata#5727

This will probably be used instead of including index coordinate
variables in the signature (return type) of many methods of ``Index``.

It has several advantages:

- More DRY, and for custom indexes that do not need to create coordinate
variables with special data adapters, it's easier to just skip
implementing this method and not bother with returning empty dicts in
other methods

- This allows to decouple index vs. coordinates creation. For many cases
this can be done at the same time but for some cases like alignment this
is useful

- It's a more elegant solution when we need to propagate
metadata (attrs, encoding)

One possible solution to the recurring problem of accessing coordinate
variables related to a given index in some of Xarray's internals.

I feel that the ``Indexes`` proxy is the right place for storing
references to those indexed coordinate variables. It's safer than
relying on a public attribute/property of ``Index``.

Expose similar properties:
- variables
- dims

Almost done rewriting `align`.

- Some fixes and clean-up in new implementation of align
- Add Index.join method (only for inner/outer join)
- Tweak index generic types
- IndexVars type: use Variable instead of IndexVariable (IndexVariable
  may eventually be dropped)

Imported all re-indexing logic into the `Alignator` class, which can be
reused directly for both `align()` and `obj.reindex()`.

TODO:
- import override indexes into `Alignator`
- connect Alignator to public API entry points
- clean-up (remove old implementation functions)

I will fix mypy errors later.

All `*align*` and `*reindex*` tests are passing! (locally)
Mypy doesn't complain.

TODO: refactor `interp` and `interp_like` (I only plan to fix it with
the new Aligner class for now)

It now reuses the new alignment/reindex internals, but it still only
supports dimension coordinates with a single index,

Also added a `index_cls` parameter to `Dataset.stack` and
`DataArray.stack`.

Custom indexes may thus implement their own logic for stack/unstack,
with the current limitation that a `pandas.MultiIndex` is still
explicitly required for unstack optimized versions.

Fix concat tests and some groupby tests

Check consistency between PandasIndex objects and
coordinate variables data adapters (PandasIndexingAdapter).

Filter indexes and preserve unique index objects for multi-coordinate
indexes.

Also fixed indexes tests (stack/unstack).

We can't just look at excluded dimensions anymore...

Check in merge that prioritized elements won't corrupt collected
indexes.

Fixes and tweaks
Refactored assign, update, setitem, delitem, drop_vars
Added or updated tests

…ables

Prevent converting special index types like ``pd.CategoricalIndex`` when
such objects are wrapped in xarray variables.

…-indexes-variables

for more information, see https://pre-commit.ci

When coord is None

Also cover the cases where indexes are equal but not identical (caused a
couple of tests failing). Perfs may not be a concern for such edge case?