Quickstart

o# Quickstart Guide

This guide will get you up and running with functional_list in just a few minutes.

📦 Installation

Basic Installation

Install the core package with pip:

pip install functional-list

Or with uv (recommended for faster installs):

uv add functional-list

Optional Features

Install with optional backends and I/O support:

# For Ray distributed computing
pip install functional-list[ray]

# For Dask distributed computing
pip install functional-list[dask]

# For Parquet file support
pip install functional-list[io]

# Install everything
pip install functional-list[all]

Development Setup

If you're developing with functional_list:

# Clone the repository
git clone https://gitlab.com/Tantelitiana22/list-function-python-project.git
cd list-function-python-project

# Install with development dependencies
uv sync --group dev

🚀 Your First Functional List

Creating a ListMapper

The ListMapper class is your main entry point:

from functional_list import ListMapper

# Create from individual items
numbers = ListMapper[int](1, 2, 3, 4)

# Create from an existing list
items = ListMapper[str](*["apple", "banana", "cherry"])

# Create from a range
big_list = ListMapper[int](*range(1000))

Basic Transformations

Map - Transform Each Element

Apply a function to each element:

from functional_list import ListMapper

numbers = ListMapper[int](1, 2, 3, 4)
squared = numbers.map(lambda x: x * x)

print(squared)  # List[1, 4, 9, 16]

Filter - Keep Only Matching Elements

Keep elements that satisfy a condition:

from functional_list import ListMapper

numbers = ListMapper[int](1, 2, 3, 4, 5, 6)
evens = numbers.filter(lambda x: x % 2 == 0)

print(evens)  # List[2, 4, 6]

Chaining Operations

Combine multiple operations elegantly:

from functional_list import ListMapper

result = (
    ListMapper[int](1, 2, 3, 4, 5, 6, 7, 8)
    .map(lambda x: x * x)           # Square: [1, 4, 9, 16, 25, 36, 49, 64]
    .filter(lambda x: x > 10)       # Filter: [16, 25, 36, 49, 64]
    .map(lambda x: x // 10)         # Divide: [1, 2, 3, 4, 6]
)

print(result)  # List[1, 2, 3, 4, 6]
print(result.to_list())  # Convert to regular Python list

🔄 Common Operations

Reduce - Aggregate to a Single Value

Combine all elements into a single result:

from functional_list import ListMapper

# Sum all numbers
total = ListMapper[int](1, 2, 3, 4, 5).reduce(lambda x, y: x + y)
print(total)  # 15

# Find maximum
maximum = ListMapper[int](3, 7, 2, 9, 1).reduce(lambda x, y: x if x > y else y)
print(maximum)  # 9

# Concatenate strings
words = ListMapper[str]("Hello", "World", "!").reduce(lambda x, y: f"{x} {y}")
print(words)  # "Hello World !"

FlatMap - Map and Flatten

Transform each element into multiple elements:

from functional_list import ListMapper

# Split sentences into words
sentences = ListMapper[str](
    "Hello world",
    "Python is great",
    "Functional programming rocks"
)
words = sentences.flat_map(lambda s: s.split())

print(words)
# List['Hello', 'world', 'Python', 'is', 'great', 'Functional', 'programming', 'rocks']

Distinct - Remove Duplicates

Get unique elements:

from functional_list import ListMapper

numbers = ListMapper[int](1, 2, 2, 3, 3, 3, 4, 5, 5)
unique = numbers.distinct()

print(unique)  # List[1, 2, 3, 4, 5]

de### Union - Combine ListMappers

Combine two ListMapper objects of the same type:

from functional_list import ListMapper

# Combine two integer lists
list1 = ListMapper(1, 2, 3)
list2 = ListMapper(4, 5, 6)
combined = list1.union(list2)
print(combined)  # List[1, 2, 3, 4, 5, 6]

# Union preserves duplicates
list1 = ListMapper(1, 2, 3)
list2 = ListMapper(3, 4, 5)
result = list1.union(list2)
print(result)  # List[1, 2, 3, 3, 4, 5]

# Remove duplicates after union
unique = list1.union(list2).distinct()
print(unique)  # List[1, 2, 3, 4, 5]

# Type-safe: this would raise TypeError
# int_list = ListMapper(1, 2, 3)
# str_list = ListMapper("a", "b", "c")
# int_list.union(str_list)  # TypeError!

Sort - Order Your Data

Sort elements with optional key functions:

from functional_list import ListMapper

# Sort numbers
numbers = ListMapper(3, 1, 4, 1, 5, 9, 2, 6)
sorted_asc = numbers.sort()
print(sorted_asc)  # List[1, 1, 2, 3, 4, 5, 6, 9]

# Sort in reverse
sorted_desc = numbers.sort(reverse=True)
print(sorted_desc)  # List[9, 6, 5, 4, 3, 2, 1, 1]

# Sort with key function - by length
words = ListMapper("apple", "pie", "a", "cherry")
by_length = words.sort(key=lambda x: len(x))
print(by_length)  # List['a', 'pie', 'apple', 'cherry']

# Sort dictionaries by field
users = ListMapper(
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25},
    {"name": "Charlie", "age": 35}
)
by_age = users.sort(key=lambda u: u["age"])
print(by_age[0])  # {'name': 'Bob', 'age': 25}

# Sort by multiple criteria
data = ListMapper(
    {"category": "A", "value": 2},
    {"category": "B", "value": 1},
    {"category": "A", "value": 1}
)
sorted_data = data.sort(key=lambda x: (x["category"], x["value"]))
# Sorted by category first, then by value

Group By and Reduce By Key

Work with key-value pairs:

from functional_list import ListMapper

# Group by key
pairs = ListMapper(("fruit", "apple"), ("fruit", "banana"), ("veg", "carrot"))
grouped = pairs.group_by_key()
print(grouped)
# List[('fruit', ['apple', 'banana']), ('veg', ['carrot'])]

# Reduce by key (sum values)
sales = ListMapper(("Mon", 100), ("Tue", 150), ("Mon", 200), ("Tue", 50))
totals = sales.reduce_by_key(lambda x, y: x + y)
print(totals)
# List[('Mon', 300), ('Tue', 200)]

🎯 Real-World Example: Word Count

The classic MapReduce word count pattern:

from functional_list import ListMapper

# Input: lines of text
documents = ListMapper[str](
    "python is good",
    "python is better than x",
    "python is the best",
    "java is good too"
)

# Word count pipeline
word_counts = (
    documents
    .flat_map(lambda line: line.split())        # Split into words
    .map(lambda word: (word, 1))                # Create (word, count) pairs
    .reduce_by_key(lambda count1, count2: count1 + count2)  # Sum counts
    .sort(key=lambda pair: pair[1], reverse=True)  # Sort by count
)

print(word_counts)
# Output: [('python', 3), ('is', 4), ('good', 2), ('better', 1),
#          ('than', 1), ('x', 1), ('the', 1), ('best', 1), ('java', 1), ('too', 1)]

# Get top 3 words
top_3 = word_counts.take(3)
print(top_3)  # [('python', 3), ('is', 4), ('good', 2)]

📊 Working with Data Files

Reading CSV Files

from functional_list import ListMapper
from functional_list.io import CSVReadOptions

# Read CSV with headers
users = ListMapper.from_csv(
    "users.csv",
    options=CSVReadOptions(skip_header=True),
    transform=lambda row: {
        "name": row[0],
        "age": int(row[1]),
        "city": row[2]
    }
)

# Process the data
adults = users.filter(lambda u: u["age"] >= 18)
cities = adults.map(lambda u: u["city"]).distinct()

Reading JSON Files

from functional_list import ListMapper

# Read JSON array
data = ListMapper.from_json("data.json")

# Extract specific fields
names = data.map(lambda item: item["name"])

Reading Text Files

from functional_list import ListMapper
from functional_list.io import TextReadOptions

# Read log file
logs = ListMapper.from_text(
    "app.log",
    options=TextReadOptions(strip_lines=True, skip_empty=True)
)

# Find errors
errors = logs.filter(lambda line: "ERROR" in line)

💤 Lazy Evaluation

For better performance with large datasets, use lazy evaluation:

from functional_list import ListMapper

# Build a lazy pipeline
lazy_pipeline = (
    ListMapper[int](*range(1_000_000))
    .lazy()                              # Switch to lazy mode
    .map(lambda x: x * 2)
    .filter(lambda x: x > 100_000)
    .map(lambda x: x // 100)
)

# No computation happens yet!

# Materialize only when needed
result = lazy_pipeline.take(10)  # Only computes first 10 results
print(result)

⚡ Using Backends for Performance

Execute operations in parallel:

from functional_list import ListMapper, LocalBackend

# CPU-bound work: use processes
def expensive_computation(x):
    return sum(i * i for i in range(x))

result = (
    ListMapper[int](*range(1, 100))
    .map(
        expensive_computation,
        backend=LocalBackend(mode="processes", workers=4)
    )
)

# I/O-bound work: use threads
import requests

def fetch_url(url):
    return requests.get(url).text

urls = ListMapper[str]("http://example.com", "http://example.org")
pages = urls.map(
    fetch_url,
    backend=LocalBackend(mode="threads", workers=10)
)

🎓 Next Steps

Now that you've got the basics, explore more:

1. Concepts: Backends - Learn about execution backends
2. Concepts: Eager vs Lazy - When to use each mode
3. Guides: I/O Operations - Deep dive into file operations
4. API Reference - Complete API documentation
5. Benchmarks - Performance comparisons

💡 Quick Tips

Performance

• Use lazy mode for large datasets
• Choose the right backend (threads for I/O, processes for CPU)
• Use chunk_size parameter with Ray/Dask for better performance

Common Pitfalls

• Don't use lambdas with multiprocessing (use named functions)
• AsyncBackend requires async def functions
• Ray and Dask are optional dependencies

Type Hints

ListMapper is fully typed: ListMapper[int], ListMapper[str], etc.

Happy functional programming! 🎉