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
from listclasses import listclass, is_listclass
@listclass
class MyList:
pass
class Car:
pass
todo = MyList()
volvo = Car()
print(is_listclass(todo))
# Output:
# True
print(is_listclass(volvo))
# Output:
# False
Math and logic operations on listclasses
Adding an item to a listclass
@listclass
class Flowers:
pass
flowers = Flowers('Rose', 'Tulip')
new_flowers = flowers + 'Lily'
print(new_flowers)
# Output:
# Flowers('Rose', 'Tulip', 'Lily')
newer_flowers = 'Poppy' + new_flowers # This adds 'Poppy' to the beggining of a listclass
print(newer_flowers)
# Output:
# Flowers('Poppy', 'Rose', 'Tulip', 'Lily')
You can also use += on listclasses.
Adding to every item of a listclass
If a listclass has a fixed length adding to it will instead add to every of its elements.
@listclass(len=3)
class Color:
pass
red = Color(255, 0, 0)
green = Color(0, 255, 0)
yellow = red + green
print(yellow)
# Output:
# Color(255, 255, 0)
Subtraction
Works the same as remove()
@listclass
class Flowers:
pass
flowers = Flowers('Rose', 'Tulip', 'Sunflower')
flowers_new = flowers - 'Rose'
print(flowers_new)
# Output:
# Flowers('Tulip', 'Sunflower')
You can also use -=, if a listclass has a fixed length subtracting from it will instead subtract from every of its elements.
Multiplication
@listclass
class Coordinates:
pass
xy = Coordinates(20, 400)
print(xy * 5)
# Output:
# Coordinates(20, 400, 20, 400, 20, 400, 20, 400, 20, 400)
You can also use *=, if a listclass has a fixed length multiplying it will instead multiply every of its elements.
Division
@listclass(len=3)
class Color:
pass
green = Color(0, 255, 0)
dark_green = green / 2
print(dark_green)
# Output
# Color(0.0, 127.5, 0.0)
You can also use /=, //, //=, **, **=.
And-ing two listclasses
@listclass(type=bool)
class Attendance:
pass
class1 = Attendance(True, False, True)
class2 = Attendance(True, True, False)
print(class1 and class2)
# Output
# Attendance(True, False, False)
You can also or and xor listclasses
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, any means all types are valid. |
| 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(),random() - Mutation (Dynamic only):
append(),pop(),clear(),insert(),__delitem__ - Ordering (Mutable only):
sort(),reverse() - Math:
__add__,__sub__,__mul__,__truediv__and more - Logic:
__and__,__or__,__xor__
Metadata
Release files for listclasses 2.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| listclasses-2.3.1.tar.gz | 10.8 kB | Without provenance | Details for listclasses-2.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| listclasses-2.3.1-py3-none-any.whl | Python 3 | none | any | Details for listclasses-2.3.1-py3-none-any.whl |
Total release size: 19.6 kB
Release files / listclasses-2.3.1.tar.gz
| Download URL | listclasses-2.3.1.tar.gz |
|---|---|
| Size | 10.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc0342db8c75194f177cb7d3ddd7fed0fc8fbd2f99f1b11035a59642fab6b1fd
|
|
BLAKE2b-256 checksum How to use checksums |
f20bff277493d9811286156d58dff5059e8ea477be539d117b28eb15adb13881
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / listclasses-2.3.1-py3-none-any.whl
| Download URL | listclasses-2.3.1-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7f592db9a81b43c9705833952eaa16a265ddb2b293ee01c91836a3931aecde61
|
|
BLAKE2b-256 checksum How to use checksums |
87385a9be2c96d30b38f63c56e9e472dfac88caefaacac12c4411c026fe4bc40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for listclasses 2.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.