Python 番茄钟命令行小工具实战:argparse 与 JSON 持久化统计
学编程最难的往往不是语法,而是坐下来、持续专注。番茄工作法把时间切成 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 持久化四块基础知识,而且写完当天就能用上。建议你先照着敲一遍跑通,再挑上面四个扩展方向做一个,明天学习时就用它来计时,顺便验证自己的统计准不准。
- 点赞
- 收藏
- 关注作者
评论(0)