# undate-python
<!-- 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-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
**undate** is a python library for working with uncertain or partially known dates.
It was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022.
---
β οΈ **WARNING:** this is pre-alpha software and is **NOT** feature complete! Use with caution. β οΈ
---
[![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)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
<!-- 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-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
## Documentation
Project documentation is available on ReadTheDocs https://undate-python.readthedocs.io/en/latest/
## License
This software is licensed under the [Apache 2.0 License](LICENSE.md).
## Installation
To install the most recent release from PyPI:
```sh
pip install undate
```
To install the latest development version from GitHub:
```sh
pip install git+https://github.com/dh-tech/undate-python.git@develop#egg=undate
```
To install a specific release or branch, run the following (replace `[tag-name]` with the tag or branch you want to install):
```sh
pip install git+https://github.com/dh-tech/undate-python.git@[tag-name]
```
## Instructions to setup for development
### Clone repo
```
$ git clone git@github.com:dh-tech/undate-python.git
cd undate-python
```
## Setup and initialize git flow
This repository uses [git-flow](https://github.com/nvie/gitflow) branching conventions:
- **main** will always contain the most recent release
- **develop** branch is the latest version of work in progress
Pull requests for new features should be made against the **develop** branch.
It is recommended to install git flow (on OSX, use brew or ports, e.g.: `brew install git-flow`; on Ubuntu/Debian, `apt-get install git-flow`) and then initialize it in this repository via `git flow init` and accept the defaults. Then you can use `git flow feature start` to create feature development branches.
Alternately, you can check out the develop branch (`git checkout develop`)
and create your branches manually based on develop (`git checkout -b feature/xxx-name`).
### Set up Python environment
Use a recent version of python 3.x; recommended to use a virtualenv, e.g.
```
python3 -m venv undate
source undate/bin/activate
```
### Install the package
Install an editable version of the local package along with python dependencies needed for testing and development.
```sh
pip install -e ".[dev]"
```
### Install pre-commit hooks
```sh
pre-commit install
```
### Run unit tests
Tests can be run with either `tox` or `pytest`.
To run all the tests in a single test file, use pytest and specify the path to the test: `pytest tests/test_dateformat/test_base.py`
To test cases by name, use pytest: `pytest -k test_str`
### Check python types
Python typing is currently only enforced by a CI check action using `mypy`.
To run mypy locally, first install mypy and the necessary typing libraries:
```sh
pip install mypy
mypy --install-types
```
Once mypy is installed, run `mypy src/` to check.
### Create documentation
```sh
tox -e docs
```
## 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></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></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></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
- [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
Raw data
{
"_id": null,
"home_page": "https://github.com/dh-tech/undate-python",
"name": "undate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "\"dates dating uncertainty uncertain-dates unknown partially-known digital-humanities\"",
"author": "DHTech",
"author_email": "\"dhtech.community@gmail.com\"",
"download_url": "https://files.pythonhosted.org/packages/8a/16/2b5cf8bcaa56e9b67e656dc89bd0249a80645cb3bf188f54411b55fbb0da/undate-0.2.0.tar.gz",
"platform": null,
"description": "# undate-python\n<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->\n[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)\n<!-- ALL-CONTRIBUTORS-BADGE:END -->\n\n**undate** is a python library for working with uncertain or partially known dates.\n\nIt was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022.\n\n---\n\n\u26a0\ufe0f **WARNING:** this is pre-alpha software and is **NOT** feature complete! Use with caution. \u26a0\ufe0f\n\n---\n\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Documentation Status](https://readthedocs.org/projects/undate-python/badge/?version=latest)](https://undate-python.readthedocs.io/en/latest/?badge=latest)\n[![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)\n[![codecov](https://codecov.io/gh/dh-tech/undate-python/branch/main/graph/badge.svg?token=GE7HZE8C9D)](https://codecov.io/gh/dh-tech/undate-python)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->\n[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)\n<!-- ALL-CONTRIBUTORS-BADGE:END -->\n\n## Documentation\n\nProject documentation is available on ReadTheDocs https://undate-python.readthedocs.io/en/latest/\n\n## License\n\nThis software is licensed under the [Apache 2.0 License](LICENSE.md).\n\n## Installation\n\nTo install the most recent release from PyPI:\n```sh\npip install undate\n```\n\nTo install the latest development version from GitHub:\n```sh\npip install git+https://github.com/dh-tech/undate-python.git@develop#egg=undate\n```\n\nTo install a specific release or branch, run the following (replace `[tag-name]` with the tag or branch you want to install):\n```sh\npip install git+https://github.com/dh-tech/undate-python.git@[tag-name]\n```\n\n## Instructions to setup for development\n\n### Clone repo\n```\n$ git clone git@github.com:dh-tech/undate-python.git\ncd undate-python\n```\n\n## Setup and initialize git flow\n\nThis repository uses [git-flow](https://github.com/nvie/gitflow) branching conventions:\n- **main** will always contain the most recent release\n- **develop** branch is the latest version of work in progress\n\nPull requests for new features should be made against the **develop** branch.\n\nIt is recommended to install git flow (on OSX, use brew or ports, e.g.: `brew install git-flow`; on Ubuntu/Debian, `apt-get install git-flow`) and then initialize it in this repository via `git flow init` and accept the defaults. Then you can use `git flow feature start` to create feature development branches.\n\nAlternately, you can check out the develop branch (`git checkout develop`)\nand create your branches manually based on develop (`git checkout -b feature/xxx-name`).\n\n### Set up Python environment\nUse a recent version of python 3.x; recommended to use a virtualenv, e.g.\n```\npython3 -m venv undate\nsource undate/bin/activate\n```\n\n### Install the package\n\nInstall an editable version of the local package along with python dependencies needed for testing and development.\n\n```sh\npip install -e \".[dev]\"\n```\n\n### Install pre-commit hooks\n```sh\npre-commit install\n```\n\n### Run unit tests\nTests can be run with either `tox` or `pytest`.\n\nTo run all the tests in a single test file, use pytest and specify the path to the test: `pytest tests/test_dateformat/test_base.py`\n\nTo test cases by name, use pytest: `pytest -k test_str`\n\n### Check python types\n\nPython typing is currently only enforced by a CI check action using `mypy`.\nTo run mypy locally, first install mypy and the necessary typing libraries:\n```sh\npip install mypy\nmypy --install-types\n```\n\nOnce mypy is installed, run `mypy src/` to check.\n\n\n### Create documentation\n\n```sh\ntox -e docs\n```\n\n## Contributors\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n <tbody>\n <tr>\n <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\">\ud83d\udcbb</a> <a href=\"https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3AColeDCrawford\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=ColeDCrawford\" title=\"Tests\">\u26a0\ufe0f</a></td>\n <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\">\ud83d\udcbb</a> <a href=\"https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Arlskoeser\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=rlskoeser\" title=\"Tests\">\u26a0\ufe0f</a> <a href=\"#blog-rlskoeser\" title=\"Blogposts\">\ud83d\udcdd</a> <a href=\"#example-rlskoeser\" title=\"Examples\">\ud83d\udca1</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=rlskoeser\" title=\"Documentation\">\ud83d\udcd6</a> <a href=\"#platform-rlskoeser\" title=\"Packaging/porting to new platform\">\ud83d\udce6</a></td>\n <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\">\ud83d\udd23</a></td>\n <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\">\ud83d\udcbb</a> <a href=\"https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Ajdamerow\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=jdamerow\" title=\"Tests\">\u26a0\ufe0f</a> <a href=\"#eventOrganizing-jdamerow\" title=\"Event Organizing\">\ud83d\udccb</a></td>\n <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\">\ud83d\udcbb</a> <a href=\"https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Amaltevogl\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=maltevogl\" title=\"Tests\">\u26a0\ufe0f</a> <a href=\"https://github.com/dh-tech/undate-python/commits?author=maltevogl\" title=\"Documentation\">\ud83d\udcd6</a></td>\n </tr>\n </tbody>\n <tfoot>\n <tr>\n <td align=\"center\" size=\"13px\" colspan=\"7\">\n <img src=\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\">\n <a href=\"https://all-contributors.js.org/docs/en/bot/usage\">Add your contributions</a>\n </img>\n </td>\n </tr>\n </tfoot>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\n\n### Related blog posts\n\n- [by Rebecca Sutton Koeser](#blog-rlskoeser)\n - [Join me for a DHTech hackathon? It\u2019s an un-date!](https://dh-tech.github.io/blog/2023-02-09-hackathon-summary/) 2023-02-09 on DHTech blog \n",
"bugtrack_url": null,
"license": "\"Apache License, Version 2.0\"",
"summary": "\"library for working with uncertain, fuzzy, or partially unknown dates and date intervals\"",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/dh-tech/undate-python/issues",
"Homepage": "https://github.com/dh-tech/undate-python",
"Project Home": "https://github.com/dh-tech/undate-python"
},
"split_keywords": [
"\"dates",
"dating",
"uncertainty",
"uncertain-dates",
"unknown",
"partially-known",
"digital-humanities\""
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73ec11932888355ccbf99cfc90ca5a1dbb313ea817d980600266c026b74ded97",
"md5": "153c9de2e8eeeedd07ef8cc04ae65924",
"sha256": "37c6718ad80d780ff05d8007e37611d16943ea4ff9abef1795584bd593ae26db"
},
"downloads": -1,
"filename": "undate-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "153c9de2e8eeeedd07ef8cc04ae65924",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19433,
"upload_time": "2024-04-25T19:43:04",
"upload_time_iso_8601": "2024-04-25T19:43:04.933773Z",
"url": "https://files.pythonhosted.org/packages/73/ec/11932888355ccbf99cfc90ca5a1dbb313ea817d980600266c026b74ded97/undate-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8a162b5cf8bcaa56e9b67e656dc89bd0249a80645cb3bf188f54411b55fbb0da",
"md5": "714d7df1a1e396ebd634c7f806a7d32c",
"sha256": "aae4ad433696c502ba25361771187c555bb24328f42d1343b86ba8df9d0b63d2"
},
"downloads": -1,
"filename": "undate-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "714d7df1a1e396ebd634c7f806a7d32c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24580,
"upload_time": "2024-04-25T19:43:06",
"upload_time_iso_8601": "2024-04-25T19:43:06.613325Z",
"url": "https://files.pythonhosted.org/packages/8a/16/2b5cf8bcaa56e9b67e656dc89bd0249a80645cb3bf188f54411b55fbb0da/undate-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 19:43:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dh-tech",
"github_project": "undate-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "undate"
}