Python 时间处理模块：time / datetime / calendar

import time

# ① 获取当前时间戳（浮点秒数）
ts = time.time()
print(f"当前时间戳: {ts}")  # 例如: 1716170400.123456

# ② 时间戳 -> 本地 struct_time
local_st = time.localtime(ts)
print(f"本地 struct_time: {local_st}")
# time.struct_time(tm_year=2024, tm_mon=5, tm_mday=20, ...)

# ③ 时间戳 -> UTC struct_time
utc_st = time.gmtime(ts)
print(f"UTC struct_time: {utc_st}")

# ④ struct_time -> 时间戳（仅限本地时间的 struct_time）
ts_back = time.mktime(local_st)
print(f"还原的时间戳: {ts_back}")  # 与原始 ts 几乎相同

import time

st = time.localtime()

# ① struct_time -> 格式化字符串
formatted = time.strftime("%Y-%m-%d %H:%M:%S", st)
print(f"格式化: {formatted}")  # "2024-05-20 13:14:00"

# ② 格式化字符串 -> struct_time
parsed = time.strptime("2024-01-15 09:30:00", "%Y-%m-%d %H:%M:%S")
print(f"解析: tm_year={parsed.tm_year}, tm_mon={parsed.tm_mon}")

import time

# ============ 推荐写法：perf_counter 计时 ============
start = time.perf_counter()

# ... 被测代码 ...
total = sum(i * i for i in range(10_000_000)

elapsed = time.perf_counter() - start
print(f"耗时: {elapsed:.6f} 秒")  # 例如: 耗时: 0.832145 秒

# ============ process_time：只算 CPU 时间 ============
start_cpu = time.process_time()

# ... CPU 密集型代码 ...
total = sum(i * i for i in range(10_000_000)

cpu_elapsed = time.process_time() - start_cpu
print(f"CPU 耗时: {cpu_elapsed:.6f} 秒")
# 注意：process_time 不含 time.sleep() 等待时间

import time

print("任务开始...")
time.sleep(0.5)    # 休眠 500 毫秒
print("500ms 后继续")

# 注意：sleep 的实际精度依赖操作系统调度器，
# Windows 默认精度约 15.6ms，Linux 通常更精确

from datetime import date, time, datetime, timezone, timedelta
from zoneinfo import ZoneInfo

# ============ date：纯日期 ============
today = date.today()                      # 当前日期
birthday = date(2000, 6, 15)             # 指定日期
from_ts = date.fromtimestamp(1716170400) # 从时间戳创建

print(f"今天: {today}")          # 2024-05-20
print(f"生日: {birthday}")       # 2000-06-15
print(f"时间戳日期: {from_ts}")  # 2024-05-20

# ============ time：纯时间 ============
morning = time(8, 30, 0)                  # 08:30:00
with_tz = time(8, 30, 0, tzinfo=ZoneInfo("Asia/Shanghai"))  # 带时区

print(f"早晨: {morning}")        # 08:30:00
print(f"带时区: {with_tz}")      # 08:30:00+08:00

# ============ datetime：日期 + 时间 ============
now_local = datetime.now()                                        # 本地 naive
now_utc = datetime.now(timezone.utc)                              # UTC aware
specific = datetime(2024, 5, 20, 13, 14, 0, tzinfo=ZoneInfo("Asia/Shanghai")
from_combine = datetime.combine(today, morning)                   # 合并 date + time

print(f"本地: {now_local}")       # 2024-05-20 13:14:00.123456 (naive)
print(f"UTC: {now_utc}")          # 2024-05-20 05:14:00.123456+00:00 (aware)
print(f"指定: {specific}")        # 2024-05-20 13:14:00+08:00
print(f"合并: {from_combine}")    # 2024-05-20 08:30:00 (naive)

from datetime import datetime, timedelta, date

now = datetime.now()

# ============ 创建 timedelta ============
one_day = timedelta(days=1)            # 1 天
custom = timedelta(                    # 任意组合
    weeks=1,       # 7 天
    days=2,        # +2 天
    hours=3,       # +3 小时
    minutes=30,    # +30 分钟
    seconds=15     # +15 秒
)
print(f"自定义时长: {custom}")         # 9 days, 3:30:15

# ============ datetime + timedelta ============
tomorrow = now + timedelta(days=1)
three_hours_ago = now - timedelta(hours=3)
print(f"明天: {tomorrow}")
print(f"3小时前: {three_hours_ago}")

# ============ datetime - datetime ============
dt1 = datetime(2024, 1, 1)
dt2 = datetime(2024, 12, 31)
diff = dt2 - dt1
print(f"差值: {diff}")                        # 365 days, 0:00:00
print(f"总秒数: {diff.total_seconds()}")       # 31536000.0
print(f"天数: {diff.days}")                    # 365

# ============ date + timedelta ============
d = date(2024, 2, 28)
next_week = d + timedelta(weeks=1)
print(f"下周: {next_week}")             # 2024-03-06

# ============ timedelta 比较与运算 ============
assert timedelta(hours=1) > timedelta(minutes=59)
assert timedelta(hours=1) + timedelta(minutes=30) == timedelta(hours=1, minutes=30)
assert timedelta(hours=2) * 3 == timedelta(hours=6)        # 乘法
assert timedelta(hours=3) / 2 == timedelta(hours=1.5)     # 除法

from datetime import datetime

now = datetime.now()

# ============ strftime：datetime -> 字符串 ============
# ① 常用格式
fmt1 = now.strftime("%Y-%m-%d %H:%M:%S")
print(f"标准格式: {fmt1}")          # "2024-05-20 13:14:00"

# ② 中文友好格式
fmt2 = now.strftime("%Y年%m月%d日 %A %H:%M")
print(f"中文格式: {fmt2}")          # "2024年05月20日 Monday 13:14"

# ③ 文件名安全格式（无特殊字符）
fmt3 = now.strftime("%Y%m%d_%H%M%S")
print(f"文件名格式: {fmt3}")        # "20240520_131400"

# ============ strptime：字符串 -> datetime ============
# 注意：strptime 返回的永远是 naive datetime
parsed = datetime.strptime("2024-05-20 13:14:00", "%Y-%m-%d %H:%M:%S")
print(f"解析结果: {parsed}")         # 2024-05-20 13:14:00 (naive!)

# ============ isoformat / fromisoformat（推荐）============
# ISO 8601 是数据交换的标准格式，无需记忆格式化字符串
iso_str = now.isoformat()
print(f"ISO 格式: {iso_str}")       # "2024-05-20T13:14:00.123456"

dt_from_iso = datetime.fromisoformat("2024-05-20T13:14:00+08:00")
print(f"ISO 解析: {dt_from_iso}")   # 2024-05-20 13:14:00+08:00 (aware)

from datetime import datetime, timezone, timedelta
from zoneinfo import ZoneInfo

# ============ 1. 创建 Aware datetime ============
# 方式 A：构建时直接指定时区
beijing = datetime(2024, 5, 20, 13, 14, 0, tzinfo=ZoneInfo("Asia/Shanghai")

# 方式 B：获取当前时间并指定时区
now_utc = datetime.now(timezone.utc)                # UTC 当前时间
now_beijing = datetime.now(ZoneInfo("Asia/Shanghai"))  # 北京当前时间

print(f"北京时间: {beijing}")          # 2024-05-20 13:14:00+08:00
print(f"UTC 现在: {now_utc}")          # 2024-05-20 05:14:00+00:00
print(f"北京现在: {now_beijing}")      # 2024-05-20 13:14:00+08:00

# ============ 2. 时区转换 ============
# 北京时间 -> 纽约时间
new_york = beijing.astimezone(ZoneInfo("America/New_York")
print(f"纽约时间: {new_york}")         # 2024-05-20 01:14:00-04:00

# 北京时间 -> UTC
utc_time = beijing.astimezone(timezone.utc)
print(f"UTC 时间: {utc_time}")         # 2024-05-20 05:14:00+00:00

# 北京时间 -> 东京时间
tokyo = beijing.astimezone(ZoneInfo("Asia/Tokyo")
print(f"东京时间: {tokyo}")            # 2024-05-20 14:14:00+09:00

# ============ 3. Naive -> Aware（本地化）============
naive_dt = datetime(2024, 5, 20, 13, 14, 0)

# ⚠️ 错误：replace 不会做时区转换，只是"贴标签"
# wrong = naive_dt.replace(tzinfo=ZoneInfo("Asia/Shanghai")
# 如果 naive_dt 本身就是北京时间的数据，这样做碰巧正确，
# 但如果它是 UTC 数据，结果就错了

# ✅ 正确：明确数据的原始时区，然后贴标签
# 假设 naive_dt 是北京时间：
aware_beijing = naive_dt.replace(tzinfo=ZoneInfo("Asia/Shanghai")
# 假设 naive_dt 是 UTC 时间：
aware_utc = naive_dt.replace(tzinfo=timezone.utc)

print(f"本地化(北京): {aware_beijing}")  # 2024-05-20 13:14:00+08:00
print(f"本地化(UTC): {aware_utc}")       # 2024-05-20 13:14:00+00:00

# ============ 4. Aware -> Naive（去除时区）============
naive_back = aware_beijing.replace(tzinfo=None)
print(f"去除时区: {naive_back}")        # 2024-05-20 13:14:00

# ============ 5. 时间戳与 Aware datetime 的互转 ============
ts = aware_beijing.timestamp()          # 正确：aware -> 时间戳
dt_from_ts = datetime.fromtimestamp(ts, tz=timezone.utc)  # 正确：时间戳 -> UTC aware
print(f"时间戳: {ts}")
print(f"还原UTC: {dt_from_ts}")

import calendar
from datetime import date

# ============ 1. 生成文本月历 ============
print(calendar.month(2024, 2)
# 输出:
#    February 2024
# Mo Tu We Th Fr Sa Su
#           1  2  3  4
#  5  6  7  8  9 10 11
# ...

# ============ 2. 月份矩阵 ============
weeks = calendar.monthcalendar(2024, 2)
for week in weeks:
    print(week)
# [0, 0, 0, 1, 2, 3, 4]    # 0 表示非本月日期
# [5, 6, 7, 8, 9, 10, 11]
# ...

# ============ 3. 月首星期 + 月天数 ============
weekday, num_days = calendar.monthrange(2024, 2)
# weekday: 3 (周四), num_days: 29 (闰年)
print(f"2024年2月: 首日周{weekday + 1}, 共{num_days}天")

# ============ 4. 闰年判断 ============
print(f"2024 闰年? {calendar.isleap(2024)}")     # True
print(f"2100 闰年? {calendar.isleap(2100)}")     # False (能被100整除但不能被400整除)
print(f"2000-2024间闰年数: {calendar.leapdays(2000, 2025)}")

# ============ 5. 自定义周起始日 ============
c = calendar.Calendar(firstweekday=6)  # 周日为起始
for day in c.itermonthdates(2024, 5):
    if day.month == 5:  # 过滤掉非本月的日期
        print(day, end=" ")
# 2024-05-01 2024-05-02 ... 2024-05-31

# ============ 6. 中文星期名 ============
print(list(calendar.day_name))       # ['Monday', 'Tuesday', ...]
# 如需中文，可以自行映射：
cn_days = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
weekday_cn = cn_days[date.today().weekday()]
print(f"今天是: {weekday_cn}")

import timeit

# ============ 1. 命令行方式（最快上手）============
# 在终端运行：
# python -m timeit "sum(range(100))"
# python -m timeit -n 1000 -r 5 "sum(range(100))"

# ============ 2. 函数调用方式 ============
# 测量列表推导 vs map 的性能
setup = "data = list(range(10000))"

time_listcomp = timeit.timeit(
    stmt="[x * 2 for x in data]",  # 被测代码
    setup=setup,                    # 预执行代码
    number=1000                     # 运行次数
)

time_map = timeit.timeit(
    stmt="list(map(lambda x: x * 2, data))",
    setup=setup,
    number=1000
)

print(f"列表推导: {time_listcomp:.4f}s")
print(f"map 函数: {time_map:.4f}s")

# ============ 3. repeat：多次独立测量 ============
results = timeit.repeat(
    stmt="sum(range(1000))",
    number=10000,
    repeat=5  # 独立运行 5 轮
)
print(f"各轮耗时: {results}")
print(f"最优时间: {min(results):.6f}s")

# ============ 4. Timer 对象（更灵活）============
timer = timeit.Timer(
    stmt="sorted(data)",
    setup="import random; data = [random.random() for _ in range(1000)]"
)

# 只运行一次，用于粗略估计
rough = timer.timeit(number=100)
print(f"粗略耗时: {rough:.6f}s")

import time
from contextlib import contextmanager

@contextmanager
def timer(label: str):
    """上下文管理器计时器，使用 perf_counter 保证精度"""
    start = time.perf_counter()   # ① 记录起始时刻
    yield                          # ② 执行被测代码块
    elapsed = time.perf_counter() - start  # ③ 计算耗时
    print(f"[{label}] 耗时: {elapsed:.6f} 秒")

# 使用示例
with timer("列表推导"):
    result = [i ** 2 for i in range(1_000_000)]

with timer("生成器求和"):
    total = sum(i ** 2 for i in range(1_000_000)

from datetime import date, timedelta

def date_range(start: date, end: date, step: timedelta = timedelta(days=1)):
    """生成从 start 到 end（不含 end）的日期序列

    Args:
        start: 起始日期（含）
        end:   结束日期（不含）
        step:  步长，默认 1 天

    Yields:
        date: 序列中的每个日期
    """
    current = start
    while current < end:               # ① 循环直到到达 end
        yield current                   # ② 产出当前日期
        current += step                 # ③ 步进

# 示例：生成 2024 年 5 月的所有日期
may_dates = list(date_range(date(2024, 5, 1), date(2024, 6, 1))
print(f"5月天数: {len(may_dates)}")  # 31

# 示例：每隔一周取一天
weekly = list(date_range(
    date(2024, 1, 1),
    date(2024, 4, 1),
    timedelta(weeks=1)
)
print(f"Q1 周数: {len(weekly)}")  # 13

# 示例：工作日过滤
workdays = [
    d for d in date_range(date(2024, 5, 1), date(2024, 6, 1)
    if d.weekday() < 5  # 0-4 = 周一到周五
]
print(f"5月工作日: {len(workdays)} 天")

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def world_clock(dt: datetime, *cities: str) -> dict[str, datetime]:
    """将一个时间转换为多个城市对应的本地时间

    Args:
        dt: 源时间（必须是 aware datetime）
        cities: IANA 时区标识符列表

    Returns:
        城市 -> 本地时间的字典
    """
    result = {}
    for city in cities:
        tz = ZoneInfo(city)
        local_time = dt.astimezone(tz)   # 时区转换
        result[city] = local_time
    return result

# 场景：安排全球会议，北京时间下午 2 点
meeting_time = datetime(2024, 5, 20, 14, 0, 0, tzinfo=ZoneInfo("Asia/Shanghai")

clocks = world_clock(
    meeting_time,
    "Asia/Shanghai",        # 北京
    "America/New_York",     # 纽约
    "Europe/London",        # 伦敦
    "Asia/Tokyo",           # 东京
    "Australia/Sydney",     # 悉尼
)

for city, t in clocks.items():
    print(f"{city:25s} {t.strftime('%Y-%m-%d %H:%M (%Z)')}")
# Asia/Shanghai              2024-05-20 14:00 (CST)
# America/New_York           2024-05-20 02:00 (EDT)
# Europe/London              2024-05-20 07:00 (BST)
# Asia/Tokyo                 2024-05-20 15:00 (JST)
# Australia/Sydney           2024-05-20 16:00 (AEST)

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def ts_to_datetime(ts: float, tz_name: str = "UTC") -> datetime:
    """时间戳 -> 指定时区的 aware datetime"""
    tz = ZoneInfo(tz_name) if tz_name != "UTC" else timezone.utc
    return datetime.fromtimestamp(ts, tz=tz)

def datetime_to_ts(dt: datetime) -> float:
    """aware/naive datetime -> 时间戳"""
    if dt.tzinfo is None:
        # naive datetime 按本地时区处理（不推荐，但需要处理）
        return dt.timestamp()
    return dt.timestamp()  # aware datetime 自动正确转换

# 示例
ts = 1716170400.0
dt_utc = ts_to_datetime(ts, "UTC")
dt_bj = ts_to_datetime(ts, "Asia/Shanghai")

print(f"时间戳 {ts}")
print(f"  UTC: {dt_utc}")    # 2024-05-20 02:00:00+00:00
print(f"  北京: {dt_bj}")    # 2024-05-20 10:00:00+08:00

# 反向转换
print(f"还原时间戳: {datetime_to_ts(dt_utc)}")  # 1716170400.0

from datetime import datetime, timezone

naive = datetime(2024, 1, 1, 8, 0, 0)
aware = datetime(2024, 1, 1, 0, 0, 0, tzinfo=timezone.utc)

# naive == aware  # TypeError: can't compare offset-naive and offset-aware datetimes

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

# 美国 2024 年 3 月 10 日夏令时开始，时钟从 2:00 跳到 3:00
tz = ZoneInfo("America/New_York")
midnight = datetime(2024, 3, 10, 0, 0, 0, tzinfo=tz)

next_day = midnight + timedelta(days=1)   # 正确：跨越 DST 切换
print(f"间隔: {(next_day - midnight).total_seconds() / 3600} 小时")  # 23 小时

# 如果你用 hours=24，得到的是同一时刻的第二天 1:00
wrong = midnight + timedelta(hours=24)
print(f"24h后: {wrong}")  # 2024-03-11 01:00:00-04:00 (不是午夜!)

import time

# 远未来的时间戳可能丢失微秒精度
ts = time.time()
print(f"时间戳: {ts:.6f}")  # 微秒级精度

# 如果需要更高精度，使用 perf_counter 的纳秒版本
ns = time.perf_counter_ns()
print(f"纳秒计时: {ns}")

from datetime import datetime

dt = datetime(2024, 5, 20, 13, 14, 0)

# dt.hour = 15  # AttributeError: attribute 'hour' is read-only

# 正确做法：用 replace() 创建新对象
dt_new = dt.replace(hour=15)
print(f"原对象: {dt}")      # 13:14:00 (不变)
print(f"新对象: {dt_new}")  # 15:14:00

from datetime import datetime, timezone

ts = 1716170400.0

# 不指定 tz -> 本地时区的 naive datetime（取决于运行环境的时区设置）
local_dt = datetime.fromtimestamp(ts)     # 危险！结果因环境而异

# 指定 tz -> 明确时区的 aware datetime
utc_dt = datetime.fromtimestamp(ts, tz=timezone.utc)  # 推荐

print(f"本地: {local_dt}")   # 结果依赖系统时区
print(f"UTC: {utc_dt}")      # 2024-05-20 02:00:00+00:00（确定性）