以下是一个企业级的 Python 函数设计,用于处理日期范围并返回修正后的时区感知日期时间对象
以下是一个企业级的 Python 函数设计,用于处理日期范围并返回修正后的时区感知日期时间对象:
```python
from datetime import datetime, date, time
from django.utils import timezone
from typing import Tuple, Optional
def create_timezone_aware_range(
start_date: date,
end_date: Optional[date] = None,
inclusive_end: bool = True
) -> Tuple[datetime, datetime]:
"""
创建时区感知的日期时间范围
将给定的开始日期和结束日期转换为包含完整时间信息的时区感知 datetime 对象
参数:
start_date (date): 范围开始日期
end_date (date, optional): 范围结束日期,默认为开始日期
inclusive_end (bool): 是否包含结束日期的完整一天,默认为 True
返回:
Tuple[datetime, datetime]: 包含时区信息的 (开始时间, 结束时间) 元组
异常:
ValueError: 如果结束日期在开始日期之前
示例:
>>> create_timezone_aware_range(date(2023, 1, 1))
(datetime(2023, 1, 1, 0, 0, tzinfo=<UTC>),
datetime(2023, 1, 1, 23, 59, 59, 999999, tzinfo=<UTC>))
>>> create_timezone_aware_range(date(2023, 1, 1), date(2023, 1, 5), False)
(datetime(2023, 1, 1, 0, 0, tzinfo=<UTC>),
datetime(2023, 1, 5, 0, 0, tzinfo=<UTC>))
"""
# 验证日期范围有效性
if end_date and end_date < start_date:
raise ValueError("结束日期不能早于开始日期")
# 设置默认结束日期
effective_end_date = end_date if end_date is not None else start_date
# 创建开始日期时间 (当天最小时间)
start_datetime = datetime.combine(start_date, time.min)
# 创建结束日期时间
if inclusive_end:
# 包含结束日期的完整一天
end_datetime = datetime.combine(effective_end_date, time.max)
else:
# 精确到结束日期的开始时刻
end_datetime = datetime.combine(effective_end_date, time.min)
# 转换为时区感知对象
aware_start = timezone.make_aware(start_datetime)
aware_end = timezone.make_aware(end_datetime)
return aware_start, aware_end
```
### 关键特性:
1. **类型注解**:
- 使用 Python 类型提示确保类型安全
- 明确输入输出类型
2. **灵活的日期处理**:
- 可选 `end_date` 参数(默认为 `start_date`)
- `inclusive_end` 参数控制是否包含结束日期的完整一天
3. **健壮的错误处理**:
- 验证结束日期是否早于开始日期
- 明确的错误消息
4. **时区感知**:
- 使用 Django 的 `make_aware` 确保所有日期时间对象有时区信息
- 自动使用项目设置的默认时区
5. **清晰的文档**:
- 完整的 docstring 说明
- 参数和返回值文档
- 使用示例
### 使用示例:
```python
from datetime import date
# 基本用法 - 单日范围
start, end = create_timezone_aware_range(date(2023, 1, 1))
print(f"开始: {start}, 结束: {end}")
# 输出: 开始: 2023-01-01 00:00:00+00:00, 结束: 2023-01-01 23:59:59.999999+00:00
# 日期范围 - 包含结束日
start, end = create_timezone_aware_range(date(2023, 1, 1), date(2023, 1, 5))
print(f"开始: {start}, 结束: {end}")
# 输出: 开始: 2023-01-01 00:00:00+00:00, 结束: 2023-01-05 23:59:59.999999+00:00
# 日期范围 - 不包含结束日
start, end = create_timezone_aware_range(date(2023, 1, 1), date(2023, 1, 5), inclusive_end=False)
print(f"开始: {start}, 结束: {end}")
# 输出: 开始: 2023-01-01 00:00:00+00:00, 结束: 2023-01-05 00:00:00+00:00
# 错误处理
try:
create_timezone_aware_range(date(2023, 1, 5), date(2023, 1, 1))
except ValueError as e:
print(f"错误: {e}")
# 输出: 错误: 结束日期不能早于开始日期
```
### 企业级优势:
1. **可复用性**:
- 独立于具体业务逻辑
- 可在项目的任何部分使用
2. **可配置性**:
- `inclusive_end` 参数适应不同业务场景需求
- 自动处理时区转换
3. **测试友好**:
- 清晰的输入输出定义
- 可预测的行为
- 易于编写单元测试
4. **符合最佳实践**:
- PEP 8 代码风格
- 类型提示增强代码可读性
- 完整的文档字符串
此函数特别适合在 Django 项目中使用,可以无缝集成到视图、管理命令或任何需要处理日期范围的业务逻辑中。