A functional programming kata for Python - recreating PyToolz functions from scratch!
This project challenges you to reimplement functions from the PyToolz library, a functional standard library for Python. By building these functions yourself, you'll learn:
- Functional programming patterns and principles
- Working with sequences and iterables
- Higher-order functions (functions that take/return functions)
- How popular Python libraries work under the hood
- Immutable data structures and pure functions
- Generators and lazy evaluation (advanced section)
PyToolz is used in real-world Python applications for data processing, analytics, and functional programming. Understanding how it works will make you a better Python developer!
- Python 3.11+ installed
- A modern web browser (Chrome, Firefox, Safari, or Edge)
- A text editor or IDE (VS Code, PyCharm, etc.)
-
Open the test runner in your browser:
Simply open
SpecRunner.htmlin your web browser.If opening directly doesn't work, start a local server:
python3 -m http.server 8000
Then navigate to:
http://localhost:8000/SpecRunner.html -
Watch the tests run!
The page will show all tests with green checkmarks (passing) or red X marks (failing). Initially, all tests will fail because the functions aren't implemented yet!
-
Implement the functions:
Edit the appropriate part file and implement each function:
src/whytoolz_part1.py- Foundation functions (start here!)src/whytoolz_part2.py- Sequence manipulation functionssrc/whytoolz_part3.py- Functions & dictionariessrc/whytoolz_advanced.py- Advanced challenges (optional)
Each file contains:
- Function signatures (without type hints, for simplicity)
- Detailed docstrings explaining what each function should do
- Examples of expected behavior
- Helpful hints
-
See your progress:
Save your changes and refresh the browser. Watch the tests turn green as you implement each function correctly!
python/
├── SpecRunner.html # Browser-based test runner (open this!)
├── README.md # This file
├── src/
│ ├── whytoolz_part1.py # Part I: Foundation functions
│ ├── whytoolz_part2.py # Part II: Sequence Manipulation functions
│ ├── whytoolz_part3.py # Part III: Functions & Dictionaries
│ └── whytoolz_advanced.py# Part IV: Advanced (Optional)
├── tests/
│ ├── framework/
│ │ └── test_framework.py # Custom test framework (don't modify)
│ ├── test_part1.py # Part I tests
│ ├── test_part2.py # Part II tests
│ ├── test_part3.py # Part III tests
│ └── test_advanced.py # Part IV tests
└── lib/
└── styles.css # Test runner styling
The functions are organized into four parts with increasing difficulty:
Focus: Basic operations on concrete data structures (lists, dicts, values)
Functions: identity, first, second, last, nth, count, frequencies, groupby, cons, merge
You'll learn:
- Working with Python's indexing and slicing
- Building dictionaries from scratch
- Iterating over sequences and objects
Start here! These functions return concrete values (lists, dicts, numbers), making them easier to understand and debug.
Focus: Working with sequences and iterables
Functions: islice, drop, tail, concat, unique, partition, interleave, pluck, accumulate, sliding_window, take_nth
You'll learn:
- Slicing and subsetting sequences
- Combining and transforming collections
- Extracting data from nested structures
- Working with any iterable (lists, strings, ranges, etc.)
Note: These functions return concrete lists/values, making them easier to understand and debug.
Focus: Higher-order functions and immutable dictionary operations
Functions: pipe, compose, complement, do, memoize, assoc, dissoc, valmap, keymap, valfilter, get_in, update_in
You'll learn:
- Function composition and chaining
- Decorators and closures
- Immutable data structure patterns
- Nested data traversal
Level up: These functions work with other functions as data!
Focus: Generators, lazy evaluation, and advanced patterns
Functions: take, iterate, topk, reduceby, juxt, curry
You'll learn:
- Generators and lazy evaluation with
yield - Creating infinite sequences
- Memory-efficient operations on large datasets
- Using heaps for efficient algorithms
- Simultaneous grouping and reduction
- Partial function application
Challenge yourself: These are harder! Try them if you finish early or want extra practice.
Each test includes a description of what it's testing:
@runner.it("first should pull the first element from a list")
def test_first_basic():
assert wt.first([1, 2, 3]) == 1Some tests have FILL_ME_IN that you need to replace:
assert wt.second('hello') == FILL_ME_IN # You figure out what this should be!When a test fails, you'll see:
- The test description (what it was testing)
- The error message (what went wrong)
- The stack trace (where the error occurred)
Use these clues to debug your implementation!
You can also run tests from the command line (but they won't look as pretty):
python3 tests/test_part1.pyEach function includes type hints:
def first(seq: Iterable[T]) -> T:
"""Return the first element of a sequence."""
passThese tell you:
- What types the function accepts (
Iterable[T]) - What type it returns (
T) - Generic types like
Tmean "any type"
Your IDE can use these hints for autocomplete and error checking!
Generators are a key concept in Part IV (Advanced). Here's a quick primer:
Regular function (eager):
def get_numbers():
return [1, 2, 3, 4, 5] # Creates entire list in memoryGenerator function (lazy):
def get_numbers():
yield 1
yield 2
yield 3
yield 4
yield 5 # Produces values one at a timeWhy use generators?
- Memory efficient (don't store everything at once)
- Can represent infinite sequences
- Only compute what you need
To convert a generator to a list: list(my_generator())
Note: Parts I-III use concrete lists/values. Part IV introduces generators for advanced lazy evaluation patterns.
Dictionary comprehension:
{key: value * 2 for key, value in my_dict.items()}Generator expression:
(x * 2 for x in range(10)) # Like list comprehension but lazyItertools:
from itertools import islice, chain
islice(seq, 5) # Take first 5 items (lazy)
chain(seq1, seq2) # Concatenate sequences (lazy)Learn more about the real PyToolz library:
- Official Docs: https://toolz.readthedocs.io/
- API Reference: https://toolz.readthedocs.io/en/latest/api.html
- GitHub: https://github.com/pytoolz/toolz
Some functions are similar to Python built-ins (but you'll implement them yourself!):
- itertools: https://docs.python.org/3/library/itertools.html
- functools: https://docs.python.org/3/library/functools.html
- Real Python: Functional Programming in Python
- Python Docs: Functional Programming HOWTO
By completing this project, you'll be able to:
- ✅ Implement functions using both eager and lazy evaluation
- ✅ Work confidently with iterators and generators
- ✅ Apply functional programming principles (pure functions, immutability)
- ✅ Use higher-order functions to create reusable abstractions
- ✅ Understand how popular Python libraries are built
- ✅ Debug complex iterator and generator behavior
- ✅ Recognize when to use lazy vs eager evaluation
Once you've completed the main functions:
-
Compare your implementations to the real PyToolz source code:
- Visit: https://github.com/pytoolz/toolz
- See how your solutions differ
- Understand what optimizations they made
-
Add your own functions:
- Think of other useful functions
- Write tests for them
- Implement them in the PyToolz style
-
Optimize for performance:
- Use
timeitto measure function speed - Try different implementation approaches
- See how close you can get to the real PyToolz performance
- Use
-
Explore CyToolz:
- PyToolz has a Cython-compiled version called CyToolz
- It's much faster! Learn why: https://github.com/pytoolz/cytoolz
This project works great with a partner! Try:
-
Driver/Navigator pattern:
- One person types (driver)
- One person guides (navigator)
- Switch roles every 15-20 minutes
-
Ping Pong pattern:
- Person A writes a test
- Person B makes it pass
- Person B writes next test
- Person A makes it pass
- Repeat!
AttributeError: module 'whytoolz' has no attribute 'identity'
→ You haven't implemented that function yet, or there's a syntax error preventing the file from loading.
AssertionError: Expected [1, 2, 3], but got [1, 2, 3, 4]
→ Your function is returning the wrong result. Check your logic!
AssertionError: Expected <class 'list'>, but got <class 'generator'>
→ Parts I-III functions should return lists/concrete values. Part IV (Advanced) functions should return generators for lazy evaluation. Check which part you're in!
ImportError: cannot import name 'identity' from 'src.whytoolz'
→ Make sure your function is defined at the module level, not inside another function.
Stuck? Try these strategies:
- Read the docstring - It explains what the function should do
- Look at the tests - They show example inputs and outputs
- Check the hints - Many functions have hints in their docstrings
- Use print statements - Debug by printing intermediate values
- Google it! - Search for "python [function name]" or "python [concept]"
- Read PyToolz docs - See how the real library describes it
- Ask a peer - Explain the problem out loud (rubber duck debugging!)
This project emphasizes:
- Test-Driven Development - Tests define the requirements
- Functional Programming - Pure functions, immutability, composition
- Pythonic Code - Using Python idioms and best practices
- Learning by Doing - Building things to understand them
Remember: The goal isn't just to make the tests pass. It's to understand how these functions work and why they're useful!
This project was inspired by:
- The original Underscore.js Kata
- The excellent PyToolz library by Matthew Rocklin
- The functional programming community
This project is for educational purposes.
Ready to start? Open src/whytoolz_part1.py and begin with identity!
Happy coding! 🐍✨