"""
This type stub file was generated by pyright.
"""

import logging
import sys
import wrapt
from collections import abc as collections_abc
from typing import Mapping, Sequence, TypeVar, Union
from .sequence import _is_attrs, _is_namedtuple, _sequence_like, _sorted
from tree import _tree

"""Functions for working with nested data structures."""
ObjectProxy = ...
__all__ = ["is_nested", "assert_same_structure", "unflatten_as", "flatten", "flatten_up_to", "flatten_with_path", "flatten_with_path_up_to", "map_structure", "map_structure_up_to", "map_structure_with_path", "map_structure_with_path_up_to", "traverse", "MAP_TO_NONE"]
__version__ = ...
_TEXT_OR_BYTES = ...
_SHALLOW_TREE_HAS_INVALID_KEYS = ...
_STRUCTURES_HAVE_MISMATCHING_TYPES = ...
_STRUCTURES_HAVE_MISMATCHING_LENGTHS = ...
_INPUT_TREE_SMALLER_THAN_SHALLOW_TREE = ...
_IF_SHALLOW_IS_SEQ_INPUT_MUST_BE_SEQ = ...
_IF_SHALLOW_IS_SEQ_INPUT_MUST_BE_SEQ_WITH_PATH = ...
K = TypeVar("K")
V = TypeVar("V")
StructureKV = Union[Sequence["StructureKV[K, V]"], Mapping[K, "StructureKV[K, V]"], V,]
Structure = StructureKV[str, V]
def is_nested(structure):
  """Checks if a given structure is nested.

  >>> tree.is_nested(42)
  False
  >>> tree.is_nested({"foo": 42})
  True

  Args:
    structure: A structure to check.

  Returns:
    `True` if a given structure is nested, i.e. is a sequence, a mapping,
    or a namedtuple, and `False` otherwise.
  """
  ...

def flatten(structure):
  r"""Flattens a possibly nested structure into a list.

  >>> tree.flatten([[1, 2, 3], [4, [5], [[6]]]])
  [1, 2, 3, 4, 5, 6]

  If `structure` is not nested, the result is a single-element list.

  >>> tree.flatten(None)
  [None]
  >>> tree.flatten(1)
  [1]

  In the case of dict instances, the sequence consists of the values,
  sorted by key to ensure deterministic behavior. This is true also for
  :class:`~collections.OrderedDict` instances: their sequence order is
  ignored, the sorting order of keys is used instead. The same convention
  is followed in :func:`~tree.unflatten`. This correctly unflattens dicts
  and ``OrderedDict``\ s after they have been flattened, and also allows
  flattening an ``OrderedDict`` and then unflattening it back using a
  corresponding plain dict, or vice-versa.

  Dictionaries with non-sortable keys cannot be flattened.

  >>> tree.flatten({100: 'world!', 6: 'Hello'})
  ['Hello', 'world!']

  Args:
    structure: An arbitrarily nested structure.

  Returns:
    A list, the flattened version of the input `structure`.

  Raises:
    TypeError: If `structure` is or contains a mapping with non-sortable keys.
  """
  ...

class _DotString:
  def __str__(self) -> str:
    ...
  
  def __repr__(self): # -> Literal['.']:
    ...
  


_DOT = ...
def assert_same_structure(a, b, check_types=...): # -> None:
  """Asserts that two structures are nested in the same way.

  >>> tree.assert_same_structure([(0, 1)], [(2, 3)])

  Note that namedtuples with identical name and fields are always considered
  to have the same shallow structure (even with `check_types=True`).

  >>> Foo = collections.namedtuple('Foo', ['a', 'b'])
  >>> AlsoFoo = collections.namedtuple('Foo', ['a', 'b'])
  >>> tree.assert_same_structure(Foo(0, 1), AlsoFoo(2, 3))

  Named tuples with different names are considered to have different shallow
  structures:

  >>> Bar = collections.namedtuple('Bar', ['a', 'b'])
  >>> tree.assert_same_structure(Foo(0, 1), Bar(2, 3))
  Traceback (most recent call last):
    ...
  TypeError: The two structures don't have the same nested structure.
  ...

  Args:
    a: an arbitrarily nested structure.
    b: an arbitrarily nested structure.
    check_types: if `True` (default) types of sequences are checked as
      well, including the keys of dictionaries. If set to `False`, for example
      a list and a tuple of objects will look the same if they have the same
      size. Note that namedtuples with identical name and fields are always
      considered to have the same shallow structure.

  Raises:
    ValueError: If the two structures do not have the same number of elements or
      if the two structures are not nested in the same way.
    TypeError: If the two structures differ in the type of sequence in any of
      their substructures. Only possible if `check_types` is `True`.
  """
  ...

def unflatten_as(structure, flat_sequence): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy:
  r"""Unflattens a sequence into a given structure.

  >>> tree.unflatten_as([[1, 2], [[3], [4]]], [5, 6, 7, 8])
  [[5, 6], [[7], [8]]]

  If `structure` is a scalar, `flat_sequence` must be a single-element list;
  in this case the return value is ``flat_sequence[0]``.

  >>> tree.unflatten_as(None, [1])
  1

  If `structure` is or contains a dict instance, the keys will be sorted to
  pack the flat sequence in deterministic order. This is true also for
  :class:`~collections.OrderedDict` instances: their sequence order is
  ignored, the sorting order of keys is used instead. The same convention
  is followed in :func:`~tree.flatten`. This correctly unflattens dicts
  and ``OrderedDict``\ s after they have been flattened, and also allows
  flattening an ``OrderedDict`` and then unflattening it back using a
  corresponding plain dict, or vice-versa.

  Dictionaries with non-sortable keys cannot be unflattened.

  >>> tree.unflatten_as({1: None, 2: None}, ['Hello', 'world!'])
  {1: 'Hello', 2: 'world!'}

  Args:
    structure: Arbitrarily nested structure.
    flat_sequence: Sequence to unflatten.

  Returns:
    `flat_sequence` unflattened into `structure`.

  Raises:
    ValueError: If `flat_sequence` and `structure` have different
      element counts.
    TypeError: If `structure` is or contains a mapping with non-sortable keys.
  """
  ...

def map_structure(func, *structures, **kwargs): # -> object | defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy:
  """Maps `func` through given structures.

  >>> structure = [[1], [2], [3]]
  >>> tree.map_structure(lambda v: v**2, structure)
  [[1], [4], [9]]
  >>> tree.map_structure(lambda x, y: x * y, structure, structure)
  [[1], [4], [9]]
  >>> Foo = collections.namedtuple('Foo', ['a', 'b'])
  >>> structure = Foo(a=1, b=2)
  >>> tree.map_structure(lambda v: v * 2, structure)
  Foo(a=2, b=4)

  Args:
    func: A callable that accepts as many arguments as there are structures.
    *structures: Arbitrarily nested structures of the same layout.
    **kwargs: The only valid keyword argument is `check_types`. If `True`
      (default) the types of components within the structures have
      to be match, e.g. ``tree.map_structure(func, [1], (1,))`` will raise
      a `TypeError`, otherwise this is not enforced. Note that namedtuples
      with identical name and fields are considered to be the same type.

  Returns:
    A new structure with the same layout as the given ones. If the
    `structures` have components of varying types, the resulting structure
    will use the same types as ``structures[0]``.

  Raises:
    TypeError: If `func` is not callable.
    ValueError: If the two structures do not have the same number of elements or
      if the two structures are not nested in the same way.
    TypeError: If `check_types` is `True` and any two `structures`
      differ in the types of their components.
    ValueError: If no structures were given or if a keyword argument other
      than `check_types` is provided.
  """
  ...

def map_structure_with_path(func, *structures, **kwargs): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy:
  """Maps `func` through given structures.

  This is a variant of :func:`~tree.map_structure` which accumulates
  a *path* while mapping through the structures. A path is a tuple of
  indices and/or keys which uniquely identifies the positions of the
  arguments passed to `func`.

  >>> tree.map_structure_with_path(
  ...     lambda path, v: (path, v**2),
  ...     [{"foo": 42}])
  [{'foo': ((0, 'foo'), 1764)}]

  Args:
    func: A callable that accepts a path and as many arguments as there are
      structures.
    *structures: Arbitrarily nested structures of the same layout.
    **kwargs: The only valid keyword argument is `check_types`. If `True`
      (default) the types of components within the structures have to be match,
      e.g. ``tree.map_structure_with_path(func, [1], (1,))`` will raise a
      `TypeError`, otherwise this is not enforced. Note that namedtuples with
      identical name and fields are considered to be the same type.

  Returns:
    A new structure with the same layout as the given ones. If the
    `structures` have components of varying types, the resulting structure
    will use the same types as ``structures[0]``.

  Raises:
    TypeError: If `func` is not callable or if the `structures` do not
      have the same layout.
    TypeError: If `check_types` is `True` and any two `structures`
      differ in the types of their components.
    ValueError: If no structures were given or if a keyword argument other
      than `check_types` is provided.
  """
  ...

def flatten_up_to(shallow_structure, input_structure, check_types=...): # -> list[Any]:
  """Flattens `input_structure` up to `shallow_structure`.

  All further nested components in `input_structure` are retained as-is.

  >>> structure = [[1, 1], [2, 2]]
  >>> tree.flatten_up_to([None, None], structure)
  [[1, 1], [2, 2]]
  >>> tree.flatten_up_to([None, [None, None]], structure)
  [[1, 1], 2, 2]

  If `shallow_structure` and `input_structure` are not nested, the
  result is a single-element list:

  >>> tree.flatten_up_to(42, 1)
  [1]
  >>> tree.flatten_up_to(42, [1, 2, 3])
  [[1, 2, 3]]

  Args:
    shallow_structure: A structure with the same (but possibly more shallow)
      layout as `input_structure`.
    input_structure: An arbitrarily nested structure.
    check_types: If `True`, check that each node in shallow_tree has the
      same type as the corresponding node in `input_structure`.

  Returns:
    A list, the partially flattened version of `input_structure` wrt
    `shallow_structure`.

  Raises:
    TypeError: If the layout of `shallow_structure` does not match that of
      `input_structure`.
    TypeError: If `check_types` is `True` and `shallow_structure` and
      `input_structure` differ in the types of their components.
  """
  ...

def flatten_with_path_up_to(shallow_structure, input_structure, check_types=...): # -> list[tuple[tuple[()], Any] | tuple[tuple[()] | Any, Any]]:
  """Flattens `input_structure` up to `shallow_structure`.

  This is a combination of :func:`~tree.flatten_up_to` and
  :func:`~tree.flatten_with_path`

  Args:
    shallow_structure: A structure with the same (but possibly more shallow)
      layout as `input_structure`.
    input_structure: An arbitrarily nested structure.
    check_types: If `True`, check that each node in shallow_tree has the
      same type as the corresponding node in `input_structure`.

  Returns:
    A list of ``(path, item)`` pairs corresponding to the partially flattened
    version of `input_structure` wrt `shallow_structure`.

  Raises:
    TypeError: If the layout of `shallow_structure` does not match that of
      `input_structure`.
    TypeError: If `input_structure` is or contains a mapping with non-sortable
      keys.
    TypeError: If `check_types` is `True` and `shallow_structure` and
      `input_structure` differ in the types of their components.
  """
  ...

def map_structure_up_to(shallow_structure, func, *structures, **kwargs): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy:
  """Maps `func` through given structures up to `shallow_structure`.

  This is a variant of :func:`~tree.map_structure` which only maps
  the given structures up to `shallow_structure`. All further nested
  components are retained as-is.

  >>> structure = [[1, 1], [2, 2]]
  >>> tree.map_structure_up_to([None, None], len, structure)
  [2, 2]
  >>> tree.map_structure_up_to([None, [None, None]], str, structure)
  ['[1, 1]', ['2', '2']]

  Args:
    shallow_structure: A structure with layout common to all `structures`.
    func: A callable that accepts as many arguments as there are structures.
    *structures: Arbitrarily nested structures of the same layout.
    **kwargs: No valid keyword arguments.
  Raises:
    ValueError: If `func` is not callable or if `structures` have different
      layout or if the layout of `shallow_structure` does not match that of
      `structures` or if no structures were given.

  Returns:
    A new structure with the same layout as `shallow_structure`.
  """
  ...

def map_structure_with_path_up_to(shallow_structure, func, *structures, **kwargs): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy:
  """Maps `func` through given structures up to `shallow_structure`.

  This is a combination of :func:`~tree.map_structure_up_to` and
  :func:`~tree.map_structure_with_path`

  Args:
    shallow_structure: A structure with layout common to all `structures`.
    func: A callable that accepts a path and as many arguments as there are
      structures.
    *structures: Arbitrarily nested structures of the same layout.
    **kwargs: No valid keyword arguments.

  Raises:
    ValueError: If `func` is not callable or if `structures` have different
      layout or if the layout of `shallow_structure` does not match that of
      `structures` or if no structures were given.

  Returns:
    Result of repeatedly applying `func`. Has the same structure layout
    as `shallow_tree`.
  """
  ...

def flatten_with_path(structure): # -> list[tuple[tuple[()], Any] | tuple[tuple[()] | Any, Any]]:
  r"""Flattens a possibly nested structure into a list.

  This is a variant of :func:`~tree.flattens` which produces a list of
  pairs: ``(path, item)``.  A path is a tuple of indices and/or keys
  which uniquely identifies the position of the corresponding ``item``.

  >>> tree.flatten_with_path([{"foo": 42}])
  [((0, 'foo'), 42)]

  Args:
    structure: An arbitrarily nested structure.

  Returns:
    A list of ``(path, item)`` pairs corresponding to the flattened version
    of the input `structure`.

  Raises:
    TypeError:
      If ``structure`` is or contains a mapping with non-sortable keys.
  """
  ...

MAP_TO_NONE = ...
def traverse(fn, structure, top_down=...): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy | None:
  """Traverses the given nested structure, applying the given function.

  The traversal is depth-first. If ``top_down`` is True (default), parents
  are returned before their children (giving the option to avoid traversing
  into a sub-tree).

  >>> visited = []
  >>> tree.traverse(visited.append, [(1, 2), [3], {"a": 4}], top_down=True)
  [(1, 2), [3], {'a': 4}]
  >>> visited
  [[(1, 2), [3], {'a': 4}], (1, 2), 1, 2, [3], 3, {'a': 4}, 4]

  >>> visited = []
  >>> tree.traverse(visited.append, [(1, 2), [3], {"a": 4}], top_down=False)
  [(1, 2), [3], {'a': 4}]
  >>> visited
  [1, 2, (1, 2), 3, [3], 4, {'a': 4}, [(1, 2), [3], {'a': 4}]]

  Args:
    fn: The function to be applied to each sub-nest of the structure.

      When traversing top-down:
        If ``fn(subtree) is None`` the traversal continues into the sub-tree.
        If ``fn(subtree) is not None`` the traversal does not continue into
        the sub-tree. The sub-tree will be replaced by ``fn(subtree)`` in the
        returned structure (to replace the sub-tree with None, use the special
        value :data:`MAP_TO_NONE`).

      When traversing bottom-up:
        If ``fn(subtree) is None`` the traversed sub-tree is returned unaltered.
        If ``fn(subtree) is not None`` the sub-tree will be replaced by
        ``fn(subtree)`` in the returned structure (to replace the sub-tree
        with None, use the special value :data:`MAP_TO_NONE`).

    structure: The structure to traverse.
    top_down: If True, parent structures will be visited before their children.

  Returns:
    The structured output from the traversal.
  """
  ...

def traverse_with_path(fn, structure, top_down=...): # -> defaultdict[Any, Any] | MappingProxyType[Any, Any] | Mapping[Any, Any] | dict[Any, Any] | list[Any] | Any | ObjectProxy | None:
  """Traverses the given nested structure, applying the given function.

  The traversal is depth-first. If ``top_down`` is True (default), parents
  are returned before their children (giving the option to avoid traversing
  into a sub-tree).

  >>> visited = []
  >>> tree.traverse_with_path(
  ...  lambda path, subtree: visited.append((path, subtree)),
  ...  [(1, 2), [3], {"a": 4}],
  ...  top_down=True)
  [(1, 2), [3], {'a': 4}]
  >>> visited == [
  ...  ((), [(1, 2), [3], {'a': 4}]),
  ...  ((0,), (1, 2)),
  ...  ((0, 0), 1),
  ...  ((0, 1), 2),
  ...  ((1,), [3]),
  ...  ((1, 0), 3),
  ...  ((2,), {'a': 4}),
  ...  ((2, 'a'), 4)]
  True

  >>> visited = []
  >>> tree.traverse_with_path(
  ...  lambda path, subtree: visited.append((path, subtree)),
  ...  [(1, 2), [3], {"a": 4}],
  ...  top_down=False)
  [(1, 2), [3], {'a': 4}]
  >>> visited == [
  ...  ((0, 0), 1),
  ...  ((0, 1), 2),
  ...  ((0,), (1, 2)),
  ...  ((1, 0), 3),
  ...  ((1,), [3]),
  ...  ((2, 'a'), 4),
  ...  ((2,), {'a': 4}),
  ... ((), [(1, 2), [3], {'a': 4}])]
  True

  Args:
    fn: The function to be applied to the path to each sub-nest of the structure
      and the sub-nest value.
      When traversing top-down: If ``fn(path, subtree) is None`` the traversal
        continues into the sub-tree. If ``fn(path, subtree) is not None`` the
        traversal does not continue into the sub-tree. The sub-tree will be
        replaced by ``fn(path, subtree)`` in the returned structure (to replace
        the sub-tree with None, use the special
        value :data:`MAP_TO_NONE`).
      When traversing bottom-up: If ``fn(path, subtree) is None`` the traversed
        sub-tree is returned unaltered. If ``fn(path, subtree) is not None`` the
        sub-tree will be replaced by ``fn(path, subtree)`` in the returned
        structure (to replace the sub-tree
        with None, use the special value :data:`MAP_TO_NONE`).
    structure: The structure to traverse.
    top_down: If True, parent structures will be visited before their children.

  Returns:
    The structured output from the traversal.
  """
  ...

