Skip to main content

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)

Source distribution for listclasses 2.3.1
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)

Table of built distributions (wheels) for listclasses 2.3.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page