dately 3.2.2__tar.gz → 3.2.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. dately-3.2.4/PKG-INFO +105 -0
  2. dately-3.2.4/README.md +84 -0
  3. {dately-3.2.2 → dately-3.2.4}/dately/_datetime_scan.py +62 -37
  4. {dately-3.2.2 → dately-3.2.4}/dately/_version.py +1 -1
  5. dately-3.2.4/dately.egg-info/PKG-INFO +105 -0
  6. {dately-3.2.2 → dately-3.2.4}/setup.py +2 -2
  7. dately-3.2.2/PKG-INFO +0 -478
  8. dately-3.2.2/README.md +0 -457
  9. dately-3.2.2/dately.egg-info/PKG-INFO +0 -478
  10. {dately-3.2.2 → dately-3.2.4}/MANIFEST.in +0 -0
  11. {dately-3.2.2 → dately-3.2.4}/dately/__envutils.py +0 -0
  12. {dately-3.2.2 → dately-3.2.4}/dately/__init__.py +0 -0
  13. {dately-3.2.2 → dately-3.2.4}/dately/__os_config.py +0 -0
  14. {dately-3.2.2 → dately-3.2.4}/dately/__user_agents_config.py +0 -0
  15. {dately-3.2.2 → dately-3.2.4}/dately/_api.py +0 -0
  16. {dately-3.2.2 → dately-3.2.4}/dately/_connect.py +0 -0
  17. {dately-3.2.2 → dately-3.2.4}/dately/_holiday.py +0 -0
  18. {dately-3.2.2 → dately-3.2.4}/dately/_log.py +0 -0
  19. {dately-3.2.2 → dately-3.2.4}/dately/_mskutils.py +0 -0
  20. {dately-3.2.2 → dately-3.2.4}/dately/_proxy.py +0 -0
  21. {dately-3.2.2 → dately-3.2.4}/dately/_sysutils.py +0 -0
  22. {dately-3.2.2 → dately-3.2.4}/dately/_temporal_scan.py +0 -0
  23. {dately-3.2.2 → dately-3.2.4}/dately/_timeutils.py +0 -0
  24. {dately-3.2.2 → dately-3.2.4}/dately/_timezone.py +0 -0
  25. {dately-3.2.2 → dately-3.2.4}/dately/_utils.py +0 -0
  26. {dately-3.2.2 → dately-3.2.4}/dately/_webutils.py +0 -0
  27. {dately-3.2.2 → dately-3.2.4}/dately/core.py +0 -0
  28. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/__init__.py +0 -0
  29. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/arithmetic.py +0 -0
  30. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/lexical_validation/__init__.py +0 -0
  31. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/lexical_validation/vocabulary_checks.py +0 -0
  32. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/quantified_time.py +0 -0
  33. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/relative_time.py +0 -0
  34. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/semantic_validation/__init__.py +0 -0
  35. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/semantic_validation/unit_bounds.py +0 -0
  36. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/string_similarity/__init__.py +0 -0
  37. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/string_similarity/spell_correction.py +0 -0
  38. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/syntactic_validation/__init__.py +0 -0
  39. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/syntactic_validation/structure_validator.py +0 -0
  40. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/syntactic_validation/temporal_structure_rules.py +0 -0
  41. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/temporal_core/__init__.py +0 -0
  42. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/temporal_core/temporal_units.py +0 -0
  43. {dately-3.2.2 → dately-3.2.4}/dately/dt_nlp/temporal_preprocessing.py +0 -0
  44. {dately-3.2.2 → dately-3.2.4}/dately/files/__init__.py +0 -0
  45. {dately-3.2.2 → dately-3.2.4}/dately/files/country_variants.json +0 -0
  46. {dately-3.2.2 → dately-3.2.4}/dately/files/holiday.json +0 -0
  47. {dately-3.2.2 → dately-3.2.4}/dately/files/os_versions.json +0 -0
  48. {dately-3.2.2 → dately-3.2.4}/dately/files/timezone_data.json +0 -0
  49. {dately-3.2.2 → dately-3.2.4}/dately/files/user_agents.json +0 -0
  50. {dately-3.2.2 → dately-3.2.4}/dately/mold/__init__.py +0 -0
  51. {dately-3.2.2 → dately-3.2.4}/dately/mold/include/clean_str.h +0 -0
  52. {dately-3.2.2 → dately-3.2.4}/dately/mold/include/iso8601T.h +0 -0
  53. {dately-3.2.2 → dately-3.2.4}/dately/mold/include/iso8601Z.h +0 -0
  54. {dately-3.2.2 → dately-3.2.4}/dately/mold/include/root_dir_search.h +0 -0
  55. {dately-3.2.2 → dately-3.2.4}/dately/mold/include/time_zones.h +0 -0
  56. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/Compiled.cp38-win_amd64.pyd +0 -0
  57. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/__init__.py +0 -0
  58. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/cdatetime/UniversalDateFormatter.cp38-win_amd64.pyd +0 -0
  59. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/cdatetime/__init__.py +0 -0
  60. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/cdatetime/iso8601T.cp38-win_amd64.pyd +0 -0
  61. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/cdatetime/iso8601Z.cp38-win_amd64.pyd +0 -0
  62. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/cdatetime/whichformat.cp38-win_amd64.pyd +0 -0
  63. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/clean_str.cp38-win_amd64.pyd +0 -0
  64. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyd/time_zones.cp38-win_amd64.pyd +0 -0
  65. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/Compiled.pyx +0 -0
  66. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/UniversalDateFormatter.pyx +0 -0
  67. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/clean_str.pyx +0 -0
  68. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/iso8601T.pyx +0 -0
  69. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/iso8601Z.pyx +0 -0
  70. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/time_zones.pyx +0 -0
  71. {dately-3.2.2 → dately-3.2.4}/dately/mold/pyx/whichformat.pyx +0 -0
  72. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/Compiled.c +0 -0
  73. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/UniversalDateFormatter.c +0 -0
  74. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/clean_str.c +0 -0
  75. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/clean_str_impl.c +0 -0
  76. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/iso8601T.c +0 -0
  77. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/iso8601T_impl.c +0 -0
  78. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/iso8601Z.c +0 -0
  79. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/iso8601Z_impl.c +0 -0
  80. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/root_dir_search_impl.c +0 -0
  81. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/time_zones.c +0 -0
  82. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/time_zones_impl.c +0 -0
  83. {dately-3.2.2 → dately-3.2.4}/dately/mold/src/whichformat.c +0 -0
  84. {dately-3.2.2 → dately-3.2.4}/dately/tests/__init__.py +0 -0
  85. {dately-3.2.2 → dately-3.2.4}/dately/tests/test_parse.py +0 -0
  86. {dately-3.2.2 → dately-3.2.4}/dately.egg-info/SOURCES.txt +0 -0
  87. {dately-3.2.2 → dately-3.2.4}/dately.egg-info/dependency_links.txt +0 -0
  88. {dately-3.2.2 → dately-3.2.4}/dately.egg-info/requires.txt +0 -0
  89. {dately-3.2.2 → dately-3.2.4}/dately.egg-info/top_level.txt +0 -0
  90. {dately-3.2.2 → dately-3.2.4}/setup.cfg +0 -0
dately-3.2.4/PKG-INFO ADDED
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.1
2
+ Name: dately
3
+ Version: 3.2.4
4
+ Summary: A comprehensive Python library for advanced date and time manipulation.
5
+ Home-page: https://github.com/cedricmoorejr/dately/tree/v3.2.4
6
+ Author: Cedric Moore Jr.
7
+ Author-email: cedricmoorejunior5@gmail.com
8
+ License: MIT
9
+ Project-URL: Source Code, https://github.com/cedricmoorejr/dately/releases/tag/v3.2.4
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Natural Language :: English
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Requires-Python: >=3.8
20
+ Description-Content-Type: text/markdown
21
+
22
+ <p align="center">
23
+ <img src="https://raw.githubusercontent.com/cedricmoorejr/dately/main/dately/assets/py_dately_logo.png" alt="Dately Logo" width="700"/>
24
+ </p>
25
+
26
+
27
+ ---
28
+
29
+ <div align="center">
30
+
31
+ # 📅 **dately** 📅
32
+
33
+ > **Comprehensive Date, Time **& Natural-Language** Handling in Python**
34
+
35
+ </div>
36
+
37
+
38
+ `dately` is an end-to-end date-and-time toolkit that now pairs its high-precision formatting utilities with a **mini natural-language-processing (NLP) engine**. Whether you feed it an ISO-8601 timestamp, a plain month/day string, or a phrase like&nbsp;“second Tuesday of next quarter”, dately can turn it into an exact `datetime` object or `(start, end)` range.
39
+
40
+
41
+ [![Downloads](https://static.pepy.tech/badge/dately)](https://pepy.tech/project/dately)
42
+ [![Downloads](https://static.pepy.tech/badge/dately/month)](https://pepy.tech/project/dately)
43
+ [![Downloads](https://static.pepy.tech/badge/dately/week)](https://pepy.tech/project/dately)
44
+ [![Python](https://img.shields.io/pypi/pyversions/dately)](https://pypi.org/project/dately/)
45
+ [![PyPI](https://img.shields.io/pypi/v/dately)](https://pypi.org/project/dately/)
46
+ [![NLP Ready](https://img.shields.io/badge/NLP-enabled-brightgreen)]()
47
+ [![Powered by DOYDL Technologies](https://img.shields.io/badge/Powered%20by-DOYDL%20Technologies-blue)](https://doydl.com)
48
+ ---
49
+
50
+ #### Table of Contents
51
+ 1. [Why Choose dately?](#why-choose-dately)
52
+ 2. [Key Features](#key-features)
53
+ 3. [Solving Windows Date Formatting Issues](#solving-windows-date-formatting-issues)
54
+ 4. [Usage Examples](#usage-examples)
55
+
56
+ #### Why Choose dately?
57
+ - **Windows Optimized** – fixes `%‐m`/#zero-suppression inconsistencies on Windows.
58
+ - **NLP Inside** – understands expressions such as “last 5 weekends”, “Q4 2026”, “3 days ago starting from April 10”.
59
+ - **Comprehensive API** – parsing, detection, extraction and conversion for raw strings, `datetime` objects, pandas Series, NumPy arrays **and** free-text phrases.
60
+ - **High Performance** – Python + Cython hot-paths for heavy string/date workloads.
61
+
62
+ #### Key Features
63
+ 1. **Date and Time Format Detection**:
64
+ - Automatically detect various date and time formats from strings, ensuring seamless parsing and conversion.
65
+ - Supports a wide range of date formats, including standard and unique custom formats.
66
+ 2. **Timezone Management**:
67
+ - Provides detailed information for specific time zones.
68
+ - Converts time from one time zone to another.
69
+ - Retrieves the current time for specific time zones.
70
+ - Categorizes time zones by country, offset, and daylight saving time observance.
71
+ 3. **String Manipulation and Validation**:
72
+ - Extract specific components (year, month, day, hour, minute, second, timezone) from datetime strings.
73
+ - Validate and replace parts of datetime strings to ensure accuracy and consistency.
74
+ - Strip time and timezone information from datetime strings when needed.
75
+ 4. **Performance Optimizations**:
76
+ - Utilizes Cython to enhance performance for computationally intensive tasks.
77
+ - Interfaces with underlying C code to perform high-speed string operations and date validations.
78
+ 5. **Natural-Language Parsing** *(new!)*
79
+ - _Relative phrases_ `"next 2 Fridays" → [date, date]`
80
+ - _Range phrases_ `"first half of last year"`
81
+ - _Anchored clauses_ `"start of Q3 2024"`
82
+ - _Token normalisation_ (cardinal ↔︎ ordinal words, plural handling, etc.)
83
+ - Rule-based NLP pipeline: tokenisation → normalisation → pattern matching → date algebra.
84
+
85
+ #### Solving Windows Date Formatting Issues
86
+ A key aspect of this module is addressing inconsistencies in Python's date formatting on the Windows operating system. The module specifically targets the handling of the hyphen-minus (-) in date format specifiers. This flag, used to remove leading zeros from formatted output (e.g., turning '01' into '1' for January), works reliably on Unix-like systems but does not function as intended on Windows.
87
+
88
+ To solve this problem on Windows, the `dately` module introduces a workaround using regular expressions. It utilizes a detection function to determine the format string and then examines each date component for leading zeros through an extract_date_component function and a subsequent has_leading_zero check. Depending on the presence of leading zeros, the module adjusts the format string-replacing `%m` with `%-m` where applicable-to emulate the behavior expected from the hyphen-minus on Unix-like systems.
89
+
90
+ This method ensures that users on Windows achieve consistent date formatting, effectively compensating for the lack of native support for the hyphen-minus in date specifiers on this system.
91
+
92
+ Overall, `dately` is a powerful utility for anyone needing precise and flexible date and time handling in their applications, making it easier to manage, format, and validate date and time data consistently and efficiently.
93
+
94
+
95
+ ## Usage Examples - Working with Date Strings
96
+ To keep this README focused, all full-length usage examples are now available in the [`examples/`](https://github.com/cedricmoorejr/dately/tree/main/examples) folder.
97
+
98
+ You can explore them here:
99
+
100
+ - [Date Conversion & Formatting](examples/convert_dates.py)
101
+ - [Replacing Date Parts](examples/replace_datestring.py)
102
+ - [Time Zone Operations](examples/timezone_operations.py)
103
+ - [Natural Language Parsing (NLP)](examples/nlp_parsing.py)
104
+
105
+ Each file contains runnable code with expected outputs.
dately-3.2.4/README.md ADDED
@@ -0,0 +1,84 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/cedricmoorejr/dately/main/dately/assets/py_dately_logo.png" alt="Dately Logo" width="700"/>
3
+ </p>
4
+
5
+
6
+ ---
7
+
8
+ <div align="center">
9
+
10
+ # 📅 **dately** 📅
11
+
12
+ > **Comprehensive Date, Time **& Natural-Language** Handling in Python**
13
+
14
+ </div>
15
+
16
+
17
+ `dately` is an end-to-end date-and-time toolkit that now pairs its high-precision formatting utilities with a **mini natural-language-processing (NLP) engine**. Whether you feed it an ISO-8601 timestamp, a plain month/day string, or a phrase like&nbsp;“second Tuesday of next quarter”, dately can turn it into an exact `datetime` object or `(start, end)` range.
18
+
19
+
20
+ [![Downloads](https://static.pepy.tech/badge/dately)](https://pepy.tech/project/dately)
21
+ [![Downloads](https://static.pepy.tech/badge/dately/month)](https://pepy.tech/project/dately)
22
+ [![Downloads](https://static.pepy.tech/badge/dately/week)](https://pepy.tech/project/dately)
23
+ [![Python](https://img.shields.io/pypi/pyversions/dately)](https://pypi.org/project/dately/)
24
+ [![PyPI](https://img.shields.io/pypi/v/dately)](https://pypi.org/project/dately/)
25
+ [![NLP Ready](https://img.shields.io/badge/NLP-enabled-brightgreen)]()
26
+ [![Powered by DOYDL Technologies](https://img.shields.io/badge/Powered%20by-DOYDL%20Technologies-blue)](https://doydl.com)
27
+ ---
28
+
29
+ #### Table of Contents
30
+ 1. [Why Choose dately?](#why-choose-dately)
31
+ 2. [Key Features](#key-features)
32
+ 3. [Solving Windows Date Formatting Issues](#solving-windows-date-formatting-issues)
33
+ 4. [Usage Examples](#usage-examples)
34
+
35
+ #### Why Choose dately?
36
+ - **Windows Optimized** – fixes `%‐m`/#zero-suppression inconsistencies on Windows.
37
+ - **NLP Inside** – understands expressions such as “last 5 weekends”, “Q4 2026”, “3 days ago starting from April 10”.
38
+ - **Comprehensive API** – parsing, detection, extraction and conversion for raw strings, `datetime` objects, pandas Series, NumPy arrays **and** free-text phrases.
39
+ - **High Performance** – Python + Cython hot-paths for heavy string/date workloads.
40
+
41
+ #### Key Features
42
+ 1. **Date and Time Format Detection**:
43
+ - Automatically detect various date and time formats from strings, ensuring seamless parsing and conversion.
44
+ - Supports a wide range of date formats, including standard and unique custom formats.
45
+ 2. **Timezone Management**:
46
+ - Provides detailed information for specific time zones.
47
+ - Converts time from one time zone to another.
48
+ - Retrieves the current time for specific time zones.
49
+ - Categorizes time zones by country, offset, and daylight saving time observance.
50
+ 3. **String Manipulation and Validation**:
51
+ - Extract specific components (year, month, day, hour, minute, second, timezone) from datetime strings.
52
+ - Validate and replace parts of datetime strings to ensure accuracy and consistency.
53
+ - Strip time and timezone information from datetime strings when needed.
54
+ 4. **Performance Optimizations**:
55
+ - Utilizes Cython to enhance performance for computationally intensive tasks.
56
+ - Interfaces with underlying C code to perform high-speed string operations and date validations.
57
+ 5. **Natural-Language Parsing** *(new!)*
58
+ - _Relative phrases_ `"next 2 Fridays" → [date, date]`
59
+ - _Range phrases_ `"first half of last year"`
60
+ - _Anchored clauses_ `"start of Q3 2024"`
61
+ - _Token normalisation_ (cardinal ↔︎ ordinal words, plural handling, etc.)
62
+ - Rule-based NLP pipeline: tokenisation → normalisation → pattern matching → date algebra.
63
+
64
+ #### Solving Windows Date Formatting Issues
65
+ A key aspect of this module is addressing inconsistencies in Python's date formatting on the Windows operating system. The module specifically targets the handling of the hyphen-minus (-) in date format specifiers. This flag, used to remove leading zeros from formatted output (e.g., turning '01' into '1' for January), works reliably on Unix-like systems but does not function as intended on Windows.
66
+
67
+ To solve this problem on Windows, the `dately` module introduces a workaround using regular expressions. It utilizes a detection function to determine the format string and then examines each date component for leading zeros through an extract_date_component function and a subsequent has_leading_zero check. Depending on the presence of leading zeros, the module adjusts the format string-replacing `%m` with `%-m` where applicable-to emulate the behavior expected from the hyphen-minus on Unix-like systems.
68
+
69
+ This method ensures that users on Windows achieve consistent date formatting, effectively compensating for the lack of native support for the hyphen-minus in date specifiers on this system.
70
+
71
+ Overall, `dately` is a powerful utility for anyone needing precise and flexible date and time handling in their applications, making it easier to manage, format, and validate date and time data consistently and efficiently.
72
+
73
+
74
+ ## Usage Examples - Working with Date Strings
75
+ To keep this README focused, all full-length usage examples are now available in the [`examples/`](https://github.com/cedricmoorejr/dately/tree/main/examples) folder.
76
+
77
+ You can explore them here:
78
+
79
+ - [Date Conversion & Formatting](examples/convert_dates.py)
80
+ - [Replacing Date Parts](examples/replace_datestring.py)
81
+ - [Time Zone Operations](examples/timezone_operations.py)
82
+ - [Natural Language Parsing (NLP)](examples/nlp_parsing.py)
83
+
84
+ Each file contains runnable code with expected outputs.
@@ -52,52 +52,77 @@ import pandas as panda
52
52
 
53
53
  # ────────── Project-specific imports (directly from this project's source code) ─────────────────────────────
54
54
  from .mold.pyd.time_zones import time_zones_dict as tz_dict
55
-
55
+ from .dt_nlp.arithmetic import timeline
56
56
 
57
57
 
58
58
 
59
59
  #────────────────────────────────────────────────────────────────────────────
60
60
  # REGEX FOR DETECTING TIME COMPONENTS IN STRINGS
61
61
  #────────────────────────────────────────────────────────────────────────────
62
- # This regex pattern is used to detect time-related components in a string. It
63
- # supports various time formats, including standard clock times, fractional
64
- # seconds, AM/PM markers, and optional time zones.
65
- #
62
+ # This regex pattern detects time-related components in a string. It supports
63
+ # a wide range of time formats and time zone expressions, using a **whitelist**
64
+ # of valid timezone abbreviations (from `tz_dict`) instead of a generic pattern.
65
+ #
66
66
  # ### Pattern Details:
67
- # - Prevention of False Matches:
68
- # - Ensures the detected pattern is not preceded by a digit (`(?<!\d)`) to
69
- # avoid misinterpreting numbers as times.
70
- #
71
- # - Option 1: Standard Time Formats
72
- # - Matches times written as:
73
- # - `HH:MM`, `HH:MM:SS`, or compact form `HHMMSS`
74
- # - Supports fractional seconds (e.g., `12:30:45.123456`)
75
- # - Recognizes AM/PM markers (e.g., `3:45 PM`)
76
- # - Optionally detects time zones (e.g., `UTC`, `+02:00`, `Z`)
77
- #
78
- # - Option 2: Standalone Timezones
79
- # - Matches timezone-only strings if preceded by whitespace or start-of-string:
80
- # - `+02:00`, `-0400`, `EST`, `UTC`, `Z`
81
- #
82
- # - Lookahead (`(?=\s|$)`)
83
- # - Ensures the match must be followed by whitespace or end-of-string to
84
- # prevent partial matches inside words.
85
- #
67
+ #
68
+ # - **False Match Prevention:**
69
+ # - Ensures the match is not **preceded by a digit** (`(?<!\d)`) to avoid
70
+ # interpreting numbers like "1230" in "AB1230CD" as a time.
71
+ #
72
+ # - **Option 1: Standard Clock Times**
73
+ # - Matches time formats like:
74
+ # - `HH:MM`, `HH:MM:SS`, or `HHMMSS`
75
+ # - Optional fractional seconds (e.g., `.123456`)
76
+ # - Optional 12-hour markers (`AM`, `PM`)
77
+ # - Optional time zone suffixes, which may be:
78
+ # ▪ UTC offset: `+02:00`, `-0400`
79
+ # ▪ Time zone abbreviation from `tz_dict`: e.g., `EST`, `PST`, `UTC`
80
+ # ▪ The literal `Z` for Zulu/UTC
81
+ #
82
+ # - **Option 2: Standalone Timezones**
83
+ # - Matches a standalone timezone if it is:
84
+ # ▪ preceded by whitespace or the beginning of the string
85
+ # ▪ and matches one of the following:
86
+ # - UTC offsets (`+HH:MM`, `-HHMM`)
87
+ # - Approved abbreviations (from `tz_dict`)
88
+ # - `Z`
89
+ #
90
+ # - **Lookahead Requirement:**
91
+ # - A match must be **followed by whitespace or end-of-string** (`(?=\s|$)`)
92
+ # to avoid matching time inside words or identifiers.
93
+ #
94
+ # ### Key Enhancement:
95
+ # - Replaces open-ended `[A-Z]{3,4}` with a strict whitelist from `tz_dict`
96
+ # to avoid false positives (e.g., interpreting "Jan" as a timezone).
97
+ #
86
98
  # ### Use Case:
87
- # - Primarily used in date format detection to extract time components
88
- # from mixed datetime strings.
89
- # - Works in conjunction with the DateFormatFinder class.
99
+ # - Used by `DateFormatFinder` to extract and isolate time components from
100
+ # strings during format detection. This helps distinguish whether the
101
+ # string represents a full datetime or a date-only value.
102
+ # Collect the keys, drop the 12 month abbreviations just in case
103
+ _month_abbrs = {f.upper() for f in timeline.months if len(f) == 3}
104
+ _tz_abbrs = sorted({k.upper() for k in tz_dict.keys()} - _month_abbrs,
105
+ key=len, reverse=True) # longest first → greedy match
106
+ _tz_pattern = "|".join(map(re.escape, _tz_abbrs)) # escapes + joins with |
107
+
90
108
  _TIME_DETECTION_RE = re.compile(
91
- r"(?<!\d)(?:" # Ensure not preceded by a digit.
92
- r"(?:(?:\d{1,2}:\d{2}(?::\d{2})?|\d{6})" # Option 1: time formats (HH:MM, HH:MM:SS, or HHMMSS)
93
- r"(?:\.\d{1,6})?" # Optional fractional seconds.
94
- r"(?:\s*[AP]M)?" # Optional AM/PM marker.
95
- r"(?:\s*(?:[+-]\d{2}:?\d{2}|[+-]\d{4}|[A-Z]{3,4}|Z))?" # Optional timezone.
96
- r")"
97
- r"|" # OR
98
- r"(?:(?<=\s)|^)(?:[+-]\d{2}:?\d{2}|[+-]\d{4}|[A-Z]{3,4}|Z)" # Option 2: timezone-only; must be preceded by whitespace or start-of-string.
99
- r")(?=\s|$)", # Lookahead: must be followed by whitespace or end-of-string.
100
- re.IGNORECASE
109
+ rf"""
110
+ (?<!\d) # not preceded by a digit
111
+ (?: # ──────────────────────────────
112
+ # Option 1 — clock time, with optional zone
113
+ (?:
114
+ (?:\d{{1,2}}:\d{{2}}(?: :\d{{2}})? | \d{{6}})
115
+ (?:\.\d{{1,6}})? # fractional seconds
116
+ (?:\s*[AP]M)? # AM/PM
117
+ (?:\s*(?:[+-]\d{{2}}:?\d{{2}} | [+-]\d{{4}} | (?:{_tz_pattern}) | Z))?
118
+ )
119
+ |
120
+ # Option 2 — standalone timezone
121
+ (?:(?<=\s)|^) (?:[+-]\d{{2}}:?\d{{2}} | [+-]\d{{4}} | (?:{_tz_pattern}) | Z)
122
+ )
123
+ (?=\s|$) # must be followed by space or end
124
+ """,
125
+ re.IGNORECASE | re.VERBOSE
101
126
  )
102
127
 
103
128
  #────────────────────────────────────────────────────────────────────────────
@@ -6,7 +6,7 @@
6
6
  # execution—if applicable—encapsulated in class and function constructs.
7
7
  # In minimal implementations, this may simply define constants, metadata,
8
8
  # or serve as an interface placeholder.
9
- __version__ = "3.2.2"
9
+ __version__ = "3.2.4"
10
10
 
11
11
 
12
12
  __all__ = ['__version__']
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.1
2
+ Name: dately
3
+ Version: 3.2.4
4
+ Summary: A comprehensive Python library for advanced date and time manipulation.
5
+ Home-page: https://github.com/cedricmoorejr/dately/tree/v3.2.4
6
+ Author: Cedric Moore Jr.
7
+ Author-email: cedricmoorejunior5@gmail.com
8
+ License: MIT
9
+ Project-URL: Source Code, https://github.com/cedricmoorejr/dately/releases/tag/v3.2.4
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Natural Language :: English
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Requires-Python: >=3.8
20
+ Description-Content-Type: text/markdown
21
+
22
+ <p align="center">
23
+ <img src="https://raw.githubusercontent.com/cedricmoorejr/dately/main/dately/assets/py_dately_logo.png" alt="Dately Logo" width="700"/>
24
+ </p>
25
+
26
+
27
+ ---
28
+
29
+ <div align="center">
30
+
31
+ # 📅 **dately** 📅
32
+
33
+ > **Comprehensive Date, Time **& Natural-Language** Handling in Python**
34
+
35
+ </div>
36
+
37
+
38
+ `dately` is an end-to-end date-and-time toolkit that now pairs its high-precision formatting utilities with a **mini natural-language-processing (NLP) engine**. Whether you feed it an ISO-8601 timestamp, a plain month/day string, or a phrase like&nbsp;“second Tuesday of next quarter”, dately can turn it into an exact `datetime` object or `(start, end)` range.
39
+
40
+
41
+ [![Downloads](https://static.pepy.tech/badge/dately)](https://pepy.tech/project/dately)
42
+ [![Downloads](https://static.pepy.tech/badge/dately/month)](https://pepy.tech/project/dately)
43
+ [![Downloads](https://static.pepy.tech/badge/dately/week)](https://pepy.tech/project/dately)
44
+ [![Python](https://img.shields.io/pypi/pyversions/dately)](https://pypi.org/project/dately/)
45
+ [![PyPI](https://img.shields.io/pypi/v/dately)](https://pypi.org/project/dately/)
46
+ [![NLP Ready](https://img.shields.io/badge/NLP-enabled-brightgreen)]()
47
+ [![Powered by DOYDL Technologies](https://img.shields.io/badge/Powered%20by-DOYDL%20Technologies-blue)](https://doydl.com)
48
+ ---
49
+
50
+ #### Table of Contents
51
+ 1. [Why Choose dately?](#why-choose-dately)
52
+ 2. [Key Features](#key-features)
53
+ 3. [Solving Windows Date Formatting Issues](#solving-windows-date-formatting-issues)
54
+ 4. [Usage Examples](#usage-examples)
55
+
56
+ #### Why Choose dately?
57
+ - **Windows Optimized** – fixes `%‐m`/#zero-suppression inconsistencies on Windows.
58
+ - **NLP Inside** – understands expressions such as “last 5 weekends”, “Q4 2026”, “3 days ago starting from April 10”.
59
+ - **Comprehensive API** – parsing, detection, extraction and conversion for raw strings, `datetime` objects, pandas Series, NumPy arrays **and** free-text phrases.
60
+ - **High Performance** – Python + Cython hot-paths for heavy string/date workloads.
61
+
62
+ #### Key Features
63
+ 1. **Date and Time Format Detection**:
64
+ - Automatically detect various date and time formats from strings, ensuring seamless parsing and conversion.
65
+ - Supports a wide range of date formats, including standard and unique custom formats.
66
+ 2. **Timezone Management**:
67
+ - Provides detailed information for specific time zones.
68
+ - Converts time from one time zone to another.
69
+ - Retrieves the current time for specific time zones.
70
+ - Categorizes time zones by country, offset, and daylight saving time observance.
71
+ 3. **String Manipulation and Validation**:
72
+ - Extract specific components (year, month, day, hour, minute, second, timezone) from datetime strings.
73
+ - Validate and replace parts of datetime strings to ensure accuracy and consistency.
74
+ - Strip time and timezone information from datetime strings when needed.
75
+ 4. **Performance Optimizations**:
76
+ - Utilizes Cython to enhance performance for computationally intensive tasks.
77
+ - Interfaces with underlying C code to perform high-speed string operations and date validations.
78
+ 5. **Natural-Language Parsing** *(new!)*
79
+ - _Relative phrases_ `"next 2 Fridays" → [date, date]`
80
+ - _Range phrases_ `"first half of last year"`
81
+ - _Anchored clauses_ `"start of Q3 2024"`
82
+ - _Token normalisation_ (cardinal ↔︎ ordinal words, plural handling, etc.)
83
+ - Rule-based NLP pipeline: tokenisation → normalisation → pattern matching → date algebra.
84
+
85
+ #### Solving Windows Date Formatting Issues
86
+ A key aspect of this module is addressing inconsistencies in Python's date formatting on the Windows operating system. The module specifically targets the handling of the hyphen-minus (-) in date format specifiers. This flag, used to remove leading zeros from formatted output (e.g., turning '01' into '1' for January), works reliably on Unix-like systems but does not function as intended on Windows.
87
+
88
+ To solve this problem on Windows, the `dately` module introduces a workaround using regular expressions. It utilizes a detection function to determine the format string and then examines each date component for leading zeros through an extract_date_component function and a subsequent has_leading_zero check. Depending on the presence of leading zeros, the module adjusts the format string-replacing `%m` with `%-m` where applicable-to emulate the behavior expected from the hyphen-minus on Unix-like systems.
89
+
90
+ This method ensures that users on Windows achieve consistent date formatting, effectively compensating for the lack of native support for the hyphen-minus in date specifiers on this system.
91
+
92
+ Overall, `dately` is a powerful utility for anyone needing precise and flexible date and time handling in their applications, making it easier to manage, format, and validate date and time data consistently and efficiently.
93
+
94
+
95
+ ## Usage Examples - Working with Date Strings
96
+ To keep this README focused, all full-length usage examples are now available in the [`examples/`](https://github.com/cedricmoorejr/dately/tree/main/examples) folder.
97
+
98
+ You can explore them here:
99
+
100
+ - [Date Conversion & Formatting](examples/convert_dates.py)
101
+ - [Replacing Date Parts](examples/replace_datestring.py)
102
+ - [Time Zone Operations](examples/timezone_operations.py)
103
+ - [Natural Language Parsing (NLP)](examples/nlp_parsing.py)
104
+
105
+ Each file contains runnable code with expected outputs.
@@ -30,7 +30,7 @@ if _TESTING_ == 1:
30
30
  name='datelynew',
31
31
  # version="3.0.2",
32
32
  version=version_str, # Default to "0.0.0" if not found
33
- packages=find_packages(exclude=["*.github", "*.__user_agents_config*", "*.__os_config*", "*wip"]),
33
+ packages=find_packages(exclude=["*.github", "*.__user_agents_config*", "*.__os_config*", "*wip", "*examples"]),
34
34
  package_data={
35
35
  'datelynew': [
36
36
  'mold/pyd/*.pyd',
@@ -65,7 +65,7 @@ else:
65
65
  project_urls={
66
66
  'Source Code': f'https://github.com/cedricmoorejr/dately/releases/tag/v{version_str}',
67
67
  },
68
- packages=find_packages(exclude=["*.github", "*.__user_agents_config*", "*.__os_config*", "*wip"]),
68
+ packages=find_packages(exclude=["*.github", "*.__user_agents_config*", "*.__os_config*", "*wip", "*examples"]),
69
69
  package_data={
70
70
  'dately': [
71
71
  'mold/pyd/*.pyd',