From 75e641c5475a38f687648acd4be14d9fa3609944 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 22 May 2025 16:13:26 -0400 Subject: [PATCH 1/4] Add installation instructions and fix century dates --- README.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c6e3560..914cb11 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,21 @@ portions of EDTF (Extended Date Time Format), and parsing and conversion for dat Read [Contributors](CONTRIBUTORS.md) for detailed contribution information. +## Installation + +*Recommended*: use pip to install the latest published version from PyPI: + +```console +pip install undate +``` + +To install a development version or specific tag or branch, you can install from GitHub. +Use the `@name` notation to specify the branch or tag; e.g., to install development version: + +```console +pip install git+https://github.com/dh-tech/undate-python@develop#egg=undate +``` + ## Example Usage Often humanities and cultural data include imprecise or uncertain temporal information. We want to store that information but also work with it in a structured way, not just treat it as text for display. Different projects may need to work with or convert between different date formats or even different calendars. @@ -123,12 +138,12 @@ An `UndateInterval` is a date range between two `Undate` objects. Intervals can >>> from undate.undate import UndateInterval >>> UndateInterval(Undate(1900), Undate(2000)) ->>> UndateInterval(Undate(1900), Undate(2000), label="19th century") ->>> UndateInterval(Undate(1900), Undate(2000), label="19th century").duration().days -36890 - ->>> UndateInterval(Undate(1900), Undate(2000), label="20th century") - +>>> UndateInterval(Undate(1801), Undate(1900), label="19th century") +>>> UndateInterval(Undate(1801), Undate(1900), label="19th century").duration().days +36524 + +>>> UndateInterval(Undate(1901), Undate(2000), label="20th century") + >>> UndateInterval(latest=Undate(2000)) # before 2000 >>> UndateInterval(Undate(1900)) # after 1900 From 473da51e3b9e4293aad937de6264f2edf2e9f780 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 22 May 2025 16:13:41 -0400 Subject: [PATCH 2/4] Increase version number for next release --- src/undate/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/undate/__init__.py b/src/undate/__init__.py index 0976d0e..2207ffc 100644 --- a/src/undate/__init__.py +++ b/src/undate/__init__.py @@ -1,4 +1,4 @@ -__version__ = "0.4.0" +__version__ = "0.5.0.dev0" from undate.date import DatePrecision from undate.undate import Undate, Calendar From 47a6c57aefa92804d70c0166a3212d13b9ca2ed1 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 22 May 2025 16:20:26 -0400 Subject: [PATCH 3/4] Fix typo flagged by @coderabbitai; fix ordering and simplify imports --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 914cb11..82e5be5 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Often humanities and cultural data include imprecise or uncertain temporal infor An `undate.Undate` is analogous to python’s builtin `datetime.date` object, but with support for varying degrees of precision and unknown information. You can initialize an undate with either strings or numbers for whichever parts of the date are known or partially known. An `Undate` can take an optional label. ```python -from undate.undate import Undate +from undate import Undate november7 = Undate(2000, 11, 7) november = Undate(2000, 11) @@ -135,13 +135,13 @@ NotImplementedError: Can't compare when one date falls within the other An `UndateInterval` is a date range between two `Undate` objects. Intervals can be open-ended, allow for optional labels, and can calculate duration if enough information is known ```python ->>> from undate.undate import UndateInterval +>>> from undate import UndateInterval >>> UndateInterval(Undate(1900), Undate(2000)) >>> UndateInterval(Undate(1801), Undate(1900), label="19th century") >>> UndateInterval(Undate(1801), Undate(1900), label="19th century").duration().days 36524 - + >>> UndateInterval(Undate(1901), Undate(2000), label="20th century") >>> UndateInterval(latest=Undate(2000)) # before 2000 From e01c0657bf3ebcb14dd064e419c13c40b6e82110 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Fri, 23 May 2025 09:34:49 -0400 Subject: [PATCH 4/4] Add a note that intervals are inclusive/closed; improve formatting --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 82e5be5..f894fed 100644 --- a/README.md +++ b/README.md @@ -42,9 +42,17 @@ pip install git+https://github.com/dh-tech/undate-python@develop#egg=undate ## Example Usage -Often humanities and cultural data include imprecise or uncertain temporal information. We want to store that information but also work with it in a structured way, not just treat it as text for display. Different projects may need to work with or convert between different date formats or even different calendars. - -An `undate.Undate` is analogous to python’s builtin `datetime.date` object, but with support for varying degrees of precision and unknown information. You can initialize an undate with either strings or numbers for whichever parts of the date are known or partially known. An `Undate` can take an optional label. +Often humanities and cultural data include imprecise or uncertain +temporal information. We want to store that information but also work +with it in a structured way, not just treat it as text for display. +Different projects may need to work with or convert between different +date formats or even different calendars. + +An `undate.Undate` is analogous to python’s builtin `datetime.date` +object, but with support for varying degrees of precision and unknown +information. You can initialize an `Undate` with either strings or +numbers for whichever parts of the date are known or partially known. +An `Undate` can take an optional label. ```python from undate import Undate @@ -61,12 +69,14 @@ easter1916 = Undate(1916, 4, 23, label="Easter 1916") ``` You can convert an `Undate` to string using a date formatter (current default is ISO8601): + ```python >>> [str(d) for d in [november7, november, year2k, november7_some_year]] ['2000-11-07', '2000-11', '2000', '--11-07'] ``` If enough information is known, an `Undate` object can report on its duration: + ```python >>> december = Undate(2000, 12) >>> feb_leapyear = Undate(2024, 2) @@ -83,7 +93,9 @@ If enough information is known, an `Undate` object can report on its duration: 2024-02 - duration in days: 29 ``` -If enough of the date is known and the precision supports it, you can check if one date falls within another date: +If enough of the date is known and the precision supports it, you can +check if one date falls within another date: + ```python >>> november7 = Undate(2000, 11, 7) >>> november2000 = Undate(2000, 11) @@ -101,7 +113,10 @@ False False ``` -For dates that are imprecise or partially known, `undate` calculates earliest and latest possible dates for comparison purposes so you can sort dates and compare with equals, greater than, and less than. You can also compare with python `datetime.date` objects. +For dates that are imprecise or partially known, `undate` calculates +earliest and latest possible dates for comparison purposes so you can +sort dates and compare with equals, greater than, and less than. You +can also compare with python `datetime.date` objects. ```python >>> november7_2020 = Undate(2020, 11, 7) @@ -119,7 +134,8 @@ False False ``` -When dates cannot be compared due to ambiguity or precision, comparison methods raise a `NotImplementedError`. +When dates cannot be compared due to ambiguity or precision, comparison +methods raise a `NotImplementedError`. ```python >>> november_2020 = Undate(2020, 11) @@ -133,7 +149,12 @@ Traceback (most recent call last): NotImplementedError: Can't compare when one date falls within the other ``` -An `UndateInterval` is a date range between two `Undate` objects. Intervals can be open-ended, allow for optional labels, and can calculate duration if enough information is known +An `UndateInterval` is a date range between two `Undate` objects. +Intervals can be open-ended, allow for optional labels, and can +calculate duration if enough information is known. `UndateIntervals` +are inclusive (i.e., a closed interval), and include both the earliest +and latest date as part of the range. + ```python >>> from undate import UndateInterval >>> UndateInterval(Undate(1900), Undate(2000)) @@ -154,8 +175,10 @@ An `UndateInterval` is a date range between two `Undate` objects. Intervals can 31 ``` -You can initialize `Undate` or `UndateInterval` objects by parsing a date string with a specific converter, and you can also output an `Undate` object in those formats. -Currently available converters are "ISO8601" and "EDTF" and supported calendars. +You can initialize `Undate` or `UndateInterval` objects by parsing a +date string with a specific converter, and you can also output an +`Undate` object in those formats. Currently available converters +are "ISO8601" and "EDTF" and supported calendars. ```python >>> from undate import Undate @@ -173,9 +196,17 @@ Currently available converters are "ISO8601" and "EDTF" and supported calendars. ### Calendars -All `Undate` objects are calendar aware, and date converters include support for parsing and working with dates from other calendars. The Gregorian calendar is used by default; currently `undate` supports the Islamic Hijri calendar and the Hebrew Anno Mundi calendar based on calendar conversion logic implemented in the [convertdate](https://convertdate.readthedocs.io/en/latest/) package. +All `Undate` objects are calendar aware, and date converters include +support for parsing and working with dates from other calendars. The +Gregorian calendar is used by default; currently `undate` supports the +Islamic Hijri calendar and the Hebrew Anno Mundi calendar based on +calendar conversion logic implemented in the +[convertdate](https://convertdate.readthedocs.io/en/latest/) package. -Dates are stored with the year, month, day and appropriate precision for the original calendar; internally, earliest and latest dates are calculated in Gregorian / Proleptic Gregorian calendar for standardized comparison across dates from different calendars. +Dates are stored with the year, month, day and appropriate precision for +the original calendar; internally, earliest and latest dates are +calculated in Gregorian / Proleptic Gregorian calendar for standardized +comparison across dates from different calendars. ```python >>> from undate import Undate @@ -198,7 +229,9 @@ Dates are stored with the year, month, day and appropriate precision for the ori * * * -For more examples, refer to the code notebooks included in the [examples](https://github.com/dh-tech/undate-python/tree/main/examples/) in this repository. +For more examples, refer to the code notebooks included in the[examples] +(https://github.com/dh-tech/undate-python/tree/main/examples/) in this +repository. ## Documentation