Merge branch 'release/0.3'

Author: rlskoeser

.all-contributorsrc

@@ -1,6 +1,6 @@
 {
   "files": [
-    "README.md"
+    "CONTRIBUTORS.md"
   ],
   "imageSize": 100,
   "commit": true,
@@ -14,7 +14,8 @@
       "contributions": [
         "code",
         "review",
-        "test"
+        "test",
+        "ideas"
       ]
     },
     {
@@ -38,7 +39,9 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/1488847?v=4",
       "profile": "https://github.com/robcast",
       "contributions": [
-        "data"
+        "data",
+        "ideas",
+        "review"
       ]
     },
     {
@@ -50,7 +53,8 @@
         "code",
         "review",
         "test",
-        "eventOrganizing"
+        "eventOrganizing",
+        "ideas"
       ]
     },
     {
@@ -72,5 +76,6 @@
   "repoType": "github",
   "repoHost": "https://github.com",
   "projectName": "undate-python",
-  "projectOwner": "dh-tech"
+  "projectOwner": "dh-tech",
+  "badgeTemplate": "![All Contributors](https://img.shields.io/github/all-contributors/dh-tech/undate-python?color=ee8449&style=flat-square)"
 }

.github/workflows/check.yml

@@ -13,26 +13,27 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.10
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
           cache: 'pip'
-          cache-dependency-path: '**/setup.cfg'
-      - name: Install package with dependencies
+          cache-dependency-path: '**/pyproject.toml'
+      - name: Install package with development dependencies
         run: pip install -e ".[dev]"
-        if: steps.python-cache.outputs.cache-hit != 'true'
 
-      # check code style
-      - name: Run black
-        run: black src --check --diff
+      # check with ruff
+      - name: Run ruff
+        run: ruff check
 
-      # check docs
-      - name: Check that documentation can be built
-        run: tox -e docs
+      # 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: Install mypy
-        run: pip install mypy
       - name: Check types in python src directory; install needed types
         run: mypy --install-types --non-interactive src
+
+      # use treon to make sure that example notebooks run
+      - name: Check jupyter notebooks with treon
+        run: treon

.github/workflows/unit_tests.yml

@@ -11,14 +11,14 @@ on:
 
 env:
   # python version used to calculate and submit code coverage
-  COV_PYTHON_VERSION: "3.11"
+  COV_PYTHON_VERSION: "3.12"
 
 jobs:
   python-unit:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.9", "3.10", "3.11", "3.12"]
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     defaults:
       run:
         working-directory: .
@@ -30,21 +30,18 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
           cache: 'pip'
-          cache-dependency-path: '**/setup.cfg'
+          cache-dependency-path: '**/pyproject.toml'
       - name: Install package with dependencies
-        run: |
-          pip install -e ".[dev]"
-          python -m pip install tox tox-gh-actions
-        if: steps.python-cache.outputs.cache-hit != 'true'
+        run: pip install -e ".[test]"
 
       # for all versions but the one we use for code coverage, run normally
       - name: Run unit tests normally
-        run: tox
+        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: tox -e coverage
+        run: pytest --cov=undate
         if: ${{ matrix.python == env.COV_PYTHON_VERSION }}
       - name: Upload test coverage to Codecov
         uses: codecov/codecov-action@v3

.gitignore

@@ -39,3 +39,6 @@ venv.bak/
 # code coverage
 .coverage
 coverage.xml
+
+# jupyter
+.ipynb_checkpoints/

.pre-commit-config.yaml

@@ -1,9 +1,11 @@
 files: \.py
 repos:
-  - repo: https://github.com/psf/black
-    rev: 22.10.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
     hooks:
-      - id: black
+      - id: ruff
+        args: [ --fix, --exit-non-zero-on-fix ]
+      - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.3.0
     hooks:
@@ -12,4 +14,9 @@ repos:
       - id: debug-statements
       - id: end-of-file-fixer
       - id: mixed-line-ending
-      - id: trailing-whitespace
+      - id: trailing-whitespace
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [numpy]

.pythonversion

@@ -0,0 +1 @@
+Python 3.12.7

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Change Log
 
+## 0.3
+
+- Updated to use numpy `datetime64` to support a greater range of years beyond the 4-digit years supported by python's builtin ``datetime.date`
+  - Custom `Date` and `Timedelta` objects as shims to make numpy datetime64 and timedelta64 act more like python `datetime` objects
+- Renamed formatters to converters for more flexibility / scope
+- Support using different converters with new `format` and `parse` methods on `Undate`
+- 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
+- Restructured sphinx documentation and added more code documentation
+- Added a project logo
+- Switch from black to ruff for pre-commit formatting
+
+### numpy impact
+
+Performance differences seem to be negligible, but it does increase payloud 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
 
 - Undate and UndateInterval now include an optional label for named dates or time periods

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

CONTRIBUTING.md

@@ -1,23 +1,58 @@
-# Contributing to Undate - A fuzzy date Python library
-
+# Contributing to undate
 
 Hey there!
 
 If you found your way here that probably means you are curious about how to contribute to this project. This is great! We are always looking for new contributors. If you can't find the information you are looking for in this document or anywhere else in the repo, please consider [opening a ticket](https://github.com/dh-tech/undate-python/issues) so we know there is something we need to address.
 
 ## Project Setup
-Instructions on how to set up the project locally and how to run the tests can be found [in the Readme file](README.md).
+Instructions on how to set up the project locally and how to run the tests can be found in [Developer Notes](DEVELOPER_NOTES.md).
 
 ## Submitting Changes
-If you would like to contribute by submitting bug fixes, improvements, or new features, please fork the repository and then make a pull request to our main branch when you are ready. For details see [this description of the Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow).
+
+If you would like to contribute by submitting bug fixes, improvements, or new features, please fork the repository and then make a pull request to undate **develop** branch when you are ready. If you haven't contributed like this before, we recommend reading [GitHub's documentation on Contributing to a Project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).
+
+We use **git flow** branching conventions, so the current release is on the **main** branch and new feature development happens on **develop**. Pull requests for new features or bug fixes should be made to **develop** for inclusion in the next release. For more details, read a longer explanation of the [Git Flow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
+
+Recommended branch naming conventions:
+
+- For a new feature, create a branch named `feature/i##-short-name` where `##` is the relevant GitHub issue number (if there is one) and `short-name` is a brief label that relates to the changes or feature
+
+In most cases branches should be created from the most recent **develop** branch. Make sure you check out develop and pull any remote changes. 
+```sh
+git checkout develop
+git pull
+```
+
+If you have `git flow` installed, you can start, you can use:
+```sh
+git flow feature start i##-short-name
+```
+
+If not, you can do the same thing with git commands:
+```sh
+git checkout -b feature/i##-short-name
+```
+
+When you are ready to contribute your changes, open a pull request from your branch to the main undate repository. Please be sure to link to the GitHub issue in your pull request comments.
+
+Ideally contributions should include documentation and tests for the proposed changes, but if that is a barrier please let us know when you submit a pull request.
+
+Please be aware that any contributions will fall under the existing Apache 2.0 license applied to this software.
 
 ## Submitting Bug Reports and Feature Requests
+
 If you find a bug or can think a feature you would really like to see being implemented, you can [create a new issue](https://github.com/dh-tech/undate-python/issues). Please first look through the existing issues, however, to avoid duplication of issues.
 
-If you report a bug, please include any error messages you get and a full description of the steps to reproduce the bug. For new feature requests, please clearly describe the functionality you are looking for and, if applicable, why any existing workflow does not suffice. Please also consider, fixing bugs and implementing new features yourself and submit pull request! :) 
+If you report a bug, please include any error messages you get and a full description of the steps to reproduce the bug. For new feature requests, please clearly describe the functionality you are looking for and, if applicable, why any existing workflow does not suffice. Please also consider fixing bugs and implementing new features yourself and submitting them via pull request! :)
+
+## Submitting Use Cases and Example Data
+
+We are particularly interested in collecting more use cases and example data where undate would be helpful!
+
+Example data can be added to the [examples/](https://github.com/dh-tech/undate-python/tree/main/examples/) folder by a pull request. 
 
 ## Getting Help
-The best and recommended way to get help is to join the [DHTech Slack](https://dh-tech.github.io/join/) and ask for help there. Only in cases when this is not feasible at all, you can open a new issue and tag it with "Help Request".  
+The best and recommended way to get help is to join the [DHTech Slack](https://dh-tech.github.io/join/) and ask for help there. Only in cases when this is not feasible at all, you can open a new issue and tag it with "Help Request".
 
 ## DHTech
 This project started during the DHTech 2022 Hackathon. If you do technical work in the digital humanities and are intersted in meeting like-minded people, [consider joining](https://dh-tech.github.io/join/)!

CONTRIBUTORS.md

@@ -0,0 +1,51 @@
+# All Contributors
+
+We use [All Contributors](https://allcontributors.org/) because we recognize that all kinds of contributions are valuable and important.
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+![All Contributors](https://img.shields.io/github/all-contributors/dh-tech/undate-python?color=ee8449&style=flat-square)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+## Contributors 
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ColeDCrawford"><img src="https://avatars.githubusercontent.com/u/16374762?v=4?s=100" width="100px;" alt="Cole Crawford"/><br /><sub><b>Cole Crawford</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=ColeDCrawford" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3AColeDCrawford" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=ColeDCrawford" title="Tests">⚠️</a> <a href="#ideas-ColeDCrawford" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://rlskoeser.github.io"><img src="https://avatars.githubusercontent.com/u/691231?v=4?s=100" width="100px;" alt="Rebecca Sutton Koeser"/><br /><sub><b>Rebecca Sutton Koeser</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Arlskoeser" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Tests">⚠️</a> <a href="#blog-rlskoeser" title="Blogposts">📝</a> <a href="#example-rlskoeser" title="Examples">💡</a> <a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Documentation">📖</a> <a href="#platform-rlskoeser" title="Packaging/porting to new platform">📦</a></td>
+      <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>
+    </tr>
+  </tbody>
+  <tfoot>
+    <tr>
+      <td align="center" size="13px" colspan="7">
+        <img src="https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg">
+          <a href="https://all-contributors.js.org/docs/en/bot/usage">Add your contributions</a>
+        </img>
+      </td>
+    </tr>
+  </tfoot>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+### Related blog posts
+
+(blog-rlskoeser)=
+#### [by Rebecca Sutton Koeser](#blog-rlskoeser)
+  - [Join me for a DHTech hackathon? It’s an un-date!](https://dh-tech.github.io/blog/2023-02-09-hackathon-summary/) 2023-02-09 on DHTech blog