tessl/pypi-dateparser

Date parsing library designed to parse dates from HTML pages

—

Pending

Overview

Eval results

Files

Core Date Parsing

Name: tessl/pypi-dateparser
Author: tessl

Primary date parsing functionality providing the main entry point for converting human-readable date strings into Python datetime objects. Supports automatic language detection, multiple date formats, and extensive localization.

Capabilities

Main Parse Function

The primary parsing function that handles most common date parsing scenarios with automatic language detection and format recognition.

def parse(date_string, date_formats=None, languages=None, locales=None, 
          region=None, settings=None, detect_languages_function=None):
    """
    Parse date and time from given date string.

    Parameters:
    - date_string (str): A string representing date and/or time in a recognizably valid format
    - date_formats (list, optional): List of format strings using strftime directives
    - languages (list, optional): List of language codes (e.g. ['en', 'es', 'zh-Hant'])  
    - locales (list, optional): List of locale codes (e.g. ['fr-PF', 'qu-EC', 'af-NA'])
    - region (str, optional): Region code (e.g. 'IN', '001', 'NE')
    - settings (dict, optional): Configure customized behavior using Settings
    - detect_languages_function (function, optional): Custom language detection function
    
    Returns:
    datetime: Parsed date if successful, else None
    
    Raises:
    ValueError: Unknown Language
    TypeError: Languages argument must be a list
    SettingValidationError: A provided setting is not valid
    """

Usage Examples:

import dateparser

# Basic parsing
date = dateparser.parse('January 15, 2023')
# Returns: datetime.datetime(2023, 1, 15, 0, 0)

# Multi-language parsing
date = dateparser.parse('15 de enero de 2023', languages=['es'])
# Returns: datetime.datetime(2023, 1, 15, 0, 0)

# Relative dates
date = dateparser.parse('2 weeks ago')
date = dateparser.parse('tomorrow')
date = dateparser.parse('next Friday')

# Custom date formats
date = dateparser.parse('2023/01/15', date_formats=['%Y/%m/%d'])

# With specific locale
date = dateparser.parse('15 janvier 2023', locales=['fr-FR'])

Advanced Parser Class

A configurable parser class for advanced parsing scenarios requiring custom language detection, settings, or reusable parser instances.

class DateDataParser:
    """
    Class which handles language detection, translation and subsequent parsing
    of string representing date and/or time.
    """
    
    def __init__(self, languages=None, locales=None, region=None, 
                 try_previous_locales=False, use_given_order=False, 
                 settings=None, detect_languages_function=None):
        """
        Initialize DateDataParser with custom configuration.
        
        Parameters:
        - languages (list, optional): List of language codes for translation
        - locales (list, optional): List of locale codes for translation
        - region (str, optional): Region code for locale construction
        - try_previous_locales (bool): Try previously used locales first
        - use_given_order (bool): Try locales in given order
        - settings (dict, optional): Custom parsing settings
        - detect_languages_function (function, optional): Custom language detection
        
        Raises:
        ValueError: Unknown Language
        TypeError: Languages/locales argument must be a list
        SettingValidationError: A provided setting is not valid
        """
    
    def get_date_data(self, date_string, date_formats=None):
        """
        Parse string representing date and/or time in recognizable localized formats.
        
        Parameters:
        - date_string (str): String to parse
        - date_formats (list, optional): List of format strings to try
        
        Returns:
        DateData: Object containing parsed date information and metadata
        """
    
    def get_date_tuple(self, *args, **kwargs):
        """
        Parse date and return tuple of parsed fields.
        
        Returns:
        tuple: Tuple containing parsed date fields
        """

Usage Examples:

from dateparser import DateDataParser

# Create parser for specific languages
parser = DateDataParser(languages=['en', 'es', 'fr'])
date_data = parser.get_date_data('15 enero 2023')
date = date_data.date_obj
locale = date_data.locale

# Create parser with custom settings
from dateparser.conf import Settings
settings = Settings(PREFER_DATES_FROM='future', STRICT_PARSING=True)
parser = DateDataParser(settings=settings)
date_data = parser.get_date_data('tomorrow')

# Reuse parser for multiple dates
parser = DateDataParser(languages=['de'], region='DE')
dates = []
for date_string in ['1. Januar 2023', '15. März 2023', 'gestern']:
    date_data = parser.get_date_data(date_string)
    if date_data:
        dates.append(date_data.date_obj)

Specialized Parsing Functions

Lower-level parsing functions for specific date formats and edge cases.

def get_date_from_timestamp(date_string, settings, negative=False):
    """
    Convert timestamp string to datetime object.
    
    Parameters:
    - date_string (str): Timestamp string to parse
    - settings (Settings): Parsing settings
    - negative (bool): Whether to handle negative timestamps
    
    Returns:
    datetime: Parsed datetime from timestamp
    """

def parse_with_formats(date_string, date_formats, settings):
    """
    Parse using provided format strings.
    
    Parameters:
    - date_string (str): String to parse
    - date_formats (list): List of strftime format strings
    - settings (Settings): Parsing settings
    
    Returns:
    datetime: Parsed datetime object
    """

def sanitize_date(date_string):
    """
    Sanitize and normalize date strings.
    
    Parameters:
    - date_string (str): String to sanitize
    
    Returns:
    str: Cleaned date string
    """

Types

class DateData:
    """Container for parsed date information and metadata."""
    
    def __init__(self, date_obj=None, period=None, locale=None):
        """
        Initialize DateData container.
        
        Parameters:
        - date_obj (datetime, optional): Parsed datetime object
        - period (str, optional): Time period information
        - locale (Locale, optional): Detected locale used for parsing
        """
    
    date_obj: datetime  # The parsed datetime object
    period: str         # Time period information (e.g., 'day', 'week')
    locale: Locale      # Locale used for parsing

Install with Tessl CLI