date-normalizer

日期规范化器

将各种格式的日期解析并规范化为一致的标准格式，用于数据清理和 ETL 工作流。

用途

日期标准化适用于：

• 数据清理和 ETL 工作流
• 包含混合日期格式的数据库导入
• 日志文件解析和分析
• 国际数据协调
• 生成日期格式一致的报告

功能

• 智能解析：自动检测并解析 100 多种日期格式
• 格式转换：转换为 ISO 8601、美国、欧洲或自定义格式
• 批量处理：规范化整个 CSV 列
• 歧义检测：标记可能有多种解释的日期
• 时区处理：转换并规范化时区
• 相对日期：解析“今天”“昨天”“下周”等表达
• 验证：检测并报告无效日期

快速入门

from date_normalizer import DateNormalizer

# Normalize single date
normalizer = DateNormalizer()
result = normalizer.normalize("03/14/2024")
print(result)  # {'normalized': '2024-03-14', 'format': 'iso8601'}

# Normalize to specific format
result = normalizer.normalize("March 14, 2024", output_format="us")
print(result)  # {'normalized': '03/14/2024', 'format': 'us'}

# Batch normalize CSV column
normalizer.normalize_csv(
    'data.csv',
    date_column='created_at',
    output='normalized.csv',
    output_format='iso8601'
)

命令行用法

# Normalize single date
python date_normalizer.py --date "March 14, 2024"

# Convert to specific format
python date_normalizer.py --date "14/03/2024" --format us

# Normalize CSV column
python date_normalizer.py --csv data.csv --column date --format iso8601 --output normalized.csv

# Detect ambiguous dates
python date_normalizer.py --date "01/02/03" --detect-ambiguous

API 参考

DateNormalizer

class DateNormalizer:
    def normalize(self, date_string: str, output_format: str = 'iso8601',
                 dayfirst: bool = False, yearfirst: bool = False) -> Dict
    def normalize_batch(self, dates: List[str], **kwargs) -> List[Dict]
    def normalize_csv(self, csv_path: str, date_column: str,
                     output: str = None, **kwargs) -> str
    def detect_format(self, date_string: str) -> str
    def is_valid(self, date_string: str) -> bool
    def is_ambiguous(self, date_string: str) -> bool
    def parse_relative(self, relative_string: str) -> datetime

输出格式

ISO 8601（默认）：

'2024-03-14'  # Date only
'2024-03-14T15:30:00'  # With time
'2024-03-14T15:30:00+00:00'  # With timezone

美国格式：

'03/14/2024'  # MM/DD/YYYY

欧洲格式：

'14/03/2024'  # DD/MM/YYYY

长格式：

'March 14, 2024'

自定义格式：

normalizer.normalize(date, output_format='%Y%m%d')  # '20240314'

支持的输入格式

数字格式：

• 2024-03-14（ISO）
• 03/14/2024（美国）
• 14/03/2024（欧洲）
• 14.03.2024（德国）
• 2024/03/14（日本）
• 20240314（紧凑格式）

文本格式：

• March 14, 2024
• 14 March 2024
• Mar 14, 2024
• 14-Mar-2024

相对日期：

• today、yesterday、tomorrow
• next week、last month
• 2 days ago、in 3 weeks

带时间：

• 2024-03-14 15:30:00
• 03/14/2024 3:30 PM
• 2024-03-14T15:30:00Z

歧义处理

像 01/02/03 这样的日期存在歧义。请指定解释方式：

# Day first (EU)
normalizer.normalize("01/02/03", dayfirst=True)
# Result: 2003-02-01

# Month first (US)
normalizer.normalize("01/02/03", dayfirst=False)
# Result: 2003-01-02

# Year first
normalizer.normalize("01/02/03", yearfirst=True)
# Result: 2001-02-03

使用场景

清理混乱数据：

messy_dates = [
    "March 14, 2024",
    "2024-03-15",
    "03/16/2024",
    "17-Mar-2024"
]

normalized = normalizer.normalize_batch(messy_dates)
# All converted to: ['2024-03-14', '2024-03-15', '2024-03-16', '2024-03-17']

CSV 规范化：

# Input CSV with mixed date formats
# Convert all to ISO 8601
normalizer.normalize_csv(
    'orders.csv',
    date_column='order_date',
    output='orders_normalized.csv',
    output_format='iso8601'
)

验证：

if not normalizer.is_valid("invalid date"):
    print("Invalid date detected")

时区转换：

normalizer.normalize(
    "2024-03-14 15:30:00+00:00",
    output_timezone='America/New_York'
)

限制

• 无法解析图像或 PDF 中的日期（请先使用 OCR）
• 歧义日期需要手动指定格式
• 对非常早的日期（<1900）的支持可能有限
• 不支持非公历
• 某些地区格式可能需要显式配置