Local Python-only LeetCode Hot 100 CLI simulator.

lc-simulator is a local command line practice tool for the LeetCode Hot 100. It ships 100 problem definitions as JSON, generates Python solution stubs, runs examples against your code, and tracks completed problems on your machine.

The project uses only the Python standard library at runtime. Your solutions stay in workspace/, while progress is stored in .data/progress.json.

• Practice the LeetCode Hot 100 locally from the terminal.
• Browse all 100 bundled problem JSON files.
• Filter problem lists by difficulty or category.
• Show a single problem by ID or all problems in one category.
• Generate Python solution stubs in workspace/.
• Run all examples for a problem or only one case with --case N.
• Mark problems as done and view completion stats.
• Switch command output between English and Chinese with --lang en|zh.
• Use pure Python runtime code with no external runtime dependencies.
• Keep user work and runtime progress out of source problem definitions.

• Python 3.9 or newer
• pip, recommended for editable installation
• pytest, only needed when running the test suite

git clone <repo-url>
cd lc_simulator
python -m pip install -e .

The install registers the lc command from lc.cli:main.

If you don't want to install the package, you can run the CLI as a module instead:

python -m lc list

lc list

Filter by category or difficulty:

lc list --category array
lc list --difficulty easy
lc list --category dp --lang zh

lc show 1

Show all problems in a category:

lc show --category sliding_window
lc show --category binary_tree --lang zh

lc new 1

This creates a Python stub in workspace/ for the selected problem. If the file already exists, the CLI leaves it in place and reports that it already exists.

lc test 1

Run only one test case, using a 1-based case number:

lc test 1 --case 1

lc done 1

This records completion in .data/progress.json.

lc stats
lc stats --lang zh

Common flags:

lc_simulator/
├── lc/                    # Core library, 9 modules
│   ├── cli.py             # CLI entry and command handlers
│   ├── problems.py        # Problem loading, lookup, and solution filenames
│   ├── runner.py          # Dynamic import and test execution
│   ├── progress.py        # JSON-based completion tracking
│   ├── templates.py       # Solution stub generation
│   ├── paths.py           # Path constants for problems, workspace, and data
│   ├── i18n.py            # Translations and category names
│   ├── __init__.py        # Package version
│   └── __main__.py        # python -m lc support
├── problems/              # 100 LeetCode Hot 100 JSON files
├── workspace/             # User solution .py files, gitignored
├── tests/                 # pytest test suite
├── scripts/               # Content fetch and validation helpers
├── cache/                 # API response cache
├── .data/                 # Runtime data, including progress.json
└── pyproject.toml         # Project metadata and lc entry point

problems/*.json
      |
      v
lc/problems.py
      |
      v
lc/cli.py + lc/runner.py + lc/progress.py
      |
      +--------------------+--------------------+
      |                    |                    |
      v                    v                    v
terminal output       workspace/*.py       .data/progress.json

Each problem is a JSON document with metadata, bilingual titles and descriptions, categories, a Python function signature, examples, constraints, and the source URL.

{
  "id": 1,
  "slug": "two-sum",
  "title_en": "Two Sum",
  "title_zh": "两数之和",
  "difficulty": "easy",
  "categories": ["array", "hash"],
  "function": {
    "name": "twoSum",
    "params": [["nums", "List[int]"], ["target", "int"]],
    "return": "List[int]"
  },
  "examples": [
    {
      "input": {"nums": [2, 7, 11, 15], "target": 9},
      "output": [0, 1]
    }
  ],
  "description_en": "...",
  "description_zh": "...",
  "constraints": "...",
  "leetcode_examples": [],
  "url": "https://leetcode.com/problems/two-sum/"
}

Runtime use of the CLI needs no external dependencies. The test suite uses pytest.

Install test tooling if needed:

python -m pip install pytest

Run all tests:

python -m pytest

Run tests for one area:

python -m pytest tests/test_cli.py
python -m pytest tests/test_runner.py
python -m pytest tests/test_fetch.py

You can also test the installed CLI directly:

lc list
lc new 1
lc test 1 --case 1
lc done 1
lc stats

Future features that would fit the project:

• Add more LeetCode tags beyond the current 17 categories.
• Add lc random to pick a problem by category, difficulty, or unfinished status.
• Add lc review for spaced repetition of completed or failed problems.
• Add lc hint to show a small clue without revealing the full solution.
• Track time spent per problem and across sessions.
• Export progress to JSON, CSV, or Markdown.
• Add multi-language templates for solution stubs.
• Add an interactive mode for browsing, creating, testing, and marking problems.
• Add a daily challenge command that selects one problem per day.

License: Not specified in this repository.