laoshi 0.6.4

CLI application for learning Chinese.

laoshi (老師)

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

Installation

pipx install laoshi

If you want to manage your AnkiDecks with laoshi, you'll need:

• Anki
• AnkiConnect

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

Usage

  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.

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:

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:

➜  ~ laoshi translate 服饰  
apparel

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

➜  ~ 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.

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

The JSON file should look like this:

[
  {
    "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:

   git clone https://gitlab.com/rbnjs/laoshi.git
   cd laoshi
   

2. Install dependencies using uv (recommended) or pip:

   # 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:

   # 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.