Clean up, improve documentation, and prep for release

Includes several items suggested or flagged by @coderabbitai

.github/workflows/check.yml

@@ -21,15 +21,15 @@ jobs:
           cache-dependency-path: '**/pyproject.toml'
       - name: Install package with development dependencies
         run: pip install -e ".[dev]"
-        if: steps.python-cache.outputs.cache-hit != 'true'
+        if: steps.setup-python.outputs.cache-hit != 'true'
 
       # check with ruff
       - name: Run ruff
         run: ruff check
 
-      # check docs
-      - name: Check that documentation can be built
-        run: sphinx-build docs docs/_build   # --fail-on-warning
+      # check docs build
+      - name: Check that documentation builds with no errors or warnings
+        run: sphinx-build docs docs/_build --fail-on-warning
 
       # check types with mypy
       - name: Check types in python src directory; install needed types

.github/workflows/unit_tests.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Install package with dependencies
         run: |
           pip install -e ".[test]"
-        if: steps.python-cache.outputs.cache-hit != 'true'
+        if: steps.setup-python.outputs.cache-hit != 'true'
 
       # for all versions but the one we use for code coverage, run normally
       - name: Run unit tests normally

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     rev: v0.3.4
     hooks:
       - id: ruff
-        args: [ --select, I, --fix, --exit-non-zero-on-fix ]
+        args: [ --fix, --exit-non-zero-on-fix ]
       - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.3.0

CHANGELOG.md

@@ -9,6 +9,12 @@
 - Improved EDTF support:
   - 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: 
+      - Letter-prefixed cbalendar year
+      - Unspecified digit from the right
+      - Partial support for extended interval
+    - Level 2: unspecified digit anywhere in the date
 - Improved readme with example usage and disclaimers about current functionality
 - Improved documentation for adding new converters
 - Improved documentation for branching guidelines in contributing

CITATION.cff

@@ -25,7 +25,7 @@ authors:
   family-names: Casties
   affiliation: Max Planck Institute for the History of Science
   orcid: https://orcid.org/0009-0008-9370-1303
-version: '0.2'
-date-released: 2024-04-25
+version: '0.3'
+date-released: 2024-11-18
 repository-code: https://github.com/dh-tech/undate-python
 license: Apache 2

README.md

@@ -156,6 +156,8 @@ Available converters are "ISO8601" and "EDTF" (but only)
 <UndateInterval 1800/1900>
 ```
 
+For more examples, refer to the [example notebooks](examples/notebooks/) included in this repository.
+
 ## Documentation
 
 Project documentation is [available on ReadTheDocs](https://undate-python.readthedocs.io/en/latest/).

docs/conf.py

@@ -63,9 +63,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# preliminary undate logo
-# html_logo = "_static/undate_logo.png"
-
 html_theme_options = {
     "logo": "undate_logo.png",
     "logo_name": False,

examples/notebooks/README.md

@@ -0,0 +1,6 @@
+# `undate` demo notebooks
+
+This folder contains code notebooks demonstrating how undate can be used on a specific dataset or for a specific problem.
+
+- [EDTF support](edtf-support.ipynb) - demonstrate and validate supported portions of the Extended Date Time Format (EDTF) specification
+- [Partial date duration logic](shxco_partial_date_durations.ipynb) - compare `undate` partial date range duration logic with a previous implementation in the _Shakespeare and Company Project_ 

examples/notebooks/edtf-support.ipynb

@@ -55,7 +55,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 2,
    "id": "9c6b7379-b2a7-4ec1-afa5-2cd9832c8a5d",
    "metadata": {},
    "outputs": [],
@@ -212,7 +212,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 5,
    "id": "8d98a139-627b-40bd-b1c5-d0028e538a53",
    "metadata": {},
    "outputs": [],
@@ -268,9 +268,9 @@
     "\n",
     "# Example 2\n",
     "# parse\n",
-    "assert Undate.parse(\"-Y170000002\", \"EDTF\").year == \"-170000002\"\n",
+    "assert Undate.parse(\"Y-170000002\", \"EDTF\").year == \"-170000002\"\n",
     "# format\n",
-    "assert str(Undate(-170000002)) == \"-Y170000002\""
+    "assert str(Undate(-170000002)) == \"Y-170000002\""
    ]
   },
   {
@@ -425,7 +425,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "id": "e47f3fff-d35c-4c2e-9568-214763f6511a",
    "metadata": {},
    "outputs": [],
@@ -481,7 +481,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 9,
    "id": "39143c1f-932a-450c-9b2d-ffbe3e1416b0",
    "metadata": {},
    "outputs": [],
@@ -535,7 +535,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "id": "95965f17-0bd5-446f-bc09-9503eaed68e2",
    "metadata": {},
    "outputs": [],
@@ -589,7 +589,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 11,
    "id": "c6c2d1a1-39f1-45eb-ac08-1de4fadbe842",
    "metadata": {},
    "outputs": [],
@@ -640,7 +640,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 12,
    "id": "f24fd31a-176a-40b5-bff4-d72b68f32a18",
    "metadata": {},
    "outputs": [],
@@ -688,7 +688,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 13,
    "id": "5910caab-eada-4715-b863-9bbbb15b9c5c",
    "metadata": {},
    "outputs": [],

pyproject.toml

@@ -49,6 +49,7 @@ classifiers = [
 
 [project.optional-dependencies]
 docs = ["sphinx>=7.0.0", "alabaster", "myst-parser", "myst-parser[linkify]"]
+test = ["pytest>=7.2", "pytest-ordering", "pytest-cov"]
 dev = [
     "ruff",
     "pre-commit>=2.20.0",
@@ -57,19 +58,17 @@ dev = [
     "build",
     "mypy",
     "treon",
-    "undate",
     "undate[docs]",
     "undate[test]",
 ]
-test = ["pytest>=7.2", "pytest-ordering", "pytest-cov"]
-all = ["undate[dev]", "undate[test]"]
+all = ["undate", "undate[dev]"]
 
 [project.urls]
 Homepage = "https://github.com/dh-tech/undate-python"
 Documentation = "https://undate-python.readthedocs.io/en/latest/"
 Repository = "https://github.com/dh-tech/undate-python.git"
 Issues = "https://github.com/dh-tech/undate-python/issues"
-Changelog = "https://github.com/dh-tech/undate/main/master/CHANGELOG.md"
+Changelog = "https://github.com/dh-tech/undate-python/blob/main/CHANGELOG.md"
 
 
 [tool.hatch.version]

src/undate/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.0.dev0"
+__version__ = "0.3.0"
 
 from undate.date import DatePrecision
 from undate.undate import Undate, UndateInterval

src/undate/converters/edtf/converter.py

@@ -75,11 +75,7 @@ def _undate_to_string(self, undate: Undate) -> str:
             # years with more than 4 digits should be prefixed with Y
             # (don't count minus sign when checking digits)
             if year and len(year.lstrip("-")) > 4:
-                negative_year = ""
-                if year.startswith("-"):
-                    negative_year = "-"
-                    year = year[1:]
-                year = f"{negative_year}Y{year}"
+                year = f"Y{year}"
 
             # TODO: handle uncertain / approximate
             parts.append(year or EDTF_UNSPECIFIED_DIGIT * 4)

src/undate/converters/edtf/edtf.lark

@@ -41,8 +41,11 @@ unspecified: /X/
 //?year_month_unspecified: year_l1 "-" month_unspecified
 ?day_unspecified: "0".."3"? unspecified ~ 1..2
 
-// 'Y' may be used at the beginning of the date string to signify that the date is a year, when (and only when) the year exceeds four digits, i.e. for years later than 9999 or earlier than -9999.
-year_fivedigitsplus: /-?Y\d{5,}/
+// 'Y' may be used at the beginning of the date string to signify that 
+// the date is a year, when (and only when) the year exceeds four digits,
+// i.e. for years later than 9999 or earlier than -9999.
+// For negative years, the minus comes after the Y.
+year_fivedigitsplus: /Y-?\d{5,}/
 ?year_l1: year_fivedigitsplus | year | year_unspecified
 
 // The values 21, 22, 23, 24 may be used used to signify

src/undate/converters/edtf/transformer.py

@@ -76,14 +76,5 @@ def year(self, items):
     def year_fivedigitsplus(self, items):
         # strip off the leading Y and convert to integer
         token = items[0]
-        value = token.value
-        # check if year is negative
-        negative = False
-        if value.startswith("-"):
-            value = value[1:]
-            negative = True
-        year = int(value.lstrip("Y"))
-
-        if negative:
-            year = -year
+        year = int(token.value.lstrip("Y"))
         return Tree(data="year", children=[year])

src/undate/undate.py

@@ -327,7 +327,7 @@ def year(self) -> Optional[str]:
         "year as string (minimum 4 characters), if year is known"
         year = self._get_date_part("year")
         if year:
-            return f"{year:>04}"
+            return f"{year:0>4}"
         # if value is unset but date precision is month or greater, return unknown month
         elif self.precision >= DatePrecision.YEAR:
             return self.MISSING_DIGIT * 4
@@ -340,7 +340,7 @@ def month(self) -> Optional[str]:
         # TODO: need to distinguish between unknown (XX) and unset/not part of the date due to granularity
         month = self._get_date_part("month")
         if month:
-            return f"{month:>02}"
+            return f"{month:0>2}"
         # if value is unset but date precision is month or greater, return unknown month
         elif self.precision >= DatePrecision.MONTH:
             return self.MISSING_DIGIT * 2
@@ -351,7 +351,7 @@ def day(self) -> Optional[str]:
         "day as 2-character string or None if unset"
         day = self._get_date_part("day")
         if day:
-            return f"{day:>02}"
+            return f"{day:0>2}"
         # if value is unset but date precision is day, return unknown day
         # (may not be possible to have day precision with day part set in normal use)
         elif self.precision == DatePrecision.DAY:

tests/test_converters/edtf/test_edtf_parser.py

@@ -12,7 +12,7 @@
     "1000-01/2000-05-01",
     # level 1
     "Y170000002",
-    "-Y170000002",
+    "Y-170000002",
     "2001-21",  # spring 2001
     # negative year
     "-1985",

tests/test_converters/edtf/test_edtf_transformer.py

@@ -14,7 +14,7 @@
     ("1000-01/2000-05-01", UndateInterval(Undate(1000, 1), Undate(2000, 5, 1))),
     # level 1
     ("Y17000002", Undate(17000002)),
-    ("-Y17000002", Undate(-17000002)),
+    ("Y-17000002", Undate(-17000002)),
     # negative year
     ("-1985", Undate(-1985)),
     # "2001-21",  # spring 2001

tests/test_converters/test_edtf.py

@@ -53,6 +53,7 @@ def test_to_string(self):
         assert EDTFDateConverter().to_string(Undate(33)) == "0033"
         assert EDTFDateConverter().to_string(Undate("20XX")) == "20XX"
         assert EDTFDateConverter().to_string(Undate(17000002)) == "Y17000002"
+        assert EDTFDateConverter().to_string(Undate(-17000002)) == "Y-17000002"
 
         assert EDTFDateConverter().to_string(Undate(1991, 6)) == "1991-06"
         assert EDTFDateConverter().to_string(Undate(1991, 5, 3)) == "1991-05-03"