> ## Documentation Index
> Fetch the complete documentation index at: https://leetcode-py.wisl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> leetcode-py is a Python LeetCode practice environment generator with one CLI: lcpy. It is not a service or platform.
> Each problem is a directory under leetcode/ with README.md, solution.py, test_solution.py, helpers.py, and playground.ipynb. lcpy gen creates them from JSON templates bundled with the package.
> Examples are backed by tests; copy them verbatim.

# Anatomy of a problem

> What lcpy gen creates, what each file is for, and which one you own.

Every generated problem is the same six files. Learn the shape once and every
problem in the catalog feels like home.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lcpy gen -n 1
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
leetcode/two_sum/
├── README.md           # problem statement, difficulty, topics, tags
├── solution.py         # your code; the only file you edit
├── test_solution.py    # 10+ parametrized cases, ready to run
├── helpers.py          # run_/assert_ pair for readable test output
├── playground.py       # percent-format scratchpad notebook
└── __init__.py
```

## README.md

The problem statement: difficulty, topics, collection tags, a link to the
original LeetCode problem, the description, and worked examples. Everything
you need to solve without leaving the terminal.

<img src="https://mintcdn.com/leetcode-py/VCrzlUI648LnF7Pk/images/readme-example.png?fit=max&auto=format&n=VCrzlUI648LnF7Pk&q=85&s=aea118af4404d48c697ecf51d7dc41d6" alt="Generated README for Two Sum" width="957" height="819" data-path="images/readme-example.png" />

## solution.py: the only file you edit

Generated with a class skeleton, the method signature with type hints, and a
`TODO` where your implementation goes. Solved examples in this repo also
carry `Time`/`Space` complexity comments at the top of the method, the
house convention.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class Solution:
    # Time: O(n)
    # Space: O(n)
    def two_sum(self, nums: list[int], target: int) -> list[int]:
        ...
```

<img src="https://mintcdn.com/leetcode-py/VCrzlUI648LnF7Pk/images/solution-boilerplate.png?fit=max&auto=format&n=VCrzlUI648LnF7Pk&q=85&s=a1cac7874c2ad7e96fff0ce22cef7d50" alt="Generated solution.py stub with TODO placeholder" width="889" height="207" data-path="images/solution-boilerplate.png" />

## test\_solution.py

A parametrized pytest suite with 10+ cases per problem, edge cases included.
It runs red the moment you generate the problem and stays the contract: make
red go green, never edit the tests. See [Testing](/practice/testing).

## helpers.py

Two functions per problem: `run_<name>` instantiates your solution class and
calls the method; `assert_<name>` compares result to expected, normalized
so order-insensitive answers compare cleanly. Failures print the inputs and
expected output instead of a raw object dump.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def run_two_sum(solution_class: type, nums: list[int], target: int):
    implementation = solution_class()
    return implementation.two_sum(nums, target)


def assert_two_sum(result: list[int], expected: list[int]) -> bool:
    assert sorted(result) == sorted(expected)
    return True
```

## playground.py

A scratchpad in jupytext percent format: plain Python in git, a notebook
when you want one. See [Notebooks](/practice/notebooks).

## Generated, not hand-rolled

Every problem directory comes from a JSON template, so files arrive
byte-identical on every machine and CI verifies they regenerate exactly.
If something looks off, regenerate the problem with `bake p-gen` rather
than editing generated files by hand.