date-normalizer

日付正規化ツール

さまざまな形式の日付を解析し、データクレンジングや ETL パイプラインで使える、一貫性のある標準形式に正規化します。

目的

日付の標準化：

• データクレンジングや ETL パイプライン
• 混在した日付形式を含むデータベースへのインポート
• ログファイルの解析と分析
• 国際的なデータの統合
• 一貫した日付形式でのレポート生成

特長

• スマート解析：100 種類以上の日付形式を自動検出して解析します
• 形式変換：ISO 8601、US、EU、またはカスタム形式に変換します
• 一括処理：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'
)

CLI の使用方法

# 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

US 形式：

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

EU 形式：

'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（US）
• 14/03/2024（EU）
• 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 年より前）は、サポートが限定的な場合があります
• グレゴリオ暦以外の暦には対応していません
• 地域によっては、形式を明示的に設定する必要があります