Python 番茄钟命令行小工具实战:argparse 与 JSON 持久化统计

举报
yd_240716394 发表于 2026/11/10 12:26:20 2026/11/10
【摘要】 学编程最难的往往不是语法,而是坐下来、持续专注。番茄工作法把时间切成 25 分钟一个“番茄”,中间休息 5 分钟,四个番茄后再长休一次,简单却很管用。本文就用 Python 写一个命令行番茄钟:启动计时、到点提醒、把每天完成的番茄数存进 JSON 文件,还能随时查统计。整个程序不到 150 行,只用标准库,适合当作第一个能真正每天用的小工具。 一、先把需求拆清楚动手写代码之前,先列出它必须会...

学编程最难的往往不是语法,而是坐下来、持续专注。番茄工作法把时间切成 25 分钟一个“番茄”,中间休息 5 分钟,四个番茄后再长休一次,简单却很管用。本文就用 Python 写一个命令行番茄钟:启动计时、到点提醒、把每天完成的番茄数存进 JSON 文件,还能随时查统计。整个程序不到 150 行,只用标准库,适合当作第一个能真正每天用的小工具。

一、先把需求拆清楚

动手写代码之前,先列出它必须会做的事:第一,接受专注时长和休息时长两个参数,默认 25 分钟和 5 分钟;第二,倒计时过程中每秒刷新剩余时间,按 Ctrl+C 可以随时中断;第三,一个番茄完成后自动记录,数据按日期保存,下次运行不会丢;第四,提供一个统计命令,告诉我今天完成了几个番茄、累计专注了多久。把需求写成清单,代码结构自然就出来了:参数解析、计时循环、数据读写、统计展示,四块互不干扰。

二、项目结构与数据格式

只需要一个文件就能跑起来,数据文件由程序第一次运行时自动创建:

tomato/
  tomato.py
  data.json   # 程序自动生成,不用手动建

data.json 里按日期存两个数字,结构非常直白:

{
  "2026-11-10": {"pomodoros": 3, "focus_minutes": 75}
}

用日期做键的好处是统计特别方便,查今天就取今天的键,查历史就遍历所有键。JSON 是纯文本,出了问题直接打开文件就能看,比用数据库调试轻松得多。

三、核心代码:参数解析

argparse 是 Python 标准库里的命令行参数工具,比自己解析 sys.argv 省事,还能自动生成帮助信息:

import argparse

def parse_args():
    parser = argparse.ArgumentParser(description="命令行番茄钟")
    parser.add_argument("--focus", type=int, default=25, help="专注时长(分钟)")
    parser.add_argument("--break", type=int, default=5, dest="break_minutes", help="休息时长(分钟)")
    parser.add_argument("--stats", action="store_true", help="只查看今日统计")
    return parser.parse_args()

运行 python tomato.py --help,就能看到每个参数的说明。给参数设好默认值后,平时直接敲 python tomato.py 就能开始一个 25 分钟的番茄,想改时长再加参数即可。

四、核心代码:倒计时循环

计时的关键是每秒减一并刷新同一行输出,用 \r 回到行首覆盖旧内容,flush=True 让它立刻显示出来:

import time

def countdown(minutes, label):
    total = minutes * 60
    try:
        for remaining in range(total, 0, -1):
            mins, secs = divmod(remaining, 60)
            print(f"\r{label} 剩余 {mins:02d}:{secs:02d}", end="", flush=True)
            time.sleep(1)
        print(f"\n{label}完成!")
    except KeyboardInterrupt:
        print("\n已中断,本次番茄不计入统计。")
        return False
    return True

这里特意把 KeyboardInterrupt 单独处理:用户按 Ctrl+C 中断时,程序会礼貌地退出,而不是抛出一大段报错,并且中断的番茄不计入统计,这样数据才真实。

五、核心代码:JSON 持久化

读写 JSON 只需要三个小函数:读、改、写。文件不存在或内容损坏时返回空字典,程序不会因此崩溃:

import json
import os
from datetime import date

DATA_FILE = os.path.join(os.path.dirname(__file__), "data.json")

def load_data():
    if not os.path.exists(DATA_FILE):
        return {}
    try:
        with open(DATA_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    except (json.JSONDecodeError, OSError):
        return {}

def save_data(data):
    with open(DATA_FILE, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)

def record_pomodoro(focus_minutes):
    data = load_data()
    today = date.today().isoformat()
    day = data.setdefault(today, {"pomodoros": 0, "focus_minutes": 0})
    day["pomodoros"] += 1
    day["focus_minutes"] += focus_minutes
    save_data(data)

ensure_ascii=False 让中文日期以外的中文内容(如果以后加备注)能直接存成可读文字,indent=2 让文件保持两格缩进,方便人眼检查。

六、把各部分组装成主流程

主函数按顺序做四件事:解析参数、如果是统计模式就打印统计并退出、否则先计时专注、专注完成后再计时休息并记录:

def show_stats():
    data = load_data()
    today = date.today().isoformat()
    day = data.get(today, {"pomodoros": 0, "focus_minutes": 0})
    print(f"今日完成 {day['pomodoros']} 个番茄,累计专注 {day['focus_minutes']} 分钟。")

def main():
    args = parse_args()
    if args.stats:
        show_stats()
        return
    if countdown(args.focus, "专注时间"):
        record_pomodoro(args.focus)
        countdown(args.break_minutes, "休息时间")

if __name__ == "__main__":
    main()

注意记录的时机:只有专注计时完整跑完才调用 record_pomodoro,休息计时不影响统计。

七、运行效果

在终端里依次执行下面三条命令,就能看到完整效果:

python tomato.py --focus 25 --break 5
python tomato.py --stats
python tomato.py --focus 1 --break 1   # 想快速验证流程时用 1 分钟

正常完成一个番茄后,终端会显示“专注时间完成!”随后进入 5 分钟休息倒计时;再执行统计命令,会看到类似这样的输出:

今日完成 3 个番茄,累计专注 75 分钟。

第一次运行时 data.json 还不存在,程序会自动创建,不用提前准备任何文件。

八、可以继续扩展的四个方向

第一,加一个长休息:每完成四个番茄,休息自动延长到 15 分钟,用取余运算判断即可。第二,到点提醒:计时结束时用系统提示音或弹窗提醒,而不是只靠终端输出。第三,周统计:遍历 data.json 的所有日期,按周汇总并画一张简单的柱状图。第四,任务备注:开始番茄前输入本次要做的事,把任务名也存进 JSON,回顾时就知道时间都花在了哪里。

九、踩坑小结

第一个坑是 time.sleep 的累积误差:每轮 sleep(1) 加上 print 的耗时,25 分钟下来会慢几秒,对番茄钟来说可以接受,如果要求更准,可以改用记录开始时间、每次用目标时间减当前时间的方式计算剩余秒数。第二个坑是 JSON 文件不存在时直接打开会报错,所以 load_data 里一定要先判断文件是否存在。第三个坑是 Ctrl+C 会抛出 KeyboardInterrupt,必须在计时循环里捕获,否则会留下一堆报错信息。

一个不到 150 行的小工具,串起了 argparse 参数解析、time 计时、异常处理和 JSON 持久化四块基础知识,而且写完当天就能用上。建议你先照着敲一遍跑通,再挑上面四个扩展方向做一个,明天学习时就用它来计时,顺便验证自己的统计准不准。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。