exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/utils/dt/base.py

@@ -1,16 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/base.py
 #exonware/xwsystem/datetime/base.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 DateTime module base classes - abstract classes for date/time functionality.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from datetime import datetime, date, time, timedelta
 from .contracts import DateTimeFormat, TimezoneType, HumanizeStyle
 
@@ -39,7 +40,7 @@ class ADateTimeBase(ABC):
         pass
     
     @abstractmethod
-    def from_timestamp(self, timestamp: Union[int, float], timezone: Optional[str] = None) -> datetime:
+    def from_timestamp(self, timestamp: int | float, timezone: Optional[str] = None) -> datetime:
         """Create datetime from timestamp."""
         pass
     
@@ -230,7 +231,7 @@ class BaseDateTime(ADateTimeBase):
         """Get current UTC datetime."""
         return datetime.utcnow()
     
-    def from_timestamp(self, timestamp: Union[int, float], timezone: Optional[str] = None) -> datetime:
+    def from_timestamp(self, timestamp: int | float, timezone: Optional[str] = None) -> datetime:
         """Create datetime from timestamp."""
         dt = datetime.fromtimestamp(timestamp)
         if timezone:

exonware/xwsystem/utils/dt/contracts.py

@@ -1,15 +1,15 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 DateTime module contracts - interfaces and enums for date/time functionality.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
+from typing import Any, Optional, Protocol, runtime_checkable
 from datetime import datetime, date, time, timezone
 
 # Import enums from types module
@@ -23,72 +23,65 @@ from .defs import (
 )
 
 
-class IDateTimeFormatter(ABC):
+@runtime_checkable
+class IDateTimeFormatter(Protocol):
     """Interface for date/time formatting."""
     
-    @abstractmethod
     def format_datetime(self, dt: datetime, format_type: TimeFormat) -> str:
         """Format datetime object."""
-        pass
+        ...
     
-    @abstractmethod
     def format_date(self, d: date, format_type: DateFormat) -> str:
         """Format date object."""
-        pass
+        ...
     
-    @abstractmethod
     def format_time(self, t: time, format_type: TimeFormat) -> str:
         """Format time object."""
-        pass
+        ...
 
 
-class IDateTimeParser(ABC):
+@runtime_checkable
+class IDateTimeParser(Protocol):
     """Interface for date/time parsing."""
     
-    @abstractmethod
     def parse_datetime(self, date_string: str, format_type: Optional[TimeFormat] = None) -> datetime:
         """Parse datetime string."""
-        pass
+        ...
     
-    @abstractmethod
     def parse_date(self, date_string: str, format_type: Optional[DateFormat] = None) -> date:
         """Parse date string."""
-        pass
+        ...
     
-    @abstractmethod
     def parse_time(self, time_string: str, format_type: Optional[TimeFormat] = None) -> time:
         """Parse time string."""
-        pass
+        ...
 
 
-class IDateTimeHumanizer(ABC):
+@runtime_checkable
+class IDateTimeHumanizer(Protocol):
     """Interface for humanizing time differences."""
     
-    @abstractmethod
     def humanize(self, dt: datetime, reference: Optional[datetime] = None) -> str:
         """Humanize datetime relative to reference."""
-        pass
+        ...
     
-    @abstractmethod
     def natural_time(self, dt: datetime, reference: Optional[datetime] = None) -> str:
         """Get natural time representation."""
-        pass
+        ...
 
 
-class ITimezoneUtils(ABC):
+@runtime_checkable
+class ITimezoneUtils(Protocol):
     """Interface for timezone utilities."""
     
-    @abstractmethod
     def get_timezone(self, tz_name: str) -> timezone:
         """Get timezone object."""
-        pass
+        ...
     
-    @abstractmethod
     def convert_timezone(self, dt: datetime, target_tz: timezone) -> datetime:
         """Convert datetime to target timezone."""
-        pass
+        ...
     
-    @abstractmethod
     def get_local_timezone(self) -> timezone:
         """Get local timezone."""
-        pass
+        ...

exonware/xwsystem/utils/dt/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/defs.py
 #exonware/xwsystem/datetime/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 07-Sep-2025
 
 DateTime types and enums for XWSystem.

exonware/xwsystem/utils/dt/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/errors.py
 #exonware/xwsystem/datetime/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 DateTime module errors - exception classes for date/time functionality.
@@ -69,7 +70,3 @@ class DateTimeUnderflowError(DateTimeError):
     """Raised when datetime value underflows."""
     pass
 
-
-# Aliases for backward compatibility
-FormatError = DateTimeFormatError
-ParseError = DateTimeParseError

exonware/xwsystem/utils/dt/formatting.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/formatting.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 DateTime formatting utilities for XSystem.
@@ -134,4 +135,89 @@ def format_relative(dt: datetime) -> str:
         minutes = diff.seconds // 60
         return f"{minutes} minutes ago"
     else:
-        return "just now"
+        return "just now"
+
+
+def get_datetime() -> str:
+    """
+    Get current datetime as formatted string.
+    
+    Returns:
+        Current datetime in "YYYY-MM-DD HH:MM:SS" format
+    
+    Examples:
+        >>> dt_str = get_datetime()
+        >>> len(dt_str) == 19
+        True
+    """
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def get_date() -> str:
+    """
+    Get current date as formatted string.
+    
+    Returns:
+        Current date in "YYYY-MM-DD" format
+    
+    Examples:
+        >>> date_str = get_date()
+        >>> len(date_str) == 10
+        True
+    """
+    return datetime.now().strftime("%Y-%m-%d")
+
+
+def get_date_from_to_month(year_month: str) -> tuple[str, str]:
+    """
+    Get start and end dates for a month.
+    
+    Args:
+        year_month: Format "YYYY-MM"
+    
+    Returns:
+        Tuple of (start_date, end_date) in "YYYY-MM-DD" format
+    
+    Examples:
+        >>> start, end = get_date_from_to_month("2025-01")
+        >>> start
+        '2025-01-01'
+        >>> end
+        '2025-01-31'
+    """
+    import calendar
+    
+    year, month = map(int, year_month.split('-'))
+    
+    # Start of the month is day 1
+    start_of_month = f"{year}-{month:02d}-01"
+    
+    # Get the last day of the month
+    _, last_day = calendar.monthrange(year, month)
+    end_of_month = f"{year}-{month:02d}-{last_day:02d}"
+    
+    return start_of_month, end_of_month
+
+
+def calculate_duration_days(date_from: datetime, date_to: datetime) -> float:
+    """
+    Calculate duration between two dates in days.
+    
+    Args:
+        date_from: Start date
+        date_to: End date
+    
+    Returns:
+        Duration in days (rounded to 2 decimal places)
+    
+    Examples:
+        >>> from datetime import datetime, timedelta
+        >>> start = datetime(2025, 1, 1)
+        >>> end = datetime(2025, 1, 5)
+        >>> calculate_duration_days(end, start)
+        4.0
+    """
+    delta = date_from - date_to
+    seconds = delta.total_seconds()
+    days = seconds / 86400  # 60 * 60 * 24
+    return round(days, 2)

exonware/xwsystem/utils/dt/humanize.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/humanize.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Human-friendly datetime formatting and parsing utilities.
@@ -10,7 +11,7 @@ Human-friendly datetime formatting and parsing utilities.
 
 import re
 from datetime import datetime, timedelta
-from typing import Optional, Union
+from typing import Optional
 
 from exonware.xwsystem.config.logging_setup import get_logger
 
@@ -85,7 +86,7 @@ def humanize_timedelta(td: timedelta, precision: int = 2, max_units: int = 2) ->
     return f"{'-' if negative else ''}{result}"
 
 
-def humanize_timestamp(timestamp: Union[datetime, float], 
+def humanize_timestamp(timestamp: datetime | float, 
                       reference: Optional[datetime] = None,
                       precision: int = 2) -> str:
     """
@@ -133,7 +134,7 @@ def humanize_timestamp(timestamp: Union[datetime, float],
     return f"{prefix}{human_diff}{suffix}"
 
 
-def time_ago(timestamp: Union[datetime, float], precision: int = 2) -> str:
+def time_ago(timestamp: datetime | float, precision: int = 2) -> str:
     """
     Get time ago string from timestamp.
     
@@ -147,7 +148,7 @@ def time_ago(timestamp: Union[datetime, float], precision: int = 2) -> str:
     return humanize_timestamp(timestamp, precision=precision)
 
 
-def time_until(timestamp: Union[datetime, float], precision: int = 2) -> str:
+def time_until(timestamp: datetime | float, precision: int = 2) -> str:
     """
     Get time until string from timestamp.
     
@@ -180,7 +181,7 @@ def format_relative_time(dt: datetime, relative_to: Optional[datetime] = None, p
     return humanize_timestamp(dt, reference=relative_to, precision=precision)
 
 
-def duration_to_human(seconds: Union[int, float], 
+def duration_to_human(seconds: int | float, 
                      precision: int = 2, 
                      max_units: int = 2) -> str:
     """
@@ -316,7 +317,7 @@ def smart_time_format(dt: datetime, reference: Optional[datetime] = None) -> str
     return dt.strftime("%b %d, %Y")
 
 
-def approximate_duration(seconds: Union[int, float]) -> str:
+def approximate_duration(seconds: int | float) -> str:
     """
     Get approximate duration in natural language.
     
@@ -409,7 +410,7 @@ class DateTimeHumanizer:
         """Convert datetime to human-readable string."""
         return smart_time_format(dt, relative_to)
     
-    def humanize_date(self, date_obj: Union[datetime, str], relative_to: Optional[datetime] = None) -> str:
+    def humanize_date(self, date_obj: datetime | str, relative_to: Optional[datetime] = None) -> str:
         """Convert date to human-readable string."""
         if isinstance(date_obj, datetime):
             return smart_time_format(date_obj, relative_to)
@@ -421,7 +422,7 @@ class DateTimeHumanizer:
                 return date_obj
         return str(date_obj)
     
-    def humanize_time(self, time_obj: Union[datetime, str], relative_to: Optional[datetime] = None) -> str:
+    def humanize_time(self, time_obj: datetime | str, relative_to: Optional[datetime] = None) -> str:
         """Convert time to human-readable string."""
         if isinstance(time_obj, datetime):
             return smart_time_format(time_obj, relative_to)

exonware/xwsystem/utils/dt/parsing.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/parsing.py
 """
 Datetime Parsing Utilities
 ==========================
@@ -7,13 +8,13 @@ Production-grade datetime parsing for XSystem.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generated: 2025-01-27
 """
 
 import re
 from datetime import datetime, date, time, timezone, timedelta
-from typing import Optional, Union
+from typing import Optional
 import logging
 
 logger = logging.getLogger(__name__)
@@ -144,13 +145,32 @@ def parse_iso8601(text: str) -> Optional[datetime]:
     return parse_datetime(text)
 
 
-def parse_timestamp(timestamp: Union[int, float, str]) -> Optional[datetime]:
-    """Parse Unix timestamp to datetime."""
+def parse_timestamp(timestamp: int | float | str) -> Optional[datetime]:
+    """
+    Parse Unix timestamp to datetime.
+    
+    Automatically detects if timestamp is in seconds or milliseconds.
+    
+    Args:
+        timestamp: Unix timestamp (seconds or milliseconds)
+    
+    Returns:
+        Parsed datetime or None
+    
+    Examples:
+        >>> dt = parse_timestamp(1609459200)  # 2021-01-01 00:00:00 UTC
+        >>> dt is not None
+        True
+        >>> dt = parse_timestamp(1609459200000)  # milliseconds
+        >>> dt is not None
+        True
+    """
     try:
         if isinstance(timestamp, str):
             timestamp = float(timestamp)
         
         # Handle both seconds and milliseconds
+        # Timestamps > 1e10 are likely milliseconds (year 2286+ in seconds)
         if timestamp > 1e10:  # Likely milliseconds
             timestamp = timestamp / 1000
         
@@ -161,6 +181,37 @@ def parse_timestamp(timestamp: Union[int, float, str]) -> Optional[datetime]:
         return None
 
 
+def parse_timestamp_milliseconds(timestamp: int | float | str) -> Optional[datetime]:
+    """
+    Parse timestamp that may be in milliseconds.
+    
+    Explicitly handles millisecond timestamps (common in JavaScript/Java).
+    
+    Args:
+        timestamp: Unix timestamp (assumed to be in milliseconds)
+    
+    Returns:
+        Parsed datetime or None
+    
+    Examples:
+        >>> dt = parse_timestamp_milliseconds(1609459200000)  # milliseconds
+        >>> dt is not None
+        True
+    """
+    try:
+        if isinstance(timestamp, str):
+            timestamp = float(timestamp)
+        
+        # Treat as milliseconds
+        timestamp_seconds = timestamp / 1000.0
+        
+        return datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
+        
+    except (ValueError, OSError, OverflowError) as e:
+        logger.debug(f"Failed to parse millisecond timestamp '{timestamp}': {e}")
+        return None
+
+
 class DateTimeParser:
     """Advanced datetime parser with multiple format support."""
     
@@ -196,7 +247,7 @@ class DateTimeParser:
         """Parse ISO 8601 datetime string."""
         return parse_iso8601(text)
     
-    def parse_timestamp(self, timestamp: Union[int, float, str]) -> Optional[datetime]:
+    def parse_timestamp(self, timestamp: int | float | str) -> Optional[datetime]:
         """Parse Unix timestamp to datetime."""
         return parse_timestamp(timestamp)
     

exonware/xwsystem/utils/dt/timezone_utils.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/dt/timezone_utils.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Timezone utilities - Placeholder.
@@ -99,26 +100,3 @@ class TimezoneUtils:
         return datetime.now()
 
 
-def convert_timezone(dt, tz):
-    """Convert timezone - backward compatibility."""
-    return TimezoneUtils.convert_timezone(dt, tz)
-    
-def get_timezone_info(tz):
-    """Get timezone info - backward compatibility."""
-    return TimezoneUtils.get_timezone_info(tz)
-    
-def list_timezones():
-    """List timezones - backward compatibility."""
-    return TimezoneUtils.list_timezones()
-    
-def get_local_timezone():
-    """Get local timezone - backward compatibility."""
-    return TimezoneUtils.get_local_timezone()
-    
-def utc_now():
-    """Get UTC now - backward compatibility."""
-    return TimezoneUtils.utc_now()
-    
-def local_now():
-    """Get local now - backward compatibility."""
-    return TimezoneUtils.local_now()

exonware/xwsystem/utils/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/utils/errors.py
 #exonware/xwsystem/utils/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Utils module errors - exception classes for utility functionality.
@@ -124,6 +125,3 @@ class ResourceExhaustionError(ResourceManagerError):
     """Raised when resources are exhausted."""
     pass
 
-
-# Aliases for backward compatibility
-PathError = PathUtilsError

exonware/xwsystem/utils/paths.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/utils/paths.py
 """
 Path utilities for XSystem.
 Provides common path operations and project root detection.

exonware/xwsystem/utils/string.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/utils/string.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+String utility functions for XSystem.
+"""
+
+from typing import Optional
+
+
+def find_nth_occurrence(text: str, key: str, n: int) -> int:
+    """
+    Find the nth occurrence of a substring in text.
+    
+    Args:
+        text: Text to search
+        key: Substring to find
+        n: Occurrence number (1-based)
+    
+    Returns:
+        Index of nth occurrence, or -1 if not found
+    
+    Examples:
+        >>> find_nth_occurrence("hello world hello", "hello", 1)
+        0
+        >>> find_nth_occurrence("hello world hello", "hello", 2)
+        12
+        >>> find_nth_occurrence("hello world hello", "hello", 3)
+        -1
+    """
+    if not text or not key or n < 1:
+        return -1
+    
+    start = text.find(key)
+    while start >= 0 and n > 1:
+        start = text.find(key, start + len(key))
+        n -= 1
+    
+    return start
+
+
+__all__ = [
+    'find_nth_occurrence',
+]