psw 0.1.4__py3-none-any.whl

psw/__init__.py

@@ -0,0 +1,10 @@
+# パッケージ外から直接 Stopwatch や Timer をインポートできるように公開します。
+# 例: from psw import Stopwatch, Timer
+from psw.stopwatch import Stopwatch
+from psw.timer import Timer
+
+# パッケージのバージョン（pyproject.toml と合わせておくと管理しやすいです）
+__version__ = "0.1.4"
+
+# `from psw import *` をした際にインポートされるクラスを指定
+__all__ = ["Stopwatch", "Timer"]

psw/__main__.py

@@ -0,0 +1,7 @@
+from psw.cli import main
+
+# This file enables the command `python -m psw` to run the CLI of the `psw` package.
+
+if __name__ == "__main__":
+    # simple structure to call the main() function of cli.py
+    main()

psw/cli.py

@@ -0,0 +1,96 @@
+import argparse
+import sys
+
+
+def main():
+    # 親パーサーの設定（プログラム全体のヘルプや基本情報を定義）
+    parser = argparse.ArgumentParser(
+        description="PSW - Python Stop Watch & Timer CLI tool",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    
+    # サブコマンド（start / timer）を管理するパーサーを追加
+    subparsers = parser.add_subparsers(
+        dest="command", 
+        required=True, 
+        help="Subcommands"
+    )
+
+    # ---------------------------------------------------------
+    # 1. 'start' (Stopwatch) サブコマンドの設定
+    # ---------------------------------------------------------
+    parser_start = subparsers.add_parser(
+        "start", 
+        help="Start the stopwatch"
+    )
+    parser_start.add_argument(
+        "-p", "--precision",
+        type=int,
+        default=3,
+        help="Decimal places for seconds (default: 3)"
+    )
+
+    # ---------------------------------------------------------
+    # 2. 'timer' サブコマンドの設定
+    # ---------------------------------------------------------
+    parser_timer = subparsers.add_parser(
+        "timer", 
+        help="Start the countdown timer"
+    )
+    # 時間指定（例: 5m, 30s, 1h 30m など可変長の引数を受け取る）
+    parser_timer.add_argument(
+        "duration",
+        nargs="+",
+        help="Duration for the timer (e.g., '5m 30s', '1h', '45s')"
+    )
+    parser_timer.add_argument(
+        "-p", "--precision",
+        type=int,
+        default=3,
+        help="Decimal places for seconds (default: 3)"
+    )
+    parser_timer.add_argument(
+        "-r", "--repeat",
+        nargs="?",      # optional
+        const=-1,       # -1 when only `-r` is used without scceeding number
+        default=1,
+        type=int,       # Recognize value as Integer when specified
+        help="Repeat the timer. Use '-r' for infinite loop, or '-r N' to repeat N times."
+    )
+    parser_timer.add_argument(
+        "-m", "--mute",
+        action="store_true",
+        help="Mute the terminal bell (\a) alert sound when the timer ends"
+    )
+
+    args = parser.parse_args()
+
+    # 各コマンドに応じた処理の分岐
+    if args.command == "start":
+        try:
+            from psw.stopwatch import Stopwatch
+            # ストップウォッチの初期化と実行
+            sw = Stopwatch(precision=args.precision)
+            sw.run()
+        except ImportError:
+            print("[Error] 'stopwatch.py' is not implemented yet.", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.command == "timer":
+        try:
+            from psw.timer import Timer
+            # タイマーの初期化と実行
+            timer = Timer(
+                duration_strings=args.duration,
+                precision=args.precision,
+                repeat=args.repeat,
+                mute=args.mute
+            )
+            timer.run()
+        except ImportError:
+            print("[Error] 'timer.py' is not implemented yet.", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

psw/stopwatch.py

@@ -0,0 +1,91 @@
+import time
+import sys
+from psw.utils import KeyListener
+
+
+class Stopwatch:
+    def __init__(self, precision: int = 3):
+        if precision < 0:
+            raise ValueError("precision must be >= 0")
+        self.precision = precision
+        self.listener = KeyListener()
+        
+        self.start_time = 0.0
+        self.elapsed_time = 0.0
+        self.running = False
+        self.laps = []
+
+    def format_time(self, seconds: float) -> str:
+        """秒数を '00 h 00 m 00.000 s' のフォーマットに整形する"""
+        h = int(seconds // 3600)
+        m = int((seconds % 3600) // 60)
+        s = seconds % 60
+        
+        # 指定された精度（小数点以下）で秒数をフォーマット
+        seconds_str = f"{s:02.{self.precision}f}"
+        # 万が一秒が繰り上がって60.00...になった場合の簡易補正
+        if float(seconds_str) >= 60.0:
+            seconds_str = f"{0.0:02.{self.precision}f}"
+            m += 1
+            if m >= 60:
+                m = 0
+                h += 1
+
+        return f"{h:02d} h {m:02d} m {seconds_str} s"
+
+    def run(self):
+        self.start_time = time.monotonic()
+        self.running = True
+        
+        print("Stopwatch started. Press 's' to pause/resume, 'l' to record lap, 'q' to quit.\n")
+        # 1行分のスペースをあける（リアルタイム描画用）
+        print() 
+
+        try:
+            while True:
+                if self.running:
+                    self.elapsed_time = time.monotonic() - self.start_time
+                
+                # カーソルを上に戻して、現在の時間を描画
+                # \033[F moves cursor to the previous line,
+                # \033[K clear the text to the end of the line.
+                sys.stdout.write(f"\033[F\033[K{self.format_time(self.elapsed_time)}\n")
+                sys.stdout.flush()
+
+                # check key input
+                char = self.listener.get_char()
+                if char == 'q':
+                    break
+                elif char == 's':
+                    if self.running:
+                        # stop
+                        self.elapsed_time = time.monotonic() - self.start_time
+                        self.running = False
+                    else:
+                        # resume
+                        self.start_time = time.monotonic() - self.elapsed_time
+                        self.running = True
+                elif char == 'l':
+                    if self.running:
+                        lap_num = len(self.laps) + 1
+                        lap_str = f"  Lap #{lap_num:02d}: {self.format_time(self.elapsed_time)}"
+                        self.laps.append(lap_str)
+                        # 一旦現在の時間表示の下にラップを挿入するために、描画位置を調整
+                        print(lap_str)
+                        print() # 次の時間描画のための空行
+
+                # CPU負荷を下げるためのウェイト（ミリ秒精度に合わせて調整）
+                # 精度が高い場合は更新頻度を上げ、低い場合は下げる
+                sleep_time = 0.01 if self.precision > 2 else 0.05
+                time.sleep(sleep_time)
+
+        finally:
+            self.listener.close()
+            
+        # 終了時のまとめ表示
+        print(f"\n--- Finished ---")
+        print(f"Total Time: {self.format_time(self.elapsed_time)}")
+        if self.laps:
+            print("Laps:")
+            for lap in self.laps:
+                print(lap)

psw/timer.py

@@ -0,0 +1,197 @@
+import time
+import sys
+import re
+import os
+from psw.utils import KeyListener
+
+is_windows = os.name == "nt" or sys.platform.startswith("win")
+if is_windows:
+    import winsound
+
+class Timer:
+    def __init__(
+        self,
+        duration_strings: list,
+        precision: int = 3,
+        repeat: int = 1,
+        mute: bool = False,
+    ):
+        if precision < 0:
+            raise ValueError("precision must be >= 0")
+        self.duration_strings = duration_strings
+        self.precision = precision
+        self.repeat = repeat
+        self.mute = mute
+
+        self.listener = KeyListener()
+        
+        # 入力された文字列（['5m', '30s'] など）から合計秒数を算出
+        self.total_seconds = self.parse_duration(duration_strings)
+        self.remaining_time = self.total_seconds
+        
+        self.running = False
+        self.start_time = 0.0
+
+    def parse_duration(self, duration_strings: list) -> float:
+        """
+        ['1h', '30m', '45s'] のような入力リストを解析し、合計秒数を返す。
+        単位が指定されていない単なる数値は「秒」として扱う。
+        """
+        total = 0.0
+        # 時間パース用の正規表現 (例: "5.5m", "10s", "1h")
+        pattern = re.compile(r"^([\d.]+)([hms]?)$")
+
+        for s in duration_strings:
+            s = s.strip().lower()
+            match = pattern.match(s)
+            if not match:
+                print(f"[Warning] Could not parse duration part: '{s}'. Ignored.", file=sys.stderr)
+                continue
+            
+            value_str, unit = match.groups()
+            try:
+                value = float(value_str)
+            except ValueError:
+                continue
+
+            if unit == "h":
+                total += value * 3600
+            elif unit == "m":
+                total += value * 60
+            elif unit == "s" or unit == "":
+                total += value
+
+        if total <= 0:
+            print("[Error] Total duration must be greater than 0.", file=sys.stderr)
+            sys.exit(1)
+
+        return total
+
+    def format_time(self, seconds: float) -> str:
+        """秒数を '00 h 00 m 00.000 s' のフォーマットに整形する"""
+        if seconds < 0:
+            seconds = 0.0
+            
+        h = int(seconds // 3600)
+        m = int((seconds % 3600) // 60)
+        s = seconds % 60
+        
+        seconds_str = f"{s:02.{self.precision}f}"
+        if float(seconds_str) >= 60.0:
+            seconds_str = f"{0.0:02.{self.precision}f}"
+            m += 1
+            if m >= 60:
+                m = 0
+                h += 1
+
+        return f"{h:02d} h {m:02d} m {seconds_str} s"
+
+    def run_single_timer(self, cycle_num: int = None) -> bool:
+        """
+        1回分のタイマーカウントダウンを実行する。
+        戻り値: True (完走した), False (ユーザーが 'q' で中断した)
+        """
+        self.remaining_time = self.total_seconds
+        self.start_time = time.monotonic()
+        self.running = True
+
+        # 進捗タイトルの表示
+        if cycle_num is not None:
+            print(f"--- Timer Cycle #{cycle_num} ---")
+        else:
+            print("--- Timer Started ---")
+        print("Press 's' to pause/resume, 'q' to quit.\n\n")
+
+        try:
+            while self.remaining_time > 0:
+                if self.running:
+                    # 経過時間を引き、残りの時間を計算
+                    elapsed = time.monotonic() - self.start_time
+                    self.remaining_time = self.total_seconds - elapsed
+                    if self.remaining_time < 0:
+                        self.remaining_time = 0.0
+
+                # カーソルを上に戻して、現在の時間を描画
+                sys.stdout.write(f"\033[F\033[K{self.format_time(self.remaining_time)}\n")
+                sys.stdout.flush()
+
+                if self.remaining_time <= 0:
+                    break
+
+                # キー入力チェック
+                char = self.listener.get_char()
+                if char == 'q':
+                    return False
+                elif char == 's':
+                    if self.running:
+                        # 一時停止
+                        self.running = False
+                    else:
+                        # 再開
+                        elapsed = self.total_seconds - self.remaining_time
+                        self.start_time = time.monotonic() - elapsed
+                        self.running = True
+
+                sleep_time = 0.01 if self.precision > 2 else 0.05
+                time.sleep(sleep_time)
+
+            # タイムアップ時、00:00:00.000を表示させる
+            sys.stdout.write(f"\033[F\033[K{self.format_time(0.0)}\n")
+            sys.stdout.flush()
+            
+            # ビープ音の鳴動
+            if not self.mute:
+                if is_windows:
+                    try:
+                        # winsound.MessageBeep() は Windows標準のアラート音を鳴らします
+                        # (winsound.Beep(1000, 500) で特定の周波数を鳴らすことも可能です)
+                        winsound.MessageBeep()
+                    except Exception:
+                        sys.stdout.write("\a")
+                        sys.stdout.flush()
+                else:
+                    # mac or linux
+                    sys.stdout.write("\a")
+                    sys.stdout.flush()
+                
+            print("\nTime's up!")
+            return True
+
+        finally:
+            # 1回分の表示領域をクリアして改行を整える
+            print()
+
+    def run(self):
+        print("run")
+        try:
+            # 1. 回数指定リピートがある場合
+            if self.repeat > 0:
+                for i in range(1, self.repeat + 1):
+                    completed = self.run_single_timer(cycle_num=i)
+                    if not completed:
+                        print("Timer canceled by user.")
+                        break
+                    # ループ間に少しウェイトを挟む（即座に次が始まって画面が崩れるのを防ぐ）
+                    if i < self.repeat:
+                        time.sleep(1)
+            
+            # 2. 無限リピート（-r）の場合
+            elif self.repeat == -1:
+                cycle = 1
+                while True:
+                    completed = self.run_single_timer(cycle_num=cycle)
+                    if not completed:
+                        print("Timer canceled by user.")
+                        break
+                    cycle += 1
+                    time.sleep(1)
+
+            # 3. 通常の1回切りタイマーの場合
+            else:
+                print("Invalid repeat count. It must be greater than 0, or -1 for infinite.")
+                # completed = self.run_single_timer()
+                # if not completed:
+                #     print("Timer canceled by user.")
+
+        finally:
+            self.listener.close()

psw/utils.py

@@ -0,0 +1,50 @@
+import sys
+
+# OS判定
+is_windows = sys.platform.startswith("win")
+
+if is_windows:
+    import msvcrt
+else:
+    import select
+    import tty
+    import termios
+
+
+class KeyListener:
+    """ノンブロッキングでキー入力を監視するクラス"""
+
+    def __init__(self):
+        self.old_settings = None
+        if not is_windows and sys.stdin.isatty():
+            # ターミナルの標準入力設定を保存
+            self.old_settings = termios.tcgetattr(sys.stdin)
+
+    def get_char(self) -> str:
+        """押されたキーを1文字取得する（押されていなければ空文字を返す）"""
+        if is_windows:
+            if msvcrt.kbhit():
+                # Windowsのキー取得
+                try:
+                    char = msvcrt.getch().decode("utf-8").lower()
+                    return char
+                except UnicodeDecodeError:
+                    return ""
+            return ""
+        else:
+            # macOS/Linuxのキー取得（cbreakモードに一時的に切り替える）
+            try:
+                tty.setcbreak(sys.stdin.fileno())
+                # 読み込み可能か確認（タイムアウト0秒）
+                dr, _, _ = select.select([sys.stdin], [], [], 0)
+                if dr:
+                    return sys.stdin.read(1).lower()
+                return ""
+            finally:
+                # ターミナル設定を元に戻す
+                termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self.old_settings)
+
+    def close(self):
+        """終了処理（ターミナルの設定を完全に復元）"""
+        if not is_windows and self.old_settings:
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self.old_settings)

psw-0.1.4.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: psw
+Version: 0.1.4
+Summary: A lightweight CLI stopwatch and timer in Python
+License-File: LICENSE
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# PSW - Python Stop Watch
+
+`psw` is a lightweight, intuitive Command Line Interface (CLI) stopwatch and timer utility written in Python. It features live console rendering, interactive real-time controls, and built-in repeat functionalities without requiring any complex external audio dependencies.
+
+## Install
+
+You can install `psw` via pip:
+
+```bash
+pip install psw
+```
+
+## Usage
+
+### 1. Stopwatch Mode
+
+Measure elapsed time directly in your terminal.
+
+#### Start the Stopwatch
+
+To start the stopwatch, run:
+
+```bash
+psw start
+```
+
+The live clock will be displayed in the console:
+
+```text
+00 h 00 m 00.000 s
+```
+
+#### Options
+
+* **`-p, --precision`**: Specifies the number of decimal places for seconds.
+* **Default**: `3` (millisecond precision)
+* **Example**: `psw start -p 2` will display `00 h 00 m 00.00 s`
+
+#### Interactive Controls (While Running)
+
+While the stopwatch is active, you can control it in real-time using the following keys:
+
+* **`s`**: Pause / Resume the stopwatch.
+* **`l`**: Record a lap time. The current lap time will be printed below the running clock without stopping the main timer.
+* **`q` (or `Ctrl+C`)**: Quit the stopwatch and display the final summary.
+
+### 2. Timer Mode
+
+Count down from a specified duration with advanced repeat and notification options.
+
+#### Start the Timer
+
+To start a countdown, use the `timer` command followed by the duration. You can specify hours (`h`), minutes (`m`), and seconds (`s`).
+
+```bash
+# Set a timer for 5 minutes and 30 seconds
+psw timer 5m 30s
+
+# Set a timer for 1 hour
+psw timer 1h
+```
+
+The countdown will be displayed in the console:
+
+```text
+00 h 05 m 30.000 s
+
+```
+
+#### Options
+
+* **`-p, --precision`**: Same as the stopwatch mode, specifies the decimal places for seconds (Default: `3`).
+* **`-r, --repeat [<integer>]`**: Restarts the timer when it reaches zero.
+  * Use without arguments for an **infinite loop**.
+    * *Example*: `psw timer 1m -r`
+  * Specify an integer to repeat a **specific number of times**.
+    * *Example*: `psw timer 1m -r 3` (Runs a 1-minute timer 3 times)
+* **`-m, --mute`**: Disables the system alert sound (terminal bell) when the timer ends.
+
+#### Interactive Controls (While Running)
+
+* **`s`**: Pause / Resume the countdown.
+* **`q` (or `Ctrl+C`)**: Cancel and exit the timer.
+
+> [!NOTE]
+> When the timer reaches `00 h 00 m 00.000 s`, the application plays a platform-appropriate alert notification (using `winsound.MessageBeep()` on Windows, and emitting a standard terminal bell sound `\a` on other platforms or as a fallback). No special OS-level audio permissions or external audio library imports are required, making it lightweight and cross-platform compatible.

psw-0.1.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+psw/__init__.py,sha256=krDS7UcIYTts333VG3dvhp0E4tmcTxEIOM16rzVua-c,453
+psw/__main__.py,sha256=mA4c_Qd7Nt6JVSqlGkzqa3LAkR8tlMXLgmGfsnOvm_g,210
+psw/cli.py,sha256=24IlFzII7lNEtQYVgHCsmVamgYGjpvKgtqA8_g3qRkc,3118
+psw/stopwatch.py,sha256=Yf7cCiCurr4EeTiSlk7XCN-pdCrMKsPOxm4wJ01mIaM,3539
+psw/timer.py,sha256=GgbrwAr4lq_r6JaTz1MaN4TlK4JS1F_qdN80wYTUo-Y,7017
+psw/utils.py,sha256=cNv_1FJetMc7OalW8Y82G8_iXh6lLitVLU-2Tkp2Ekk,1727
+psw-0.1.4.dist-info/METADATA,sha256=yJFxxumpdmnvAEz0s1Xa7Blc0-3_5oSiFCCbOTYop3M,2942
+psw-0.1.4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+psw-0.1.4.dist-info/entry_points.txt,sha256=L5f-rin-ZZigbuu7NBaFiX8-8L0HA9VVdgasWNQgT6w,37
+psw-0.1.4.dist-info/licenses/LICENSE,sha256=8rbF82lNR6xmU0nap8dg72OWYgQQ3qoewPKhpNRRamo,1069
+psw-0.1.4.dist-info/RECORD,,

psw-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

psw-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+psw = psw.cli:main

psw-0.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenji Otsuka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.