Metadata-Version: 2.4
Name: listclasses
Version: 1.0.1
Summary: A simple decorator to make custom sequence types
Description-Content-Type: text/markdown
Dynamic: description
Dynamic: description-content-type
Dynamic: summary

# 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
Installation: Add the listclass decorator code directly to your project

```commandline
pip install listclasses
```

```python
from listclasses import listclass
```

# Basic Usage

```python
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

```python
@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

```python
@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)
```

### Setting Fixed Lengths

```python
@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

```python
@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.

```python
@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
```
# 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__ (+=)
