Release v0.5

.all-contributorsrc

@@ -68,6 +68,16 @@
         "test",
         "doc"
       ]
+    },
+    {
+      "login": "taylor-arnold",
+      "name": "Taylor Arnold",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5752184?v=4",
+      "profile": "http://taylorarnold.org",
+      "contributions": [
+        "review",
+        "ideas"
+      ]
     }
   ],
   "contributorsPerLine": 7,
@@ -77,5 +87,6 @@
   "repoHost": "https://github.com",
   "projectName": "undate-python",
   "projectOwner": "dh-tech",
-  "badgeTemplate": "![All Contributors](https://img.shields.io/github/all-contributors/dh-tech/undate-python?color=ee8449&style=flat-square)"
+  "badgeTemplate": "![All Contributors](https://img.shields.io/github/all-contributors/dh-tech/undate-python?color=ee8449&style=flat-square)",
+  "commitType": "docs"
 }

.github/workflows/check.yml

@@ -3,6 +3,9 @@ name: Check style + docs + types
 on:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   check:
     runs-on: ubuntu-latest

.github/workflows/unit_tests.yml

@@ -1,5 +1,9 @@
 name: unit tests
 
+permissions:
+  contents: read
+  id-token: write
+
 on:
   push:
     branches:
@@ -33,26 +37,25 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: '**/pyproject.toml'
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
-
-      - name: Install package with dev and test dependencies
-        run: uv sync --extra test
+      - name: Install package with dependencies
+        run: pip install -e ".[test]"
 
       # for all versions but the one we use for code coverage, run normally
-      - name: Run unit tests normally
-        run: uv run pytest
+      - name: Run unit tests without code coverage
+        run: pytest
         if: ${{ matrix.python != env.COV_PYTHON_VERSION }}
 
       # run code coverage in one version only
       - name: Run unit tests with code coverage reporting
-        run: uv run pytest --cov=undate
+        run: pytest --cov=.
         if: ${{ matrix.python == env.COV_PYTHON_VERSION }}
-      - name: Upload test coverage to Codecov
-        uses: codecov/codecov-action@v3
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         if: ${{ matrix.python == env.COV_PYTHON_VERSION }}
 

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## 0.5
+
+- New `UnDelta` and `UnInt` classes for uncertain durations
+  - `Undate.duration` now returns either a `Timedelta` or an `UnDelta` if the duration is ambiguous
+- New properties `possible_years` and `representative_years` on `Undate` class, used for calculating durations for uncertain years and months
+- New `weekday` method on class `undate.date.Date`
+- Calendar converter improvements:
+  - Calendar converter classes can optional provide minimum and maximum years for uncertain dates
+  - New calendar methods `days_in_year` and `representative_years`
+  - Hebrew date parser now allows for week days, along with additional month variants
+  - Preliminary Seleucide calendar converter class, based on Hebrew calendar with a year offset
+  - New method `as_calendar` on `Undate` class, to set calendar without doing any conversion
+- Readme examples have been improved and extended
+- New example notebook testing Hebrew, Islamic, and Seleucid date parsing and conversion with Princeton Geniza Project data
+- bugfix: duration for uncertain years previously returned the duration from earliest to latest possible dates in range; now returns an `UnDelta` with the possible durations for the possible years in the given calendar
+
 ## 0.4
 
 - Undate is now Calendar aware / Calendar explicit; default is Gregorian
@@ -20,7 +36,6 @@
 - Reorganized examples folder to avoid unnecessary nesting
   - ISMI data has been updated from older JSON data to examples in RDF (turtle)
 
-
 ## 0.3.1
 
 Update readthedocs config for current installation
@@ -49,7 +64,7 @@ Update readthedocs config for current installation
 
 ### numpy impact
 
-Performance differences seem to be negligible, but it does increase payload size.  The virtualenv for installing version 0.2 was 14MB; when installing the newer version with numpy, the virtualenv is 46MB (the numpy folder in site packages is 31MB on its own).
+Performance differences seem to be negligible, but it does increase payload size. The virtualenv for installing version 0.2 was 14MB; when installing the newer version with numpy, the virtualenv is 46MB (the numpy folder in site packages is 31MB on its own).
 
 ## 0.2
 

CONTRIBUTORS.md

@@ -19,6 +19,7 @@ We use [All Contributors](https://allcontributors.org/) because we recognize tha
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/robcast"><img src="https://avatars.githubusercontent.com/u/1488847?v=4?s=100" width="100px;" alt="Robert Casties"/><br /><sub><b>Robert Casties</b></sub></a><br /><a href="#data-robcast" title="Data">🔣</a> <a href="#ideas-robcast" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Arobcast" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jdamerow"><img src="https://avatars.githubusercontent.com/u/8881141?v=4?s=100" width="100px;" alt="Julia Damerow"/><br /><sub><b>Julia Damerow</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=jdamerow" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Ajdamerow" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=jdamerow" title="Tests">⚠️</a> <a href="#eventOrganizing-jdamerow" title="Event Organizing">📋</a> <a href="#ideas-jdamerow" title="Ideas, Planning, & Feedback">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/maltevogl"><img src="https://avatars.githubusercontent.com/u/20907912?v=4?s=100" width="100px;" alt="Malte Vogl"/><br /><sub><b>Malte Vogl</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Amaltevogl" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Tests">⚠️</a> <a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://taylorarnold.org"><img src="https://avatars.githubusercontent.com/u/5752184?v=4?s=100" width="100px;" alt="Taylor Arnold"/><br /><sub><b>Taylor Arnold</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Ataylor-arnold" title="Reviewed Pull Requests">👀</a> <a href="#ideas-taylor-arnold" title="Ideas, Planning, & Feedback">🤔</a></td>
     </tr>
   </tbody>
   <tfoot>

README.md

@@ -5,34 +5,60 @@
 **undate** is a python library for working with uncertain or partially known dates.
 
 > [!WARNING]
-> This is alpha software and is not yet feature complete! Use with caution and give us feedback.
-> Currently `undate` supports parsing and formatting dates in ISO8601, some 
-portions of EDTF (Extended Date Time Format), and parsing and conversion for dates in Hebrew Anno Mundi and Islamic Hijri calendars
+> This is beta software and is not yet feature complete! Use with caution and give us feedback.
+> Currently `undate` supports parsing and formatting dates in ISO8601, some
+> portions of EDTF (Extended Date Time Format), and parsing and conversion for dates in Hebrew Anno Mundi and Islamic Hijri calendars.
 
-*Undate was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022.*
+_Undate was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022._
 
-* * * 
+---
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11068867.svg)](https://doi.org/10.5281/zenodo.11068867)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Documentation Status](https://readthedocs.org/projects/undate-python/badge/?version=latest)](https://undate-python.readthedocs.io/en/latest/?badge=latest)
 [![unit tests](https://github.com/dh-tech/undate-python/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/dh-tech/undate-python/actions/workflows/unit_tests.yml)
 [![codecov](https://codecov.io/gh/dh-tech/undate-python/branch/main/graph/badge.svg?token=GE7HZE8C9D)](https://codecov.io/gh/dh-tech/undate-python)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+
 [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](CONTRIBUTORS.md)
+
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 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.
+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.
+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)
@@ -46,12 +72,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)
@@ -68,7 +96,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)
@@ -86,7 +116,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)
@@ -104,7 +137,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)
@@ -118,17 +152,22 @@ 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.undate import UndateInterval
+>>> from undate import UndateInterval
 >>> UndateInterval(Undate(1900), Undate(2000))
 <UndateInterval 1900/2000>
->>> UndateInterval(Undate(1900), Undate(2000), label="19th century")
->>> UndateInterval(Undate(1900), Undate(2000), label="19th century").duration().days
-36890
-<UndateInterval '19th century' (1900/2000)>
->>> UndateInterval(Undate(1900), Undate(2000), label="20th century")
-<UndateInterval '20th century' (1900/2000)>
+>>> UndateInterval(Undate(1801), Undate(1900), label="19th century")
+>>> UndateInterval(Undate(1801), Undate(1900), label="19th century").duration().days
+36524
+<UndateInterval '19th century' (1801/1900)>
+>>> UndateInterval(Undate(1901), Undate(2000), label="20th century")
+<UndateInterval '20th century' (1901/2000)>
 >>> UndateInterval(latest=Undate(2000))  # before 2000
 <UndateInterval ../2000>
 >>> UndateInterval(Undate(1900))  # after 1900
@@ -139,8 +178,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
@@ -158,9 +199,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
@@ -181,9 +230,11 @@ Dates are stored with the year, month, day and appropriate precision for the ori
 [<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>, <Undate 'Rajab 495 Hijrī' 0495-07 (Islamic)>, <Undate 2001 (Gregorian)>]
 ```
 
-* * * 
+---
 
-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
 

codecov.yml

@@ -0,0 +1,14 @@
+coverage:
+  status:
+    project:
+      default: false  # disable default status check
+      app:  # custom target for app code
+        target: auto  # default target (95%)
+        paths:
+          - "src/"  # limit to files within src code directory
+      tests:  # declare a new status context  for "tests"
+        target: 100%  # we always want 100% coverage here
+        paths:
+          - "tests/"  # only include coverage in "tests/" folder
+
+