pureset

For general Python development matters, being this package or any, contact me at
gabrielmaia.silva00@gmail.com

---

A robust, immutable, homogeneous, and ordered collection library for Python, blending the best features of sets, tuples, sequences, and mappings.

PureSet and PureMap offer accuracy, predictability, and clarity in managing homogeneous data structures.

They ensure type homogeneity across elements or entries, making them robust replacements for sets, sequences, or dictionaries in production applications.

NumPy and Pandas support is added with no dependency to the package itself. Currently supported types are:

• numpy.ndarray
• pandas.Series
• pandas.DataFrame
• pandas.Index

---

Core Features

• Immutability: Elements (PureSet) and key-value pairs (PureMap) cannot be changed after creation, assuring data integrity.
• Ordering: Retains insertion sequence—predictable for iteration, exporting, or display use cases.
• Hashability: Collections of hashable (and nested) objects are themselves hashable; can be used as dictionary keys.
• Uniqueness: Sets remove duplicates by value; maps ensure unique keys.
• Deep Type & Schema Homogeneity: All elements (PureSet) or keys and values (PureMap) must share the same type and “shape”.
• Performance: Optimized for membership, intersection, union, mapping, and set-like operations—even at scale.
• Signature Inspection: .signature property represents the canonical type/structure, for debugging and schema checks.
• Universal Container: Works seamlessly with primitives, containers, numpy, pandas, UserString/UserList/..., and nested containers.
• Extensible: Transparent support for new types via freeze/restore protocol.
• Serialization Ready: Pickleable and custom freeze/restore.
• Advanced API: Set operations, mapping/filtering, slices, composition, schema validation, and more, for both types.

---

Installation & Requirements

To install the latest PureSet package, use pip:

pip install -U pureset

• Python Versions: Python 3.9+.
• Dependencies: None!

---

Usage & API Overview

This section presents realistic, production-focused examples for both PureSet and PureMap.

---

Basic Example Usage**

>>> from pureset import PureSet
>>> PureSet(1, 2, 3)
PureSet(1, 2, 3)
>>> PureSet(1, 2, 2, 3)
PureSet(1, 2, 3)
>>> PureSet("a", "b", "b")
PureSet('a', 'b')
>>> len(PureSet(8, 8, 9))
2

>>> from pureset import PureMap
>>> pm = PureMap(a=1, b=2)
>>> pm['a']
1

>>> user_ages = PureMap({"alice": 30, "bob": 28})
>>> set(user_ages.keys())
{'alice', 'bob'}
>>> user_ages.signature
(<class 'str'>, <class 'int'>)

>>>PureMap({1: 'abc', "key": 123})
Traceback (most recent call last):
  ...
TypeError: All keys/values must be of the same type/shape.

---

PureSet: Robust Enum Replacement | State Management

>>> ORDER_STATES = PureSet("Pending", "Processing", "Shipped", "Delivered", "Cancelled")
>>> "Processing" in ORDER_STATES
True
>>> "Returned" in ORDER_STATES
False

---

PureSet: Contracts & API Schema Checking

>>> user_profiles = PureSet(
...   {"id": 1, "name": "Alice Smith", "age": 28, "email": "alice@example.com"},
...   {"id": 2, "name": "Bob Johnson", "age": 35, "email": "bob@example.com"},
... )
>>> user_profiles.signature
(<class 'dict'>, {'age': <class 'int'>, 'email': <class 'str'>, 'id': <class 'int'>, 'name': <class 'str'>})

---

Deduplication and Set Algebra (PureSet)

>>> a = PureSet(1, 2, 3)
>>> b = PureSet(3, 4, 2)
>>> (a | b).to_list()
[1, 2, 3, 4]
>>> (a & b).to_list()
[2, 3]
>>> (a - b).to_list()
[1]
>>> (a ^ b).to_list()
[1, 4]

---

Using PureSet and PureMap with Numpy and Pandas

>>> import numpy as np, pandas as pd
>>> arr = np.array([1, 2, 3])
>>> ps = PureSet(arr)
>>> ps[0].shape
(3,)

>>> df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})
>>> PureSet(df)[0].equals(df)
True
>>> PureMap({0: df})[0].equals(df)
True

>>> idx = pd.Index([5, 7, 9])
>>> PureSet(idx)[0].equals(idx)
True

---

Freeze/Restore: Reliable, Deep Immutability and Serialization

>>> x = [{'a': [1, 2]}, {'a': [3, 4]}]
>>> frozen = PureSet.freeze(x)
>>> PureSet.restore(frozen)
[{'a': [1, 2]}, {'a': [3, 4]}]

>>> pm = PureMap({'k1': [1, 2]})
>>> PureMap.restore(PureMap.freeze(pm)) == pm
True

---

Advanced Features and Extensibility

• Rich Set Algebra (PureSet): |, &, -, ^
• Dict-like Operations (PureMap): all mapping protocol methods, plus strict homogeneity and freezing.
• Slicing and Indexing: Supports Pythonic sequence semantics.
• Compatibility Checking: .compatible(other) method.
• Signature Inspection: .signature for schema introspection.
• Freeze/Restore API: For both types.
• Mixes with UserString, Counter, ChainMap, deque, array.array, memoryview, and more.

---

Performance and Scalability

• Highly optimized for construction, lookup, set/mapping algebra.
• PureSet and PureMap scale efficiently for large practical workloads.

---

Testing

v1.2.250706.0: 88 tests; 0 Failures; 0 Errors; OK.

Test suite covers all PureSet and PureMap core and edge-case behaviors:

• Edge cases for numpy, pandas, UserDict/UserList/UserString, Counter, deque, ChainMap
• Nested, empty, custom, standard containers
• Contract enforcement for mixed and homogeneous datasets
• Deep serialization and "restoration" safety

See tests here.

---

License

Released under Apache License 2.0. See LICENSE.

---

PureSet and PureMap are engineered to safely power production-scale scenarios across APIs, analytics, ML, and more!