listclasses 1.2.1

A simple decorator to create custom sequence types

listclasses

A Python library providing a @listclass decorator that transforms standard classes into powerful, type-safe, and highly customizable custom sequence types

Features:

• Type Safety: Enforce strict data types for sequence items
• Length Constraints: Define fixed-size or dynamic sequences
• Immutability: Easily create read-only (frozen) collections
• Rich API: Seamlessly integrates with built-in functions (len(), repr(), iteration, slicing)
• Copy Support: Native support for shallow and deep copying
• Pretty Printing: Built-in methods for clean text formatting out of the box
• Is Listclass Checking : Support for checking if an object or a class is a listclass
• Installation: Add the listclass decorator code directly to your project

pip install listclasses

from listclasses import listclass, is_listclass

Basic Usage

from listclasses import listclass

@listclass
class Inventory:
    pass

# Create an instance with initial items
items = Inventory("Sword", "Shield", "Potion")

print(items)          # Output: Inventory(Sword, Shield, Potion)
print(items[0])       # Output: Sword
print(len(items))     # Output: 3

Advanced Configuration

The @listclass decorator accepts configuration parameters to restrict container behavior

Enforcing Strict Types

@listclass(type=int)
class IntegerList:
    pass

# Works perfectly
numbers = IntegerList(1, 2, 3)

# Raises TypeError: Incorrect type: expected: int got: str
numbers = IntegerList(1, "two", 3)

Multi-Type Union Support

@listclass(type=int | str)
class MixedList:
    pass

# Both integers and strings are valid
mixed = MixedList(1, "hello", 42, "world")

# Appending a float raises an error
# Raises TypeError: Incorrect type: expected: int | str got: float
mixed.append(3.14)

Advanced types

@listclass(type=list[int])
class ListOfListsOfInts:
    pass

# Works
mixed = ListOfListsOfInts([1, 2], [3, 4, 5])

# Appending a list of string raises an error
# Raises TypeError: Incorrect type: expected: list[int] got: list[str]
mixed.append(['6'])

Setting Fixed Lengths

@listclass(len=2)
class Coordinates:
    pass

# Works perfectly
point = Coordinates(10, 20)

# Raises ValueError: Too many items: expected: 2 got: 3
point = Coordinates(10, 20, 30)

Creating Frozen (Immutable) Lists

@listclass(frozen=True)
class ReadOnlyData:
    pass

data = ReadOnlyData("A", "B")

# Raises TypeError: 'ReadOnlyData' object does not support item assignment
data[0] = "Z"

Built-in Formatting

listclasses comes with utility methods to print your items cleanly.

@listclass
class TodoList:
    pass

todos = TodoList("Buy milk", "Clean room", "Code Python")

# Dotted list format
todos.print_dotted('-')
# Output:
# -  Buy milk
# -  Clean room
# -  Code Python

# Numbered list format
todos.print_numbered()
# Output:
# 1. Buy milk
# 2. Clean room
# 3. Code Python

Random item selection

@listclass
class TodoList:
    pass

tasks = TodoList('Clean the bathroom', 'Make the bed', 'Touch grass')
random_task = tasks.random()

Checking for listclasses

listclasses comes with a function to check if an object or a class is a listclass.

Checking if a class is a listclass

@listclass
class MyList:
    pass

class Car:
    pass

print(is_listclass(MyList))
# Output:
# True

print(is_listclass(Car))
# Output:
# False

Checking if an object is a listclass

@listclass
class MyList:
    pass

class Car:
    pass

todo = MyList()
volvo = Car()

print(is_listclass(todo))
# Output:
# True

print(is_listclass(volvo))
# Output:
# False

API Reference

Decorator Arguments

Argument	Type	Default	Description
len	int	0	Expected length of the collection. 0 means dynamic size.
type	type	any	Restricts elements to a single or multiple explicit python types.
frozen	bool	False	If True, prevents item assignment and mutating operations.

Available Methods

Depending on configuration (frozen and len), instances support standard list operations:

• Access: __getitem__, __iter__, __contains__, count(), index()
• Mutation (Dynamic only): append(), pop(), clear(), insert(), __delitem__
• Ordering (Mutable only): sort(), reverse()
• Math: __add__, __iadd__, __mul__, __imul__