convert-python-roc

name	convert-python-roc
description	Convert Python code to idiomatic Roc. Use when migrating Python projects to Roc, translating Python patterns to idiomatic Roc, or refactoring Python codebases for type safety, functional purity, and native performance. Extends meta-convert-dev with Python-to-Roc specific patterns.

Convert Python to Roc

Convert Python code to idiomatic Roc. This skill extends meta-convert-dev with Python-to-Roc specific type mappings, idiom translations, and architectural guidance for transforming dynamic, garbage-collected Python code into statically-typed, pure functional Roc with platform-separated effects.

This Skill Extends

• meta-convert-dev - Foundational conversion patterns (APTV workflow, testing strategies)

For general concepts like the Analyze → Plan → Transform → Validate workflow, testing strategies, and common pitfalls, see the meta-skill first.

This Skill Adds

• Type mappings: Python types → Roc types (dynamic → static with inference)
• Idiom translations: Python patterns → idiomatic Roc
• Error handling: Exceptions → Result types
• Platform architecture: Python runtime → Roc platform/application model
• Async patterns: asyncio → Task-based effects
• Class hierarchy: OOP → records + functions
• Dev workflow: REPL-driven → expect-driven development

This Skill Does NOT Cover

• General conversion methodology - see meta-convert-dev
• Python language fundamentals - see lang-python-dev
• Roc language fundamentals - see lang-roc-dev
• Reverse conversion (Roc → Python) - not recommended

---

Quick Reference

Python	Roc	Notes
int	I64 or U64	Roc uses fixed-size integers; Python has arbitrary precision
float	F64	64-bit floating point
bool	Bool	Direct mapping
str	Str	UTF-8 strings
bytes	List U8	Byte arrays become lists
list[T]	List a	Immutable lists
tuple	(a, b) or record	Tuples or named records
dict[K, V]	Dict k v	Immutable dictionaries
set[T]	Set a	Immutable sets
None	[Some a, None]	Use tag unions for optional
Union[T, U]	[A a, B b] tag union	Tagged unions
Optional[T]	[Some a, None]	Optional values
Callable[[Args], Ret]	args -> ret	Functions
class	record + module	Data + behavior separated
async def	Task a err	Platform-provided effects
@dataclass	{ ... } record	Structural records
Exception	Result a err	No exceptions in Roc

When Converting Code

1. Analyze source thoroughly before writing target
2. Map types first - Python's dynamic types need explicit Roc types
3. Separate pure from effectful - Roc strictly enforces purity
4. Embrace immutability - no mutable keyword in Roc
5. Adopt Roc idioms - don't write "Python code in Roc syntax"
6. Think in pattern matching - replace if/elif chains
7. Let types guide - use Roc's type inference
8. Test equivalence - same inputs → same outputs
9. Consider platform model - effects go through platform boundary

---

Paradigm Translation

Mental Model Shift: Python Runtime → Roc Platform Model

The biggest conceptual shift is how effects (I/O, async, state) are handled:

Python Concept	Roc Approach	Key Insight
Python runtime with GC	Platform provides runtime	Runtime external to application
Direct I/O anywhere	Platform-provided Task	Application stays pure
async/await	Task ok err via platform	Effects delegated to platform
Mutable by default	Immutable by default	No mutation operators
Duck typing	Static structural typing	Compiler infers types
Dynamic introspection	Compile-time types only	No runtime type inspection
Exception handling	Result type only	No runtime exceptions
Classes with state	Records + module functions	Data and behavior separated

Architecture Mental Model

Python                             Roc (Platform Model)
┌─────────────────────┐           ┌─────────────────────┐
│   Your Python Code  │           │   Your Roc Code     │
│   (can do I/O)      │           │   (pure only)       │
│   ↓                 │           │   ↓                 │
│   Python stdlib     │           │   Platform API      │
│   ↓                 │           │   ↓                 │
│   CPython runtime   │           │   Platform Host     │
└─────────────────────┘           └─────────────────────┘
     Everything in                    Clear separation
     same runtime                     between pure & effects

Key shift: In Python, you can call print() anywhere. In Roc, all I/O goes through the platform's Task type. This enforces functional purity in your application code.

---

Type System Mapping

Primitive Types

Python	Roc	Notes
int	I64	Python has arbitrary precision; Roc uses 64-bit signed
int	U64	For positive-only values
int	I32, I16, I8	Smaller sizes for memory efficiency
int	U32, U16, U8	Unsigned variants
float	F64	Default 64-bit floating point
float	F32	32-bit for memory efficiency
bool	Bool	Direct mapping
str	Str	UTF-8 strings (both immutable)
bytes	List U8	Byte arrays as lists
None	Tag in union	Use [Some a, None] pattern

Critical differences:

• Python int has arbitrary precision; Roc integers have fixed sizes (choose appropriately)
• Python strings are unicode; Roc strings are UTF-8 (compatible but mind encoding)
• Python None is a singleton; Roc uses tag unions for optional values

Collection Types

Python	Roc	Notes
list[T]	List a	Both are ordered; Roc is immutable
tuple[T, U]	(a, b)	Fixed-size tuples map directly
dict[K, V]	Dict k v	Immutable dictionaries
set[T]	Set a	Immutable sets
frozenset[T]	Set a	All Roc collections are immutable
collections.deque	List a	Use list; platform-specific for performance
collections.Counter	Dict a U64	Map to counts
collections.defaultdict	Dict.get(key, default)	Use default parameter

Key insight: All Roc collections are immutable by default. Operations return new collections.

Composite Types

Python	Roc	Notes
@dataclass	{ ... } record	Structural records
class (data)	{ ... } record	Data-only classes
class (behavior)	record + module	Separate data and functions
TypedDict	{ ... } record	Named fields
NamedTuple	{ ... } record	Named record preferred
enum.Enum	[A, B, C] tag union	Discriminated unions
Union[T, U]	[A a, B b] tag	Tagged unions
Optional[T]	[Some a, None]	Optional pattern
Literal["a", "b"]	[A, B] tag union	Enumerated values
Callable[[Args], Ret]	args -> ret	Function types

Type Annotations → Type Signatures

Python	Roc	Notes
def f(x: int) -> int	f : I64 -> I64	Function type signature
def f(x: T) -> T	f : a -> a	Generic type variable
x: Any	a (generic)	Use generics instead of Any
x: list[int]	List I64	List of integers
x: Optional[int]	[Some I64, None]	Optional via tag union
x: Union[int, str]	[Int I64, Str Str]	Discriminated union

---

Idiom Translation

Pattern 1: None/Optional Handling

Python:

def find_user(user_id: int) -> Optional[dict]:
    for user in users:
        if user["id"] == user_id:
            return user
    return None

# Usage with walrus operator
if user := find_user(1):
    name = user["name"]
else:
    name = "Unknown"

# Or with ternary
name = user["name"] if user else "Unknown"

Roc:

findUser : I64 -> [Some User, None]
findUser = \userId ->
    when List.findFirst(users, \u -> u.id == userId) is
        Ok(user) -> Some(user)
        Err(_) -> None

# Usage with pattern matching
name = when findUser(1) is
    Some(user) -> user.name
    None -> "Unknown"

Why this translation:

• Python uses None and truthy checks; Roc uses tag unions [Some a, None]
• Python allows property access on potentially-None values (runtime error); Roc requires pattern matching (compile-time safety)
• Roc's exhaustive pattern matching prevents forgetting the None case

Pattern 2: Result for Error Handling

Python:

def divide(x: int, y: int) -> int:
    if y == 0:
        raise ValueError("Division by zero")
    return x // y

# Exception handling
try:
    result = divide(10, 2)
    print(f"Result: {result}")
except ValueError as e:
    print(f"Error: {e}")

Roc:

divide : I64, I64 -> Result I64 [DivByZero]
divide = \x, y ->
    if y == 0 then
        Err(DivByZero)
    else
        Ok(x // y)

# Pattern matching
when divide(10, 2) is
    Ok(result) -> Stdout.line!("Result: \(Num.toStr(result))")
    Err(DivByZero) -> Stdout.line!("Error: Division by zero")

Why this translation:

• Python uses exceptions; Roc uses Result type (compile-time error handling)
• Python try/except → Roc when ... is pattern matching
• Roc errors are typed (DivByZero tag, not string), enabling exhaustive checking

Pattern 3: List Comprehensions

Python:

# List comprehension
squared_evens = [x * x for x in numbers if x % 2 == 0]

# Generator expression with sum
total = sum(x * x for x in numbers if x % 2 == 0)

# Nested comprehension
matrix = [[i+j for j in range(3)] for i in range(3)]

Roc:

# List operations
squaredEvens =
    numbers
    |> List.keepIf(\x -> x % 2 == 0)
    |> List.map(\x -> x * x)

# Fold for aggregation
total =
    numbers
    |> List.keepIf(\x -> x % 2 == 0)
    |> List.map(\x -> x * x)
    |> List.walk(0, Num.add)

# Nested - use map
matrix =
    List.range({ start: At(0), end: Before(3) })
    |> List.map(\i ->
        List.range({ start: At(0), end: Before(3) })
        |> List.map(\j -> i + j)
    )

Why this translation:

• Python comprehensions are concise but limited; Roc uses explicit pipeline of operations
• Roc's List.keepIf (filter) + List.map composes clearly
• For aggregation, use List.walk (fold) instead of built-in sum
• Pipeline operator |> provides left-to-right data flow like comprehensions

Pattern 4: Dictionary Operations

Python:

# Get with default
value = config.get("timeout", 30)

# Dictionary comprehension
squared = {k: v * v for k, v in items.items()}

# Update
config["timeout"] = 60  # Mutable

# Merge dictionaries
merged = {**dict1, **dict2}

Roc:

# Get with default
value = Dict.get(config, "timeout") |> Result.withDefault(30)

# Map values (transform dictionary)
squared = Dict.map(items, \_, v -> v * v)

# Update (returns new dictionary)
newConfig = Dict.insert(config, "timeout", 60)

# Merge dictionaries
merged = Dict.insertAll(dict1, dict2)

Why this translation:

• Python dicts are mutable; Roc dicts are immutable (operations return new dicts)
• Python dict.get(key, default) → Roc Dict.get returns Result, use withDefault
• Dict comprehensions → Dict.map for value transformation
• Roc's functional style makes data flow explicit

Pattern 5: String Formatting

Python:

# f-strings (Python 3.6+)
message = f"User {user['name']} has {count} items"

# format method
message = "User {} has {} items".format(user['name'], count)

# % formatting
message = "User %s has %d items" % (user['name'], count)

Roc:

# String interpolation
message = "User \(user.name) has \(Num.toStr(count)) items"

# String concatenation (avoid for complex strings)
message = Str.concat([
    "User ",
    user.name,
    " has ",
    Num.toStr(count),
    " items",
])

Why this translation:

• Python f-strings auto-convert to string; Roc requires explicit Num.toStr for numbers
• Roc uses \(expr) for interpolation (similar to f-string braces)
• String concatenation is available but interpolation is cleaner

Pattern 6: Class → Record + Module Functions

Python:

@dataclass
class User:
    id: int
    name: str
    email: str
    active: bool = True

    def deactivate(self):
        self.active = False

    def get_display_name(self) -> str:
        return f"{self.name} ({self.email})"

# Usage
user = User(id=1, name="Alice", email="[e-mail]")
user.deactivate()
display = user.get_display_name()

Roc:

# Record type
User : {
    id : I64,
    name : Str,
    email : Str,
    active : Bool,
}

# Module functions
deactivate : User -> User
deactivate = \user ->
    { user & active: Bool.false }

getDisplayName : User -> Str
getDisplayName = \user ->
    "\(user.name) (\(user.email))"

# Usage
user = { id: 1, name: "Alice", email: "[e-mail]", active: Bool.true }
deactivatedUser = deactivate(user)
display = getDisplayName(deactivatedUser)

Why this translation:

• Python classes combine data and behavior; Roc separates into records (data) and module functions (behavior)
• Python methods mutate self; Roc functions return new values (immutability)
• No self in Roc - pass the record explicitly as a parameter
• Roc's approach is more functional: data + pure functions

Pattern 7: Async/Await → Task

Python:

import asyncio

async def fetch_user(user_id: int) -> dict:
    await asyncio.sleep(0.1)  # Simulate I/O
    return {"id": user_id, "name": f"User {user_id}"}

async def process_users(user_ids: list[int]) -> list[dict]:
    tasks = [fetch_user(uid) for uid in user_ids]
    return await asyncio.gather(*tasks)

# Run
result = asyncio.run(process_users([1, 2, 3]))

Roc:

import pf.Task exposing [Task]
import pf.Http

fetchUser : I64 -> Task User [HttpErr]*
fetchUser = \userId ->
    # Platform handles I/O
    Http.get!("https://api.example.com/users/\(Num.toStr(userId))")

processUsers : List I64 -> Task (List User) [HttpErr]*
processUsers = \userIds ->
    # Platform may parallelize
    userIds
    |> List.map(fetchUser)
    |> Task.sequence

# main is already a Task - no explicit run
main : Task {} []
main =
    users = processUsers!([1, 2, 3])
    Stdout.line!("Processed \(Num.toStr(List.len(users))) users")

Why this translation:

• Python async def → Roc Task a err (platform-provided)
• Python await → Roc ! suffix (try operator)
• Python asyncio.gather → Roc Task.sequence (platform controls parallelism)
• Python needs asyncio.run; Roc main is already a Task that platform executes
• Roc's platform model separates pure code from effectful I/O

Pattern 8: Context Managers → Try with Cleanup

Python:

# with statement for automatic cleanup
with open("file.txt") as f:
    content = f.read()
# File automatically closed

# Custom context manager
from contextlib import contextmanager

@contextmanager
def timer():
    start = time.time()
    yield
    print(f"Elapsed: {time.time() - start:.2f}s")

with timer():
    # Code to time
    expensive_operation()

Roc:

# File I/O with platform Task
readFile : Str -> Task Str [FileReadErr]*
readFile = \path ->
    File.readUtf8!(Path.fromStr(path))
    # Platform handles file closing

# No direct equivalent to context managers
# Resource cleanup handled by platform
# For custom timing, use explicit start/end
processWithTiming : {} -> Task {} []
processWithTiming = \{} ->
    start = getCurrentTime!
    expensiveOperation!
    end = getCurrentTime!
    elapsed = end - start
    Stdout.line!("Elapsed: \(Num.toStr(elapsed))s")

Why this translation:

• Python context managers (with) → Roc platforms handle resource cleanup
• Python's __enter__/__exit__ protocol → No direct equivalent; platform manages resources
• File operations return Task; platform ensures proper cleanup
• For custom resource management, structure as explicit acquisition/release in Task chains

Pattern 9: Exception Hierarchy → Tagged Errors

Python:

class ValidationError(Exception):
    pass

class InvalidName(ValidationError):
    pass

class InvalidAge(ValidationError):
    pass

def validate_person(name: str, age: int) -> dict:
    if not name:
        raise InvalidName("Name cannot be empty")
    if age < 0 or age > 120:
        raise InvalidAge("Age must be 0-120")
    return {"name": name, "age": age}

try:
    person = validate_person("", 30)
except InvalidName as e:
    print(f"Name error: {e}")
except InvalidAge as e:
    print(f"Age error: {e}")
except ValidationError as e:
    print(f"Validation error: {e}")

Roc:

ValidationError : [InvalidName Str, InvalidAge Str]

Person : { name : Str, age : I64 }

validatePerson : Str, I64 -> Result Person ValidationError
validatePerson = \name, age ->
    if Str.isEmpty(name) then
        Err(InvalidName("Name cannot be empty"))
    else if age < 0 || age > 120 then
        Err(InvalidAge("Age must be 0-120"))
    else
        Ok({ name, age })

# Pattern matching on errors
when validatePerson("", 30) is
    Ok(person) -> Stdout.line!("Valid: \(person.name)")
    Err(InvalidName(msg)) -> Stdout.line!("Name error: \(msg)")
    Err(InvalidAge(msg)) -> Stdout.line!("Age error: \(msg)")

Why this translation:

• Python exception hierarchies → Roc tag unions for error types
• Python raise → Roc Err(tag)
• Python try/except with hierarchy → Roc pattern matching on all error variants
• Roc's exhaustive matching ensures all error cases are handled at compile time

Pattern 10: Decorators → Higher-Order Functions

Python:

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        result = func(*args, **kwargs)
        print(f"Result: {result}")
        return result
    return wrapper

@log_calls
def add(a: int, b: int) -> int:
    return a + b

result = add(2, 3)

Roc:

# Higher-order function approach
logCalls : (a -> b), Str -> (a -> b)
logCalls = \fn, name ->
    \arg ->
        Stdout.line!("Calling \(name)")
        result = fn(arg)
        Stdout.line!("Result: \(Inspect.toStr(result))")
        result

# Note: The above won't work because Stdout.line! is effectful
# In Roc, decorators with side effects need Task wrapping

# For pure logging (accumulated), use:
loggedAdd : I64, I64 -> (I64, List Str)
loggedAdd = \a, b ->
    result = a + b
    logs = ["Calling add", "Result: \(Num.toStr(result))"]
    (result, logs)

Why this translation:

• Python decorators can have side effects anywhere; Roc enforces purity
• For logging with I/O, wrap in Task (not shown above for simplicity)
• For pure transformations, use higher-order functions
• Roc has no built-in decorator syntax; use explicit function composition

---

Error Handling

Python Exceptions → Roc Result

Python relies heavily on exceptions for error handling. Roc has no exceptions - all errors are values via the Result type.

Conversion strategy:

1. Identify all raise statements → Convert to Err(tag) returns
2. Identify all try/except blocks → Convert to when ... is pattern matching
3. Define error tag unions for related errors
4. Use ! (try operator) for error propagation up the call stack

Python:

def parse_and_divide(a_str: str, b_str: str) -> int:
    try:
        a = int(a_str)
        b = int(b_str)
        if b == 0:
            raise ValueError("Division by zero")
        return a // b
    except ValueError as e:
        raise ValueError(f"Invalid input: {e}")

try:
    result = parse_and_divide("10", "2")
    print(f"Result: {result}")
except ValueError as e:
    print(f"Error: {e}")

Roc:

ParseError : [InvalidNumber Str, DivByZero]

parseAndDivide : Str, Str -> Result I64 ParseError
parseAndDivide = \aStr, bStr ->
    a = Str.toI64!(aStr)
        |> Result.mapErr(\_ -> InvalidNumber("Invalid number: \(aStr)"))

    b = Str.toI64!(bStr)
        |> Result.mapErr(\_ -> InvalidNumber("Invalid number: \(bStr)"))

    if b == 0 then
        Err(DivByZero)
    else
        Ok(a // b)

# Usage
when parseAndDivide("10", "2") is
    Ok(result) -> Stdout.line!("Result: \(Num.toStr(result))")
    Err(InvalidNumber(msg)) -> Stdout.line!("Error: \(msg)")
    Err(DivByZero) -> Stdout.line!("Error: Division by zero")

Key differences:

• Python exceptions can be raised from anywhere; Roc Result must be explicitly returned
• Python exception hierarchy (base/derived); Roc tag unions (flat structure with tags)
• Python try/except is runtime; Roc pattern matching is compile-time verified (exhaustiveness)

---

Concurrency & Async Patterns

Python Threading/Asyncio → Roc Task

Python has multiple concurrency models (threading, multiprocessing, asyncio). Roc delegates all concurrency to the platform via Task.

Python (Threading):

import threading

def worker(name: str, result_list: list):
    # Simulate work
    result = f"Worker {name} done"
    result_list.append(result)

results = []
threads = [
    threading.Thread(target=worker, args=(f"T{i}", results))
    for i in range(3)
]

for t in threads:
    t.start()
for t in threads:
    t.join()

print(results)

Python (Asyncio):

import asyncio

async def worker(name: str) -> str:
    await asyncio.sleep(0.1)
    return f"Worker {name} done"

async def main():
    tasks = [worker(f"T{i}") for i in range(3)]
    results = await asyncio.gather(*tasks)
    print(results)

asyncio.run(main())

Roc:

import pf.Task exposing [Task]

worker : Str -> Task Str []
worker = \name ->
    # Platform handles concurrency
    Task.ok("Worker \(name) done")

main : Task {} []
main =
    tasks = List.range({ start: At(0), end: Before(3) })
        |> List.map(\i -> worker("T\(Num.toStr(i))"))

    results = Task.sequence!(tasks)  # Platform may parallelize

    Stdout.line!(Inspect.toStr(results))

Why this translation:

• Python explicit threading/asyncio → Roc platform-controlled concurrency
• Python asyncio.gather → Roc Task.sequence (platform decides how to execute)
• Python threads share memory (GIL); Roc Task isolates effects via platform
• Roc applications don't manage threads - the platform does

GIL Considerations

Python's Global Interpreter Lock (GIL) limits true parallelism for CPU-bound tasks. Roc has no GIL - parallelism is platform-dependent.

Python Limitation	Roc Advantage
Threading blocked by GIL	Platform can use true parallelism
Need multiprocessing for CPU-bound	Platform handles scheduling
Async only for I/O-bound	Task can be I/O or compute

Key insight: When converting from Python, you may gain concurrency benefits if the Roc platform implements parallel task execution.

---

Dev Workflow Translation

REPL-Driven Development → Expect-Driven Development

Python has a strong REPL culture (IPython, Jupyter). Roc has roc repl but it's more limited. The conversion requires adapting workflows.

Python Workflow	Roc Equivalent	Notes
IPython REPL	roc repl	Limited compared to IPython
Jupyter notebooks	N/A	No notebook support
Interactive debugging	dbg function	Print-style debugging
Hot reload	roc dev	Watches and rebuilds
python script.py	roc run script.roc	Direct execution
pytest -k test_name	roc test	Runs all expect statements

Python (REPL-driven):

# IPython session
>>> def double(x):
...     return x * 2
>>> double(5)  # Immediate feedback
10
>>> [double(x) for x in range(5)]  # Experiment
[0, 2, 4, 6, 8]

Roc (Expect-driven):

# In file
double : I64 -> I64
double = \x -> x * 2

# Inline tests provide rapid feedback
expect double(5) == 10
expect List.map([0, 1, 2, 3, 4], double) == [0, 2, 4, 6, 8]

# Run with: roc test file.roc

Migration strategy:

1. Convert interactive REPL experiments to expect statements
2. Use roc test for rapid feedback (similar to running code in REPL)
3. Use roc dev for watch mode during development
4. For exploration, write small test files instead of REPL sessions

---

Common Pitfalls

1. Trying to mutate variables

   • Python allows x = x + 1 on existing variable
   • Roc has no mutation - you'd create new bindings in new scopes
   • Fix: Embrace immutability; use recursion or fold for accumulation

2. Assuming exceptions work

   • Python: raise ValueError("message")
   • Roc has no exceptions
   • Fix: Use Result a err for all fallible operations

3. Expecting duck typing

   • Python: "If it has a .read() method, it's file-like"
   • Roc uses static structural typing
   • Fix: Define explicit record types or use abilities

4. Forgetting to handle all error cases

   • Python: Can catch broad Exception or miss cases
   • Roc enforces exhaustive pattern matching
   • Fix: Handle all variants in when ... is blocks

5. Using mutable data structures

   • Python: list.append(), dict[key] = value
   • Roc collections are immutable
   • Fix: Operations return new collections: List.append, Dict.insert

6. Mixing pure and effectful code

   • Python allows I/O anywhere
   • Roc enforces purity; I/O must be in Task
   • Fix: Separate pure business logic from effectful I/O at platform boundaries

7. Expecting arbitrary precision integers

   • Python int has unlimited precision
   • Roc integers have fixed sizes (I64, U64, etc.)
   • Fix: Choose appropriate size or handle overflow explicitly

8. Assuming REPL workflow

   • Python: IPython, interactive development
   • Roc REPL is more limited
   • Fix: Use expect for inline tests, roc test for rapid feedback

---

Module System

Python Modules → Roc Interfaces

Python:

# user.py
from dataclasses import dataclass

@dataclass
class User:
    id: int
    name: str
    email: str

def create_user(name: str, email: str) -> User:
    return User(id=generate_id(), name=name, email=email)

def get_name(user: User) -> str:
    return user.name

Roc:

# User.roc
interface User
    exposes [User, createUser, getName]
    imports []

User : {
    id : I64,
    name : Str,
    email : Str,
}

createUser : Str, Str -> User
createUser = \name, email -> {
    id: generateId(),
    name,
    email,
}

getName : User -> Str
getName = \user -> user.name

Migration notes:

• Python modules → Roc interfaces (file-based modules)
• Python implicit exports → Roc explicit exposes
• Python imports → Roc imports clause

---

Build System

Python Project → Roc Application

Python (pyproject.toml):

[project]
name = "myproject"
version = "1.0.0"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "ruff>=0.1.0",
]

Roc:

# main.roc
app [main] {
    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.10.0/vNe6s9hWzoTZtFmNkvEICPErI9ptji_ySjicO6CkucY.tar.br"
}

import pf.Task exposing [Task]
import pf.Stdout

main : Task {} []
main =
    Stdout.line!("Hello, Roc!")

Build commands:

# Python
pip install .
pip install .[dev]
python -m myproject

# Roc
roc build main.roc
roc run main.roc
roc test main.roc

Key differences:

• Python uses pyproject.toml + pip/uv; Roc uses platform URLs
• Python has rich dependency ecosystem (PyPI); Roc uses platforms (more limited)
• Roc infers dependencies from imports; no separate manifest needed

---

Testing

pytest → expect

Python (pytest):

# test_math.py
import pytest

def add(a: int, b: int) -> int:
    return a + b

def test_addition():
    assert add(2, 2) == 4

def test_addition_negative():
    assert add(-1, 1) == 0

@pytest.mark.parametrize("a,b,expected", [
    (1, 1, 2),
    (2, 3, 5),
    (10, -5, 5),
])
def test_addition_parametrized(a, b, expected):
    assert add(a, b) == expected

Roc:

# math.roc
add : I64, I64 -> I64
add = \a, b -> a + b

# Inline tests
expect add(2, 2) == 4
expect add(-1, 1) == 0

# Multiple test cases
expect add(1, 1) == 2
expect add(2, 3) == 5
expect add(10, -5) == 5

Run tests:

# Python
pytest

# Roc
roc test math.roc

Migration strategy:

• Convert pytest test functions to expect statements
• Place expects near the functions they test
• Parametrized tests become multiple expect statements
• Run with roc test

---

Examples

Example 1: Simple - Optional Handling

Before (Python):

from typing import Optional

def find_first_even(numbers: list[int]) -> Optional[int]:
    for n in numbers:
        if n % 2 == 0:
            return n
    return None

numbers = [1, 3, 5, 6, 7, 8]
result = find_first_even(numbers)

if result is not None:
    print(f"Found: {result}")
else:
    print("No even number found")

After (Roc):

findFirstEven : List I64 -> [Some I64, None]
findFirstEven = \numbers ->
    when List.findFirst(numbers, \n -> n % 2 == 0) is
        Ok(n) -> Some(n)
        Err(_) -> None

numbers = [1, 3, 5, 6, 7, 8]
result = findFirstEven(numbers)

when result is
    Some(n) -> Stdout.line!("Found: \(Num.toStr(n))")
    None -> Stdout.line!("No even number found")

Example 2: Medium - Result Error Handling with Chain

Before (Python):

from typing import Union

def parse_int(s: str) -> Union[int, str]:
    try:
        return int(s)
    except ValueError:
        return f"Invalid number: {s}"

def divide(a: int, b: int) -> Union[int, str]:
    if b == 0:
        return "Division by zero"
    return a // b

def calculate(a_str: str, b_str: str) -> Union[int, str]:
    a = parse_int(a_str)
    if isinstance(a, str):  # Error
        return a

    b = parse_int(b_str)
    if isinstance(b, str):  # Error
        return b

    return divide(a, b)

result = calculate("10", "2")
if isinstance(result, int):
    print(f"Result: {result}")
else:
    print(f"Error: {result}")

After (Roc):

CalcError : [ParseError Str, DivByZero]

parseInt : Str -> Result I64 [ParseError Str]
parseInt = \s ->
    Str.toI64(s)
    |> Result.mapErr(\_ -> ParseError("Invalid number: \(s)"))

divide : I64, I64 -> Result I64 [DivByZero]
divide = \a, b ->
    if b == 0 then
        Err(DivByZero)
    else
        Ok(a // b)

calculate : Str, Str -> Result I64 CalcError
calculate = \aStr, bStr ->
    a = parseInt!(aStr)
    b = parseInt!(bStr)
    divide!(a, b)

main : Task {} []
main =
    when calculate("10", "2") is
        Ok(result) -> Stdout.line!("Result: \(Num.toStr(result))")
        Err(ParseError(msg)) -> Stdout.line!("Error: \(msg)")
        Err(DivByZero) -> Stdout.line!("Error: Division by zero")

Example 3: Complex - Async File Processing

Before (Python):

import asyncio
from typing import List
from pathlib import Path

async def read_file(path: str) -> str:
    # Simulate async file read
    await asyncio.sleep(0.01)
    with open(path) as f:
        return f.read()

async def process_line(line: str) -> str:
    # Simulate async processing
    await asyncio.sleep(0.01)
    return line.upper()

async def process_file(input_path: str, output_path: str) -> None:
    # Read file
    content = await read_file(input_path)

    # Process lines concurrently
    lines = content.split('\n')
    tasks = [process_line(line) for line in lines]
    processed_lines = await asyncio.gather(*tasks)

    # Write result
    result = '\n'.join(processed_lines)
    with open(output_path, 'w') as f:
        f.write(result)

    print(f"Processed {len(lines)} lines")

async def main():
    try:
        await process_file("input.txt", "output.txt")
    except FileNotFoundError as e:
        print(f"File not found: {e}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())

After (Roc):

app [main] {
    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.10.0/vNe6s9hWzoTZtFmNkvEICPErI9ptji_ySjicO6CkucY.tar.br"
}

import pf.File
import pf.Path
import pf.Task exposing [Task]
import pf.Stdout

# Pure function - process a line
processLine : Str -> Str
processLine = \line ->
    Str.toUpper(line)

# Task-based file processing
processFile : Str, Str -> Task {} [FileReadErr Path.ReadErr, FileWriteErr Path.WriteErr]*
processFile = \inputPath, outputPath ->
    # Read file (Task)
    content = File.readUtf8!(Path.fromStr(inputPath))

    # Process lines (pure)
    lines = Str.split(content, "\n")
    processedLines = List.map(lines, processLine)
    result = Str.joinWith(processedLines, "\n")

    # Write file (Task)
    File.writeUtf8!(Path.fromStr(outputPath), result)

    # Log completion
    Stdout.line!("Processed \(Num.toStr(List.len(lines))) lines")

main : Task {} []
main =
    when processFile("input.txt", "output.txt") is
        Ok({}) -> Stdout.line!("Success!")
        Err(FileReadErr(_)) -> Stdout.line!("Error: Could not read file")
        Err(FileWriteErr(_)) -> Stdout.line!("Error: Could not write file")

Key conversions demonstrated:

• Python async/await → Roc Task with ! operator
• Python asyncio.gather for concurrency → Roc uses pure List.map (no async needed for CPU-bound processing)
• Python exception handling → Roc when ... is with typed errors
• Python mixes I/O and logic → Roc separates pure (processLine) from effectful (File.read, File.write)

---

Limitations

Due to gaps in the lang-roc-dev skill (6/8 pillars), external research and inference were used for:

Coverage Gaps

Pillar	Python	Roc	Mitigation
Module	✓	✓	Both well-documented
Error	✓	✓	Result pattern clear
Concurrency	✓	✓	Task model documented
Metaprogramming	~	✓	Roc minimalist approach clear
Zero/Default	✓	~	Used tag union pattern
Serialization	✓	~	Inferred from abilities
Build	✓	~	Inferred from examples
Testing	✓	✓	Both covered
Dev Workflow	✓	~	Python REPL → Roc expect

Combined Score: 14.5/18 (Good) - 8 pillars + dev workflow pillar

Known Limitations:

1. Serialization: Roc Encode/Decode abilities exist but aren't fully documented in lang-roc-dev; patterns inferred from platform usage
2. Build System: Roc build is simpler than Python's but emerging; limited packaging guidance
3. Zero/Default: Roc handles via tag unions and pattern matching; no dedicated section in lang-roc-dev

External Resources Used

Resource	What It Provided	Reliability
Roc Tutorial	Platform model, Task usage	High
lang-python-dev	Comprehensive Python patterns	High
lang-roc-dev	Type system, records, tags	High
convert-python-erlang	REPL → compiled workflow	High
convert-fsharp-roc	Functional → Roc patterns	High

---

Tooling

Tool	Purpose	Notes
roc CLI	Build, run, test, format	All-in-one tool
roc build	Compile to binary	Fast incremental builds
roc run	Execute directly	Like python script.py
roc test	Run expect statements	Inline testing
roc format	Code formatting	Like black or ruff format
roc repl	Interactive shell	More limited than IPython
roc dev	Watch mode	Rebuild on file changes
Roc LSP	Editor support	VS Code, vim integration

---

See Also

For more examples and patterns, see:

• meta-convert-dev - Foundational patterns with cross-language examples
• convert-python-rust - Python → Rust conversion for ownership focus
• convert-python-erlang - Python → Erlang for BEAM runtime patterns
• convert-fsharp-roc - F# → Roc for .NET to native functional conversion
• lang-python-dev - Python development patterns
• lang-roc-dev - Roc development patterns

Cross-cutting pattern skills:

• patterns-concurrency-dev - Async, Task, threading across languages
• patterns-serialization-dev - JSON, validation across languages
• patterns-metaprogramming-dev - Decorators, code generation across languages

---

References

• Roc Tutorial
• Roc Platform Model
• Python Type Hints
• Python to Functional Programming