Skip to main content
skill CX Codex

python-scala-idioms — Claude Code skill: what it does, how to install

python-scala-idioms guides AI agents to translate Python into idiomatic Scala. Enforces immutability, pattern matching, sealed domain traits, and type-safe error handling.

Apache-2.0 1 installs ★ 1,933 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add benchflow-ai/skillsbench --skill python-scala-idioms -a claude-code
Open on GitHub

What python-scala-idioms does

This skill prevents AI agents from generating literal line-by-line ports of Python scripts. Instead of migrating mutable state and loops as var structures, it directs the model to apply Scala idioms: expressions over statements, pattern matching over conditional branches, and Option or Either over raw null checks.

The guidance includes side-by-side patterns for mapping list comprehensions to collection combinators, replacing string-typed dispatch with exhaustive sealed trait hierarchies, and modeling state transitions through case class copy calls. It also establishes Scala naming rules (camelCase for methods, CamelCase for constants) and discourages casting with asInstanceOf or typing values as Any.

Keep in mind that these guidelines assume idiomatic functional Scala. If your target codebase relies heavily on mutable state for low-level performance tuning, the patterns enforced here will directly clash with that design.

What it helps with

  • convert imperative Python workflows into functional Scala collections
  • eliminate null checks by migrating Python code to Option chains
  • turn string-based conditional branching into compiler-checked sealed trait hierarchies
  • replace mutable loop accumulators with foldLeft or map pipelines

Example prompts for the agent

  • Translate this Python user service into idiomatic Scala using immutable case classes
  • Refactor these nested Python dict.get calls into an Option for-comprehension in Scala
  • Convert this Python status dispatcher into a Scala sealed trait hierarchy with pattern matching

How to install python-scala-idioms

1Skills CLI (Vercel)

npx skills add benchflow-ai/skillsbench --skill python-scala-idioms -a claude-code

2Manually: put the files in place

~/.claude/skills/python-scala-idioms/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/python-scala-idioms/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about python-scala-idioms

How to install python-scala-idioms in Claude Code?

Run npx skills add benchflow-ai/skillsbench --skill python-scala-idioms -a claude-code in your terminal. Alternatively, place the specification file into ~/.claude/skills/python-scala-idioms/SKILL.md.

What is the goal of python-scala-idioms?

It ensures the assistant writes clean, idiomatic Scala code instead of syntactically converted Python. It promotes immutable collections, explicit typing, pattern matching, and error modeling without null values.

How does this skill handle Python functions returning None on failure?

The guidelines steer the model away from returning Unit or nulls, prompting it to return structured types like Either[Error, Result] or wrap calls in Try.

Source text

SKILL.md · Apache-2.0
---
name: python-scala-idioms
description: Guide for writing idiomatic Scala when translating from Python. Use when the goal is not just syntactic translation but producing clean, idiomatic Scala code. Covers immutability, expression-based style, sealed hierarchies, and common Scala conventions.
---

# Python to Idiomatic Scala Translation

## Core Principles

When translating Python to Scala, aim for idiomatic Scala, not literal translation:

1. **Prefer immutability** - Use `val` over `var`, immutable collections
2. **Expression-based** - Everything returns a value, minimize statements
3. **Type safety** - Leverage Scala's type system, avoid `Any`
4. **Pattern matching** - Use instead of if-else chains
5. **Avoid null** - Use `Option`, `Either`, `Try`

## Immutability First

```python
# Python - mutable by default
class Counter:
    def __init__(self):
        self.count = 0

    def increment(self):
        self.count += 1
        return self.count
```

```scala
// Scala - immutable approach
case class Counter(count: Int = 0) {
  def increment: Counter = copy(count = count + 1)
}

// Usage
val c1 = Counter()
val c2 = c1.increment  // Counter(1)
val c3 = c2.increment  // Counter(2)
// c1 is still Counter(0)
```

## Expression-Based Style

```python
# Python - statement-based
def get_status(code):
    if code == 200:
        status = "OK"
    elif code == 404:
        status = "Not Found"
    else:
        status = "Unknown"
    return status
```

```scala
// Scala - expression-based
def getStatus(code: Int): String = code match {
  case 200 => "OK"
  case 404 => "Not Found"
  case _ => "Unknown"
}

// No intermediate variable, match is an expression
```

## Sealed Hierarchies for Domain Modeling

```python
# Python - loose typing
def process_payment(method: str, amount: float):
    if method == "credit":
        # process credit
        pass
    elif method == "debit":
        # process debit
        pass
    elif method == "crypto":
        # process crypto
        pass
```

```scala
// Scala - sealed trait for exhaustive matching
sealed trait PaymentMethod
case class CreditCard(number: String, expiry: String) extends PaymentMethod
case class DebitCard(number: String) extends PaymentMethod
case class Crypto(walletAddress: String) extends PaymentMethod

def processPayment(method: PaymentMethod, amount: Double): Unit = method match {
  case CreditCard(num, exp) => // process credit
  case DebitCard(num) => // process debit
  case Crypto(addr) => // process crypto
}
// Compiler warns if you miss a case!
```

## Replace Null Checks with Option

```python
# Python
def find_user(id):
    user = db.get(id)
    if user is None:
        return None
    profile = user.get("profile")
    if profile is None:
        return None
    return profile.get("email")
```

```scala
// Scala - Option chaining
def findUser(id: Int): Option[String] = for {
  user <- db.get(id)
  profile <- user.profile
  email <- profile.email
} yield email

// Or with flatMap
def findUser(id: Int): Option[String] =
  db.get(id)
    .flatMap(_.profile)
    .flatMap(_.email)
```

## Prefer Methods on Collections

```python
# Python
result = []
for item in items:
    if item.active:
        result.append(item.value * 2)
```

```scala
// Scala - use collection methods
val result = items
  .filter(_.active)
  .map(_.value * 2)
```

## Avoid Side Effects in Expressions

```python
# Python
items = []
for x in range(10):
    items.append(x * 2)
    print(f"Added {x * 2}")
```

```scala
// Scala - separate side effects
val items = (0 until 10).map(_ * 2).toList
items.foreach(x => println(s"Value: $x"))

// Or use tap for debugging
val items = (0 until 10)
  .map(_ * 2)
  .tapEach(x => println(s"Value: $x"))
  .toList
```

## Use Named Parameters for Clarity

```python
# Python
def create_user(name, email, admin=False, active=True):
    pass

user = create_user("Alice", "[email protected]", admin=True)
```

```scala
// Scala - named parameters work the same
def createUser(
  name: String,
  email: String,
  admin: Boolean = false,
  active: Boolean = true
): User = ???

val user = createUser("Alice", "[email protected]", admin = true)

// Case class with defaults is often better
case class User(
  name: String,
  email: String,
  admin: Boolean = false,
  active: Boolean = true
)

val user = User("Alice", "[email protected]", admin = true)
```

## Scala Naming Conventions

| Python | Scala |
|--------|-------|
| `snake_case` (variables, functions) | `camelCase` |
| `SCREAMING_SNAKE` (constants) | `CamelCase` or `PascalCase` |
| `PascalCase` (classes) | `PascalCase` |
| `_private` | `private` keyword |
| `__very_private` | `private[this]` |

```python
# Python
MAX_RETRY_COUNT = 3
def calculate_total_price(items):
    pass

class ShoppingCart:
    def __init__(self):
        self._items = []
```

```scala
// Scala
val MaxRetryCount = 3  // or final val MAX_RETRY_COUNT
def calculateTotalPrice(items: List[Item]): Double = ???

class ShoppingCart {
  private var items: List[Item] = Nil
}
```

## Avoid Returning Unit

```python
# Python - None return is common
def save_user(user):
    db.save(user)
    # implicit None return
```

```scala
// Scala - consider returning useful information
def saveUser(user: User): Either[Error, UserId] = {
  db.save(user) match {
    case Right(id) => Right(id)
    case Left(err) => Left(err)
  }
}

// Or at minimum, use Try
def saveUser(user: User): Try[Unit] = Try {
  db.save(user)
}
```

## Use Apply for Factory Methods

```python
# Python
class Parser:
    def __init__(self, config):
        self.config = config

    @classmethod
    def default(cls):
        return cls(Config())
```

```scala
// Scala - companion object with apply
class Parser(config: Config)

object Parser {
  def apply(config: Config): Parser = new Parser(config)
  def apply(): Parser = new Parser(Config())
}

// Usage
val parser = Parser()  // Calls apply()
val parser = Parser(customConfig)
```

## Cheat Sheet: Common Transformations

| Python Pattern | Idiomatic Scala |
|---------------|-----------------|
| `if x is None` | `x.isEmpty` or pattern match |
| `if x is not None` | `x.isDefined` or `x.nonEmpty` |
| `x if x else default` | `x.getOrElse(default)` |
| `[x for x in xs if p(x)]` | `xs.filter(p)` |
| `[f(x) for x in xs]` | `xs.map(f)` |
| `any(p(x) for x in xs)` | `xs.exists(p)` |
| `all(p(x) for x in xs)` | `xs.forall(p)` |
| `next(x for x in xs if p(x), None)` | `xs.find(p)` |
| `dict(zip(keys, values))` | `keys.zip(values).toMap` |
| `isinstance(x, Type)` | `x.isInstanceOf[Type]` or pattern match |
| `try: ... except: ...` | `Try { ... }` or pattern match |
| Mutable accumulator loop | `foldLeft` / `foldRight` |
| `for i, x in enumerate(xs)` | `xs.zipWithIndex` |

## Anti-Patterns to Avoid

```scala
// DON'T: Use null
val name: String = null  // Bad!

// DO: Use Option
val name: Option[String] = None

// DON'T: Use Any or type casts
val data: Any = getData()
val name = data.asInstanceOf[String]

// DO: Use proper types and pattern matching
sealed trait Data
case class UserData(name: String) extends Data
val data: Data = getData()
data match {
  case UserData(name) => // use name
}

// DON'T: Nested if-else chains
if (x == 1) ... else if (x == 2) ... else if (x == 3) ...

// DO: Pattern matching
x match {
  case 1 => ...
  case 2 => ...
  case 3 => ...
}

// DON'T: var with mutation
var total = 0
for (x <- items) total += x

// DO: fold
val total = items.sum
// or
val total = items.foldLeft(0)(_ + _)
```

© benchflow-ai · Apache-2.0 · benchflow-ai/skillsbench

Similar skills

All skills for Programming languages →

From the same set22

The whole set →
text-to-speech The text-to-speech skill guides TTS cleanup, loudness matching, and segment timing for video audio exports. CX Codex +1 4installs civ6lib civ6lib validates Civilization 6 district placement and computes adjacency bonuses. Use it when an agent needs to reason about city layouts and game rules. CX Codex +1 2installs meteorology-driver-classification meteorology-driver-classification sorts the columns of an environmental dataset into heat, flow, wind and human drivers, so an attribution run can treat each group as one factor. CX Codex +1 2installs scipy-curve-fit scipy-curve-fit guides coding agents to estimate nonlinear model parameters from experimental data with scipy.optimize.curve_fit. CX Codex +1 2installs first-order-model-fitting The first-order-model-fitting skill fits first-order models to experimental step responses and returns K and tau. Use it when you need a compact model of thermal, electrical, or mechanical behavior. CX Codex +1 1installs hex-grid-spatial hex-grid-spatial is a Claude Code skill that calculates neighbours, hex distance, and radius cells on odd-r offset maps for movement or area-of-effect logic. CX Codex +1 1installs python-scala-syntax-mapping python-scala-syntax-mapping is a Claude Code skill that maps Python syntax to Scala for coding assistants translating variables, comprehensions, and control structures. CX Codex +1 1installs image-ocr Use this skill to read text in images with Tesseract OCR through Python. It fits scans, screenshots, and batches of image files. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open