API Reference

All public functions are available from the main module.

import pydash

pydash.<function>

This is the recommended way to use pydash.

# OK (importing main module)
import pydash
pydash.where({})

# OK (import from main module)
from pydash import where
where({})

# NOT RECOMMENDED (importing from submodule)
from pydash.collections import where

Only the main pydash module API is guaranteed to adhere to semver. It’s possible that backwards incompatibility outside the main module API could be broken between minor releases.

py_ Instance

There is a special py_ instance available from pydash that supports method calling and method chaining from a single object:

from pydash import py_

# Method calling
py_.initial([1, 2, 3, 4, 5]) == [1, 2, 3, 4]

# Method chaining
py_([1, 2, 3, 4, 5]).initial().value() == [1, 2, 3, 4]

# Method aliasing to underscore suffixed methods that shadow builtin names
py_.map is py_.map_
py_([1, 2, 3]).map(_.to_string).value() == py_([1, 2, 3]).map_(_.to_string).value()

The py_ instance is basically a combination of using pydash.<function> and pydash.chain.

A full listing of aliased py_ methods:

Arrays

Functions that operate on lists.

Added in version 1.0.0.

pydash.arrays.chunk(array: Sequence[T], size: int = 1) List[Sequence[T]][source]

Creates a list of elements split into groups the length of size. If array can’t be split evenly, the final chunk will be the remaining elements.

Parameters:
  • array – List to chunk.

  • size – Chunk size. Defaults to 1.

Returns:

New list containing chunks of array.

Example

>>> chunk([1, 2, 3, 4, 5], 2)
[[1, 2], [3, 4], [5]]

Added in version 1.1.0.

pydash.arrays.compact(array: Iterable[T | None]) List[T][source]

Creates a list with all falsey values of array removed.

Parameters:

array – List to compact.

Returns:

Compacted list.

Example

>>> compact(["", 1, 0, True, False, None])
[1, True]

Added in version 1.0.0.

pydash.arrays.concat(*arrays: Iterable[T]) List[T][source]

Concatenates zero or more lists into one.

Parameters:

arrays – Lists to concatenate.

Returns:

Concatenated list.

Example

>>> concat([1, 2], [3, 4], [[5], [6]])
[1, 2, 3, 4, [5], [6]]

Added in version 2.0.0.

Changed in version 4.0.0: Renamed from cat to concat.

pydash.arrays.difference(array: Iterable[T], *others: Iterable[T]) List[T][source]

Creates a list of list elements not present in others.

Parameters:
  • array – List to process.

  • others – Lists to check.

Returns:

Difference between others.

Example

>>> difference([1, 2, 3], [1], [2])
[3]

Added in version 1.0.0.

pydash.arrays.difference_by(array: Iterable[T], *others: Iterable[T], iteratee: int | str | List | Tuple | Dict | Callable[[T], Any] | None) List[T][source]
pydash.arrays.difference_by(array: Iterable[T], *others: int | str | List | Tuple | Dict | Iterable[T] | Callable[[T], Any]) List[T]

This method is like difference() except that it accepts an iteratee which is invoked for each element of each array to generate the criterion by which they’re compared. The order and references of result values are determined by array. The iteratee is invoked with one argument: (value).

Parameters:
  • array – The array to find the difference of.

  • others – Lists to check for difference with array.

Keyword Arguments:

iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

Difference between others.

Example

>>> difference_by([1.2, 1.5, 1.7, 2.8], [0.9, 3.2], round)
[1.5, 1.7]

Added in version 4.0.0.

pydash.arrays.difference_with(array: Iterable[T], *others: Iterable[T2], comparator: Callable[[T, T2], Any] | None) List[T][source]
pydash.arrays.difference_with(array: Iterable[T], *others: Iterable[T2] | Callable[[T, T2], Any]) List[T]

This method is like difference() except that it accepts a comparator which is invoked to compare the elements of all arrays. The order and references of result values are determined by the first array. The comparator is invoked with two arguments: (arr_val, oth_val).

Parameters:
  • array – The array to find the difference of.

  • others – Lists to check for difference with array.

Keyword Arguments:

comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

Difference between others.

Example

>>> array = ["apple", "banana", "pear"]
>>> others = (["avocado", "pumpkin"], ["peach"])
>>> comparator = lambda a, b: a[0] == b[0]
>>> difference_with(array, *others, comparator=comparator)
['banana']

Added in version 4.0.0.

pydash.arrays.drop(array: Sequence[T], n: int = 1) List[T][source]

Creates a slice of array with n elements dropped from the beginning.

Parameters:
  • array – List to process.

  • n – Number of elements to drop. Defaults to 1.

Returns:

Dropped list.

Example

>>> drop([1, 2, 3, 4], 2)
[3, 4]

Added in version 1.0.0.

Changed in version 1.1.0: Added n argument and removed as alias of rest().

Changed in version 3.0.0: Made n default to 1.

pydash.arrays.drop_right(array: Sequence[T], n: int = 1) List[T][source]

Creates a slice of array with n elements dropped from the end.

Parameters:
  • array – List to process.

  • n – Number of elements to drop. Defaults to 1.

Returns:

Dropped list.

Example

>>> drop_right([1, 2, 3, 4], 2)
[1, 2]

Added in version 1.1.0.

Changed in version 3.0.0: Made n default to 1.

pydash.arrays.drop_right_while(array: Sequence[T], predicate: Callable[[T, int, List[T]], Any]) List[T][source]
pydash.arrays.drop_right_while(array: Sequence[T], predicate: Callable[[T, int], Any]) List[T]
pydash.arrays.drop_right_while(array: Sequence[T], predicate: Callable[[T], Any]) List[T]
pydash.arrays.drop_right_while(array: Sequence[T], predicate: None = None) List[T]

Creates a slice of array excluding elements dropped from the end. Elements are dropped until the predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

Parameters:
  • array – List to process.

  • predicate – Predicate called per iteration

Returns:

Dropped list.

Example

>>> drop_right_while([1, 2, 3, 4], lambda x: x >= 3)
[1, 2]

Added in version 1.1.0.

pydash.arrays.drop_while(array: Sequence[T], predicate: Callable[[T, int, List[T]], Any]) List[T][source]
pydash.arrays.drop_while(array: Sequence[T], predicate: Callable[[T, int], Any]) List[T]
pydash.arrays.drop_while(array: Sequence[T], predicate: Callable[[T], Any]) List[T]
pydash.arrays.drop_while(array: Sequence[T], predicate: None = None) List[T]

Creates a slice of array excluding elements dropped from the beginning. Elements are dropped until the predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

Parameters:
  • array – List to process.

  • predicate – Predicate called per iteration

Returns:

Dropped list.

Example

>>> drop_while([1, 2, 3, 4], lambda x: x < 3)
[3, 4]

Added in version 1.1.0.

pydash.arrays.duplicates(array: Sequence[T], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) List[T][source]

Creates a unique list of duplicate values from array. If iteratee is passed, each element of array is passed through an iteratee before duplicates are computed. The iteratee is invoked with three arguments: (value, index, array). If an object path is passed for iteratee, the created iteratee will return the path value of the given element. If an object is passed for iteratee, the created filter style iteratee will return True for elements that have the properties of the given object, else False.

Parameters:
  • array – List to process.

  • iteratee – Iteratee applied per iteration.

Returns:

List of duplicates.

Example

>>> duplicates([0, 1, 3, 2, 3, 1])
[3, 1]

Added in version 3.0.0.

pydash.arrays.fill(array: Sequence[T], value: T2, start: int = 0, end: int | None = None) List[T | T2][source]

Fills elements of array with value from start up to, but not including, end.

Parameters:
  • array – List to fill.

  • value – Value to fill with.

  • start – Index to start filling. Defaults to 0.

  • end – Index to end filling. Defaults to len(array).

Returns:

Filled array.

Example

>>> fill([1, 2, 3, 4, 5], 0)
[0, 0, 0, 0, 0]
>>> fill([1, 2, 3, 4, 5], 0, 1, 3)
[1, 0, 0, 4, 5]
>>> fill([1, 2, 3, 4, 5], 0, 0, 100)
[0, 0, 0, 0, 0]

Warning

array is modified in place.

Added in version 3.1.0.

pydash.arrays.find_index(array: Iterable[T], predicate: Callable[[T, int, List[T]], Any]) int[source]
pydash.arrays.find_index(array: Iterable[T], predicate: Callable[[T, int], Any]) int
pydash.arrays.find_index(array: Iterable[T], predicate: Callable[[T], Any]) int
pydash.arrays.find_index(array: Iterable[Any], predicate: int | str | List | Tuple | Dict) int
pydash.arrays.find_index(array: Iterable[Any], predicate: None = None) int

This method is similar to pydash.collections.find(), except that it returns the index of the element that passes the predicate check, instead of the element itself.

Parameters:
  • array – List to process.

  • predicate – Predicate applied per iteration.

Returns:

Index of found item or -1 if not found.

Example

>>> find_index([1, 2, 3, 4], lambda x: x >= 3)
2
>>> find_index([1, 2, 3, 4], lambda x: x > 4)
-1

Added in version 1.0.0.

pydash.arrays.find_last_index(array: Iterable[T], predicate: Callable[[T, int, List[T]], Any]) int[source]
pydash.arrays.find_last_index(array: Iterable[T], predicate: Callable[[T, int], Any]) int
pydash.arrays.find_last_index(array: Iterable[T], predicate: Callable[[T], Any]) int
pydash.arrays.find_last_index(array: Iterable[Any], predicate: int | str | List | Tuple | Dict) int
pydash.arrays.find_last_index(array: Iterable[Any], predicate: None = None) int

This method is similar to find_index(), except that it iterates over elements from right to left.

Parameters:
  • array – List to process.

  • predicate – Predicate applied per iteration.

Returns:

Index of found item or -1 if not found.

Example

>>> find_last_index([1, 2, 3, 4], lambda x: x >= 3)
3
>>> find_last_index([1, 2, 3, 4], lambda x: x > 4)
-1

Added in version 1.0.0.

pydash.arrays.flatten(array: Iterable[Iterable[T]]) List[T][source]
pydash.arrays.flatten(array: Iterable[T]) List[T]

Flattens array a single level deep.

Parameters:

array – List to flatten.

Returns:

Flattened list.

Example

>>> flatten([[1], [2, [3]], [[4]]])
[1, 2, [3], [4]]

Added in version 1.0.0.

Changed in version 2.0.0: Removed callback option. Added is_deep option. Made it shallow by default.

Changed in version 4.0.0: Removed is_deep option. Use flatten_deep() instead.

pydash.arrays.flatten_deep(array: Iterable) List[source]

Flattens an array recursively.

Parameters:

array – List to flatten.

Returns:

Flattened list.

Example

>>> flatten_deep([[1], [2, [3]], [[4]]])
[1, 2, 3, 4]

Added in version 2.0.0.

pydash.arrays.flatten_depth(array: Iterable, depth: int = 1) List[source]

Recursively flatten array up to depth times.

Parameters:
  • array – List to flatten.

  • depth – Depth to flatten to. Defaults to 1.

Returns:

Flattened list.

Example

>>> flatten_depth([[[1], [2, [3]], [[4]]]], 1)
[[1], [2, [3]], [[4]]]
>>> flatten_depth([[[1], [2, [3]], [[4]]]], 2)
[1, 2, [3], [4]]
>>> flatten_depth([[[1], [2, [3]], [[4]]]], 3)
[1, 2, 3, 4]
>>> flatten_depth([[[1], [2, [3]], [[4]]]], 4)
[1, 2, 3, 4]

Added in version 4.0.0.

pydash.arrays.from_pairs(pairs: Iterable[Tuple[T, T2]]) Dict[T, T2][source]
pydash.arrays.from_pairs(pairs: Iterable[List[T | T2]]) Dict[T | T2, T | T2]

Returns a dict from the given list of pairs.

Parameters:

pairs – List of key-value pairs.

Returns:

dict

Example

>>> from_pairs([["a", 1], ["b", 2]]) == {"a": 1, "b": 2}
True

Added in version 4.0.0.

pydash.arrays.head(array: Sequence[T]) T | None[source]

Return the first element of array.

Parameters:

array – List to process.

Returns:

First element of list.

Example

>>> head([1, 2, 3, 4])
1

Added in version 1.0.0.

Changed in version Renamed: from first to head.

pydash.arrays.index_of(array: Sequence[T], value: T, from_index: int = 0) int[source]

Gets the index at which the first occurrence of value is found.

Parameters:
  • array – List to search.

  • value – Value to search for.

  • from_index – Index to search from.

Returns:

Index of found item or -1 if not found.

Example

>>> index_of([1, 2, 3, 4], 2)
1
>>> index_of([2, 1, 2, 3], 2, from_index=1)
2

Added in version 1.0.0.

pydash.arrays.initial(array: Sequence[T]) Sequence[T][source]

Return all but the last element of array.

Parameters:

array – List to process.

Returns:

Initial part of array.

Example

>>> initial([1, 2, 3, 4])
[1, 2, 3]

Added in version 1.0.0.

pydash.arrays.intercalate(array: Iterable[Iterable[T]], separator: T2) List[T | T2][source]
pydash.arrays.intercalate(array: Iterable[T], separator: T2) List[T | T2]

Like intersperse() for lists of lists but shallowly flattening the result.

Parameters:
  • array – List to intercalate.

  • separator – Element to insert.

Returns:

Intercalated list.

Example

>>> intercalate([1, [2], [3], 4], "x")
[1, 'x', 2, 'x', 3, 'x', 4]

Added in version 2.0.0.

pydash.arrays.interleave(*arrays: Iterable[T]) List[T][source]

Merge multiple lists into a single list by inserting the next element of each list by sequential round-robin into the new list.

Parameters:

arrays – Lists to interleave.

Returns:

Interleaved list.

Example

>>> interleave([1, 2, 3], [4, 5, 6], [7, 8, 9])
[1, 4, 7, 2, 5, 8, 3, 6, 9]

Added in version 2.0.0.

pydash.arrays.intersection(array: Sequence[T], *others: Iterable[Any]) List[T][source]

Computes the intersection of all the passed-in arrays.

Parameters:
  • array – The array to find the intersection of.

  • others – Lists to check for intersection with array.

Returns:

Intersection of provided lists.

Example

>>> intersection([1, 2, 3], [1, 2, 3, 4, 5], [2, 3])
[2, 3]
>>> intersection([1, 2, 3])
[1, 2, 3]

Added in version 1.0.0.

Changed in version 4.0.0: Support finding intersection of unhashable types.

pydash.arrays.intersection_by(array: Sequence[T], *others: Iterable[Any], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict) List[T][source]
pydash.arrays.intersection_by(array: Sequence[T], *others: Iterable[Any] | Callable[[T], Any] | int | str | List | Tuple | Dict) List[T]

This method is like intersection() except that it accepts an iteratee which is invoked for each element of each array to generate the criterion by which they’re compared. The order and references of result values are determined by array. The iteratee is invoked with one argument: (value).

Parameters:
  • array – The array to find the intersection of.

  • others – Lists to check for intersection with array.

Keyword Arguments:

iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

Intersection of provided lists.

Example

>>> intersection_by([1.2, 1.5, 1.7, 2.8], [0.9, 3.2], round)
[1.2, 2.8]

Added in version 4.0.0.

pydash.arrays.intersection_with(array: Sequence[T], *others: Iterable[T2], comparator: Callable[[T, T2], Any]) List[T][source]
pydash.arrays.intersection_with(array: Sequence[T], *others: Iterable[T2] | Callable[[T, T2], Any]) List[T]

This method is like intersection() except that it accepts a comparator which is invoked to compare the elements of all arrays. The order and references of result values are determined by the first array. The comparator is invoked with two arguments: (arr_val, oth_val).

Parameters:
  • array – The array to find the intersection of.

  • others – Lists to check for intersection with array.

Keyword Arguments:

comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

Intersection of provided lists.

Example

>>> array = ["apple", "banana", "pear"]
>>> others = (["avocado", "pumpkin"], ["peach"])
>>> comparator = lambda a, b: a[0] == b[0]
>>> intersection_with(array, *others, comparator=comparator)
['pear']

Added in version 4.0.0.

pydash.arrays.intersperse(array: Iterable[T], separator: T2) List[T | T2][source]

Insert a separating element between the elements of array.

Parameters:
  • array – List to intersperse.

  • separator – Element to insert.

Returns:

Interspersed list.

Example

>>> intersperse([1, [2], [3], 4], "x")
[1, 'x', [2], 'x', [3], 'x', 4]

Added in version 2.0.0.

pydash.arrays.last(array: Sequence[T]) T | None[source]

Return the last element of array.

Parameters:

array – List to process.

Returns:

Last part of array.

Example

>>> last([1, 2, 3, 4])
4

Added in version 1.0.0.

pydash.arrays.last_index_of(array: Sequence[Any], value: Any, from_index: int | None = None) int[source]

Gets the index at which the last occurrence of value is found.

Parameters:
  • array – List to search.

  • value – Value to search for.

  • from_index – Index to search from.

Returns:

Index of found item or -1 if not found.

Example

>>> last_index_of([1, 2, 2, 4], 2)
2
>>> last_index_of([1, 2, 2, 4], 2, from_index=1)
1

Added in version 1.0.0.

pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T, int, List[T]], List[T2] | List[List[T2]]]) List[T2][source]
pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T, int, List[T]], T2]) List[T2]
pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T, int], List[T2] | List[List[T2]]]) List[T2]
pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T, int], T2]) List[T2]
pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T], List[T2] | List[List[T2]]]) List[T2]
pydash.arrays.mapcat(array: Iterable[T], iteratee: Callable[[T], T2]) List[T2]
pydash.arrays.mapcat(array: Iterable[List[T] | List[List[T]]], iteratee: None = None) List[T | List[T]]

Map an iteratee to each element of a list and concatenate the results into a single list using concat().

Parameters:
  • array – List to map and concatenate.

  • iteratee – Iteratee to apply to each element.

Returns:

Mapped and concatenated list.

Example

>>> mapcat(range(4), lambda x: list(range(x)))
[0, 0, 1, 0, 1, 2]

Added in version 2.0.0.

pydash.arrays.nth(array: Iterable[T], pos: int = 0) T | None[source]

Gets the element at index n of array.

Parameters:
  • array – List passed in by the user.

  • pos – Index of element to return.

Returns:

Returns the element at pos.

Example

>>> nth([1, 2, 3], 0)
1
>>> nth([3, 4, 5, 6], 2)
5
>>> nth([11, 22, 33], -1)
33
>>> nth([11, 22, 33])
11

Added in version 4.0.0.

pydash.arrays.pull(array: List[T], *values: T) List[T][source]

Removes all provided values from the given array.

Parameters:
  • array – List to pull from.

  • values – Values to remove.

Returns:

Modified array.

Warning

array is modified in place.

Example

>>> pull([1, 2, 2, 3, 3, 4], 2, 3)
[1, 4]

Added in version 1.0.0.

Changed in version 4.0.0: pull() method now calls pull_all() method for the desired functionality.

pydash.arrays.pull_all(array: List[T], values: Iterable[T]) List[T][source]

Removes all provided values from the given array.

Parameters:
  • array – Array to modify.

  • values – Values to remove.

Returns:

Modified array.

Example

>>> pull_all([1, 2, 2, 3, 3, 4], [2, 3])
[1, 4]

Added in version 4.0.0.

pydash.arrays.pull_all_by(array: List[T], values: Iterable[T], iteratee: int | str | List | Tuple | Dict | Callable[[T], Any] | None = None) List[T][source]

This method is like pull_all() except that it accepts iteratee which is invoked for each element of array and values to generate the criterion by which they’re compared. The iteratee is invoked with one argument: (value).

Parameters:
  • array – Array to modify.

  • values – Values to remove.

  • iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

Modified array.

Example

>>> array = [{"x": 1}, {"x": 2}, {"x": 3}, {"x": 1}]
>>> pull_all_by(array, [{"x": 1}, {"x": 3}], "x")
[{'x': 2}]

Added in version 4.0.0.

pydash.arrays.pull_all_with(array: List[T], values: Iterable[T], comparator: Callable[[T, T], Any] | None = None) List[T][source]

This method is like pull_all() except that it accepts comparator which is invoked to compare elements of array to values. The comparator is invoked with two arguments: (arr_val, oth_val).

Parameters:
  • array – Array to modify.

  • values – Values to remove.

  • comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

Modified array.

Example

>>> array = [{"x": 1, "y": 2}, {"x": 3, "y": 4}, {"x": 5, "y": 6}]
>>> res = pull_all_with(array, [{"x": 3, "y": 4}], lambda a, b: a == b)
>>> res == [{"x": 1, "y": 2}, {"x": 5, "y": 6}]
True
>>> array = [{"x": 1, "y": 2}, {"x": 3, "y": 4}, {"x": 5, "y": 6}]
>>> res = pull_all_with(array, [{"x": 3, "y": 4}], lambda a, b: a != b)
>>> res == [{"x": 3, "y": 4}]
True

Added in version 4.0.0.

pydash.arrays.pull_at(array: List[T], *indexes: int) List[T][source]

Removes elements from array corresponding to the specified indexes and returns a list of the removed elements. Indexes may be specified as a list of indexes or as individual arguments.

Parameters:
  • array – List to pull from.

  • indexes – Indexes to pull.

Returns:

Modified array.

Warning

array is modified in place.

Example

>>> pull_at([1, 2, 3, 4], 0, 2)
[2, 4]

Added in version 1.1.0.

pydash.arrays.push(array: List[T], *items: T2) List[T | T2][source]

Push items onto the end of array and return modified array.

Parameters:
  • array – List to push to.

  • items – Items to append.

Returns:

Modified array.

Warning

array is modified in place.

Example

>>> array = [1, 2, 3]
>>> push(array, 4, 5, [6])
[1, 2, 3, 4, 5, [6]]

Added in version 2.2.0.

Changed in version 4.0.0: Removed alias append.

pydash.arrays.remove(array: List[T], predicate: Callable[[T, int, List[T]], Any] | Callable[[T, int], Any] | Callable[[T], Any] | None = None) List[T][source]

Removes all elements from a list that the predicate returns truthy for and returns an array of removed elements.

Parameters:
  • array – List to remove elements from.

  • predicate – Predicate applied per iteration.

Returns:

Removed elements of array.

Warning

array is modified in place.

Example

>>> array = [1, 2, 3, 4]
>>> items = remove(array, lambda x: x >= 3)
>>> items
[3, 4]
>>> array
[1, 2]

Added in version 1.0.0.

pydash.arrays.reverse(array: SequenceT) SequenceT[source]

Return array in reverse order.

Parameters:

array – Object to process.

Returns:

Reverse of object.

Example

>>> reverse([1, 2, 3, 4])
[4, 3, 2, 1]

Added in version 2.2.0.

pydash.arrays.shift(array: List[T]) T[source]

Remove the first element of array and return it.

Parameters:

array – List to shift.

Returns:

First element of array.

Warning

array is modified in place.

Example

>>> array = [1, 2, 3, 4]
>>> item = shift(array)
>>> item
1
>>> array
[2, 3, 4]

Added in version 2.2.0.

pydash.arrays.slice_(array: SequenceT, start: int = 0, end: int | None = None) SequenceT[source]

Slices array from the start index up to, but not including, the end index.

Parameters:
  • array – Array to slice.

  • start – Start index. Defaults to 0.

  • end – End index. Defaults to selecting the value at start index.

Returns:

Sliced list.

Example

>>> slice_([1, 2, 3, 4])
[1]
>>> slice_([1, 2, 3, 4], 1)
[2]
>>> slice_([1, 2, 3, 4], 1, 3)
[2, 3]

Added in version 1.1.0.

pydash.arrays.sort(array: t.List['SupportsRichComparisonT'], comparator: None = None, key: None = None, reverse: bool = False) t.List['SupportsRichComparisonT'][source]
pydash.arrays.sort(array: List[T], comparator: Callable[[T, T], int], *, reverse: bool = False) List[T]
pydash.arrays.sort(array: List[T], *, key: t.Callable[[T], 'SupportsRichComparisonT'], reverse: bool = False) List[T]

Sort array using optional comparator, key, and reverse options and return sorted array.

Note

Python 3 removed the option to pass a custom comparator function and instead only allows a key function. Therefore, if a comparator function is passed in, it will be converted to a key function automatically using functools.cmp_to_key.

Parameters:
  • array – List to sort.

  • comparator – A custom comparator function used to sort the list. Function should accept two arguments and return a negative, zero, or position number depending on whether the first argument is considered smaller than, equal to, or larger than the second argument. Defaults to None. This argument is mutually exclusive with key.

  • key – A function of one argument used to extract a comparator key from each list element. Defaults to None. This argument is mutually exclusive with comparator.

  • reverse – Whether to reverse the sort. Defaults to False.

Returns:

Sorted list.

Warning

array is modified in place.

Example

>>> sort([2, 1, 4, 3])
[1, 2, 3, 4]
>>> sort([2, 1, 4, 3], reverse=True)
[4, 3, 2, 1]
>>> results = sort([{'a': 2, 'b': 1},                            {'a': 3, 'b': 2},                            {'a': 0, 'b': 3}],                           key=lambda item: item['a'])
>>> assert results == [{'a': 0, 'b': 3},                               {'a': 2, 'b': 1},                               {'a': 3, 'b': 2}]

Added in version 2.2.0.

pydash.arrays.sorted_index(array: Sequence[SupportsRichComparisonT], value: SupportsRichComparisonT) int[source]

Uses a binary search to determine the lowest index at which value should be inserted into array in order to maintain its sort order.

Parameters:
  • array – List to inspect.

  • value – Value to evaluate.

Returns:

Returns the index at which value should be inserted into array.

Example

>>> sorted_index([1, 2, 2, 3, 4], 2)
1

Added in version 1.0.0.

Changed in version 4.0.0: Move iteratee support to sorted_index_by().

pydash.arrays.sorted_index_by(array: Sequence[T], value: T, iteratee: t.Union[IterateeObjT, t.Callable[[T], 'SupportsRichComparisonT']]) int[source]
pydash.arrays.sorted_index_by(array: t.Sequence['SupportsRichComparisonT'], value: SupportsRichComparisonT, iteratee: None = None) int

This method is like sorted_index() except that it accepts iteratee which is invoked for value and each element of array to compute their sort ranking. The iteratee is invoked with one argument: (value).

Parameters:
  • array – List to inspect.

  • value – Value to evaluate.

  • iteratee – The iteratee invoked per element. Defaults to identity().

Returns:

Returns the index at which value should be inserted into array.

Example

>>> array = [{"x": 4}, {"x": 5}]
>>> sorted_index_by(array, {"x": 4}, lambda o: o["x"])
0
>>> sorted_index_by(array, {"x": 4}, "x")
0

Added in version 4.0.0.

pydash.arrays.sorted_index_of(array: Sequence[SupportsRichComparisonT], value: SupportsRichComparisonT) int[source]

Returns the index of the matched value from the sorted array, else -1.

Parameters:
  • array – Array to inspect.

  • value – Value to search for.

Returns:

Returns the index of the first matched value, else -1.

Example

>>> sorted_index_of([3, 5, 7, 10], 3)
0
>>> sorted_index_of([10, 10, 5, 7, 3], 10)
-1

Added in version 4.0.0.

pydash.arrays.sorted_last_index(array: Sequence[SupportsRichComparisonT], value: SupportsRichComparisonT) int[source]

This method is like sorted_index() except that it returns the highest index at which value should be inserted into array in order to maintain its sort order.

Parameters:
  • array – List to inspect.

  • value – Value to evaluate.

Returns:

Returns the index at which value should be inserted into array.

Example

>>> sorted_last_index([1, 2, 2, 3, 4], 2)
3

Added in version 1.1.0.

Changed in version 4.0.0: Move iteratee support to sorted_last_index_by().

pydash.arrays.sorted_last_index_by(array: Sequence[T], value: T, iteratee: t.Union[IterateeObjT, t.Callable[[T], 'SupportsRichComparisonT']]) int[source]
pydash.arrays.sorted_last_index_by(array: t.Sequence['SupportsRichComparisonT'], value: SupportsRichComparisonT, iteratee: None = None) int

This method is like sorted_last_index() except that it accepts iteratee which is invoked for value and each element of array to compute their sort ranking. The iteratee is invoked with one argument: (value).

Parameters:
  • array – List to inspect.

  • value – Value to evaluate.

  • iteratee – The iteratee invoked per element. Defaults to identity().

Returns:

Returns the index at which value should be inserted into array.

Example

>>> array = [{"x": 4}, {"x": 5}]
>>> sorted_last_index_by(array, {"x": 4}, lambda o: o["x"])
1
>>> sorted_last_index_by(array, {"x": 4}, "x")
1
pydash.arrays.sorted_last_index_of(array: Sequence[SupportsRichComparisonT], value: SupportsRichComparisonT) int[source]

This method is like last_index_of() except that it performs a binary search on a sorted array.

Parameters:
  • array – Array to inspect.

  • value – Value to search for.

Returns:

Returns the index of the matched value, else -1.

Example

>>> sorted_last_index_of([4, 5, 5, 5, 6], 5)
3
>>> sorted_last_index_of([6, 5, 5, 5, 4], 6)
-1

Added in version 4.0.0.

pydash.arrays.sorted_uniq(array: Iterable[SupportsRichComparisonT]) List[SupportsRichComparisonT][source]

Return sorted array with unique elements.

Parameters:

array – List of values to be sorted.

Returns:

List of unique elements in a sorted fashion.

Example

>>> sorted_uniq([4, 2, 2, 5])
[2, 4, 5]
>>> sorted_uniq([-2, -2, 4, 1])
[-2, 1, 4]

Added in version 4.0.0.

pydash.arrays.sorted_uniq_by(array: Iterable[SupportsRichComparisonT], iteratee: Callable[[SupportsRichComparisonT], SupportsRichComparisonT] | None = None) List[SupportsRichComparisonT][source]

This method is like sorted_uniq() except that it accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed. The order of result values is determined by the order they occur in the array. The iteratee is invoked with one argument: (value).

Parameters:
  • array – List of values to be sorted.

  • iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

Unique list.

Example

>>> sorted_uniq_by([3, 2, 1, 3, 2, 1], lambda val: val % 2)
[2, 3]

Added in version 4.0.0.

pydash.arrays.splice(array: MutableSequenceT, start: int, count: int | None = None, *items: Any) MutableSequenceT[source]

Modify the contents of array by inserting elements starting at index start and removing count number of elements after.

Parameters:
  • array – List to splice.

  • start – Start to splice at.

  • count – Number of items to remove starting at start. If None then all items after start are removed. Defaults to None.

  • items – Elements to insert starting at start. Each item is inserted in the order given.

Returns:

The removed elements of array or the spliced string.

Warning

array is modified in place if list.

Example

>>> array = [1, 2, 3, 4]
>>> splice(array, 1)
[2, 3, 4]
>>> array
[1]
>>> array = [1, 2, 3, 4]
>>> splice(array, 1, 2)
[2, 3]
>>> array
[1, 4]
>>> array = [1, 2, 3, 4]
>>> splice(array, 1, 2, 0, 0)
[2, 3]
>>> array
[1, 0, 0, 4]

Added in version 2.2.0.

Changed in version 3.0.0: Support string splicing.

pydash.arrays.split_at(array: Sequence[T], index: int) List[Sequence[T]][source]

Returns a list of two lists composed of the split of array at index.

Parameters:
  • array – List to split.

  • index – Index to split at.

Returns:

Split list.

Example

>>> split_at([1, 2, 3, 4], 2)
[[1, 2], [3, 4]]

Added in version 2.0.0.

pydash.arrays.tail(array: Sequence[T]) Sequence[T][source]

Return all but the first element of array.

Parameters:

array – List to process.

Returns:

Rest of the list.

Example

>>> tail([1, 2, 3, 4])
[2, 3, 4]

Added in version 1.0.0.

Changed in version 4.0.0: Renamed from rest to tail.

pydash.arrays.take(array: Sequence[T], n: int = 1) Sequence[T][source]

Creates a slice of array with n elements taken from the beginning.

Parameters:
  • array – List to process.

  • n – Number of elements to take. Defaults to 1.

Returns:

Taken list.

Example

>>> take([1, 2, 3, 4], 2)
[1, 2]

Added in version 1.0.0.

Changed in version 1.1.0: Added n argument and removed as alias of first().

Changed in version 3.0.0: Made n default to 1.

pydash.arrays.take_right(array: Sequence[T], n: int = 1) Sequence[T][source]

Creates a slice of array with n elements taken from the end.

Parameters:
  • array – List to process.

  • n – Number of elements to take. Defaults to 1.

Returns:

Taken list.

Example

>>> take_right([1, 2, 3, 4], 2)
[3, 4]

Added in version 1.1.0.

Changed in version 3.0.0: Made n default to 1.

pydash.arrays.take_right_while(array: Sequence[T], predicate: Callable[[T, int, List[T]], Any]) Sequence[T][source]
pydash.arrays.take_right_while(array: Sequence[T], predicate: Callable[[T, int], Any]) Sequence[T]
pydash.arrays.take_right_while(array: Sequence[T], predicate: Callable[[T], Any]) Sequence[T]
pydash.arrays.take_right_while(array: Sequence[T], predicate: None = None) Sequence[T]

Creates a slice of array with elements taken from the end. Elements are taken until the predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

Parameters:
  • array – List to process.

  • predicate – Predicate called per iteration

Returns:

Dropped list.

Example

>>> take_right_while([1, 2, 3, 4], lambda x: x >= 3)
[3, 4]

Added in version 1.1.0.

pydash.arrays.take_while(array: Sequence[T], predicate: Callable[[T, int, List[T]], Any]) List[T][source]
pydash.arrays.take_while(array: Sequence[T], predicate: Callable[[T, int], Any]) List[T]
pydash.arrays.take_while(array: Sequence[T], predicate: Callable[[T], Any]) List[T]
pydash.arrays.take_while(array: Sequence[T], predicate: None = None) List[T]

Creates a slice of array with elements taken from the beginning. Elements are taken until the predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

Parameters:
  • array – List to process.

  • predicate – Predicate called per iteration

Returns:

Taken list.

Example

>>> take_while([1, 2, 3, 4], lambda x: x < 3)
[1, 2]

Added in version 1.1.0.

pydash.arrays.union(array: Sequence[T]) List[T][source]
pydash.arrays.union(array: Sequence[T], *others: Sequence[T2]) List[T | T2]

Computes the union of the passed-in arrays.

Parameters:
  • array – List to union with.

  • others – Lists to unionize with array.

Returns:

Unionized list.

Example

>>> union([1, 2, 3], [2, 3, 4], [3, 4, 5])
[1, 2, 3, 4, 5]

Added in version 1.0.0.

pydash.arrays.union_by(array: Sequence[T], *others: Iterable[T], iteratee: Callable[[T], Any]) List[T][source]
pydash.arrays.union_by(array: Sequence[T], *others: Iterable[T] | Callable[[T], Any]) List[T]

This method is similar to union() except that it accepts iteratee which is invoked for each element of each array to generate the criterion by which uniqueness is computed.

Parameters:
  • array – List to unionize with.

  • others – Lists to unionize with array.

Keyword Arguments:

iteratee – Function to invoke on each element.

Returns:

Unionized list.

Example

>>> union_by([1, 2, 3], [2, 3, 4], iteratee=lambda x: x % 2)
[1, 2]
>>> union_by([1, 2, 3], [2, 3, 4], iteratee=lambda x: x % 9)
[1, 2, 3, 4]

Added in version 4.0.0.

pydash.arrays.union_with(array: Sequence[T], *others: Iterable[T2], comparator: Callable[[T, T2], Any]) List[T][source]
pydash.arrays.union_with(array: Sequence[T], *others: Iterable[T2] | Callable[[T, T2], Any]) List[T]

This method is like union() except that it accepts comparator which is invoked to compare elements of arrays. Result values are chosen from the first array in which the value occurs.

Parameters:
  • array – List to unionize with.

  • others – Lists to unionize with array.

Keyword Arguments:

comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

Unionized list.

Example

>>> comparator = lambda a, b: (a % 2) == (b % 2)
>>> union_with([1, 2, 3], [2, 3, 4], comparator=comparator)
[1, 2]
>>> union_with([1, 2, 3], [2, 3, 4])
[1, 2, 3, 4]

Added in version 4.0.0.

pydash.arrays.uniq(array: Iterable[T]) List[T][source]

Creates a duplicate-value-free version of the array. If iteratee is passed, each element of array is passed through an iteratee before uniqueness is computed. The iteratee is invoked with three arguments: (value, index, array). If an object path is passed for iteratee, the created iteratee will return the path value of the given element. If an object is passed for iteratee, the created filter style iteratee will return True for elements that have the properties of the given object, else False.

Parameters:

array – List to process.

Returns:

Unique list.

Example

>>> uniq([1, 2, 3, 1, 2, 3])
[1, 2, 3]

Added in version 1.0.0.

Changed in version 4.0.0:

  • Moved iteratee argument to uniq_by().

  • Removed alias unique.

pydash.arrays.uniq_by(array: Iterable[T], iteratee: Callable[[T], Any] | None = None) List[T][source]

This method is like uniq() except that it accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed. The order of result values is determined by the order they occur in the array. The iteratee is invoked with one argument: (value).

Parameters:
  • array – List to process.

  • iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

Unique list.

Example

>>> uniq_by([1, 2, 3, 1, 2, 3], lambda val: val % 2)
[1, 2]

Added in version 4.0.0.

pydash.arrays.uniq_with(array: Sequence[T], comparator: Callable[[T, T], Any] | None = None) List[T][source]

This method is like uniq() except that it accepts comparator which is invoked to compare elements of array. The order of result values is determined by the order they occur in the array.The comparator is invoked with two arguments: (value, other).

Parameters:
  • array – List to process.

  • comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

Unique list.

Example

>>> uniq_with([1, 2, 3, 4, 5], lambda a, b: (a % 2) == (b % 2))
[1, 2]

Added in version 4.0.0.

pydash.arrays.unshift(array: List[T], *items: T2) List[T | T2][source]

Insert the given elements at the beginning of array and return the modified list.

Parameters:
  • array – List to modify.

  • items – Items to insert.

Returns:

Modified list.

Warning

array is modified in place.

Example

>>> array = [1, 2, 3, 4]
>>> unshift(array, -1, -2)
[-1, -2, 1, 2, 3, 4]
>>> array
[-1, -2, 1, 2, 3, 4]

Added in version 2.2.0.

pydash.arrays.unzip(array: Iterable[Tuple[T, T2]]) List[Tuple[T, T2]][source]
pydash.arrays.unzip(array: Iterable[Tuple[T, T2, T3]]) List[Tuple[T, T2, T3]]
pydash.arrays.unzip(array: Iterable[Tuple[T, T2, T3, T4]]) List[Tuple[T, T2, T3, T4]]
pydash.arrays.unzip(array: Iterable[Tuple[T, T2, T3, T4, T5]]) List[Tuple[T, T2, T3, T4, T5]]
pydash.arrays.unzip(array: Iterable[Iterable[Any]]) List[Tuple[Any, ...]]

The inverse of zip_(), this method splits groups of elements into tuples composed of elements from each group at their corresponding indexes.

Parameters:

array – List to process.

Returns:

Unzipped list.

Example

>>> unzip([(1, 4, 7), (2, 5, 8), (3, 6, 9)])
[(1, 2, 3), (4, 5, 6), (7, 8, 9)]

Added in version 1.0.0.

Changed in version 8.0.0: Support list of tuples instead.

pydash.arrays.unzip_with(array: Iterable[Tuple[T, T2]], iteratee: Callable[[T | T2 | T3, T | T2, int], T3] | Callable[[T | T2 | T3, T | T2], T3] | Callable[[T | T2 | T3], T3]) List[T3][source]
pydash.arrays.unzip_with(array: Iterable[Iterable[Any]], iteratee: Callable[[Any, Any, int], T3] | Callable[[Any, Any], T3] | Callable[[Any], T3]) List[T3]
pydash.arrays.unzip_with(array: Iterable[Iterable[T]], iteratee: None = None) List[Tuple[T]]

This method is like unzip() except that it accepts an iteratee to specify how regrouped values should be combined. The iteratee is invoked with three arguments: (accumulator, value, index).

Parameters:
  • array – List to process.

  • iteratee – Function to combine regrouped values.

Returns:

Unzipped list.

Example

>>> from pydash import add
>>> unzip_with([(1, 10, 100), (2, 20, 200)], add)
[3, 30, 300]

Added in version 3.3.0.

pydash.arrays.without(array: Iterable[T], *values: T) List[T][source]

Creates an array with all occurrences of the passed values removed.

Parameters:
  • array – List to filter.

  • values – Values to remove.

Returns:

Filtered list.

Example

>>> without([1, 2, 3, 2, 4, 4], 2, 4)
[1, 3]

Added in version 1.0.0.

pydash.arrays.xor(array: Iterable[T], *lists: Iterable[T]) List[T][source]

Creates a list that is the symmetric difference of the provided lists.

Parameters:
  • array – List to process.

  • *lists – Lists to xor with.

Returns:

XOR’d list.

Example

>>> xor([1, 3, 4], [1, 2, 4], [2])
[3]

Added in version 1.0.0.

pydash.arrays.xor_by(array: Iterable[T], *lists: Iterable[T], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict) List[T][source]
pydash.arrays.xor_by(array: Iterable[T], *lists: Iterable[T] | Callable[[T], Any]) List[T]

This method is like xor() except that it accepts iteratee which is invoked for each element of each arras to generate the criterion by which they’re compared. The order of result values is determined by the order they occur in the arrays. The iteratee is invoked with one argument: (value).

Parameters:
  • array – List to process.

  • *lists – Lists to xor with.

Keyword Arguments:

iteratee – Function to transform the elements of the arrays. Defaults to identity().

Returns:

XOR’d list.

Example

>>> xor_by([2.1, 1.2], [2.3, 3.4], round)
[1.2, 3.4]
>>> xor_by([{"x": 1}], [{"x": 2}, {"x": 1}], "x")
[{'x': 2}]

Added in version 4.0.0.

pydash.arrays.xor_with(array: Sequence[T], *lists: Iterable[T2], comparator: Callable[[T, T2], Any]) List[T][source]
pydash.arrays.xor_with(array: Sequence[T], *lists: Iterable[T2] | Callable[[T, T2], Any]) List[T]

This method is like xor() except that it accepts comparator which is invoked to compare elements of arrays. The order of result values is determined by the order they occur in the arrays. The comparator is invoked with two arguments: (arr_val, oth_val).

Parameters:
  • array – List to process.

  • *lists – Lists to xor with.

Keyword Arguments:

comparator – Function to compare the elements of the arrays. Defaults to is_equal().

Returns:

XOR’d list.

Example

>>> objects = [{"x": 1, "y": 2}, {"x": 2, "y": 1}]
>>> others = [{"x": 1, "y": 1}, {"x": 1, "y": 2}]
>>> expected = [{"y": 1, "x": 2}, {"y": 1, "x": 1}]
>>> xor_with(objects, others, lambda a, b: a == b) == expected
True

Added in version 4.0.0.

pydash.arrays.zip_(array1: Iterable[T], array2: Iterable[T2], /) List[Tuple[T, T2]][source]
pydash.arrays.zip_(array1: Iterable[T], array2: Iterable[T2], array3: Iterable[T3], /) List[Tuple[T, T2, T3]]
pydash.arrays.zip_(array1: Iterable[T], array2: Iterable[T2], array3: Iterable[T3], array4: Iterable[T4], /) List[Tuple[T, T2, T3, T4]]
pydash.arrays.zip_(array1: Iterable[T], array2: Iterable[T2], array3: Iterable[T3], array4: Iterable[T4], array5: Iterable[T5], /) List[Tuple[T, T2, T3, T4, T5]]
pydash.arrays.zip_(*arrays: Iterable[Any]) List[Tuple[Any, ...]]

Groups the elements of each array at their corresponding indexes. Useful for separate data sources that are coordinated through matching array indexes.

Parameters:

arrays – Lists to process.

Returns:

Zipped list.

Example

>>> zip_([1, 2, 3], [4, 5, 6], [7, 8, 9])
[(1, 4, 7), (2, 5, 8), (3, 6, 9)]

Added in version 1.0.0.

Changed in version 8.0.0: Return list of tuples instead of list of lists.

pydash.arrays.zip_object(keys: Iterable[Tuple[T, T2]], values: None = None) Dict[T, T2][source]
pydash.arrays.zip_object(keys: Iterable[List[T | T2]], values: None = None) Dict[T | T2, T | T2]
pydash.arrays.zip_object(keys: Iterable[T], values: List[T2]) Dict[T, T2]

Creates a dict composed of lists of keys and values. Pass either a single two-dimensional list, i.e. [[key1, value1], [key2, value2]], or two lists, one of keys and one of corresponding values.

Parameters:
  • keys – Either a list of keys or a list of [key, value] pairs.

  • values – List of values to zip.

Returns:

Zipped dict.

Example

>>> zip_object([1, 2, 3], [4, 5, 6])
{1: 4, 2: 5, 3: 6}

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias object_.

pydash.arrays.zip_object_deep(keys: Iterable[Any], values: List[Any] | None = None) Dict[source]

This method is like zip_object() except that it supports property paths.

Parameters:
  • keys – Either a list of keys or a list of [key, value] pairs.

  • values – List of values to zip.

Returns:

Zipped dict.

Example

>>> expected = {"a": {"b": {"c": 1, "d": 2}}}
>>> zip_object_deep(["a.b.c", "a.b.d"], [1, 2]) == expected
True

Added in version 4.0.0.

pydash.arrays.zip_with(array1: Iterable[T], array2: Iterable[T2], *, iteratee: Callable[[T, T2, int], T3] | Callable[[T, T2], T3] | Callable[[T], T3]) List[T3][source]
pydash.arrays.zip_with(*arrays: Iterable[Any], iteratee: Callable[[Any, Any, int], T2] | Callable[[Any, Any], T2] | Callable[[Any], T2]) List[T2]
pydash.arrays.zip_with(*arrays: Iterable[Any] | Callable[[Any, Any, int], T2] | Callable[[Any, Any], T2] | Callable[[Any], T2]) List[T2]

This method is like zip() except that it accepts an iteratee to specify how grouped values should be combined. The iteratee is invoked with three arguments: (accumulator, value, index).

Parameters:

*arrays – Lists to process.

Keyword Arguments:

iteratee (callable) – Function to combine grouped values.

Returns:

Zipped list of grouped elements.

Example

>>> from pydash import add
>>> zip_with([1, 2], [10, 20], [100, 200], add)
[111, 222]
>>> zip_with([1, 2], [10, 20], [100, 200], iteratee=add)
[111, 222]

Added in version 3.3.0.

Chaining

pydash.chaining.chain(value: ~pydash.chaining.chaining.T | ~pydash.helpers.Unset = <pydash.helpers.Unset object>) Chain[T][source]

Creates a Chain object which wraps the given value to enable intuitive method chaining. Chaining is lazy and won’t compute a final value until Chain.value() is called.

Parameters:

value – Value to initialize chain operations with.

Returns:

Instance of Chain initialized with value.

Example

>>> chain([1, 2, 3, 4]).map(lambda x: x * 2).sum().value()
20
>>> chain().map(lambda x: x * 2).sum()([1, 2, 3, 4])
20
>>> summer = chain([1, 2, 3, 4]).sum()
>>> new_summer = summer.plant([1, 2])
>>> new_summer.value()
3
>>> summer.value()
10
>>> def echo(item):
...     print(item)
>>> summer = chain([1, 2, 3, 4]).for_each(echo).sum()
>>> committed = summer.commit()
1
2
3
4
>>> committed.value()
10
>>> summer.value()
1
2
3
4
10

Added in version 1.0.0.

Changed in version 2.0.0: Made chaining lazy.

Changed in version 3.0.0:

  • Added support for late passing of value.

  • Added Chain.plant() for replacing initial chain value.

  • Added Chain.commit() for returning a new Chain instance initialized with the results from calling Chain.value().

pydash.chaining.tap(value: T, interceptor: Callable[[T], Any]) T[source]

Invokes interceptor with the value as the first argument and then returns value. The purpose of this method is to “tap into” a method chain in order to perform operations on intermediate results within the chain.

Parameters:
  • value – Current value of chain operation.

  • interceptor – Function called on value.

Returns:

value after interceptor call.

Example

>>> data = []
>>> def log(value):
...     data.append(value)
>>> chain([1, 2, 3, 4]).map(lambda x: x * 2).tap(log).value()
[2, 4, 6, 8]
>>> data
[[2, 4, 6, 8]]

Added in version 1.0.0.

Collections

Functions that operate on lists and dicts.

Added in version 1.0.0.

pydash.collections.at(collection: Mapping[T, T2], *paths: T) List[T2 | None][source]
pydash.collections.at(collection: Mapping[T, Any], *paths: T | Iterable[T]) List[Any]
pydash.collections.at(collection: Iterable[T], *paths: int) List[T | None]
pydash.collections.at(collection: Iterable[Any], *paths: int | Iterable[int]) List[Any]

Creates a list of elements from the specified indexes, or keys, of the collection. Indexes may be specified as individual arguments or as arrays of indexes.

Parameters:
  • collection – Collection to iterate over.

  • *paths – The indexes of collection to retrieve, specified as individual indexes or arrays of indexes.

Returns:

filtered list

Example

>>> at([1, 2, 3, 4], 0, 2)
[1, 3]
>>> at({"a": 1, "b": 2, "c": 3, "d": 4}, "a", "c")
[1, 3]
>>> at({"a": 1, "b": 2, "c": {"d": {"e": 3}}}, "a", ["c", "d", "e"])
[1, 3]

Added in version 1.0.0.

Changed in version 4.1.0: Support deep path access.

pydash.collections.count_by(collection: Mapping[Any, T2], iteratee: None = None) Dict[T2, int][source]
pydash.collections.count_by(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], T3]) Dict[T3, int]
pydash.collections.count_by(collection: Mapping[T, T2], iteratee: Callable[[T2, T], T3]) Dict[T3, int]
pydash.collections.count_by(collection: Mapping[Any, T2], iteratee: Callable[[T2], T3]) Dict[T3, int]
pydash.collections.count_by(collection: Iterable[T], iteratee: None = None) Dict[T, int]
pydash.collections.count_by(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], T2]) Dict[T2, int]
pydash.collections.count_by(collection: Iterable[T], iteratee: Callable[[T, int], T2]) Dict[T2, int]
pydash.collections.count_by(collection: Iterable[T], iteratee: Callable[[T], T2]) Dict[T2, int]

Creates an object composed of keys generated from the results of running each element of collection through the iteratee.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Dict containing counts by key.

Example

>>> results = count_by([1, 2, 1, 2, 3, 4])
>>> assert results == {1: 2, 2: 2, 3: 1, 4: 1}
>>> results = count_by(["a", "A", "B", "b"], lambda x: x.lower())
>>> assert results == {"a": 2, "b": 2}
>>> results = count_by({"a": 1, "b": 1, "c": 3, "d": 3})
>>> assert results == {1: 2, 3: 2}

Added in version 1.0.0.

pydash.collections.every(collection: Iterable[T], predicate: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) bool[source]

Checks if the predicate returns a truthy value for all elements of a collection. The predicate is invoked with three arguments: (value, index|key, collection). If a property name is passed for predicate, the created pluck() style predicate will return the property value of the given element. If an object is passed for predicate, the created matches() style predicate will return True for elements that have the properties of the given object, else False.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

Whether all elements are truthy.

Example

>>> every([1, True, "hello"])
True
>>> every([1, False, "hello"])
False
>>> every([{"a": 1}, {"a": True}, {"a": "hello"}], "a")
True
>>> every([{"a": 1}, {"a": False}, {"a": "hello"}], "a")
False
>>> every([{"a": 1}, {"a": 1}], {"a": 1})
True
>>> every([{"a": 1}, {"a": 2}], {"a": 1})
False

Added in version 1.0.0.

pydash.collections.filter_(collection: Mapping[T, T2], predicate: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict | None = None) List[T2][source]
pydash.collections.filter_(collection: Mapping[T, T2], predicate: Callable[[T2, T], Any] | int | str | List | Tuple | Dict | None = None) List[T2]
pydash.collections.filter_(collection: Mapping[Any, T2], predicate: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None) List[T2]
pydash.collections.filter_(collection: Iterable[T], predicate: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.filter_(collection: Iterable[T], predicate: Callable[[T, int], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.filter_(collection: Iterable[T], predicate: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) List[T]

Iterates over elements of a collection, returning a list of all elements the predicate returns truthy for.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

Filtered list.

Example

>>> results = filter_([{"a": 1}, {"b": 2}, {"a": 1, "b": 3}], {"a": 1})
>>> assert results == [{"a": 1}, {"a": 1, "b": 3}]
>>> filter_([1, 2, 3, 4], lambda x: x >= 3)
[3, 4]

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias select.

pydash.collections.find(collection: Dict[T, T2], predicate: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict | None = None) T2 | None[source]
pydash.collections.find(collection: Dict[T, T2], predicate: Callable[[T2, T], Any] | int | str | List | Tuple | Dict | None = None) T2 | None
pydash.collections.find(collection: Dict[T, T2], predicate: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None) T2 | None
pydash.collections.find(collection: List[T], predicate: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict | None = None) T | None
pydash.collections.find(collection: List[T], predicate: Callable[[T, int], Any] | int | str | List | Tuple | Dict | None = None) T | None
pydash.collections.find(collection: List[T], predicate: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) T | None

Iterates over elements of a collection, returning the first element that the predicate returns truthy for.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

First element found or None.

Example

>>> find([1, 2, 3, 4], lambda x: x >= 3)
3
>>> find([{"a": 1}, {"b": 2}, {"a": 1, "b": 2}], {"a": 1})
{'a': 1}

Added in version 1.0.0.

Changed in version 4.0.0: Removed aliases detect and find_where.

pydash.collections.find_last(collection: Dict[T, T2], predicate: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict | None = None) T2 | None[source]
pydash.collections.find_last(collection: Dict[T, T2], predicate: Callable[[T2, T], Any] | int | str | List | Tuple | Dict | None = None) T2 | None
pydash.collections.find_last(collection: Dict[Any, T2], predicate: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None) T2 | None
pydash.collections.find_last(collection: List[T], predicate: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict | None = None) T | None
pydash.collections.find_last(collection: List[T], predicate: Callable[[T, int], Any] | int | str | List | Tuple | Dict | None = None) T | None
pydash.collections.find_last(collection: List[T], predicate: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) T | None

This method is like find() except that it iterates over elements of a collection from right to left.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

Last element found or None.

Example

>>> find_last([1, 2, 3, 4], lambda x: x >= 3)
4
>>> results = find_last([{'a': 1}, {'b': 2}, {'a': 1, 'b': 2}],                                 {'a': 1})
>>> assert results == {'a': 1, 'b': 2}

Added in version 1.0.0.

pydash.collections.flat_map(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], Iterable[T3]]) List[T3][source]
pydash.collections.flat_map(collection: Mapping[T, T2], iteratee: Callable[[T2, T], Iterable[T3]]) List[T3]
pydash.collections.flat_map(collection: Mapping[Any, T2], iteratee: Callable[[T2], Iterable[T3]]) List[T3]
pydash.collections.flat_map(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], T3]) List[T3]
pydash.collections.flat_map(collection: Mapping[T, T2], iteratee: Callable[[T2, T], T3]) List[T3]
pydash.collections.flat_map(collection: Mapping[Any, T2], iteratee: Callable[[T2], T3]) List[T3]
pydash.collections.flat_map(collection: Mapping[Any, Iterable[T2]], iteratee: None = None) List[T2]
pydash.collections.flat_map(collection: Mapping[Any, T2], iteratee: None = None) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], Iterable[T2]]) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T, int], Iterable[T2]]) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T], Iterable[T2]]) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], T2]) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T, int], T2]) List[T2]
pydash.collections.flat_map(collection: Iterable[T], iteratee: Callable[[T], T2]) List[T2]
pydash.collections.flat_map(collection: Iterable[Iterable[T]], iteratee: None = None) List[T]
pydash.collections.flat_map(collection: Iterable[T], iteratee: None = None) List[T]

Creates a flattened list of values by running each element in collection through iteratee and flattening the mapped results. The iteratee is invoked with three arguments: (value, index|key, collection).

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Flattened mapped list.

Example

>>> duplicate = lambda n: [[n, n]]
>>> flat_map([1, 2], duplicate)
[[1, 1], [2, 2]]

Added in version 4.0.0.

pydash.collections.flat_map_deep(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], Any] | None = None) List[source]
pydash.collections.flat_map_deep(collection: Mapping[T, T2], iteratee: Callable[[T2, T], Any] | None = None) List
pydash.collections.flat_map_deep(collection: Mapping[Any, T2], iteratee: Callable[[T2], Any] | None = None) List
pydash.collections.flat_map_deep(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], Any] | None = None) List
pydash.collections.flat_map_deep(collection: Iterable[T], iteratee: Callable[[T, int], Any] | None = None) List
pydash.collections.flat_map_deep(collection: Iterable[T], iteratee: Callable[[T], Any] | None = None) List

This method is like flat_map() except that it recursively flattens the mapped results.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Flattened mapped list.

Example

>>> duplicate = lambda n: [[n, n]]
>>> flat_map_deep([1, 2], duplicate)
[1, 1, 2, 2]

Added in version 4.0.0.

pydash.collections.flat_map_depth(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], Any] | None = None, depth: int = 1) List[source]
pydash.collections.flat_map_depth(collection: Mapping[T, T2], iteratee: Callable[[T2, T], Any] | None = None, depth: int = 1) List
pydash.collections.flat_map_depth(collection: Mapping[Any, T2], iteratee: Callable[[T2], Any] | None = None, depth: int = 1) List
pydash.collections.flat_map_depth(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], Any] | None = None, depth: int = 1) List
pydash.collections.flat_map_depth(collection: Iterable[T], iteratee: Callable[[T, int], Any] | None = None, depth: int = 1) List
pydash.collections.flat_map_depth(collection: Iterable[T], iteratee: Callable[[T], Any] | None = None, depth: int = 1) List

This method is like flat_map() except that it recursively flattens the mapped results up to depth times.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Flattened mapped list.

Example

>>> duplicate = lambda n: [[n, n]]
>>> flat_map_depth([1, 2], duplicate, 1)
[[1, 1], [2, 2]]
>>> flat_map_depth([1, 2], duplicate, 2)
[1, 1, 2, 2]

Added in version 4.0.0.

pydash.collections.for_each(collection: Dict[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict | None = None) Dict[T, T2][source]
pydash.collections.for_each(collection: Dict[T, T2], iteratee: Callable[[T2, T], Any] | int | str | List | Tuple | Dict | None = None) Dict[T, T2]
pydash.collections.for_each(collection: Dict[T, T2], iteratee: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None) Dict[T, T2]
pydash.collections.for_each(collection: List[T], iteratee: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.for_each(collection: List[T], iteratee: Callable[[T, int], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.for_each(collection: List[T], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) List[T]

Iterates over elements of a collection, executing the iteratee for each element.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

collection

Example

>>> results = {}
>>> def cb(x):
...     results[x] = x**2
>>> for_each([1, 2, 3, 4], cb)
[1, 2, 3, 4]
>>> assert results == {1: 1, 2: 4, 3: 9, 4: 16}

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias each.

pydash.collections.for_each_right(collection: Dict[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict) Dict[T, T2][source]
pydash.collections.for_each_right(collection: Dict[T, T2], iteratee: Callable[[T2, T], Any] | int | str | List | Tuple | Dict) Dict[T, T2]
pydash.collections.for_each_right(collection: Dict[T, T2], iteratee: Callable[[T2], Any] | int | str | List | Tuple | Dict) Dict[T, T2]
pydash.collections.for_each_right(collection: List[T], iteratee: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict) List[T]
pydash.collections.for_each_right(collection: List[T], iteratee: Callable[[T, int], Any] | int | str | List | Tuple | Dict) List[T]
pydash.collections.for_each_right(collection: List[T], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict) List[T]

This method is like for_each() except that it iterates over elements of a collection from right to left.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

collection

Example

>>> results = {"total": 1}
>>> def cb(x):
...     results["total"] = x * results["total"]
>>> for_each_right([1, 2, 3, 4], cb)
[1, 2, 3, 4]
>>> assert results == {"total": 24}

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias each_right.

pydash.collections.group_by(collection: Iterable[T], iteratee: Callable[[T], T2]) Dict[T2, List[T]][source]
pydash.collections.group_by(collection: Iterable[T], iteratee: int | str | List | Tuple | Dict | None = None) Dict[Any, List[T]]

Creates an object composed of keys generated from the results of running each element of a collection through the iteratee.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Results of grouping by iteratee.

Example

>>> results = group_by([{'a': 1, 'b': 2}, {'a': 3, 'b': 4}], 'a')
>>> assert results == {1: [{'a': 1, 'b': 2}], 3: [{'a': 3, 'b': 4}]}
>>> results = group_by([{'a': 1, 'b': 2}, {'a': 3, 'b': 4}], {'a': 1})
>>> assert results == {False: [{'a': 3, 'b': 4}],                               True: [{'a': 1, 'b': 2}]}

Added in version 1.0.0.

pydash.collections.includes(collection: Sequence | Dict, target: Any, from_index: int = 0) bool[source]

Checks if a given value is present in a collection. If from_index is negative, it is used as the offset from the end of the collection.

Parameters:
  • collection – Collection to iterate over.

  • target – Target value to compare to.

  • from_index – Offset to start search from.

Returns:

Whether target is in collection.

Example

>>> includes([1, 2, 3, 4], 2)
True
>>> includes([1, 2, 3, 4], 2, from_index=2)
False
>>> includes({"a": 1, "b": 2, "c": 3, "d": 4}, 2)
True

Added in version 1.0.0.

Changed in version 4.0.0: Renamed from contains to includes and removed alias include.

pydash.collections.invoke_map(collection: Iterable, path: Hashable | List[Hashable], *args: Any, **kwargs: Any) List[Any][source]

Invokes the method at path of each element in collection, returning a list of the results of each invoked method. Any additional arguments are provided to each invoked method. If path is a function, it’s invoked for each element in collection.

Parameters:
  • collection – Collection to iterate over.

  • path – String path to method to invoke or callable to invoke for each element in collection.

  • args – Arguments to pass to method call.

  • kwargs – Keyword arguments to pass to method call.

Returns:

List of results of invoking method of each item.

Example

>>> items = [{"a": [{"b": 1}]}, {"a": [{"c": 2}]}]
>>> expected = [{"b": 1}.items(), {"c": 2}.items()]
>>> invoke_map(items, "a[0].items") == expected
True

Added in version 4.0.0.

pydash.collections.key_by(collection: Iterable[T], iteratee: Callable[[T], T2]) Dict[T2, T][source]
pydash.collections.key_by(collection: Iterable, iteratee: int | str | List | Tuple | Dict | None = None) Dict

Creates an object composed of keys generated from the results of running each element of the collection through the given iteratee.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Results of indexing by iteratee.

Example

>>> results = key_by([{"a": 1, "b": 2}, {"a": 3, "b": 4}], "a")
>>> assert results == {1: {"a": 1, "b": 2}, 3: {"a": 3, "b": 4}}

Added in version 1.0.0.

Changed in version 4.0.0: Renamed from index_by to key_by.

pydash.collections.map_(collection: Mapping[Any, T2], iteratee: Callable[[T2], T3]) List[T3][source]
pydash.collections.map_(collection: Mapping[T, T2], iteratee: Callable[[T2, T], T3]) List[T3]
pydash.collections.map_(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], T3]) List[T3]
pydash.collections.map_(collection: Iterable[T], iteratee: Callable[[T], T2]) List[T2]
pydash.collections.map_(collection: Iterable[T], iteratee: Callable[[T, int], T2]) List[T2]
pydash.collections.map_(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], T2]) List[T2]
pydash.collections.map_(collection: Iterable, iteratee: int | str | List | Tuple | Dict | None = None) List

Creates an array of values by running each element in the collection through the iteratee. The iteratee is invoked with three arguments: (value, index|key, collection). If a property name is passed for iteratee, the created pluck() style iteratee will return the property value of the given element. If an object is passed for iteratee, the created matches() style iteratee will return True for elements that have the properties of the given object, else False.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

Returns:

Mapped list.

Example

>>> map_([1, 2, 3, 4], str)
['1', '2', '3', '4']
>>> map_([{"a": 1, "b": 2}, {"a": 3, "b": 4}, {"a": 5, "b": 6}], "a")
[1, 3, 5]
>>> map_([[[0, 1]], [[2, 3]], [[4, 5]]], "0.1")
[1, 3, 5]
>>> map_([{"a": {"b": 1}}, {"a": {"b": 2}}], "a.b")
[1, 2]
>>> map_([{"a": {"b": [0, 1]}}, {"a": {"b": [2, 3]}}], "a.b[1]")
[1, 3]

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias collect.

pydash.collections.nest(collection: Iterable, *properties: Any) Any[source]

This method is like group_by() except that it supports nested grouping by multiple string properties. If only a single key is given, it is like calling group_by(collection, prop).

Parameters:
  • collection – Collection to iterate over.

  • *properties – Properties to nest by.

Returns:

Results of nested grouping by properties.

Example

>>> results = nest([{'shape': 'square', 'color': 'red', 'qty': 5},                            {'shape': 'square', 'color': 'blue', 'qty': 10},                            {'shape': 'square', 'color': 'orange', 'qty': 5},                            {'shape': 'circle', 'color': 'yellow', 'qty': 5},                            {'shape': 'circle', 'color': 'pink', 'qty': 10},                            {'shape': 'oval', 'color': 'purple', 'qty': 5}],                           'shape', 'qty')
>>> expected = {            'square': {5: [{'shape': 'square', 'color': 'red', 'qty': 5},                           {'shape': 'square', 'color': 'orange', 'qty': 5}],                       10: [{'shape': 'square', 'color': 'blue', 'qty': 10}]},            'circle': {5: [{'shape': 'circle', 'color': 'yellow', 'qty': 5}],                       10: [{'shape': 'circle', 'color': 'pink', 'qty': 10}]},            'oval': {5: [{'shape': 'oval', 'color': 'purple', 'qty': 5}]}}
>>> results == expected
True

Added in version 4.3.0.

pydash.collections.order_by(collection: Mapping[Any, T2], keys: Iterable[str | int], orders: Iterable[bool] | bool, reverse: bool = False) List[T2][source]
pydash.collections.order_by(collection: Mapping[Any, T2], keys: Iterable[str], orders: None = None, reverse: bool = False) List[T2]
pydash.collections.order_by(collection: Iterable[T], keys: Iterable[str | int], orders: Iterable[bool] | bool, reverse: bool = False) List[T]
pydash.collections.order_by(collection: Iterable[T], keys: Iterable[str], orders: None = None, reverse: bool = False) List[T]

This method is like sort_by() except that it sorts by key names instead of an iteratee function. Keys can be sorted in descending order by prepending a "-" to the key name (e.g. "name" would become "-name") or by passing a list of boolean sort options via orders where True is ascending and False is descending.

Parameters:
  • collection – Collection to iterate over.

  • keys – List of keys to sort by. By default, keys will be sorted in ascending order. To sort a key in descending order, prepend a "-" to the key name. For example, to sort the key value for "name" in descending order, use "-name".

  • orders – List of boolean sort orders to apply for each key. True corresponds to ascending order while False is descending. Defaults to None.

  • reverse (bool, optional) – Whether to reverse the sort. Defaults to False.

Returns:

Sorted list.

Example

>>> items = [{'a': 2, 'b': 1}, {'a': 3, 'b': 2}, {'a': 1, 'b': 3}]
>>> results = order_by(items, ['b', 'a'])
>>> assert results == [{'a': 2, 'b': 1},                               {'a': 3, 'b': 2},                               {'a': 1, 'b': 3}]
>>> results = order_by(items, ['a', 'b'])
>>> assert results == [{'a': 1, 'b': 3},                               {'a': 2, 'b': 1},                               {'a': 3, 'b': 2}]
>>> results = order_by(items, ['-a', 'b'])
>>> assert results == [{'a': 3, 'b': 2},                               {'a': 2, 'b': 1},                               {'a': 1, 'b': 3}]
>>> results = order_by(items, ['a', 'b'], [False, True])
>>> assert results == [{'a': 3, 'b': 2},                               {'a': 2, 'b': 1},                               {'a': 1, 'b': 3}]

Added in version 3.0.0.

Changed in version 3.2.0: Added orders argument.

Changed in version 3.2.0: Added sort_by_order() as alias.

Changed in version 4.0.0: Renamed from order_by to order_by and removed alias sort_by_order.

pydash.collections.partition(collection: Mapping[T, T2], predicate: Callable[[T2, T, Dict[T, T2]], Any]) List[List[T2]][source]
pydash.collections.partition(collection: Mapping[T, T2], predicate: Callable[[T2, T], Any]) List[List[T2]]
pydash.collections.partition(collection: Mapping[Any, T2], predicate: Callable[[T2], Any]) List[List[T2]]
pydash.collections.partition(collection: Mapping[Any, T2], predicate: int | str | List | Tuple | Dict | None = None) List[List[T2]]
pydash.collections.partition(collection: Iterable[T], predicate: Callable[[T, int, List[T]], Any]) List[List[T]]
pydash.collections.partition(collection: Iterable[T], predicate: Callable[[T, int], Any]) List[List[T]]
pydash.collections.partition(collection: Iterable[T], predicate: Callable[[T], Any]) List[List[T]]
pydash.collections.partition(collection: Iterable[T], predicate: int | str | List | Tuple | Dict | None = None) List[List[T]]

Creates an array of elements split into two groups, the first of which contains elements the predicate returns truthy for, while the second of which contains elements the predicate returns falsey for. The predicate is invoked with three arguments: (value, index|key, collection).

If a property name is provided for predicate the created pluck() style predicate returns the property value of the given element.

If an object is provided for predicate the created matches() style predicate returns True for elements that have the properties of the given object, else False.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

List of grouped elements.

Example

>>> partition([1, 2, 3, 4], lambda x: x >= 3)
[[3, 4], [1, 2]]

Added in version 1.1.0.

pydash.collections.pluck(collection: Iterable, path: Hashable | List[Hashable]) List[source]

Retrieves the value of a specified property from all elements in the collection.

Parameters:
  • collection – List of dicts.

  • path – Collection’s path to pluck

Returns:

Plucked list.

Example

>>> pluck([{"a": 1, "b": 2}, {"a": 3, "b": 4}, {"a": 5, "b": 6}], "a")
[1, 3, 5]
>>> pluck([[[0, 1]], [[2, 3]], [[4, 5]]], "0.1")
[1, 3, 5]
>>> pluck([{"a": {"b": 1}}, {"a": {"b": 2}}], "a.b")
[1, 2]
>>> pluck([{"a": {"b": [0, 1]}}, {"a": {"b": [2, 3]}}], "a.b.1")
[1, 3]
>>> pluck([{"a": {"b": [0, 1]}}, {"a": {"b": [2, 3]}}], ["a", "b", 1])
[1, 3]

Added in version 1.0.0.

Changed in version 4.0.0: Function removed.

Changed in version 4.0.1: Made property access deep.

pydash.collections.reduce_(collection: Mapping[T, T2], iteratee: Callable[[T3, T2, T], T3], accumulator: T3) T3[source]
pydash.collections.reduce_(collection: Mapping[Any, T2], iteratee: Callable[[T3, T2], T3], accumulator: T3) T3
pydash.collections.reduce_(collection: Mapping, iteratee: Callable[[T3], T3], accumulator: T3) T3
pydash.collections.reduce_(collection: Mapping[T, T2], iteratee: Callable[[T2, T2, T], T2], accumulator: None = None) T2
pydash.collections.reduce_(collection: Mapping[Any, T2], iteratee: Callable[[T2, T2], T2], accumulator: None = None) T2
pydash.collections.reduce_(collection: Mapping, iteratee: Callable[[T], T], accumulator: None = None) T
pydash.collections.reduce_(collection: Iterable[T], iteratee: Callable[[T2, T, int], T2], accumulator: T2) T2
pydash.collections.reduce_(collection: Iterable[T], iteratee: Callable[[T2, T], T2], accumulator: T2) T2
pydash.collections.reduce_(collection: Iterable, iteratee: Callable[[T2], T2], accumulator: T2) T2
pydash.collections.reduce_(collection: Iterable[T], iteratee: Callable[[T, T, int], T], accumulator: None = None) T
pydash.collections.reduce_(collection: Iterable[T], iteratee: Callable[[T, T], T], accumulator: None = None) T
pydash.collections.reduce_(collection: Iterable, iteratee: Callable[[T], T], accumulator: None = None) T
pydash.collections.reduce_(collection: Iterable[T], iteratee: None = None, accumulator: T | None = None) T

Reduces a collection to a value which is the accumulated result of running each element in the collection through the iteratee, where each successive iteratee execution consumes the return value of the previous execution.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • accumulator – Initial value of aggregator. Default is to use the result of the first iteration.

Returns:

Accumulator object containing results of reduction.

Example

>>> reduce_([1, 2, 3, 4], lambda total, x: total * x)
24

Added in version 1.0.0.

Changed in version 4.0.0: Removed aliases foldl and inject.

pydash.collections.reduce_right(collection: Mapping[T, T2], iteratee: Callable[[T3, T2, T], T3], accumulator: T3) T3[source]
pydash.collections.reduce_right(collection: Mapping[Any, T2], iteratee: Callable[[T3, T2], T3], accumulator: T3) T3
pydash.collections.reduce_right(collection: Mapping, iteratee: Callable[[T3], T3], accumulator: T3) T3
pydash.collections.reduce_right(collection: Mapping[T, T2], iteratee: Callable[[T2, T2, T], T2], accumulator: None = None) T2
pydash.collections.reduce_right(collection: Mapping[Any, T2], iteratee: Callable[[T2, T2], T2], accumulator: None = None) T2
pydash.collections.reduce_right(collection: Mapping, iteratee: Callable[[T], T], accumulator: None = None) T
pydash.collections.reduce_right(collection: Iterable[T], iteratee: Callable[[T2, T, int], T2], accumulator: T2) T2
pydash.collections.reduce_right(collection: Iterable[T], iteratee: Callable[[T2, T], T2], accumulator: T2) T2
pydash.collections.reduce_right(collection: Iterable, iteratee: Callable[[T2], T2], accumulator: T2) T2
pydash.collections.reduce_right(collection: Iterable[T], iteratee: Callable[[T, T, int], T], accumulator: None = None) T
pydash.collections.reduce_right(collection: Iterable[T], iteratee: Callable[[T, T], T], accumulator: None = None) T
pydash.collections.reduce_right(collection: Iterable, iteratee: Callable[[T], T], accumulator: None = None) T
pydash.collections.reduce_right(collection: Iterable[T], iteratee: None = None, accumulator: T | None = None) T

This method is like reduce_() except that it iterates over elements of a collection from right to left.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • accumulator – Initial value of aggregator. Default is to use the result of the first iteration.

Returns:

Accumulator object containing results of reduction.

Example

>>> reduce_right([1, 2, 3, 4], lambda total, x: total**x)
4096

Added in version 1.0.0.

Changed in version 3.2.1: Fix bug where collection was not reversed correctly.

Changed in version 4.0.0: Removed alias foldr.

pydash.collections.reductions(collection: Mapping[T, T2], iteratee: Callable[[T3, T2, T], T3], accumulator: T3, from_right: bool = False) List[T3][source]
pydash.collections.reductions(collection: Mapping[Any, T2], iteratee: Callable[[T3, T2], T3], accumulator: T3, from_right: bool = False) List[T3]
pydash.collections.reductions(collection: Mapping, iteratee: Callable[[T3], T3], accumulator: T3, from_right: bool = False) List[T3]
pydash.collections.reductions(collection: Mapping[T, T2], iteratee: Callable[[T2, T2, T], T2], accumulator: None = None, from_right: bool = False) List[T2]
pydash.collections.reductions(collection: Mapping[Any, T2], iteratee: Callable[[T2, T2], T2], accumulator: None = None, from_right: bool = False) List[T2]
pydash.collections.reductions(collection: Mapping, iteratee: Callable[[T], T], accumulator: None = None, from_right: bool = False) List[T]
pydash.collections.reductions(collection: Iterable[T], iteratee: Callable[[T2, T, int], T2], accumulator: T2, from_right: bool = False) List[T2]
pydash.collections.reductions(collection: Iterable[T], iteratee: Callable[[T2, T], T2], accumulator: T2, from_right: bool = False) List[T2]
pydash.collections.reductions(collection: Iterable, iteratee: Callable[[T2], T2], accumulator: T2, from_right: bool = False) List[T2]
pydash.collections.reductions(collection: Iterable[T], iteratee: Callable[[T, T, int], T], accumulator: None = None, from_right: bool = False) List[T]
pydash.collections.reductions(collection: Iterable[T], iteratee: Callable[[T, T], T], accumulator: None = None, from_right: bool = False) List[T]
pydash.collections.reductions(collection: Iterable, iteratee: Callable[[T], T], accumulator: None = None, from_right: bool = False) List[T]
pydash.collections.reductions(collection: Iterable[T], iteratee: None = None, accumulator: T | None = None, from_right: bool = False) List[T]

This function is like reduce_() except that it returns a list of every intermediate value in the reduction operation.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • accumulator – Initial value of aggregator. Default is to use the result of the first iteration.

Returns:

Results of each reduction operation.

Example

>>> reductions([1, 2, 3, 4], lambda total, x: total * x)
[2, 6, 24]

Note

The last element of the returned list would be the result of using reduce_().

Added in version 2.0.0.

pydash.collections.reductions_right(collection: Mapping[T, T2], iteratee: Callable[[T3, T2, T], T3], accumulator: T3) List[T3][source]
pydash.collections.reductions_right(collection: Mapping[Any, T2], iteratee: Callable[[T3, T2], T3], accumulator: T3) List[T3]
pydash.collections.reductions_right(collection: Mapping, iteratee: Callable[[T3], T3], accumulator: T3) List[T3]
pydash.collections.reductions_right(collection: Mapping[T, T2], iteratee: Callable[[T2, T2, T], T2], accumulator: None = None) List[T2]
pydash.collections.reductions_right(collection: Mapping[Any, T2], iteratee: Callable[[T2, T2], T2], accumulator: None = None) List[T2]
pydash.collections.reductions_right(collection: Mapping, iteratee: Callable[[T], T], accumulator: None = None) List[T]
pydash.collections.reductions_right(collection: Iterable[T], iteratee: Callable[[T2, T, int], T2], accumulator: T2) List[T2]
pydash.collections.reductions_right(collection: Iterable[T], iteratee: Callable[[T2, T], T2], accumulator: T2) List[T2]
pydash.collections.reductions_right(collection: Iterable, iteratee: Callable[[T2], T2], accumulator: T2) List[T2]
pydash.collections.reductions_right(collection: Iterable[T], iteratee: Callable[[T, T, int], T], accumulator: None = None) List[T]
pydash.collections.reductions_right(collection: Iterable[T], iteratee: Callable[[T, T], T], accumulator: None = None) List[T]
pydash.collections.reductions_right(collection: Iterable, iteratee: Callable[[T], T], accumulator: None = None) List[T]
pydash.collections.reductions_right(collection: Iterable[T], iteratee: None = None, accumulator: T | None = None) List[T]

This method is like reductions() except that it iterates over elements of a collection from right to left.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • accumulator – Initial value of aggregator. Default is to use the result of the first iteration.

Returns:

Results of each reduction operation.

Example

>>> reductions_right([1, 2, 3, 4], lambda total, x: total**x)
[64, 4096, 4096]

Note

The last element of the returned list would be the result of using reduce_().

Added in version 2.0.0.

pydash.collections.reject(collection: Mapping[T, T2], predicate: Callable[[T2, T, Dict[T, T2]], Any] | int | str | List | Tuple | Dict | None = None) List[T2][source]
pydash.collections.reject(collection: Mapping[T, T2], predicate: Callable[[T2, T], Any] | int | str | List | Tuple | Dict | None = None) List[T2]
pydash.collections.reject(collection: Mapping[Any, T2], predicate: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None) List[T2]
pydash.collections.reject(collection: Iterable[T], predicate: Callable[[T, int, List[T]], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.reject(collection: Iterable[T], predicate: Callable[[T, int], Any] | int | str | List | Tuple | Dict | None = None) List[T]
pydash.collections.reject(collection: Iterable[T], predicate: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None) List[T]

The opposite of filter_() this method returns the elements of a collection that the predicate does not return truthy for.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

Rejected elements of collection.

Example

>>> reject([1, 2, 3, 4], lambda x: x >= 3)
[1, 2]
>>> reject([{"a": 0}, {"a": 1}, {"a": 2}], "a")
[{'a': 0}]
>>> reject([{"a": 0}, {"a": 1}, {"a": 2}], {"a": 1})
[{'a': 0}, {'a': 2}]

Added in version 1.0.0.

pydash.collections.sample(collection: Sequence[T]) T[source]

Retrieves a random element from a given collection.

Parameters:

collection – Collection to iterate over.

Returns:

Random element from the given collection.

Example

>>> items = [1, 2, 3, 4, 5]
>>> results = sample(items)
>>> assert results in items

Added in version 1.0.0.

Changed in version 4.0.0: Moved multiple samples functionality to sample_size(). This function now only returns a single random sample.

pydash.collections.sample_size(collection: Sequence[T], n: int | None = None) List[T][source]

Retrieves list of n random elements from a collection.

Parameters:
  • collection – Collection to iterate over.

  • n – Number of random samples to return.

Returns:

List of n sampled collection values.

Examples

>>> items = [1, 2, 3, 4, 5]
>>> results = sample_size(items, 2)
>>> assert len(results) == 2
>>> assert set(items).intersection(results) == set(results)

Added in version 4.0.0.

pydash.collections.shuffle(collection: Mapping[Any, T]) List[T][source]
pydash.collections.shuffle(collection: Iterable[T]) List[T]

Creates a list of shuffled values, using a version of the Fisher-Yates shuffle.

Parameters:

collection – Collection to iterate over.

Returns:

Shuffled list of values.

Example

>>> items = [1, 2, 3, 4]
>>> results = shuffle(items)
>>> assert len(results) == len(items)
>>> assert set(results) == set(items)

Added in version 1.0.0.

pydash.collections.size(collection: Sized) int[source]

Gets the size of the collection by returning len(collection) for iterable objects.

Parameters:

collection – Collection to iterate over.

Returns:

Collection length.

Example

>>> size([1, 2, 3, 4])
4

Added in version 1.0.0.

pydash.collections.some(collection: Iterable[T], predicate: Callable[[T], Any] | None = None) bool[source]

Checks if the predicate returns a truthy value for any element of a collection. The predicate is invoked with three arguments: (value, index|key, collection). If a property name is passed for predicate, the created map_() style predicate will return the property value of the given element. If an object is passed for predicate, the created matches() style predicate will return True for elements that have the properties of the given object, else False.

Parameters:
  • collection – Collection to iterate over.

  • predicate – Predicate applied per iteration.

Returns:

Whether any of the elements are truthy.

Example

>>> some([False, True, 0])
True
>>> some([False, 0, None])
False
>>> some([1, 2, 3, 4], lambda x: x >= 3)
True
>>> some([1, 2, 3, 4], lambda x: x == 0)
False

Added in version 1.0.0.

Changed in version 4.0.0: Removed alias any_.

pydash.collections.sort_by(collection: Mapping[Any, T2], iteratee: Callable[[T2], Any] | int | str | List | Tuple | Dict | None = None, reverse: bool = False) List[T2][source]
pydash.collections.sort_by(collection: Iterable[T], iteratee: Callable[[T], Any] | int | str | List | Tuple | Dict | None = None, reverse: bool = False) List[T]

Creates a list of elements, sorted in ascending order by the results of running each element in a collection through the iteratee.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • reverse – Whether to reverse the sort. Defaults to False.

Returns:

Sorted list.

Example

>>> sort_by({"a": 2, "b": 3, "c": 1})
[1, 2, 3]
>>> sort_by({"a": 2, "b": 3, "c": 1}, reverse=True)
[3, 2, 1]
>>> sort_by([{"a": 2}, {"a": 3}, {"a": 1}], "a")
[{'a': 1}, {'a': 2}, {'a': 3}]

Added in version 1.0.0.

Functions

Functions that wrap other functions.

Added in version 1.0.0.

pydash.functions.after(func: Callable[[P], T], n: SupportsInt) After[P, T][source]

Creates a function that executes func, with the arguments of the created function, only after being called n times.

Parameters:
  • func – Function to execute.

  • n – Number of times func must be called before it is executed.

Returns:

Function wrapped in an After context.

Example

>>> func = lambda a, b, c: (a, b, c)
>>> after_func = after(func, 3)
>>> after_func(1, 2, 3)
>>> after_func(1, 2, 3)
>>> after_func(1, 2, 3)
(1, 2, 3)
>>> after_func(4, 5, 6)
(4, 5, 6)

Added in version 1.0.0.

Changed in version 3.0.0: Reordered arguments to make func first.

pydash.functions.ary(func: Callable[[...], T], n: SupportsInt | None) Ary[T][source]

Creates a function that accepts up to n arguments ignoring any additional arguments. Only positional arguments are capped. All keyword arguments are allowed through.

Parameters:
  • func – Function to cap arguments for.

  • n – Number of arguments to accept.

Returns:

Function wrapped in an Ary context.

Example

>>> func = lambda a, b, c=0, d=5: (a, b, c, d)
>>> ary_func = ary(func, 2)
>>> ary_func(1, 2, 3, 4, 5, 6)
(1, 2, 0, 5)
>>> ary_func(1, 2, 3, 4, 5, 6, c=10, d=20)
(1, 2, 10, 20)

Added in version 3.0.0.

pydash.functions.before(func: Callable[[P], T], n: SupportsInt) Before[P, T][source]

Creates a function that executes func, with the arguments of the created function, until it has been called n times.

Parameters:
  • func – Function to execute.

  • n – Number of times func may be executed.

Returns:

Function wrapped in an Before context.

Example

>>> func = lambda a, b, c: (a, b, c)
>>> before_func = before(func, 3)
>>> before_func(1, 2, 3)
(1, 2, 3)
>>> before_func(1, 2, 3)
(1, 2, 3)
>>> before_func(1, 2, 3)
>>> before_func(1, 2, 3)

Added in version 1.1.0.

Changed in version 3.0.0: Reordered arguments to make func first.

pydash.functions.conjoin(*funcs: Callable[[T], Any]) Callable[[Iterable[T]], bool][source]

Creates a function that composes multiple predicate functions into a single predicate that tests whether all elements of an object pass each predicate.

Parameters:

*funcs – Function(s) to conjoin.

Returns:

Function(s) wrapped in a Conjoin context.

Example

>>> conjoiner = conjoin(lambda x: isinstance(x, int), lambda x: x > 3)
>>> conjoiner([1, 2, 3])
False
>>> conjoiner([1.0, 2, 1])
False
>>> conjoiner([4.0, 5, 6])
False
>>> conjoiner([4, 5, 6])
True

Added in version 2.0.0.

pydash.functions.curry(func: Callable[[T1], T], arity: int | None = None) CurryOne[T1, T][source]
pydash.functions.curry(func: Callable[[T1, T2], T], arity: int | None = None) CurryTwo[T1, T2, T]
pydash.functions.curry(func: Callable[[T1, T2, T3], T], arity: int | None = None) CurryThree[T1, T2, T3, T]
pydash.functions.curry(func: Callable[[T1, T2, T3, T4], T], arity: int | None = None) CurryFour[T1, T2, T3, T4, T]
pydash.functions.curry(func: Callable[[T1, T2, T3, T4, T5], T], arity: int | None = None) CurryFive[T1, T2, T3, T4, T5, T]

Creates a function that accepts one or more arguments of func that when invoked either executes func returning its result (if all func arguments have been provided) or returns a function that accepts one or more of the remaining func arguments, and so on.

Parameters:
  • func – Function to curry.

  • arity – Number of function arguments that can be accepted by curried function. Default is to use the number of arguments that are accepted by func.

Returns:

Function wrapped in a Curry context.

Example

>>> func = lambda a, b, c: (a, b, c)
>>> currier = curry(func)
>>> currier = currier(1)
>>> assert isinstance(currier, Curry)
>>> currier = currier(2)
>>> assert isinstance(currier, Curry)
>>> currier = currier(3)
>>> currier
(1, 2, 3)

Added in version 1.0.0.

pydash.functions.curry_right(func: Callable[[T1], T], arity: int | None = None) CurryRightOne[T1, T][source]
pydash.functions.curry_right(func: Callable[[T1, T2], T], arity: int | None = None) CurryRightTwo[T2, T1, T]
pydash.functions.curry_right(func: Callable[[T1, T2, T3], T], arity: int | None = None) CurryRightThree[T3, T2, T1, T]
pydash.functions.curry_right(func: Callable[[T1, T2, T3, T4], T], arity: int | None = None) CurryRightFour[T4, T3, T2, T1, T]
pydash.functions.curry_right(func: Callable[[T1, T2, T3, T4, T5], T]) CurryRightFive[T5, T4, T3, T2, T1, T]

This method is like curry() except that arguments are applied to func in the manner of partial_right() instead of partial().

Parameters:
  • func – Function to curry.

  • arity – Number of function arguments that can be accepted by curried function. Default is to use the number of arguments that are accepted by func.

Returns:

Function wrapped in a CurryRight context.

Example

>>> func = lambda a, b, c: (a, b, c)
>>> currier = curry_right(func)
>>> currier = currier(1)
>>> assert isinstance(currier, CurryRight)
>>> currier = currier(2)
>>> assert isinstance(currier, CurryRight)
>>> currier = currier(3)
>>> currier
(3, 2, 1)

Added in version 1.1.0.

pydash.functions.debounce(func: Callable[[P], T], wait: int, max_wait: int | Literal[False] = False) Debounce[P, T][source]

Creates a function that will delay the execution of func until after wait milliseconds have elapsed since the last time it was invoked. Subsequent calls to the debounced function will return the result of the last func call.

Parameters:
  • func – Function to execute.

  • wait – Milliseconds to wait before executing func.

  • max_wait (optional) – Maximum time to wait before executing func.

Returns:

Function wrapped in a Debounce context.

Added in version 1.0.0.

pydash.functions.delay(func: ~typing.Callable[[~P], ~pydash.functions.T], wait: int, *args: ~typing.~P, **kwargs: ~typing.~P) T[source]

Executes the func function after wait milliseconds. Additional arguments will be provided to func when it is invoked.

Parameters:
  • func – Function to execute.

  • wait – Milliseconds to wait before executing func.

  • *args – Arguments to pass to func.

  • **kwargs – Keyword arguments to pass to func.

Returns:

Return from func.

Added in version 1.0.0.

pydash.functions.disjoin(*funcs: Callable[[T], Any]) Disjoin[T][source]

Creates a function that composes multiple predicate functions into a single predicate that tests whether any elements of an object pass each predicate.

Parameters:

*funcs – Function(s) to disjoin.

Returns:

Function(s) wrapped in a Disjoin context.

Example

>>> disjoiner = disjoin(lambda x: isinstance(x, float),                                lambda x: isinstance(x, int))
>>> disjoiner([1, '2', '3'])
True
>>> disjoiner([1.0, '2', '3'])
True
>>> disjoiner(['1', '2', '3'])
False

Added in version 2.0.0.

pydash.functions.flip(func: Callable[[T1, T2, T3, T4, T5], T]) Callable[[T5, T4, T3, T2, T1], T][source]
pydash.functions.flip(func: Callable[[T1, T2, T3, T4], T]) Callable[[T4, T3, T2, T1], T]
pydash.functions.flip(func: Callable[[T1, T2, T3], T]) Callable[[T3, T2, T1], T]
pydash.functions.flip(func: Callable[[T1, T2], T]) Callable[[T2, T1], T]
pydash.functions.flip(func: Callable[[T1], T]) Callable[[T1], T]

Creates a function that invokes the method with arguments reversed.

Parameters:

func – Function to flip arguments for.

Returns:

Function wrapped in a Flip context.

Example

>>> flipped = flip(lambda *args: args)
>>> flipped(1, 2, 3, 4)
(4, 3, 2, 1)
>>> flipped = flip(lambda *args: [i * 2 for i in args])
>>> flipped(1, 2, 3, 4)
[8, 6, 4, 2]

Added in version 4.0.0.

pydash.functions.flow(func1: Callable[[P], T2], func2: Callable[[T2], T3], func3: Callable[[T3], T4], func4: Callable[[T4], T5], func5: Callable[[T5], T]) Flow[P, T][source]
pydash.functions.flow(func1: Callable[[P], T2], func2: Callable[[T2], T3], func3: Callable[[T3], T4], func4: Callable[[T4], T]) Flow[P, T]
pydash.functions.flow(func1: Callable[[P], T2], func2: Callable[[T2], T3], func3: Callable[[T3], T]) Flow[P, T]
pydash.functions.flow(func1: Callable[[P], T2], func2: Callable[[T2], T]) Flow[P, T]
pydash.functions.flow(func1: Callable[[P], T]) Flow[P, T]

Creates a function that is the composition of the provided functions, where each successive invocation is supplied the return value of the previous. For example, composing the functions f(), g(), and h() produces h(g(f())).

Parameters:

*funcs – Function(s) to compose.

Returns:

Function(s) wrapped in a Flow context.

Example

>>> mult_5 = lambda x: x * 5
>>> div_10 = lambda x: x / 10.0
>>> pow_2 = lambda x: x**2
>>> ops = flow(sum, mult_5, div_10, pow_2)
>>> ops([1, 2, 3, 4])
25.0

Added in version 2.0.0.

Changed in version 2.3.1: Added pipe() as alias.

Changed in version 4.0.0: Removed alias pipe.

pydash.functions.flow_right(func5: Callable[[T4], T], func4: Callable[[T3], T4], func3: Callable[[T2], T3], func2: Callable[[T1], T2], func1: Callable[[P], T1]) Flow[P, T][source]
pydash.functions.flow_right(func4: Callable[[T3], T], func3: Callable[[T2], T3], func2: Callable[[T1], T2], func1: Callable[[P], T1]) Flow[P, T]
pydash.functions.flow_right(func3: Callable[[T2], T], func2: Callable[[T1], T2], func1: Callable[[P], T1]) Flow[P, T]
pydash.functions.flow_right(func2: Callable[[T1], T], func1: Callable[[P], T1]) Flow[P, T]
pydash.functions.flow_right(func1: Callable[[P], T]) Flow[P, T]

This function is like flow() except that it creates a function that invokes the provided functions from right to left. For example, composing the functions f(), g(), and h() produces f(g(h())).

Parameters:

*funcs – Function(s) to compose.

Returns:

Function(s) wrapped in a Flow context.

Example

>>> mult_5 = lambda x: x * 5
>>> div_10 = lambda x: x / 10.0
>>> pow_2 = lambda x: x**2
>>> ops = flow_right(mult_5, div_10, pow_2, sum)
>>> ops([1, 2, 3, 4])
50.0

Added in version 1.0.0.

Changed in version 2.0.0: Added flow_right() and made compose() an alias.

Changed in version 2.3.1: Added pipe_right() as alias.

Changed in version 4.0.0: Removed aliases pipe_right and compose.

pydash.functions.iterated(func: Callable[[T], T]) Iterated[T][source]

Creates a function that is composed with itself. Each call to the iterated function uses the previous function call’s result as input. Returned Iterated instance can be called with (initial, n) where initial is the initial value to seed func with and n is the number of times to call func.

Parameters:

func – Function to iterate.

Returns:

Function wrapped in a Iterated context.

Example

>>> doubler = iterated(lambda x: x * 2)
>>> doubler(4, 5)
128
>>> doubler(3, 9)
1536

Added in version 2.0.0.

pydash.functions.juxtapose(*funcs: Callable[[P], T]) Juxtapose[P, T][source]

Creates a function whose return value is a list of the results of calling each funcs with the supplied arguments.

Parameters:

*funcs – Function(s) to juxtapose.

Returns:

Function wrapped in a Juxtapose context.

Example

>>> double = lambda x: x * 2
>>> triple = lambda x: x * 3
>>> quadruple = lambda x: x * 4
>>> juxtapose(double, triple, quadruple)(5)
[10, 15, 20]

Added in version 2.0.0.

pydash.functions.negate(func: Callable[[P], Any]) Negate[P][source]

Creates a function that negates the result of the predicate func. The func function is executed with the arguments of the created function.

Parameters:

func – Function to negate execute.

Returns:

Function wrapped in a Negate context.

Example

>>> not_is_number = negate(lambda x: isinstance(x, (int, float)))
>>> not_is_number(1)
False
>>> not_is_number("1")
True

Added in version 1.1.0.

pydash.functions.once(func: Callable[[P], T]) Once[P, T][source]

Creates a function that is restricted to execute func once. Repeat calls to the function will return the value of the first call.

Parameters:

func – Function to execute.

Returns:

Function wrapped in a Once context.

Example

>>> oncer = once(lambda *args: args[0])
>>> oncer(5)
5
>>> oncer(6)
5

Added in version 1.0.0.

pydash.functions.over_args(func: Callable[[T1, T2, T3, T4, T5], T], transform_one: Callable[[T1], T1], transform_two: Callable[[T2], T2], transform_three: Callable[[T3], T3], transform_four: Callable[[T4], T4], transform_five: Callable[[T5], T5]) Callable[[T1, T2, T3, T4, T5], T][source]
pydash.functions.over_args(func: Callable[[T1, T2, T3, T4], T], transform_one: Callable[[T1], T1], transform_two: Callable[[T2], T2], transform_three: Callable[[T3], T3], transform_four: Callable[[T4], T4]) Callable[[T1, T2, T3, T4], T]
pydash.functions.over_args(func: Callable[[T1, T2, T3], T], transform_one: Callable[[T1], T1], transform_two: Callable[[T2], T2], transform_three: Callable[[T3], T3]) Callable[[T1, T2, T3], T]
pydash.functions.over_args(func: Callable[[T1, T2], T], transform_one: Callable[[T1], T1], transform_two: Callable[[T2], T2]) Callable[[T1, T2], T]
pydash.functions.over_args(func: Callable[[T1], T], transform_one: Callable[[T1], T1]) Callable[[T1], T]

Creates a function that runs each argument through a corresponding transform function.

Parameters:
  • func – Function to wrap.

  • *transforms – Functions to transform arguments, specified as individual functions or lists of functions.

Returns:

Function wrapped in a OverArgs context.

Example

>>> squared = lambda x: x**2
>>> double = lambda x: x * 2
>>> modder = over_args(lambda x, y: [x, y], squared, double)
>>> modder(5, 10)
[25, 20]

Added in version 3.3.0.

Changed in version 4.0.0: Renamed from mod_args to over_args.

pydash.functions.partial(func: Callable[[...], T], *args: Any, **kwargs: Any) Partial[T][source]

Creates a function that, when called, invokes func with any additional partial arguments prepended to those provided to the new function.

Parameters:
  • func – Function to execute.

  • *args – Partial arguments to prepend to function call.

  • **kwargs – Partial keyword arguments to bind to function call.

Returns:

Function wrapped in a Partial context.

Example

>>> dropper = partial(lambda array, n: array[n:], [1, 2, 3, 4])
>>> dropper(2)
[3, 4]
>>> dropper(1)
[2, 3, 4]
>>> myrest = partial(lambda array, n: array[n:], n=1)
>>> myrest([1, 2, 3, 4])
[2, 3, 4]

Added in version 1.0.0.

pydash.functions.partial_right(func: Callable[[...], T], *args: Any, **kwargs: Any) Partial[T][source]

This method is like partial() except that partial arguments are appended to those provided to the new function.

Parameters:
  • func – Function to execute.

  • *args – Partial arguments to append to function call.

  • **kwargs – Partial keyword arguments to bind to function call.

Returns:

Function wrapped in a Partial context.

Example

>>> myrest = partial_right(lambda array, n: array[n:], 1)
>>> myrest([1, 2, 3, 4])
[2, 3, 4]

Added in version 1.0.0.

pydash.functions.rearg(func: Callable[[P], T], *indexes: int) Rearg[P, T][source]

Creates a function that invokes func with arguments arranged according to the specified indexes where the argument value at the first index is provided as the first argument, the argument value at the second index is provided as the second argument, and so on.

Parameters:
  • func – Function to rearrange arguments for.

  • *indexes – The arranged argument indexes.

Returns:

Function wrapped in a Rearg context.

Example

>>> jumble = rearg(lambda *args: args, 1, 2, 3)
>>> jumble(1, 2, 3)
(2, 3, 1)
>>> jumble("a", "b", "c", "d", "e")
('b', 'c', 'd', 'a', 'e')

Added in version 3.0.0.

pydash.functions.spread(func: Callable[[...], T]) Spread[T][source]

Creates a function that invokes func with the array of arguments provided to the created function.

Parameters:

func – Function to spread.

Returns:

Function wrapped in a Spread context.

Example

>>> greet = spread(lambda *people: "Hello " + ", ".join(people) + "!")
>>> greet(["Mike", "Don", "Leo"])
'Hello Mike, Don, Leo!'

Added in version 3.1.0.

pydash.functions.throttle(func: Callable[[P], T], wait: int) Throttle[P, T][source]

Creates a function that, when executed, will only call the func function at most once per every wait milliseconds. Subsequent calls to the throttled function will return the result of the last func call.

Parameters:
  • func – Function to throttle.

  • wait – Milliseconds to wait before calling func again.

Returns:

Results of last func call.

Added in version 1.0.0.

pydash.functions.unary(func: Callable[[...], T]) Ary[T][source]

Creates a function that accepts up to one argument, ignoring any additional arguments.

Parameters:

func – Function to cap arguments for.

Returns:

Function wrapped in an Ary context.

Example

>>> func = lambda a, b=1, c=0, d=5: (a, b, c, d)
>>> unary_func = unary(func)
>>> unary_func(1, 2, 3, 4, 5, 6)
(1, 1, 0, 5)
>>> unary_func(1, 2, 3, 4, 5, 6, b=0, c=10, d=20)
(1, 0, 10, 20)

Added in version 4.0.0.

pydash.functions.wrap(value: T1, func: Callable[[Concatenate[T1, P]], T]) Partial[T][source]

Creates a function that provides value to the wrapper function as its first argument. Additional arguments provided to the function are appended to those provided to the wrapper function.

Parameters:
  • value – Value provided as first argument to function call.

  • func – Function to execute.

Returns:

Function wrapped in a Partial context.

Example

>>> wrapper = wrap("hello", lambda *args: args)
>>> wrapper(1, 2)
('hello', 1, 2)

Added in version 1.0.0.

Numerical

Numerical/mathematical related functions.

Added in version 2.1.0.

pydash.numerical.add(a: SupportsAdd[T, T2], b: T) T2[source]
pydash.numerical.add(a: T, b: SupportsAdd[T, T2]) T2

Adds two numbers.

Parameters:
  • a – First number to add.

  • b – Second number to add.

Returns:

number

Example

>>> add(10, 5)
15

Added in version 2.1.0.

Changed in version 3.3.0: Support adding two numbers when passed as positional arguments.

Changed in version 4.0.0: Only support two argument addition.

pydash.numerical.ceil(x: float | int | Decimal, precision: int = 0) float[source]

Round number up to precision.

Parameters:
  • x – Number to round up.

  • precision – Rounding precision. Defaults to 0.

Returns:

Number rounded up.

Example

>>> ceil(3.275) == 4.0
True
>>> ceil(3.215, 1) == 3.3
True
>>> ceil(6.004, 2) == 6.01
True

Added in version 3.3.0.

pydash.numerical.clamp(x: NumT, lower: NumT2, upper: NumT3 | None = None) NumT | NumT2 | NumT3[source]

Clamps number within the inclusive lower and upper bounds.

Parameters:
  • x – Number to clamp.

  • lower – Lower bound.

  • upper – Upper bound

Returns:

number

Example

>>> clamp(-10, -5, 5)
-5
>>> clamp(10, -5, 5)
5
>>> clamp(10, 5)
5
>>> clamp(-10, 5)
-10

Added in version 4.0.0.

pydash.numerical.divide(dividend: float | int | Decimal | None, divisor: float | int | Decimal | None) float[source]

Divide two numbers.

Parameters:
  • dividend – The first number in a division.

  • divisor – The second number in a division.

Returns:

Returns the quotient.

Example

>>> divide(20, 5)
4.0
>>> divide(1.5, 3)
0.5
>>> divide(None, None)
1.0
>>> divide(5, None)
5.0

Added in version 4.0.0.

pydash.numerical.floor(x: float | int | Decimal, precision: int = 0) float[source]

Round number down to precision.

Parameters:
  • x – Number to round down.

  • precision – Rounding precision. Defaults to 0.

Returns:

Number rounded down.

Example

>>> floor(3.75) == 3.0
True
>>> floor(3.215, 1) == 3.2
True
>>> floor(0.046, 2) == 0.04
True

Added in version 3.3.0.

pydash.numerical.max_(collection: t.Mapping[t.Any, 'SupportsRichComparisonT'], default: Unset = UNSET) SupportsRichComparisonT[source]
pydash.numerical.max_(collection: t.Mapping[t.Any, 'SupportsRichComparisonT'], default: T) t.Union['SupportsRichComparisonT', T]
pydash.numerical.max_(collection: t.Iterable['SupportsRichComparisonT'], default: Unset = UNSET) SupportsRichComparisonT
pydash.numerical.max_(collection: t.Iterable['SupportsRichComparisonT'], default: T) t.Union['SupportsRichComparisonT', T]

Retrieves the maximum value of a collection.

Parameters:
  • collection – Collection to iterate over.

  • default – Value to return if collection is empty.

Returns:

Maximum value.

Example

>>> max_([1, 2, 3, 4])
4
>>> max_([], default=-1)
-1

Added in version 1.0.0.

Changed in version 4.0.0: Moved iteratee iteratee support to max_by().

pydash.numerical.max_by(collection: t.Mapping[t.Any, 'SupportsRichComparisonT'], iteratee: None = None, default: Unset = UNSET) SupportsRichComparisonT[source]
pydash.numerical.max_by(collection: Mapping[Any, T2], iteratee: t.Callable[[T2], 'SupportsRichComparisonT'], default: Unset = UNSET) T2
pydash.numerical.max_by(collection: Mapping[Any, T2], iteratee: t.Callable[[T2], 'SupportsRichComparisonT'], *, default: T) T2 | T
pydash.numerical.max_by(collection: t.Mapping[t.Any, 'SupportsRichComparisonT'], iteratee: None = None, *, default: T) t.Union['SupportsRichComparisonT', T]
pydash.numerical.max_by(collection: t.Iterable['SupportsRichComparisonT'], iteratee: None = None, default: Unset = UNSET) SupportsRichComparisonT
pydash.numerical.max_by(collection: Iterable[T2], iteratee: t.Callable[[T2], 'SupportsRichComparisonT'], default: Unset = UNSET) T2
pydash.numerical.max_by(collection: Iterable[T2], iteratee: t.Callable[[T2], 'SupportsRichComparisonT'], *, default: T) T2 | T
pydash.numerical.max_by(collection: t.Iterable['SupportsRichComparisonT'], iteratee: None = None, *, default: T) t.Union['SupportsRichComparisonT', T]
pydash.numerical.max_by(collection: Iterable[T], iteratee: int | str | List | Tuple | Dict, default: Unset = UNSET) T
pydash.numerical.max_by(collection: Iterable[T], iteratee: int | str | List | Tuple | Dict, default: T2) T | T2

Retrieves the maximum value of a collection.

Parameters:
  • collection – Collection to iterate over.

  • iteratee – Iteratee applied per iteration.

  • default – Value to return if collection is empty.

Returns:

Maximum value.

Example

>>> max_by([1.0, 1.5, 1.8], math.floor)
1.0
>>> max_by([{"a": 1}, {"a": 2}, {"a": 3}], "a")
{'a': 3}
>>> max_by([], default=-1)
-1

Added in version 4.0.0.

pydash.numerical.mean(collection: t.Mapping[t.Any, 'SupportsAdd[int, t.Any]']) float[source]
pydash.numerical.mean(collection: t.Iterable['SupportsAdd[int, t.Any]']) float

Calculate arithmetic mean of each element in collection.

Parameters:

collection – Collection to process.

Returns:

Result of mean.

Example

>>> mean([1, 2, 3, 4])
2.5

Added in version 2.1.0.

Changed in version 4.0.0:

  • Removed average and avg aliases.

  • Moved iteratee functionality to mean_by().

pydash.numerical.mean_by(collection: Mapping[T, T2], iteratee: t.Callable[[T2, T, t.Dict[T, T2]], 'SupportsAdd[int, t.Any]']) float[source]
pydash.numerical.mean_by(collection: Mapping[T, T2], iteratee: t.Callable[[T2, T], 'SupportsAdd[int, t.Any]']) float
pydash.numerical.mean_by(collection: Mapping[Any, T2], iteratee: t.Callable[[T2], 'SupportsAdd[int, t.Any]']) float
pydash.numerical.mean_by(collection: Iterable[T], iteratee: t.Callable[[T, int, t.List[T]], 'SupportsAdd[int, t.Any]']) float
pydash.numerical.mean_by(collection: Iterable[T], iteratee: t.Callable[[T, int], 'SupportsAdd[int, t.Any]']) float
pydash.numerical.mean_by(collection: Iterable[T], iteratee: t.Callable[[T], 'SupportsAdd[int, t.Any]']) float
pydash.numerical.mean_by(collection: t.Mapping[t.Any, 'SupportsAdd[int, t.Any]'], iteratee: None = None) float
pydash.numerical.mean_by(collection: t.Iterable['SupportsAdd[int, t.Any]'], iteratee: None = None) float

Calculate arithmetic mean of each element in collection. If iteratee is passed, each element of collection is passed through an iteratee before the mean is computed.

Parameters:
  • collection – Collection to process.

  • iteratee – Iteratee applied per iteration.

Returns:

Result of mean.

Example

>>> mean_by([1, 2, 3, 4], lambda x: x**2)
7.5

Added in version 4.0.0.

pydash.numerical.median(collection: Mapping[T, T2], iteratee: Callable[[T2, T, Dict[T, T2]], float | int | Decimal]) float | int[source]
pydash.numerical.median(collection: Mapping[T, T2], iteratee: Callable[[T2, T], float | int | Decimal]) float | int
pydash.numerical.median(collection: Mapping[Any, T2], iteratee: Callable[[T2], float | int | Decimal]) float | int
pydash.numerical.median(collection: Iterable[T], iteratee: Callable[[T, int, List[T]], float | int | Decimal]) float | int
pydash.numerical.median(collection: Iterable[T], iteratee: Callable[[T, int], float | int | Decimal]) float | int
pydash.numerical.median(collection: Iterable[T