More Itertools

https://more-itertools.readthedocs.io/en/stable
Admin
More Itertools is a Python library that provides a collection of additional building blocks,...
Tokens:156,783
Snippets:1,162
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install more-itertools

Source: https://more-itertools.readthedocs.io/en/stable/index.html

Install the library using pip. This is the first step to using the additional itertools functions.

```bash
pip install more-itertools

```

--------------------------------

### Generating an infinite iterator with iterate and take

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Shows how to use iterate to create an infinite iterator and take to limit the number of items yielded. The example doubles the previous value starting from 1.

```python
>>> take(10, iterate(lambda x: 2*x, 1))
[1, 2, 4, 8, 16, 32, 64, 128, 256, 512]
```

--------------------------------

### Bucket Example: Handling Non-existent or Invalid Buckets

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Illustrates the behavior of the 'bucket' class when checking for the existence of a bucket or retrieving items from a bucket that does not contain valid items according to the validator. This example uses an infinite iterator.

```python
from itertools import count
it = count(1, 2)  # Infinite sequence of odd numbers
key = lambda x: x % 10  # Bucket by last digit
validator = lambda x: x in {1, 3, 5, 7, 9}  # Odd digits only
s = bucket(it, key=key, validator=validator)
2 in s
list(s[2])
```

--------------------------------

### Generate a numeric range with Fraction start, stop, and step

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Supports Fraction types for start, stop, and step. Output items match the type of start + step.

```python
>>> from fractions import Fraction
>>> start = Fraction(1, 2)  # Start at 1/2
>>> stop = Fraction(5, 2)  # End at 5/2
>>> step = Fraction(1, 2)  # Count by 1/2
>>> list(numeric_range(start, stop, step))
[Fraction(1, 2), Fraction(1, 1), Fraction(3, 2), Fraction(2, 1)]
```

--------------------------------

### Install tox for Multiple Python Versions

Source: https://more-itertools.readthedocs.io/en/stable/_sources/testing.rst.txt

Install the tox tool, which is used to automate testing across different Python versions. This is a prerequisite for running tox tests.

```bash
pip install tox
```

--------------------------------

### iterate

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Return start, func(start), func(func(start)), ... producing an infinite iterator.

```APIDOC
## iterate(func, start)

### Description
Return ``start``, ``func(start)``, ``func(func(start))``, and so on, producing an infinite iterator.

### Method Signature
`iterate(func, start)`

### Parameters
* `func` - A function that takes one argument and returns a value.
* `start` - The initial value to begin the iteration.

### Returns
An iterator yielding the sequence generated by repeatedly applying `func` to `start`.

### Example
```python
# Take the first 10 elements of an iteration starting at 1 and doubling each time
# take(10, iterate(lambda x: 2*x, 1))
# Result: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512]

# Collatz sequence example
# collatz = lambda x: 3*x + 1 if x%2==1 else x // 2
# list(takewhile_inclusive(lambda x: x!=1, iterate(collatz, 10)))
# Result: [10, 5, 16, 8, 4, 2, 1]
```

### Note
To add a stopping condition, use functions like :func:`take`, ``takewhile``, or :func:`takewhile_inclusive`.
```

--------------------------------

### SequenceView Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates how SequenceView provides a dynamic view of a sequence that updates with the sequence. It supports indexing, slicing, and length queries but not assignment.

```python
>>> seq = ['0', '1', '2']
>>> view = SequenceView(seq)
>>> view
SequenceView(['0', '1', '2'])
>>> seq.append('3')
>>> view
SequenceView(['0', '1', '2', '3'])
```

```python
>>> view[1]
'1'
>>> view[1:-1]
['1', '2']
>>> len(view)
4
```

--------------------------------

### Install tox for Multiple Python Versions

Source: https://more-itertools.readthedocs.io/en/stable/testing.html

Install the tox tool, which is used to automate testing across different Python versions. This is a prerequisite for running tests on all supported Python environments.

```bash
pip install tox

```

--------------------------------

### Run Unit Tests

Source: https://more-itertools.readthedocs.io/en/stable/_sources/testing.rst.txt

Execute the project's unit tests using the standard Python unittest module. Ensure all dependencies are installed before running.

```bash
python -m unittest
```

--------------------------------

### Generate a numeric range with Decimal start and stop values

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Accepts Decimal types for start and stop, with step defaulting to 1. Output items match the type of start.

```python
>>> from decimal import Decimal
>>> start = Decimal('2.1')
>>> stop = Decimal('5.1')
>>> list(numeric_range(start, stop))
[Decimal('2.1'), Decimal('3.1'), Decimal('4.1')]
```

--------------------------------

### Numeric Range with Custom Start, Stop, and Step

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Creates a sequence similar to Python's built-in range but accepts any orderable numeric type for start, stop, and step arguments. The output type matches the type of the start and step arguments. Raises ValueError if step is zero.

```Python
>>> list(numeric_range(3.5))
[0.0, 1.0, 2.0, 3.0]
```

```Python
>>> from decimal import Decimal
>>> start = Decimal('2.1')
>>> stop = Decimal('5.1')
>>> list(numeric_range(start, stop))
[Decimal('2.1'), Decimal('3.1'), Decimal('4.1')]
```

```Python
>>> from fractions import Fraction
>>> start = Fraction(1, 2)  # Start at 1/2
>>> stop = Fraction(5, 2)  # End at 5/2
>>> step = Fraction(1, 2)  # Count by 1/2
>>> list(numeric_range(start, stop, step))
[Fraction(1, 2), Fraction(1, 1), Fraction(3, 2), Fraction(2, 1)]
```

```Python
>>> list(numeric_range(3, -1, -1.0))
[3.0, 2.0, 1.0, 0.0]
```

--------------------------------

### Seekable Iterator Reset Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Shows how to reset a seekable iterator to its beginning using the seek(0) method. This is useful for re-processing elements from the start of an iterable.

```python
>>> from itertools import count
>>> it = seekable((str(n) for n in count()))
>>> next(it), next(it), next(it)
('0', '1', '2')
>>> it.seek(0)
>>> next(it), next(it), next(it)
('0', '1', '2')
```

--------------------------------

### split_into example with exact sizes

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Splits an iterable into chunks of specified lengths. Useful for parsing data streams or fixed-size records.

```python
>>> list(split_into([1,2,3,4,5,6], [1,2,3]))
[[1], [2, 3], [4, 5, 6]]
```

--------------------------------

### split_before example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Splits an iterable into lists, where each list ends just before an item satisfying the predicate. Useful for segmenting data based on a condition met by the start of a new segment.

```python
>>> list(split_before('OneTwo', lambda s: s.isupper()))
[['O', 'n', 'e'], ['T', 'w', 'o']]
```

--------------------------------

### Peekable Prepend Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates how to prepend items to a peekable iterator, allowing them to be returned before existing items. This can also be used to 'resurrect' a peekable that has raised StopIteration.

```python
>>> p = peekable([1, 2, 3])
>>> p.prepend(10, 11, 12)
>>> next(p)
10
>>> list(p)
[11, 12, 1, 2, 3]
```

```python
>>> p = peekable([])
>>> next(p)
Traceback (most recent call last):
  ...
StopIteration
>>> p.prepend(1)
>>> next(p)
1
>>> next(p)
Traceback (most recent call last):
  ...
StopIteration
```

--------------------------------

### Run Tests with tox

Source: https://more-itertools.readthedocs.io/en/stable/_sources/testing.rst.txt

Execute the project's tests across all supported Python versions using tox. This command should be run after installing tox and its dependencies.

```bash
tox
```

--------------------------------

### split_into example with fewer items than sizes

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates split_into when the iterable is shorter than the sum of specified sizes. Shows that fewer items are returned and subsequent lists are empty.

```python
>>> list(split_into([1,2,3,4], [1,2,3,4]))
[[1], [2, 3], [4], []]
```

--------------------------------

### tabulate(function, start=0)

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Returns an iterator over the results of ``func(start)``, ``func(start + 1)``, ``func(start + 2)``... The function should accept one integer argument.

```APIDOC
## tabulate(function, start=0)

### Description
Return an iterator over the results of ``func(start)``, ``func(start + 1)``, ``func(start + 2)``...

*func* should be a function that accepts one integer argument.

If *start* is not specified it defaults to 0. It will be incremented each time the iterator is advanced.

### Parameters
#### Path Parameters
- **function** (callable) - Required - The function to apply to each number.
- **start** (integer) - Optional - The starting number for the sequence (defaults to 0).

### Response
#### Success Response (iterator)
- Returns an iterator yielding the results of applying the function to the sequence of numbers.
```

--------------------------------

### nth_product Example

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Calculates the nth product of iterables. The `repeat` argument specifies the number of repetitions.

```python
>>> nth_product(8, range(2), repeat=4)
(1, 0, 0, 0)
```

--------------------------------

### Seekable Iterator Peek Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Shows how to use the peek method to look at the next item in a seekable iterator without advancing the iterator. A default value can be provided for when the iterator is empty.

```python
>>> it = seekable('1234')
>>> it.peek()
'1'
>>> list(it)
['1', '2', '3', '4']
>>> it.peek(default='empty')
'empty'
```

--------------------------------

### split_when example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Splits an iterable based on a predicate applied to adjacent pairs of items. Useful for detecting changes or boundaries between consecutive elements.

```python
>>> list(split_when([1, 2, 3, 3, 2, 5, 2, 4, 2], lambda x, y: x > y))
[[1, 2, 3, 3], [2, 5], [2, 4], [2]]
```

--------------------------------

### Seekable Iterator Forward Seek Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates seeking forward in a seekable iterator. Seeking past the end of the source is handled gracefully, and resetting is possible even after reaching the end.

```python
>>> it = seekable((str(n) for n in range(20)))
>>> it.seek(10)
>>> next(it)
'10'
>>> it.seek(20)
>>> list(it)
[]
>>> it.seek(0)
>>> next(it)
'0'
```

--------------------------------

### nth_permutation Example

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Computes the nth lexicographically ordered permutation of a given length without generating previous permutations. Raises IndexError for invalid index or ValueError for negative r.

```python
>>> nth_permutation('ghijk', 2, 5)
('h', 'i')
```

--------------------------------

### Get Substrings and Indexes with `substrings_indexes`

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Yields all substrings along with their start and end indexes for iterables that support slicing. The `reverse` parameter controls the order of yielded items.

```python
>>> for item in substrings_indexes('more'):
...    print(item)
('m', 0, 1)
('o', 1, 2)
('r', 2, 3)
('e', 3, 4)
('mo', 0, 2)
('or', 1, 3)
('re', 2, 4)
('mor', 0, 3)
('ore', 1, 4)
('more', 0, 4)
```

--------------------------------

### Get nth prime number with more_itertools.nth_prime

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Returns the nth prime number, starting from 0. Set approximate=True for a much faster estimation of a prime close to the nth prime.

```python
>>> nth_prime(0)
2
>>> nth_prime(100)
547
```

```python
>>> nth_prime(200_000_000, approximate=True)  # Exact result is 4222234763
4217820427
```

--------------------------------

### Bucket Example: Grouping and Accessing Items

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates how to use the 'bucket' class to group items from an iterable based on a key function and access these groups. Shows retrieving items from a specific bucket.

```python
iterable = ['a1', 'b1', 'c1', 'a2', 'b2', 'c2', 'b3']
s = bucket(iterable, key=lambda x: x[0])  # Bucket by 1st character
sorted(list(s))  # Get the keys
a_iterable = s['a']
next(a_iterable)
next(a_iterable)
list(s['b'])
```

--------------------------------

### Create and Use a SequenceView

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Demonstrates creating a read-only view of a mutable sequence and observing its updates.

```python
>>> seq = ['0', '1', '2']
>>> view = SequenceView(seq)
>>> view
SequenceView(['0', '1', '2'])
>>> seq.append('3')
>>> view
SequenceView(['0', '1', '2', '3'])
```

--------------------------------

### Spying on the first N elements of an iterable

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Use spy to get the first N elements of an iterable and an iterator over the same elements. This is useful for inspecting the start of an iterable without consuming it.

```python
>>> iterable = 'abcdefg'
>>> head, iterable = spy(iterable)
>>> head
['a']
>>> list(iterable)
['a', 'b', 'c', 'd', 'e', 'f', 'g']
```

```python
>>> (head,), iterable = spy('abcdefg')
>>> head
'a'
>>> (first, second), iterable = spy('abcdefg', 2)
>>> first
'a'
>>> second
'b'
```

```python
>>> iterable = [1, 2, 3, 4, 5]
>>> head, iterable = spy(iterable, 10)
>>> head
[1, 2, 3, 4, 5]
>>> list(iterable)
[1, 2, 3, 4, 5]
```

--------------------------------

### Seekable Iterator Elements View Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Illustrates using the elements method to get a SequenceView of the cached items in a seekable iterator. This view dynamically updates as new elements are consumed.

```python
>>> it = seekable((str(n) for n in range(10)))
>>> next(it), next(it), next(it)
('0', '1', '2')
>>> elements = it.elements()
>>> elements
SequenceView(['0', '1', '2'])
>>> next(it)
'3'
>>> elements
SequenceView(['0', '1', '2', '3'])
```

--------------------------------

### Generate set partitions with size constraints

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Use `set_partitions` with `min_size` and `max_size` arguments to control the size of each block within the partitions.

```python
>>> iterable = 'abc'
>>> for part in set_partitions(iterable, min_size=2):
...     print([''.join(p) for p in part])
['abc']
>>> for part in set_partitions(iterable, max_size=2):
...     print([''.join(p) for p in part])
['a', 'bc']
['ab', 'c']
['b', 'ac']
['a', 'b', 'c']

```

--------------------------------

### take

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Returns the first n items of an iterable as a list.

```APIDOC
## take

### Description
Returns a list containing the first `n` items from the provided iterable. If the iterable has fewer than `n` items, all available items are returned.

### Parameters
- `_n_`: The number of items to take.
- `_iterable_`: The input iterable.
```

--------------------------------

### Reconstructing sequence with initial value using difference

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Demonstrates how the 'initial' keyword argument in difference can be used to reconstruct a sequence when the accumulated iterable had an initial value.

```python
>>> it = [10, 11, 13, 16]  # from accumulate([1, 2, 3], initial=10)
>>> list(difference(it, initial=10))
[1, 2, 3]
```

--------------------------------

### sample(iterable, k, weights=None, *, counts=None, strict=False)

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Return a k-length list of elements chosen (without replacement) from the iterable. This function works on inputs that aren't indexable and on inputs where the size isn't known in advance. It supports weighted selections and can handle iterables with repeated elements using the `counts` parameter.

```APIDOC
## sample(iterable, k, weights=None, *, counts=None, strict=False)

### Description
Return a *k*-length list of elements chosen (without replacement) from the *iterable*. Similar to :func:`random.sample`, but works on inputs that aren't indexable (such as sets and dictionaries) and on inputs where the size isn't known in advance (such as generators).

For iterables with repeated elements, you may supply *counts* to indicate the repeats.

An iterable with *weights* may be given. Weighted selections are made without replacement. After an element is selected, it is removed from the pool and the relative weights of the other elements increase. Note that *weights* may not be used with *counts*.

If the length of *iterable* is less than *k*, ``ValueError`` is raised if *strict* is ``True`` and all elements are returned (in shuffled order) if *strict* is ``False``.

By default, the `Algorithm L <https://w.wiki/ANrM>`__ reservoir sampling technique is used. When *weights* are provided, `Algorithm A-ExpJ <https://w.wiki/ANrS>`__ is used instead.

### Parameters
* **iterable**: The input iterable to sample from.
* **k**: The number of elements to sample.
* **weights** (Optional): An iterable of weights corresponding to the elements in `iterable`. Cannot be used with `counts`.
* **counts** (Optional): An iterable of counts corresponding to the elements in `iterable`. Indicates repeats of elements.
* **strict** (Optional): If True, raises ValueError if the length of `iterable` is less than `k`. Defaults to False.

### Notes on reproducibility:

* The algorithms rely on inexact floating-point functions provided by the underlying math library (e.g. ``log``, ``log1p``, and ``pow``). Those functions can `produce slightly different results <https://members.loria.fr/PZimmermann/papers/accuracy.pdf>`_ on different builds. Accordingly, selections can vary across builds even for the same seed.

* The algorithms loop over the input and make selections based on ordinal position, so selections from unordered collections (such as sets) won't reproduce across sessions on the same platform using the same seed.
```

--------------------------------

### Generating Infinite Sequences with iterate

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

The iterate function generates an infinite sequence starting with 'start' and applying 'func' repeatedly. Use with functions like take or takewhile to limit the output.

```python
>>> take(10, iterate(lambda x: 2*x, 1))
[1, 2, 4, 8, 16, 32, 64, 128, 256, 512]
```

```python
>>> collatz = lambda x: 3*x + 1 if x%2==1 else x // 2
>>> list(takewhile_inclusive(lambda x: x!=1, iterate(collatz, 10)))
[10, 5, 16, 8, 4, 2, 1]
```

--------------------------------

### more_itertools.iterate

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Return an infinite iterator starting with a given value and repeatedly applying a function.

```APIDOC
## more_itertools.iterate

### Description
Return `start`, `func(start)`, `func(func(start))`, … Produces an infinite iterator.

### Parameters
- **_func_** (function) - The function to apply repeatedly.
- **_start_** (any) - The initial value for the iterator.

### Request Example
```python
from more_itertools import take, iterate, takewhile_inclusive

# Example: Exponential growth
list(take(10, iterate(lambda x: 2*x, 1)))

# Example: Collatz conjecture sequence
collatz = lambda x: 3*x + 1 if x%2==1 else x // 2
list(takewhile_inclusive(lambda x: x!=1, iterate(collatz, 10)))
```

### Response
#### Success Response (Iterator)
An infinite iterator yielding values generated by repeatedly applying the function.

#### Response Example
(No direct response example, as it's an infinite iterator)
```

--------------------------------

### Weighted Random Sampling (A-ExpJ)

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Implements weighted random sampling using the 'A-ExpJ' algorithm for numerical stability with weights. It uses a reservoir-based approach and log-transformed weights.

```python
def _sample_weighted(iterator, k, weights, strict):
    # Implementation of "A-ExpJ" from the 2006 paper by Efraimidis et al. :
    # "Weighted random sampling with a reservoir".

    # Log-transform for numerical stability for weights that are small/large
    weight_keys = (log(random()) / weight for weight in weights)

    # Fill up the reservoir (collection of samples) with the first `k`
    # weight-keys and elements, then heapify the list.
    reservoir = take(k, zip(weight_keys, iterator))
    if strict and len(reservoir) < k:
        raise ValueError('Sample larger than population')

    heapify(reservoir)

    # The number of jumps before changing the reservoir is a random variable
    # with an exponential distribution. Sample it using random() and logs.
    smallest_weight_key, _ = reservoir[0]
    weights_to_skip = log(random()) / smallest_weight_key

    for weight, element in zip(weights, iterator):
        if weight >= weights_to_skip:
            # The notation here is consistent with the paper, but we store
            # the weight-keys in log-space for better numerical stability.
            smallest_weight_key, _ = reservoir[0]
            t_w = exp(weight * smallest_weight_key)
            r_2 = uniform(t_w, 1)  # generate U(t_w, 1)
            weight_key = log(r_2) / weight
            heapreplace(reservoir, (weight_key, element))
            smallest_weight_key, _ = reservoir[0]
            weights_to_skip = log(random()) / smallest_weight_key
        else:
            weights_to_skip -= weight

    ret = [element for weight_key, element in reservoir]
    shuffle(ret)
    return ret
```

--------------------------------

### iter_index

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Yields the index of each occurrence of a specified value within an iterable, optionally within a start and stop range.

```APIDOC
## iter_index

### Description
Yield the index of each place in _iterable_ that _value_ occurs, beginning with index _start_ and ending before index _stop_.

The behavior for non-scalar _values_ matches the built-in Python types.

### Usage
```python
# Find all occurrences of 'A'
list(iter_index('AABCADEAF', 'A'))
# Output: [0, 1, 4, 7]

# Start searching from index 1
list(iter_index('AABCADEAF', 'A', 1))
# Output: [1, 4, 7]

# Search within a range (exclusive of stop index)
list(iter_index('AABCADEAF', 'A', 1, 7))
# Output: [1, 4]

# Searching for substrings
list(iter_index('ABCDABCD', 'AB'))
# Output: [0, 4]

# Searching for lists within a list of lists
list(iter_index([[0, 1], [2, 3], [0, 1], [2, 3]], [0, 1]))
# Output: [0, 2]
```

See `locate()` for a more general means of finding the indexes associated with particular values.
```

--------------------------------

### more_itertools.islice_extended

Source: https://more-itertools.readthedocs.io/en/stable/api.html

An extended version of itertools.islice that supports negative values for stop, start, and step, and allows slice notation.

```APIDOC
## more_itertools.islice_extended

### Description
An extension of `itertools.islice()` that supports negative values for _stop_, _start_, and _step_. It also supports direct slice notation.

### Parameters
- `_iterable_`: The input iterable.
- `_start`: The starting index (can be negative).
- `_stop`: The stopping index (can be negative).
- `_step`: The step value (can be negative).
```

--------------------------------

### Running Minimum Calculation

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Calculates the smallest value seen so far. Use *maxlen* to specify a sliding window size.

```python
>>> list(running_min([4, 3, 7, 0, 8, 1, 6, 2, 9, 5]))
[4, 3, 3, 0, 0, 0, 0, 0, 0, 0]
```

```python
>>> list(running_min([4, 3, 7, 0, 8, 1, 6, 2, 9, 5], maxlen=3))
[4, 3, 3, 0, 0, 0, 1, 1, 2, 2]
```

--------------------------------

### numeric_range

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

An extension of the built-in range() function that accepts any orderable numeric type for start, stop, and step arguments.

```APIDOC
## numeric_range(start, stop[, step])

### Description
An extension of the built-in ``range()`` function whose arguments can be any orderable numeric type. It supports various numeric types including floats, Decimals, Fractions, and datetime objects with timedelta steps.

### Parameters
#### Path Parameters
- **start**: The starting value of the range. Can be any orderable numeric type.
- **stop**: The ending value of the range (exclusive). Can be any orderable numeric type.
- **step**: The step value. Can be any orderable numeric type. Defaults to 1. If step is zero, ValueError is raised. For datetime objects, step must be a timedelta object.

### Response
#### Success Response (200)
- **numeric_value**: Yields numbers of the appropriate numeric type within the specified range.
```

--------------------------------

### Map Reduce with Key, Value, and Reduce Functions

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Groups items by a key function, transforms them with a value function, and then summarizes each group using a reduce function.

```python
>>> keyfunc = lambda x: x.upper()
>>> valuefunc = lambda x: 1
>>> reducefunc = sum
>>> result = map_reduce('abbccc', keyfunc, valuefunc, reducefunc)
>>> sorted(result.items())
[('A', 1), ('B', 2), ('C', 3)]
```

--------------------------------

### Generating All Substrings of an Iterable

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Yields all contiguous substrings (as tuples) of a given iterable, starting with the shortest. Works for any iterable, not just strings.

```python
from more_itertools import substrings

# For strings
print([''.join(s) for s in substrings('more')])
# Output: ['m', 'o', 'r', 'e', 'mo', 'or', 're', 'mor', 'ore', 'more']

# For non-string iterables
print(list(substrings([0, 1, 2])))
# Output: [(0,), (1,), (2,), (0, 1), (1, 2), (0, 1, 2)]
```

--------------------------------

### split_before basic usage

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Illustrates the fundamental behavior of split_before, splitting an iterable based on a predicate. Useful for partitioning sequences into sub-sequences.

```python
>>> list(split_before(range(10), lambda n: n % 3 == 0))
[[0, 1, 2], [3, 4, 5], [6, 7, 8], [9]]
```

--------------------------------

### side_effect

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Invokes a function on each item or chunk of items from an iterable before yielding the item. It can also execute functions before iteration starts and after it ends.

```APIDOC
## side_effect(func, iterable, chunk_size=None, before=None, after=None)

### Description
Invoke *func* on each item in *iterable* (or on each *chunk_size* group of items) before yielding the item. `func` must be a function that takes a single argument. Its return value will be discarded. *before* and *after* are optional functions that take no arguments. They will be executed before iteration starts and after it ends, respectively.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```python
# Emitting a status message:
from more_itertools import consume
func = lambda item: print('Received {}'.format(item))
consume(side_effect(func, range(2)))
# Output: Received 0\nReceived 1

# Operating on chunks of items:
pair_sums = []
func = lambda chunk: pair_sums.append(sum(chunk))
list(side_effect(func, [0, 1, 2, 3, 4, 5], 2))
# Output: [0, 1, 2, 3, 4, 5]
list(pair_sums)
# Output: [1, 5, 9]

# Writing to a file-like object:
from io import StringIO
from more_itertools import consume
f = StringIO()
func = lambda x: print(x, file=f)
before = lambda: print(u'HEADER', file=f)
after = f.close
it = [u'a', u'b', u'c']
consume(side_effect(func, it, before=before, after=after))
f.closed
# Output: True
```

### Response
#### Success Response (200)
- Yields items from the iterable after invoking the side effect function.

#### Response Example
```json
{
  "example": "[0, 1, 2, 3, 4, 5]"
}
```
```

--------------------------------

### always_reversible Example

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Reverses any iterable, including those not natively supporting reversal. Caches non-reversible iterables, potentially using significant memory.

```python
>>> print(*always_reversible(x for x in range(3)))
2 1 0
```

--------------------------------

### Collapse Bytes and Strings

Source: https://more-itertools.readthedocs.io/en/stable/_sources/versions.rst.txt

Demonstrates the behavior of the `collapse` function when encountering bytes objects, which are now treated similarly to strings.

```python
from more_itertools import collapse
iterable = [[1, 2], b'345', [6]]
print(list(collapse(iterable)))
```

--------------------------------

### Progressive division using difference with a custom function

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Illustrates using the difference function with a custom lambda function for progressive division to recover an original sequence.

```python
>>> iterable = [1, 2, 6, 24, 120]
>>> func = lambda x, y: x // y
>>> list(difference(iterable, func))
[1, 2, 3, 4, 5]
```

--------------------------------

### Seekable Iterator with Maxlen Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Demonstrates using the maxlen parameter to limit the cache size of a seekable iterator. This restricts how far back one can seek and causes older elements to be discarded.

```python
>>> from itertools import count
>>> it = seekable((str(n) for n in count()), maxlen=2)
>>> next(it), next(it), next(it), next(it)
('0', '1', '2', '3')
>>> list(it.elements())
['2', '3']
>>> it.seek(0)
>>> next(it), next(it), next(it), next(it)
('2', '3', '4', '5')
>>> next(it)
'6'
```

--------------------------------

### Yield Index of Value Occurrences

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Yields the index of each occurrence of a specified value within an iterable, within a given start and stop range.

```Python
def iter_index(iterable, value, start=0, stop=None):
    """Yield the index of each place in *iterable* that *value* occurs,
    beginning with index *start* and ending before index *stop*.

```

--------------------------------

### Customizing strictly_n Error Handling (Too Long)

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Allows custom handling for iterables that are too long by providing a `too_long` function. This example prints a message.

```python
>>> def too_long(item_count):
...     print('The boss is going to hear about this')
>>> it = strictly_n('abcdef', 4, too_long=too_long)
>>> list(it)
The boss is going to hear about this
['a', 'b', 'c', 'd']


```

--------------------------------

### Customizing strictly_n Error Handling (Too Short)

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Allows custom handling for iterables that are too short by providing a `too_short` function. This example raises a RuntimeError.

```python
>>> def too_short(item_count):
...     raise RuntimeError
>>> it = strictly_n('abcd', 6, too_short=too_short)
>>> list(it)
Traceback (most recent call last):
...RuntimeError


```

--------------------------------

### take(n, iterable)

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Returns the first *n* items of the *iterable* as a list. If there are fewer than *n* items, all of them are returned.

```APIDOC
## take(n, iterable)

### Description
Return first *n* items of the *iterable* as a list.

If there are fewer than *n* items in the iterable, all of them are returned.

### Parameters
#### Path Parameters
- **n** (integer) - Required - The number of items to take.
- **iterable** (iterable) - Required - The iterable to take items from.

### Response
#### Success Response (list)
- Returns a list containing the first *n* items from the iterable.
```

--------------------------------

### duplicates_justseen Example

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Yields serially-duplicate elements from an iterable after their first appearance. A key function can be provided to determine duplicates based on a transformed value.

```python
>>> list(duplicates_justseen('mississippi'))
['s', 's', 'p']
```

```python
>>> list(duplicates_justseen('AaaBbbCccAaa', str.lower))
['a', 'a', 'b', 'b', 'c', 'c', 'a', 'a']
```

--------------------------------

### Sample Function: General Usage

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Provides a general sampling function similar to `random.sample` but works with non-indexable iterables and generators. Supports weighted and counted sampling.

```python
def sample(iterable, k, weights=None, *, counts=None, strict=False):
    """Return a *k*-length list of elements chosen (without replacement)
    from the *iterable*.

    Similar to :func:`random.sample`, but works on inputs that aren't
    indexable (such as sets and dictionaries) and on inputs where the
    size isn't known in advance (such as generators).

    >>> iterable = range(100)
    >>> sample(iterable, 5)  # doctest: +SKIP
    [81, 60, 96, 16, 4]

    For iterables with repeated elements, you may supply *counts* to
    indicate the repeats.

    >>> iterable = ['a', 'b']
    >>> counts = [3, 4]  # Equivalent to 'a', 'a', 'a', 'b', 'b', 'b', 'b'
    >>> sample(iterable, k=3, counts=counts)  # doctest: +SKIP
    ['a', 'a', 'b']

    An iterable with *weights* may be given:

    >>> iterable = range(100)
    >>> weights = (i * i + 1 for i in range(100))
    >>> sampled = sample(iterable, 5, weights=weights)  # doctest: +SKIP
    [79, 67, 74, 66, 78]

    Weighted selections are made without replacement.
    After an element is selected, it is removed from the pool and the
    relative weights of the other elements increase (this
    does not match the behavior of :func:`random.sample`'s *counts*
    parameter). Note that *weights* may not be used with *counts*.

    If the length of *iterable* is less than *k*,
    ``ValueError`` is raised if *strict* is ``True`` and
    all elements are returned (in shuffled order) if *strict* is ``False``.

    By default, the `Algorithm L <https://w.wiki/ANrM>`__ reservoir sampling
    technique is used. When *weights* are provided,
    `Algorithm A-ExpJ <https://w.wiki/ANrS>`__ is used instead.

    Notes on reproducibility:

    * The algorithms rely on inexact floating-point functions provided
      by the underlying math library (e.g. ``log``, ``log1p``, and ``pow``).
      Those functions can `produce slightly different results
      <https://members.loria.fr/PZimmermann/papers/accuracy.pdf>`_ on
      different builds.  Accordingly, selections can vary across builds
      even for the same seed.

    * The algorithms loop over the input and make selections based on
      ordinal position, so selections from unordered collections (such as
      sets) won't reproduce across sessions on the same platform using the
      same seed.  For example, this won't reproduce::
```

--------------------------------

### Applying Collatz conjecture with iterate and takewhile_inclusive

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Demonstrates generating a sequence using the Collatz conjecture with iterate and stopping when the value reaches 1 using takewhile_inclusive.

```python
>>> collatz = lambda x: 3*x + 1 if x%2==1 else x // 2
>>> list(takewhile_inclusive(lambda x: x!=1, iterate(collatz, 10)))
[10, 5, 16, 8, 4, 2, 1]
```

--------------------------------

### Get the nth Prime Number

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Returns the nth prime number (0-indexed). Can optionally return an approximation for large values of n for performance.

```python
def nth_prime(n, *, approximate=False):
    """Return the nth prime (counting from 0).

    >>> nth_prime(0)
    2
    >>> nth_prime(100)
    547

    If *approximate* is set to True, will return a prime close
    to the nth prime.  The estimation is much faster than computing
    an exact result.

    >>> nth_prime(200_000_000, approximate=True)  # Exact result is 4222234763
    4217820427

    """
    lb, ub = _nth_prime_bounds(n + 1)

    if not approximate or n <= 1_000_000:
        return nth(sieve(ceil(ub)), n)

    # Search from the midpoint and return the first odd prime
    odd = floor((lb + ub) / 2) | 1
    return first_true(count(odd, step=2), pred=is_prime)
```

--------------------------------

### Access Elements and Length of SequenceView

Source: https://more-itertools.readthedocs.io/en/stable/api.html

Shows how SequenceView supports indexing, slicing, and length queries, similar to the underlying sequence.

```python
>>> view[1]
'1'
>>> view[1:-1]
['1', '2']
>>> len(view)
4
```

--------------------------------

### Finding Substrings and Their Positions

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Yields all substrings of a sequence along with their start and end indices. Requires the input sequence to support slicing (e.g., strings).

```python
from more_itertools import substrings_indexes

for item in substrings_indexes('more'):
    print(item)
# Output:
# ('m', 0, 1)
# ('o', 1, 2)
# ('r', 2, 3)
# ('e', 3, 4)
# ('mo', 0, 2)
# ('or', 1, 3)
# ('re', 2, 4)
# ('mor', 0, 3)
# ('ore', 1, 4)
# ('more', 0, 4)

# With reverse=True
print(list(substrings_indexes('abc', reverse=True)))
# Output: [('abc', 0, 3), ('bc', 1, 3), ('c', 2, 3), ('ab', 0, 2), ('b', 1, 2), ('a', 0, 1)]
```

--------------------------------

### Prime Factorization in Python

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Yields the prime factors of a given integer. Uses trial division for small factors and Pollard's rho algorithm for larger ones.

```python
from more_itertools import sieve, is_prime
from math import gcd
from functools import reduce
from itertools import chain, islice, repeat

def _factor_pollard(n):
    # Return a factor of n using Pollard's rho algorithm.
    # Efficient when n is odd and composite.
    for b in range(1, n):
        x = y = 2
        d = 1
        while d == 1:
            x = (x * x + b) % n
            y = (y * y + b) % n
            y = (y * y + b) % n
            d = gcd(x - y, n)
        if d != n:
            return d
    raise ValueError('prime or under 5')  # pragma: no cover


_primes_below_211 = tuple(sieve(211))


def factor(n):
    """Yield the prime factors of n.

    >>> list(factor(360))
    [2, 2, 2, 3, 3, 5]

    Finds small factors with trial division.  Larger factors are
    either verified as prime with ``is_prime`` or split into
    smaller factors with Pollard's rho algorithm.
    """

    # Corner case reduction
    if n < 2:
        return

    # Trial division reduction
    for prime in _primes_below_211:
        while not n % prime:
            yield prime
            n //= prime

    # Pollard's rho reduction
    primes = []
    todo = [n] if n > 1 else []
    for n in todo:
        if n < 211**2 or is_prime(n):
            primes.append(n)
        else:
            fact = _factor_pollard(n)
            todo += (fact, n // fact)
    yield from sorted(primes)
```

--------------------------------

### Iterate and find indices of a value

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/recipes.html

Finds all occurrences of a value in an iterable and returns their indices. Supports specifying start and stop indices for the search range.

```python
>>> list(iter_index('AABCADEAF', 'A'))
[0, 1, 4, 7]
```

```python
>>> list(iter_index('AABCADEAF', 'A', 1))  # start index is inclusive
[1, 4, 7]
```

```python
>>> list(iter_index('AABCADEAF', 'A', 1, 7))  # stop index is not inclusive
[1, 4]
```

```python
>>> list(iter_index('ABCDABCD', 'AB'))
[0, 4]
```

```python
>>> list(iter_index([0, 1, 2, 3, 0, 1, 2, 3], [0, 1]))
[]
```

```python
>>> list(iter_index([[0, 1], [2, 3], [0, 1], [2, 3]], [0, 1]))
[0, 2]
```

--------------------------------

### split_before with maxsplit

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Shows how to limit the number of splits performed by split_before. Useful for processing only the initial segments of a large iterable.

```python
>>> list(split_before(range(10), lambda n: n % 3 == 0, maxsplit=2))
[[0, 1, 2], [3, 4, 5], [6, 7, 8, 9]]
```

--------------------------------

### map_reduce with keyfunc, valuefunc, and reducefunc

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Groups items by a key function, transforms them with valuefunc, and then summarizes each group using reducefunc. Ideal for aggregation tasks.

```python
keyfunc = lambda x: x.upper()
valuefunc = lambda x: 1
reducefunc = sum
result = map_reduce('abbccc', keyfunc, valuefunc, reducefunc)
sorted(result.items())
```

--------------------------------

### split_into example with remaining items ignored

Source: https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html

Shows split_into behavior when the sum of sizes is less than the iterable length. The remaining items in the iterable are not yielded.

```python
>>> list(split_into([1,2,3,4,5,6], [2,3]))
[[1, 2], [3, 4, 5]]
```
Tokens:
Raw