laoshi 0.6.4
CLI application for learning Chinese.
Requires Python: <4.0,>=3.10

# laoshi (老師)

CLI application for learning Chinese. I wanted to have an interactive
experience while I use the terminal, so I made this app.

## Installation

```commandline
pipx install laoshi
```

If you want to manage your AnkiDecks with laoshi, you'll need:
- [Anki](https://apps.ankiweb.net/)
- [AnkiConnect](https://git.foosoft.net/alex/anki-connect)

This allows us to make HTTP calls to your Anki application, you're
going to need to have Anki open.

## Usage

```commandline
  cli application to learn chinese.

Options:
  --help  Show this message and exit.

Commands:
  cc           Convert characters
  manage-deck  Manage deck group
  translate    Translate a phrase 
```

You're able to convert characters, manage an Anki deck or translate a phrase.

```commandline
Usage: laoshi cc [OPTIONS] WORD

  Convert characters

Options:
  -t, --to [traditional|simplified|pinyin]

```

The manage-deck subcommand allows you to create a deck from one seed word or phrase using `create-deck`,
you can also add notes with `add-note`:

```commandline
Usage: laoshi manage-deck [OPTIONS] COMMAND [ARGS]...

  Manage deck group

Options:
  --help  Show this message and exit.

Commands:
  add-note     add note function for click
  create-deck  Create a deck function for click
```

Lastly you can translate phrases or words with `translate`, by default we use english, but you can change that:

```
Usage: laoshi translate [OPTIONS] PHRASE

  Translate a phrase

Options:
  -t, --to TEXT
  --help         Show this message and exit.
```

Examples:
```commandline
➜  ~ laoshi translate 服饰  
apparel
```

```commandline
➜  ~ laoshi cc -t pinyin 服饰
fúshì
```

```commandline
➜  ~ python -m laoshi.main manage-deck add-note -c simplified hsk5+ 涉及 # You have to create the AnkiDeck first.
```

### Batch Import from JSON

You can import multiple flashcards at once using a JSON file.

```commandline
laoshi manage-deck add-notes-from-json <deck_name> <path_to_json_file>
```

The JSON file should look like this:

```json
[
  {
    "id": 1,
    "traditional_chinese": "你好",
    "pinyin": "nǐ hǎo",
    "part_of_speech": "phrase",
    "english_definition": "Hello",
    "example_sentences": [
      "你好吗？",
      "你好！"
    ]
  }
]
```

## Local Development

To set up the project locally for development:

1.  Clone the repository:
    ```bash
    git clone https://gitlab.com/rbnjs/laoshi.git
    cd laoshi
    ```

2.  Install dependencies using `uv` (recommended) or `pip`:
    ```bash
    # using uv
    uv sync
    
    # or using pip
    pip install .
    pip install -r requirements-dev.txt # if available, or just install dev deps manually
    ```

3.  Run the application locally:
    ```bash
    # using uv
    uv run python -m laoshi.main --help
    
    # using standard python (after activating venv)
    python -m laoshi.main --help
    ```

## Deployment

Deployment to PyPI is automated via GitLab CI/CD.

To trigger a deployment:

1.  Update the `version` in `pyproject.toml`.
2.  Push the changes to the `master` branch.
3.  The CI pipeline will automatically build and publish the package to PyPI using `uv`.

Ensure you have the necessary PyPI credentials configured in the GitLab CI/CD variables.