Merge pull request #118 from dh-tech/release/0.4

Release v0.4

Author: rlskoeser

.github/workflows/check.yml

@@ -17,23 +17,28 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-          cache: 'pip'
-          cache-dependency-path: '**/pyproject.toml'
-      - name: Install package with development dependencies
-        run: pip install -e ".[dev]"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install package with check dependencies
+        run: uv sync --extra check
 
       # check with ruff
       - name: Run ruff
-        run: ruff check
+        run: uv run ruff check
 
       # check docs build
       - name: Check that documentation builds with no errors or warnings
-        run: sphinx-build docs docs/_build --fail-on-warning
+        run: uv run sphinx-build docs docs/_build --fail-on-warning
 
       # check types with mypy
       - name: Check types in python src directory; install needed types
-        run: mypy --install-types --non-interactive src
+        run: uv run mypy --install-types --non-interactive src
 
       # use treon to make sure that example notebooks run
       - name: Check jupyter notebooks with treon
-        run: treon
+        run: uv run treon

.github/workflows/unit_tests.yml

@@ -8,6 +8,8 @@ on:
       - 'undate/**'
       - 'tests/**'
   pull_request:
+    branches:
+      - "**"
 
 env:
   # python version used to calculate and submit code coverage
@@ -18,30 +20,37 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python: ["3.10", "3.11", "3.12", "3.13"]
     defaults:
       run:
         working-directory: .
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+
+      # use github python action instead of uv to take advantage of caching
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
-          cache: 'pip'
-          cache-dependency-path: '**/pyproject.toml'
-      - name: Install package with dependencies
-        run: pip install -e ".[test]"
+
+      - 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
 
       # for all versions but the one we use for code coverage, run normally
       - name: Run unit tests normally
-        run: pytest
+        run: uv 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: pytest --cov=undate
+        run: uv run pytest --cov=undate
         if: ${{ matrix.python == env.COV_PYTHON_VERSION }}
       - name: Upload test coverage to Codecov
         uses: codecov/codecov-action@v3

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change Log
 
+## 0.4
+
+- Undate is now Calendar aware / Calendar explicit; default is Gregorian
+  - New `BaseCalendarConverter` class, with additional methods required for calendar converters
+  - `HebrewDateConverter`: Parsing and calendar conversion for Hebrew/Anno Mundi
+  - `IslamicDateConverter`: Parsing and calendar conversion for Islamic/Hijri
+  - `GregorianDateConverter`: basic Gregorian calendar logic
+  - `undate.Calendar` class to track `Undate` object calendar, and match with calendar converters
+- BaseDateConverter class now includes nested/descendant subclasses when looking
+  for available converters
+- `Undate.to_undate` method to convert supported date objects to `Undate` (`datetime.date`, `datetime.datetime`, and internal `undate.date.Date` class)
+- `UndateInterval` improvements
+  - Can be initialized with `Undate` objects or any type supported by `Undate.to_undate`
+  - New method for contains (`in`), to determine if another interval or date is contained by an interval
+  - New method `intersection` to determine the overlap between two `UndateInterval` objects
+- EDTF parser : fixed day parsing for some unsupported cases
+- Dropped support for Python 3.9
+- 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
@@ -14,7 +35,7 @@ Update readthedocs config for current installation
   - Support 5+ digit years with leading Y (thanks to numpy.datetime64)
   - Jupyter notebook demonstrating / validating EDTF support
     - Full support for Level 0 Date and Time Interval (no Date and Time support)
-    - Level 1: 
+    - Level 1:
       - Letter-prefixed calendar year
       - Unspecified digit from the right
       - Partial support for extended interval

README.md

@@ -5,13 +5,13 @@
 **undate** is a python library for working with uncertain or partially known dates.
 
 > [!WARNING]
-> This is pre-alpha software and is **NOT** feature complete! Use with caution.
-> Currently it only supports parsing and formatting dates in ISO8601 format and
-> some portions of EDTF (Extended Date Time Format).
+> 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
 
 *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)
@@ -140,7 +140,7 @@ An `UndateInterval` is a date range between two `Undate` objects. Intervals can
 ```
 
 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.
-Available converters are "ISO8601" and "EDTF" (but only)
+Currently available converters are "ISO8601" and "EDTF" and supported calendars.
 
 ```python
 >>> from undate import Undate
@@ -156,7 +156,34 @@ Available converters are "ISO8601" and "EDTF" (but only)
 <UndateInterval 1800/1900>
 ```
 
-For more examples, refer to the [example notebooks](https://github.com/dh-tech/undate-python/tree/main/examples/notebooks/) included in this repository.
+### 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. 
+
+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
+>>> tammuz4816 = Undate.parse("26 Tammuz 4816", "Hebrew")
+>>> tammuz4816
+<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>
+>>> rajab495 = Undate.parse("Rajab 495", "Islamic")
+>>> rajab495
+<Undate 'Rajab 495 Hijrī' 0495-07 (Islamic)>
+>>> y2k = Undate.parse("2001", "EDTF")
+>>> y2k
+<Undate 2001 (Gregorian)>
+>>> [str(d.earliest) for d in [rajab495, tammuz4816, y2k]]
+['1102-04-28', '1056-07-17', '2001-01-01']
+>>> [str(d.precision) for d in [rajab495, tammuz4816, y2k]]
+['MONTH', 'DAY', 'YEAR']
+>>> sorted([rajab495, tammuz4816, y2k])
+[<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.
 
 ## Documentation
 

docs/undate/converters.rst

@@ -1,19 +1,25 @@
 Converters
 ==========
 
+Overview
+--------
+
 .. automodule:: undate.converters.base
    :members:
    :undoc-members:
 
+Formats
+--------
+
 ISO8601
--------
+^^^^^^^
 
 .. automodule:: undate.converters.iso8601
    :members:
    :undoc-members:
 
 Extended Date-Time Format (EDTF)
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: undate.converters.edtf.converter
    :members:
@@ -23,8 +29,25 @@ Extended Date-Time Format (EDTF)
    :members:
    :undoc-members:
 
-.. transformer is more of an internal, probably doesn't make sense to include
-.. .. automodule:: undate.converters.edtf.transformer
-..    :members:
-..    :undoc-members:
+
+Calendars
+---------
+
+Gregorian
+^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.gregorian
+   :members:
+
+Hebrew Anno Mundi calendar
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.hebrew.converter
+   :members:
+
+Islamic Hijri calendar
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.islamic.converter
+   :members:
 

docs/undate/core.rst

@@ -1,13 +1,16 @@
 Undate objects
 ==============
 
-undates and undate intervals
+dates, intervals, and calendar
 ------------------------------
 
 .. autoclass:: undate.undate.Undate
    :members:
 
-.. autoclass:: undate.undate.UndateInterval
+.. autoclass:: undate.undate.Calendar
+   :members:
+
+.. autoclass:: undate.interval.UndateInterval
    :members:
 
 date, timedelta, and date precision

examples/README.md

@@ -1,7 +1,13 @@
 # undate examples
 
-Example data and projects with use cases for uncertain date logic and 
-example code notebooks using undate.
-
-- [use cases](use-cases) - examples from projects or specific data with use cases for undate
-- [notebooks](notebooks) - code notebooks showing how undate can be used on a specific dataset or for a specific problem
+This folder contains code notebooks demonstrating how `undate` can be 
+used on a specific dataset, problem, or format, as well as example 
+data from projects with use cases for uncertain date logic.
+ 
+## Contents 
+ 
+- [EDTF support](edtf-support.ipynb) - demonstrate and validate supported portions of the Extended Date Time Format (EDTF) specification (jupyter notebook)
+- [ISMI](ismi) - Sample data from the Islamic Scientific Manuscript Initiative project
+- [Shakespeare and Company Project](shakespeare-and-company-project) - data, description of partial date implementation, and example notebook
+  - Events data from version 1.2 of Shakespeare and Company Project datasets
+  - [Partial date duration logic](shakespeare-and-company-project/shxco_partial_date_durations.ipynb) - compare `undate` partial date range duration logic with a previous implementation in the _Shakespeare and Company Project_ (jupyter notebook)

examples/notebooks/edtf-support.ipynb renamed to examples/edtf-support.ipynb

@@ -55,7 +55,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "id": "9c6b7379-b2a7-4ec1-afa5-2cd9832c8a5d",
    "metadata": {},
    "outputs": [],
@@ -92,7 +92,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 2,
    "id": "923476ff-344a-4018-a02e-6e5f80ea76a8",
    "metadata": {},
    "outputs": [],
@@ -159,7 +159,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "6ed422de-34a2-4324-b254-f62db00563f7",
    "metadata": {},
    "outputs": [],
@@ -212,7 +212,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "id": "8d98a139-627b-40bd-b1c5-d0028e538a53",
    "metadata": {},
    "outputs": [],
@@ -255,7 +255,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 5,
    "id": "532470db-851e-4f91-9242-cd93d35054cf",
    "metadata": {},
    "outputs": [],
@@ -320,7 +320,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 6,
    "id": "a5abd0e4-0b26-49b0-bf78-3e1fe6c046d8",
    "metadata": {},
    "outputs": [],
@@ -425,7 +425,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "id": "e47f3fff-d35c-4c2e-9568-214763f6511a",
    "metadata": {},
    "outputs": [],
@@ -481,7 +481,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "id": "39143c1f-932a-450c-9b2d-ffbe3e1416b0",
    "metadata": {},
    "outputs": [],
@@ -535,7 +535,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 9,
    "id": "95965f17-0bd5-446f-bc09-9503eaed68e2",
    "metadata": {},
    "outputs": [],
@@ -589,7 +589,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "id": "c6c2d1a1-39f1-45eb-ac08-1de4fadbe842",
    "metadata": {},
    "outputs": [],
@@ -640,7 +640,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 11,
    "id": "f24fd31a-176a-40b5-bff4-d72b68f32a18",
    "metadata": {},
    "outputs": [],
@@ -688,7 +688,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 12,
    "id": "5910caab-eada-4715-b863-9bbbb15b9c5c",
    "metadata": {},
    "outputs": [],