Add ruff (lint+format) and pyright (type check) tooling

- Add ruff and pyright as dev dependencies in pyproject.toml
- Configure ruff: target py310, line-length 120, select E/F/I/UP, ignore E501
- Configure ruff format: skip-magic-trailing-comma (match project style)
- Configure pyright: pythonVersion 3.10, exclude gui_streamlit
- Auto-fix lint issues (import sorting, Optional->union syntax, f-string cleanup)
- Fix all pyright type errors across the codebase
- Document code quality checks in README Development Guide
- Exclude uv.lock from version control

Author: MaleicAcid

.gitignore

@@ -6,3 +6,4 @@ run.py
 /dist/
 /openfaker.egg-info/
 __pycache__/
+uv.lock

README.md

@@ -306,6 +306,23 @@ uv venv
 uv sync
 ```
 
+### Code quality checks
+
+Before committing, please make sure the following checks pass locally:
+
+```shell
+# Lint
+uv run ruff check openlrc/ tests/
+
+# Format
+uv run ruff format --check openlrc/ tests/
+# To auto-fix formatting:
+# uv run ruff format openlrc/ tests/
+
+# Type check
+uv run pyright openlrc/
+```
+
 For live translation testing as a developer (and for CI usage), set:
 
 ```shell

openlrc/__init__.py

@@ -1,10 +1,9 @@
 #  Copyright (C) 2024. Hao Zheng
 #  All rights reserved.
 
-from openlrc.models import list_chatbot_models, ModelConfig, ModelProvider
+from openlrc.models import ModelConfig, ModelProvider, list_chatbot_models
 from openlrc.openlrc import LRCer, TranscriptionConfig, TranslationConfig
 
-__all__ = ('LRCer', 'TranscriptionConfig', 'TranslationConfig',
-           'ModelConfig', 'list_chatbot_models', 'ModelProvider')
-__version__ = '1.5.2'
-__author__ = 'zh-plus'
+__all__ = ("LRCer", "TranscriptionConfig", "TranslationConfig", "ModelConfig", "list_chatbot_models", "ModelProvider")
+__version__ = "1.5.2"
+__author__ = "zh-plus"

openlrc/agents.py

@@ -1,19 +1,18 @@
 #  Copyright (C) 2025. Hao Zheng
 #  All rights reserved.
 import re
-from typing import Optional, Union, List
 
 from pydantic import BaseModel
 
 from openlrc import ModelConfig
 
 
 class TranslationContext(BaseModel):
-    previous_summaries: Optional[List[str]] = None
-    summary: Optional[str] = ''
-    scene: Optional[str] = ''
-    model: Optional[Union[str, ModelConfig]] = None
-    guideline: Optional[str] = None
+    previous_summaries: list[str] | None = None
+    summary: str | None = ""
+    scene: str | None = ""
+    model: str | ModelConfig | None = None
+    guideline: str | None = None
 
     def update(self, **args):
         for key, value in args.items():
@@ -22,12 +21,14 @@ def update(self, **args):
 
     @property
     def non_glossary_guideline(self) -> str:
-        cleaned_text = re.sub(r'### Glossary.*?### Characters', '### Characters', self.guideline, flags=re.DOTALL)
+        if not self.guideline:
+            return ""
+        cleaned_text = re.sub(r"### Glossary.*?### Characters", "### Characters", self.guideline, flags=re.DOTALL)
         return cleaned_text
 
 
 class TranslateInfo(BaseModel):
-    title: Optional[str] = ''
-    audio_type: str = 'Movie'
-    glossary: Optional[dict] = None
+    title: str | None = ""
+    audio_type: str = "Movie"
+    glossary: dict | None = None
     forced_glossary: bool = False

openlrc/chatbot.py

@@ -12,27 +12,23 @@
     "repetition_penalty": 1.0,
     "no_repeat_ngram_size": 0,
     "temperature": 0.0,
-
     # We assume the voice is valid after VAD, log_prob_threshold is not reliable, set these 3 to None to prevent
     # miss-transcription, see https://github.com/openai/whisper/discussions/29#discussioncomment-3726710 for details
     "compression_ratio_threshold": None,
     "log_prob_threshold": None,
     "no_speech_threshold": None,
     "condition_on_previous_text": True,
-
     "initial_prompt": None,
     "prefix": None,
     "suppress_blank": True,
     "suppress_tokens": [-1],
     "without_timestamps": False,
-
     "word_timestamps": True,
     "prepend_punctuations": "\"'“¿([{-",
     "append_punctuations": "\"'.。,，!！?？:：”)]}、",
     # "hallucination_silence_threshold": 2,
     "hotwords": None,
-
-    "chunk_length": None
+    "chunk_length": None,
 }
 
 # Check https://github.com/SYSTRAN/faster-whisper/blob/master/faster_whisper/transcribe.py#L123 for details
@@ -42,22 +38,62 @@
     "min_speech_duration_ms": 0,
     "max_speech_duration_s": float("inf"),
     "min_silence_duration_ms": 2000,
-    "speech_pad_ms": 400
+    "speech_pad_ms": 400,
 }
 
-default_preprocess_options = {
-    'atten_lim_db': 15
-}
+default_preprocess_options = {"atten_lim_db": 15}
 
 # Currently bottleneck-ed by Spacy
 supported_languages = {
-    'ca', 'zh', 'hr', 'da', 'nl', 'en', 'fi', 'fr', 'de', 'el', 'it', 'ja', 'ko', 'lt', 'mk', 'nb', 'pl', 'pt', 'ro',
-    'ru', 'sl', 'es', 'sv', 'uk'
+    "ca",
+    "zh",
+    "hr",
+    "da",
+    "nl",
+    "en",
+    "fi",
+    "fr",
+    "de",
+    "el",
+    "it",
+    "ja",
+    "ko",
+    "lt",
+    "mk",
+    "nb",
+    "pl",
+    "pt",
+    "ro",
+    "ru",
+    "sl",
+    "es",
+    "sv",
+    "uk",
 }
 
 supported_languages_lingua = {
-    Language.CATALAN, Language.CHINESE, Language.CROATIAN, Language.DANISH, Language.DUTCH, Language.ENGLISH,
-    Language.FINNISH, Language.FRENCH, Language.GERMAN, Language.GREEK, Language.ITALIAN, Language.JAPANESE,
-    Language.KOREAN, Language.LITHUANIAN, Language.MACEDONIAN, Language.BOKMAL, Language.POLISH, Language.PORTUGUESE,
-    Language.ROMANIAN, Language.RUSSIAN, Language.SLOVENE, Language.SPANISH, Language.SWEDISH, Language.UKRAINIAN
+    Language.CATALAN,
+    Language.CHINESE,
+    Language.CROATIAN,
+    Language.DANISH,
+    Language.DUTCH,
+    Language.ENGLISH,
+    Language.FINNISH,
+    Language.FRENCH,
+    Language.GERMAN,
+    Language.GREEK,
+    Language.ITALIAN,
+    Language.JAPANESE,
+    Language.KOREAN,
+    Language.LITHUANIAN,
+    Language.MACEDONIAN,
+    Language.BOKMAL,
+    Language.POLISH,
+    Language.PORTUGUESE,
+    Language.ROMANIAN,
+    Language.RUSSIAN,
+    Language.SLOVENE,
+    Language.SPANISH,
+    Language.SWEDISH,
+    Language.UKRAINIAN,
 }

openlrc/context.py

@@ -1,7 +1,6 @@
 #  Copyright (C) 2025. Hao Zheng
 #  All rights reserved.
 import abc
-from typing import Union
 
 from openlrc.agents import TranslationEvaluatorAgent
 from openlrc.models import ModelConfig
@@ -26,7 +25,7 @@ class LLMTranslationEvaluator(TranslationEvaluator):
     Evaluate the translated texts using large language models.
     """
 
-    def __init__(self, chatbot_model: Union[str, ModelConfig] = 'gpt-4.1-nano'):
+    def __init__(self, chatbot_model: str | ModelConfig = "gpt-4.1-nano"):
         self.agenet = TranslationEvaluatorAgent(chatbot_model=chatbot_model)
 
     def evaluate(self, src_texts, target_texts, src_lang=None, target_lang=None):

openlrc/defaults.py

@@ -1,6 +1,5 @@
 #  Copyright (C) 2024. Hao Zheng
 #  All rights reserved.
-from typing import Union
 
 from anthropic.types import Message
 from openai.types.chat import ChatCompletion
@@ -13,8 +12,8 @@ class SameLanguageException(Exception):
 
     def __init__(self):
         super().__init__(
-            'Source language and target language are the same, no need to translate. '
-            'If you want to translate, set force_translate=True.'
+            "Source language and target language are the same, no need to translate. "
+            "If you want to translate, set force_translate=True."
         )
 
 
@@ -32,8 +31,9 @@ class LengthExceedException(ChatBotException):
     Raised when the length of generated response exceeds the limit.
     """
 
-    def __init__(self, response: Union[ChatCompletion, Message]):
+    def __init__(self, response: ChatCompletion | Message):
         if isinstance(response, ChatCompletion):
+            assert response.usage is not None, "ChatCompletion.usage is None"
             prompt_tokens = response.usage.prompt_tokens
             completion_tokens = response.usage.completion_tokens
             total_tokens = response.usage.total_tokens
@@ -42,14 +42,14 @@ def __init__(self, response: Union[ChatCompletion, Message]):
             completion_tokens = response.usage.output_tokens
             total_tokens = prompt_tokens + completion_tokens
         else:
-            raise ValueError(f'Invalid response type: {type(response)}')
+            raise ValueError(f"Invalid response type: {type(response)}")
 
         super().__init__(
-            f'Failed to get completion. Exceed max token length. '
-            f'Prompt tokens: {prompt_tokens}, '
-            f'Completion tokens: {completion_tokens}, '
-            f'Total tokens: {total_tokens} '
-            f'Reduce chunk_size may help.'
+            f"Failed to get completion. Exceed max token length. "
+            f"Prompt tokens: {prompt_tokens}, "
+            f"Completion tokens: {completion_tokens}, "
+            f"Total tokens: {total_tokens} "
+            f"Reduce chunk_size may help."
         )
 
 
@@ -59,7 +59,7 @@ class OpenaiFailureException(Exception):
     """
 
     def __init__(self):
-        super().__init__('OpenAI API failed to generate response.')
+        super().__init__("OpenAI API failed to generate response.")
 
 
 class FfmpegException(Exception):
@@ -74,4 +74,4 @@ def __init__(self, message):
 
 class DependencyException(Exception):
     def __init__(self, message):
-        super().__init__(f'Dependency not correctly installed: {message}')
+        super().__init__(f"Dependency not correctly installed: {message}")