set_utils#

Utilities for working with sets and layered (leveled) collections.

  • powerset: iterate over all subsets of an iterable.

  • LeveledSet: maintain items grouped by discovery “levels”, with optional compact internal storage via (to_string/from_string) conversions.

This module is lightweight and has no heavy imports.

Functions

powerset(iterable)

Iterate over all subsets (the power set) of an iterable.

Classes

LeveledSet([items, to_string, from_string])

A leveled set structure with optional compact internal representation.
powerset(iterable)#

Iterate over all subsets (the power set) of an iterable.

Subsets are yielded as tuples in increasing size order.

Parameters:

iterable (Iterable[T]) – Any iterable of items.

Yields:

Tuples representing each subset, starting with the empty tuple.

Return type:

Iterator[tuple[T, …]]

Example

>>> list(powerset([1, 2, 3]))
[(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
class LeveledSet(items=None, to_string=None, from_string=None)#

Bases: Generic[T, I]

A leveled set structure with optional compact internal representation.

Items can be stored internally as strings (or any type I) to reduce memory usage or enable hashing on otherwise unhashable public types. You can provide a pair of conversion functions:

  • to_string(item: T) -> I stores items internally (often as str).

  • from_string(stored: I) -> T reconstructs external/public items.

If either function is omitted (None), items are stored directly.

Levels:

The structure maintains a list of levels. New items are added into the current level (the last one). Calling new_level() creates a new level only if the last level is non-empty (so you don’t accumulate trailing empties). All seen items are tracked in a global set to avoid duplicates across levels.

Notes

  • All set operations (union, intersection, difference) act on the global content, not per-level content.

  • Iteration yields public/external items (T), applying conversion back if needed.

Parameters:

  • items (Iterable[T] | None) – Optional initial items to insert at level 0.

  • to_string (Callable[[T], I] | None) – Function to convert an external item T to internal I.

  • from_string (Callable[[I], T] | None) – Function to convert an internal item I back to T.

number_of_levels()#

Return the number of levels currently stored.

Return type:

int

level_sizes()#

Return a tuple with the size of each level.

Return type:

tuple[int, …]

number_of_items()#

Return the total number of unique items across all levels.

Return type:

int

is_level_empty(level)#

Return whether a given level is empty.

Parameters:

level (int) – Level index (supports negative indexing like Python lists).

Raises:

IndexError – If level is out of range.

Return type:

bool

new_level(items=None)#

Create a new current level (only if last level is non-empty), then add optional items.

Parameters:

items (Iterable[T] | T | None) – Optional single item or iterable of items to add to the new current level.

Return type:

None

remove_empty_levels()#

Remove trailing empty levels.

Return type:

None

add(item)#

Add a single item to the current level if not seen before.

Parameters:

item (T)

Return type:

None

extend(items)#

Add multiple items to the current level.

Parameters:

items (Iterable[T])

Return type:

None

contains(item)#

Return True if the item appears in any level.

Parameters:

item (T)

Return type:

bool

union(other)#

Return the union of contents (as external items) with another LeveledSet.

Parameters:

other (LeveledSet[T, I])

Return type:

set[T]

intersection(other)#

Return the intersection of contents (as external items) with another LeveledSet.

Parameters:

other (LeveledSet[T, I])

Return type:

set[T]

difference(other)#

Return the difference of contents (as external items) with another LeveledSet.

Parameters:

other (LeveledSet[T, I])

Return type:

set[T]

isdisjoint(other)#

Return True if the two LeveledSets share no common items.

Parameters:

other (LeveledSet[T, I])

Return type:

bool

iter_level(level)#

Iterate items of a specific level (converted to external items).

Parameters:

level (int) – Level index (supports negative indexing).

Yields:

Items at the requested level.

Raises:

IndexError – If level is out of range.

Return type:

Iterator[T]