0
# Collections Extended
1

2
A comprehensive Python library providing extended collections that fill gaps in the standard library. Collections Extended offers specialized data structures including bags (multisets) for counting elements with duplicates, setlists (ordered sets) that maintain both uniqueness and insertion order, bijections for one-to-one mappings with inverse lookups, RangeMaps for mapping ranges to values, and IndexedDicts for ordered mappings with index-based access.
3

4
## Package Information
5

6
- **Package Name**: collections-extended
7
- **Language**: Python
8
- **Installation**: `pip install collections-extended`
9

10
## Core Imports
11

12
```python
13
from collections_extended import bag, frozenbag, setlist, frozensetlist, bijection, IndexedDict, RangeMap
14
```
15

16
All collection types:
17
```python
18
from collections_extended import (
19
    Collection,               # Standard Collection ABC (re-exported)
20
    Bag, bag, frozenbag,      # Bags (base class and implementations)
21
    SetList, setlist, frozensetlist,  # Setlists (base class and implementations)
22
    bijection,                # One-to-one mappings
23
    IndexedDict,              # Ordered mappings with index access
24
    RangeMap, MappedRange,    # Range mappings
25
    collection                # Factory function
26
)
27
```
28

29
## Basic Usage
30

31
```python
32
from collections_extended import bag, setlist, bijection, RangeMap, IndexedDict
33
from datetime import date
34

35
# Bags - multisets that count duplicates
36
b = bag('abracadabra')
37
print(b.count('a'))  # 5
38
b.remove('a')
39
print(b.count('a'))  # 4
40
print('a' in b)      # True
41

42
# Setlists - ordered sets maintaining insertion order
43
sl = setlist('abracadabra')
44
print(sl)            # setlist(('a', 'b', 'r', 'c', 'd'))
45
print(sl[3])         # 'c'  
46
print(sl.index('d')) # 4
47

48
# Bijections - one-to-one mappings with inverse lookup
49
bij = bijection({'a': 1, 'b': 2, 'c': 3})
50
print(bij.inverse[2])  # 'b'
51
bij['a'] = 2
52
print(bij == bijection({'a': 2, 'c': 3}))  # True
53

54
# RangeMaps - map ranges to values
55
version = RangeMap()
56
version[date(2017, 10, 20): date(2017, 10, 27)] = '0.10.1'
57
version[date(2017, 10, 27): date(2018, 2, 14)] = '1.0.0'
58
version[date(2018, 2, 14):] = '1.0.1'
59
print(version[date(2017, 10, 24)])  # '0.10.1'
60

61
# IndexedDict - ordered mapping with index access
62
idict = IndexedDict()
63
idict['a'] = "A"
64
idict['b'] = "B"
65
idict['c'] = "C"
66
print(idict.get(key='a'))    # 'A'
67
print(idict.get(index=2))    # 'C'
68
print(idict.index('b'))      # 1
69
```
70

71
## Architecture
72

73
Collections Extended provides five main collection types, each with mutable and immutable variants:
74

75
- **Bags**: Multisets that track element counts, supporting mathematical set operations with multiplicity
76
- **Setlists**: Ordered sets combining list indexing with set uniqueness constraints
77
- **Bijections**: One-to-one mappings maintaining both forward and inverse relationships
78
- **RangeMaps**: Mappings from continuous ranges to values using efficient interval trees
79
- **IndexedDicts**: Ordered dictionaries with both key-based and index-based access
80

81
The library follows Python collection protocols and provides both mutable and frozen (hashable) variants for data structure immutability when needed.
82

83
## Capabilities
84

85
### Bags (Multisets)
86

87
Multisets that track element counts with duplicates allowed. Support mathematical set operations, counting, and statistical operations on collections with repeated elements.
88

89
```python { .api }
90
class bag:
91
    def __init__(self, iterable=None): ...
92
    def count(self, value): ...
93
    def add(self, elem): ...
94
    def remove(self, elem): ...
95
    def discard(self, elem): ...
96
    def unique_elements(self): ...
97
    def counts(self): ...
98

99
class frozenbag(bag, Hashable):
100
    def __hash__(self): ...
101
```
102

103
[Bags and Multisets](./bags.md)
104

105
### Setlists (Ordered Sets)
106

107
Ordered sets maintaining both uniqueness and insertion order. Combine list-like indexing with set-like uniqueness constraints and operations.
108

109
```python { .api }
110
class setlist:
111
    def __init__(self, iterable=None, raise_on_duplicate=False): ...
112
    def append(self, value): ...
113
    def insert(self, index, value): ...
114
    def index(self, value, start=0, end=None): ...
115
    def count(self, value): ...
116

117
class frozensetlist(setlist, Hashable):
118
    def __hash__(self): ...
119
```
120

121
[Setlists and Ordered Sets](./setlists.md)
122

123
### Bijections
124

125
One-to-one mappings with automatic inverse relationship maintenance. Enable efficient bidirectional lookups and enforce uniqueness in both keys and values.
126

127
```python { .api }
128
class bijection:
129
    def __init__(self, iterable=None, **kwargs): ...
130
    @property
131
    def inverse(self): ...
132
    def copy(self): ...
133
    def clear(self): ...
134
```
135

136
[Bijections and One-to-One Mappings](./bijections.md)
137

138
### Range Mappings
139

140
Mappings from continuous ranges to values using efficient interval-based storage. Support slice notation and range operations for time series, version ranges, and interval data.
141

142
```python { .api }
143
class RangeMap:
144
    def __init__(self, iterable=None, default_value=NOT_SET): ...
145
    def set(self, value, start=None, stop=None): ...
146
    def get(self, key, restval=None): ...
147
    def ranges(self, start=None, stop=None): ...
148

149
class MappedRange:
150
    def __init__(self, start, stop, value): ...
151
    start: Any
152
    stop: Any  
153
    value: Any
154
```
155

156
[Range Mappings](./range-maps.md)
157

158
### Indexed Dictionaries
159

160
Ordered mappings with both key-based and index-based access. Maintain insertion order while providing efficient positional access and manipulation.
161

162
```python { .api }
163
class IndexedDict:
164
    def __init__(self, iterable=None, **kwargs): ...
165
    def get(self, key=NOT_SET, index=NOT_SET, default=NOT_SET): ...
166
    def pop(self, key=NOT_SET, index=NOT_SET, default=NOT_SET): ...
167
    def index(self, key): ...
168
    def key(self, index): ...
169
```
170

171
[Indexed Dictionaries](./indexed-dicts.md)
172

173
### Factory Function
174

175
Utility function that returns the appropriate collection type based on specified properties.
176

177
```python { .api }
178
def collection(iterable=None, mutable=True, ordered=False, unique=False):
179
    """Return a Collection with the specified properties.
180
    
181
    Args:
182
        iterable: Collection to instantiate new collection from
183
        mutable: Whether the new collection is mutable
184
        ordered: Whether the new collection is ordered  
185
        unique: Whether the new collection contains only unique values
186
    
187
    Returns:
188
        Appropriate collection type based on parameters
189
    """
190
```