### Install fractional-indexing Package

Source: https://github.com/httpie/fractional-indexing-python/blob/main/README.md

Install the fractional-indexing library using pip.

```bash
pip install fractional-indexing
```

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

### Generate keys with custom Base95 digits

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Demonstrates generating keys using a custom Base95 alphabet, which includes all printable ASCII characters for maximum density. Includes examples for generating single keys, multiple keys, and keys before a given key.

```python
# Base95 — all printable ASCII characters for maximum density
BASE_95 = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~'

first  = generate_key_between(None, None, digits=BASE_95)
print(first)   # 'a '

second = generate_key_between(first, None, digits=BASE_95)
print(second)  # 'a!'

before = generate_key_between(None, first, digits=BASE_95)
print(before)  # 'Z~'

mid_keys = generate_n_keys_between('a ', 'a!', n=3, digits=BASE_95)
print(mid_keys)  # ['a 8', 'a P', 'a h']
```

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

### Generate keys with custom Base10 digits

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Use the `digits` parameter to specify a custom alphabet for key generation. This example uses Base10 for debugging.

```python
from fractional_indexing import generate_key_between, generate_n_keys_between, validate_order_key

# Base10 — useful for debugging and testing
BASE_10 = '0123456789'
keys = generate_n_keys_between('a0', 'a2', n=20, digits=BASE_10)
print(' '.join(keys))
```

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

### Validate a Base95 key

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Use `validate_order_key` to check if a given key conforms to the specified digit set. This example shows a valid key and an invalid key with a trailing zero.

```python
# Validate a Base95 key
validate_order_key('a ', digits=BASE_95)  # OK
try:
    validate_order_key('a0 ', digits=BASE_95)  # trailing zero (space = zero digit in Base95)
except Exception as e:
    print(e)  # invalid order key: a0
```

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

### Safely insert keys using FIError

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Demonstrates how to use a try-except block to catch `FIError` when generating keys between invalid inputs. This prevents application crashes and allows for graceful error handling.

```python
from fractional_indexing import generate_key_between, FIError

def safe_insert(a, b):
    """Insert a key between a and b, returning None if inputs are invalid."""
    try:
        return generate_key_between(a, b)
    except FIError as e:
        print(f"Cannot insert between {a!r} and {b!r}: {e}")
        return None

print(safe_insert(None, None))    # 'a0'
print(safe_insert('a0', 'a1'))   # 'a0V'
print(safe_insert('a1', 'a0'))   # Cannot insert between 'a1' and 'a0': a1 >= a0  ->  None
print(safe_insert('a00', 'a1'))  # Cannot insert between 'a00' and 'a1': invalid order key: a00  ->  None
```

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

### Generate Single Key Between Positions

Source: https://github.com/httpie/fractional-indexing-python/blob/main/README.md

Generate a single fractional index key. Use `None` for the lower bound to insert at the beginning, or for the upper bound to insert at the end. Inserting between existing keys generates a key at the midpoint.

```python
from fractional_indexing import generate_key_between


# Insert at the beginning
first = generate_key_between(None, None)
assert first == 'a0'

# Insert after 1st
second = generate_key_between(first, None)
assert second == 'a1'

# Insert after 2nd
third = generate_key_between(second, None)
assert third == 'a2'

# Insert before 1st
zeroth = generate_key_between(None, first)
assert zeroth == 'Zz'

# Insert in between 2nd and 3rd (midpoint)
second_and_half = generate_key_between(second, third)
assert second_and_half == 'a1V'
```

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

### Generate Multiple Keys Between Positions

Source: https://github.com/httpie/fractional-indexing-python/blob/main/README.md

Generate multiple keys at once. This method spaces keys more evenly, resulting in shorter keys compared to generating them individually. Use `None` for bounds to insert at the beginning or end.

```python
from fractional_indexing import generate_n_keys_between


# Insert 3 at the beginning
keys = generate_n_keys_between(None, None, n=3)
assert keys == ['a0', 'a1', 'a2']

# Insert 3 after 1st
keys = generate_n_keys_between('a0', None, n=3)
assert keys == ['a1', 'a2', 'a3']

# Insert 3 before 1st
keys = generate_n_keys_between(None, 'a0', n=3)
assert keys == ['Zx', 'Zy', 'Zz']

# Insert 3 in between 2nd and 3rd (midpoint)
keys = generate_n_keys_between('a1', 'a2', n=3)
assert keys == ['a1G', 'a1V', 'a1l']
```

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

### Generate Multiple Keys Between Bounds

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Use `generate_n_keys_between` to efficiently create multiple distinct order keys between `a` and `b`. This is preferred over looping `generate_key_between` for better key spacing and shorter strings. Returns an empty list if `n=0`. Raises `FIError` for invalid bounds.

```python
from fractional_indexing import generate_n_keys_between, FIError

# Generate the first 5 keys in an empty list
keys = generate_n_keys_between(None, None, n=5)
print(keys)  # ['a0', 'a1', 'a2', 'a3', 'a4']

# Append 3 keys after 'a4'
keys = generate_n_keys_between('a4', None, n=3)
print(keys)  # ['a5', 'a6', 'a7']

# Prepend 3 keys before 'a0'
keys = generate_n_keys_between(None, 'a0', n=5)
print(keys)  # ['Z5', 'Z6', 'Z7', 'Z8', 'Z9']

# Insert 3 keys between 'a1' and 'a2'
keys = generate_n_keys_between('a1', 'a2', n=3)
print(keys)  # ['a1G', 'a1V', 'a1l']

# All resulting keys are sorted
assert keys == sorted(keys)

# n=0 returns an empty list
assert generate_n_keys_between('a0', 'a1', n=0) == []

# Error: invalid bounds
try:
    generate_n_keys_between('a2', 'a1', n=2)
except FIError as e:
    print(e)  # a2 >= a1
```

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

### Generate Single Key Between Bounds

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Use `generate_key_between` to create a single order key that sorts between two existing keys. Pass `None` for `a` to insert at the beginning, `None` for `b` to insert at the end, or `None` for both to generate the very first key. Raises `FIError` for invalid bounds or malformed keys.

```python
from fractional_indexing import generate_key_between, FIError

# First key in an empty list
first = generate_key_between(None, None)
print(first)   # 'a0'

# Append after the first item
second = generate_key_between(first, None)
print(second)  # 'a1'

# Append after the second item
third = generate_key_between(second, None)
print(third)   # 'a2'

# Prepend before the first item
zeroth = generate_key_between(None, first)
print(zeroth)  # 'Zz'

# Insert between second ('a1') and third ('a2')
between = generate_key_between(second, third)
print(between) # 'a1V'

# Keys remain lexicographically ordered
assert sorted([zeroth, first, between, second, third]) == [zeroth, first, second, between, third]

# Error: a must be strictly less than b
try:
    generate_key_between('a1', 'a0')
except FIError as e:
    print(e)   # a1 >= a0

# Error: malformed key
try:
    generate_key_between('a00', None)
except FIError as e:
    print(e)   # invalid order key: a00
```

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

### Use Custom Base Digits

Source: https://github.com/httpie/fractional-indexing-python/blob/main/README.md

Generate and validate keys using a custom set of base digits instead of the default Base62. Ensure the custom digits are unique and ordered.

```python
from fractional_indexing import generate_key_between, generate_n_keys_between, validate_order_key


BASE_95_DIGITS = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~'

assert generate_key_between(None, None, digits=BASE_95_DIGITS) == 'a '
assert generate_key_between('a ', None, digits=BASE_95_DIGITS) == 'a!'
assert generate_key_between(None, 'a ', digits=BASE_95_DIGITS) == 'Z~'

assert generate_n_keys_between('a ', 'a!', n=3, digits=BASE_95_DIGITS) == ['a"', 'a#', 'a$']

validate_order_key('a ', digits=BASE_95_DIGITS)
```

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

### generate_n_keys_between

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Generates `n` distinct order keys in sorted order between `a` and `b`. This is more efficient than calling `generate_key_between` in a loop for multiple insertions.

```APIDOC
## `generate_n_keys_between(a, b, n, digits=BASE_62_DIGITS)`

### Description
Generates `n` distinct order keys in sorted order between `a` and `b`. Prefer this function over calling `generate_key_between` in a loop when inserting multiple items at once — it spaces keys more evenly and produces shorter strings. Returns an empty list when `n=0`. Raises `FIError` under the same conditions as `generate_key_between`.

### Parameters
#### Path Parameters
- **a** (string | None) - Required - The lower bound key. Use `None` to insert at the beginning.
- **b** (string | None) - Required - The upper bound key. Use `None` to insert at the end.
- **n** (integer) - Required - The number of keys to generate.
- **digits** (string) - Optional - The alphabet of digits to use for encoding. Defaults to Base62.

### Request Example
```python
from fractional_indexing import generate_n_keys_between, FIError

# Generate the first 5 keys in an empty list
keys = generate_n_keys_between(None, None, n=5)
print(keys)  # ['a0', 'a1', 'a2', 'a3', 'a4']

# Append 3 keys after 'a4'
keys = generate_n_keys_between('a4', None, n=3)
print(keys)  # ['a5', 'a6', 'a7']

# Prepend 3 keys before 'a0'
keys = generate_n_keys_between(None, 'a0', n=5)
print(keys)  # ['Z5', 'Z6', 'Z7', 'Z8', 'Z9']

# Insert 3 keys between 'a1' and 'a2'
keys = generate_n_keys_between('a1', 'a2', n=3)
print(keys)  # ['a1G', 'a1V', 'a1l']
```

### Response
#### Success Response (200)
- **keys** (list[string]) - A list of `n` newly generated, sorted order keys.

#### Error Response (FIError)
- **error** (string) - A descriptive error message if `a >= b`, keys are invalid, or the key space is exhausted.

### Error Example
```python
# n=0 returns an empty list
assert generate_n_keys_between('a0', 'a1', n=0) == []

# Error: invalid bounds
try:
    generate_n_keys_between('a2', 'a1', n=2)
except FIError as e:
    print(e)  # a2 >= a1
```
```

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

### Validate Order Key

Source: https://github.com/httpie/fractional-indexing-python/blob/main/README.md

Validate if a given string is a correctly formatted fractional index key. Raises `FIError` if the key is invalid.

```python
from fractional_indexing import validate_order_key, FIError


validate_order_key('a0')

try:
    validate_order_key('foo')
except FIError as e:
    print(e)  # fractional_indexing.FIError: invalid order key: foo
```

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

### generate_key_between

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Generates a single order key that sorts lexicographically between two existing keys, `a` and `b`. Supports inserting at the beginning (None for `a`) or end (None for `b`) of a list.

```APIDOC
## `generate_key_between(a, b, digits=BASE_62_DIGITS)`

### Description
Generates a single order key that sorts lexicographically between `a` and `b`. Pass `None` for `a` to insert before all existing keys, `None` for `b` to insert after all existing keys, or `None` for both to generate the very first key. Raises `FIError` if `a >= b`, if either key is structurally invalid, or if the key space is exhausted.

### Parameters
#### Path Parameters
- **a** (string | None) - Required - The lower bound key. Use `None` to insert at the beginning.
- **b** (string | None) - Required - The upper bound key. Use `None` to insert at the end.
- **digits** (string) - Optional - The alphabet of digits to use for encoding. Defaults to Base62.

### Request Example
```python
from fractional_indexing import generate_key_between, FIError

# First key in an empty list
first = generate_key_between(None, None)
print(first)   # 'a0'

# Append after the first item
second = generate_key_between(first, None)
print(second)  # 'a1'

# Prepend before the first item
zeroth = generate_key_between(None, first)
print(zeroth)  # 'Zz'

# Insert between second ('a1') and third ('a2')
between = generate_key_between(second, third)
print(between) # 'a1V'
```

### Response
#### Success Response (200)
- **key** (string) - The newly generated order key.

#### Error Response (FIError)
- **error** (string) - A descriptive error message if `a >= b`, keys are invalid, or the key space is exhausted.

### Error Example
```python
# Error: a must be strictly less than b
try:
    generate_key_between('a1', 'a0')
except FIError as e:
    print(e)   # a1 >= a0

# Error: malformed key
try:
    generate_key_between('a00', None)
except FIError as e:
    print(e)   # invalid order key: a00
```
```

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

### Validate Order Key Format

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Use `validate_order_key` to check if a string is a well-formed order key. It returns `None` on success and raises `FIError` for invalid formats, such as trailing zeros or incorrect head characters. This is useful for sanitizing external input.

```python
from fractional_indexing import validate_order_key, FIError

# Valid keys — no exception raised
validate_order_key('a0')
validate_order_key('a1V')
validate_order_key('Zz')

# Invalid: trailing zero in fractional part
try:
    validate_order_key('a00')
except FIError as e:
    print(e)  # invalid order key: a00

# Invalid: head character not in the expected range
try:
    validate_order_key('foo')
except FIError as e:
    print(e)  # invalid order key head: f (or similar)

# Invalid: minimum representable key (underflow sentinel)
try:
    validate_order_key('A' + '0' * 26)
except FIError as e:
    print(e)  # invalid order key: A00000000000000000000000000
```

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

### validate_order_key

Source: https://context7.com/httpie/fractional-indexing-python/llms.txt

Validates if a given string is a well-formed order key according to the specified digit alphabet. Raises `FIError` for invalid keys.

```APIDOC
## `validate_order_key(key, digits=BASE_62_DIGITS)`

### Description
Validates that a string is a well-formed order key for the given digit alphabet. Returns `None` on success and raises `FIError` with a descriptive message if the key is structurally invalid (bad head character, trailing zero, minimum-value key, wrong integer-part length, etc.). Useful for sanitising keys received from external sources before using them in comparisons.

### Parameters
#### Path Parameters
- **key** (string) - Required - The order key string to validate.
- **digits** (string) - Optional - The alphabet of digits to use for validation. Defaults to Base62.

### Request Example
```python
from fractional_indexing import validate_order_key, FIError

# Valid keys — no exception raised
validate_order_key('a0')
validate_order_key('a1V')
validate_order_key('Zz')
```

### Response
#### Success Response (200)
- **None** - Indicates the key is valid.

#### Error Response (FIError)
- **error** (string) - A descriptive error message if the key is structurally invalid.

### Error Example
```python
# Invalid: trailing zero in fractional part
try:
    validate_order_key('a00')
except FIError as e:
    print(e)  # invalid order key: a00

# Invalid: head character not in the expected range
try:
    validate_order_key('foo')
except FIError as e:
    print(e)  # invalid order key head: f (or similar)

# Invalid: minimum representable key (underflow sentinel)
try:
    validate_order_key('A' + '0' * 26)
except FIError as e:
    print(e)  # invalid order key: A00000000000000000000000000
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.