kd_ext.kv.types.View API

A view on a particular path inside an object.

See the docstring for view() method for more details.

View.__init__(self, obj: Any, depth: int, internal_call: object, /)

Internal constructor. Please use kv.view() instead.

View.append(self, value: ViewOrAutoBoxType)

Appends an item or items to all containers in the view.

View.collapse(self, ndim: int = 1) -> View

Collapses equal items along the specified number dimensions of the view.

View.deep_clone(self) -> View

Returns a deep copy of the view.

View.deep_map(self, f: Callable[[Any], Any], *, include_missing: bool = False, namespace: str = '') -> View

Applies a function to every nested primitive value in the view.

Unlike `map`, which applies the function to each value at the current depth,
`deep_map` traverses nested structures indiscriminately using
`optree.tree_map` while keeping structures intact. See
https://optree.readthedocs.io for more details on how to register handlers
for custom types.

Example:
  view([1, None, 2]).deep_map(lambda x: x * 2).get()
  # [2, None, 4]
  view([1, None, 2])[:].deep_map(lambda x: x * 2).get()
  # (2, None, 4)
  view([{'x': 1, 'y': 2, 'z': None}]).deep_map(lambda x: x * 2).get()
  # [{'x': 2, 'y': 4, 'z': None}]

Args:
  f: The function to apply.
  include_missing: Specifies whether `f` applies to all items (`=True`) or
    only to present items (`=False`).
  namespace: The namespace to use for the custom type handler.

Returns:
  A new view with the function applied to every nested primitive value.

View.expand_to(self, other: ViewOrAutoBoxType, ndim: int = 0) -> View

Expands the view to the shape of other view.

View.explode(self, ndim: int = 1) -> View

Unnests iterable elements, increasing rank by `ndim`.

View.flatten(self, from_dim: int = 0, to_dim: int | None = None) -> View

Flattens the specified dimensions of the view.

View.get(self) -> Any

Returns an object represented by the view.

Example:
  view('foo').get()
  # 'foo'
  view([[1,2],[3]])[:].get()
  # ([1,2],[3]).
  view([[1,2],[3]])[:][:].get()
  # ((1,2),(3,)).

View.get_attr(self, attr_name: str, default: Any = NO_DEFAULT) -> View

Returns a new view with the given attribute of each item.

View.get_depth(self) -> int

Returns the depth of the view.

View.get_item(self, key_or_index: ViewOrAutoBoxType | slice) -> View

Returns an item or items from the given view containing containers.

View.group_by(self, *args: ViewOrAutoBoxType, sort: bool = False) -> View

Groups items by the values of the given args.

View.implode(self, ndim: int = 1) -> View

Reduces view dimension by grouping items into tuples.

View.inverse_select(self, fltr: ViewOrAutoBoxType) -> View

Restores the original shape that was reduced by select.

View.map(self, f: Callable[[Any], Any], *, ndim: int = 0, include_missing: bool | None = None) -> View

Applies a function to every item in the view.

If `ndim=0`, then the function is applied to the items of the view.
If `ndim=1`, then the function is applied to tuples of items of the
view corresponding to the last dimension. If `ndim=2`, then the function
is applied to tuples of tuples, and so on. The depth of the result is
therefore decreased by `ndim` compared to the depth of `self`.

Example:
  view([1, None, 2])[:].map(lambda x: x * 2).get()
  # (2, None, 4)
  view([1, None, 2]).map(lambda x: x * 2).get()
  # [1, None, 2, 1, None, 2]
  # We have used "*" operator on the list [1, None, 2] and the integer 2.
  view([1, None, 2])[:].map(lambda x: x * 2, ndim=1).get()
  # (1, None, 2, 1, None, 2)
  # Here we have used "*" operator on the tuple (1, None, 2) and the integer
  # 2.

Args:
  f: The function to apply.
  ndim: Dimensionality of items to pass to `f`, must be less or equal to the
    depth of the view.
  include_missing: Specifies whether `f` applies to all items (`=True`) or
    only to present items (`=False`, valid only when `ndim=0`); defaults to
    `False` when `ndim=0`.

Returns:
  A new view with the function applied to every item.

View.select(self, fltr: ViewOrAutoBoxType, expand_filter: bool = True) -> View

Keeps only items in the view where the filter is present.

View.set_attrs(self, /, **attrs: ViewOrAutoBoxType) -> None

Sets the given attributes of each item.

View.set_item(self, key_or_index: ViewOrAutoBoxType, value: ViewOrAutoBoxType)

Sets an item or items for all containers in the view.

View.take(self, index: ViewOrAutoBoxType) -> View

Returns a view with the given index in the last dimension.