{"id":40664481,"url":"https://github.com/backplane/datetimecalc","last_synced_at":"2026-02-17T12:25:46.032Z","repository":{"id":188098589,"uuid":"678106111","full_name":"backplane/datetimecalc","owner":"backplane","description":"calculator for datetimes and timedeltas","archived":false,"fork":false,"pushed_at":"2025-10-25T09:24:42.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-25T11:20:00.830Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/backplane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-13T17:42:59.000Z","updated_at":"2025-10-25T09:23:45.000Z","dependencies_parsed_at":"2025-10-30T04:33:06.601Z","dependency_job_id":null,"html_url":"https://github.com/backplane/datetimecalc","commit_stats":null,"previous_names":["backplane/datetimecalc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/backplane/datetimecalc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backplane%2Fdatetimecalc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backplane%2Fdatetimecalc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backplane%2Fdatetimecalc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backplane%2Fdatetimecalc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/backplane","download_url":"https://codeload.github.com/backplane/datetimecalc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backplane%2Fdatetimecalc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28630940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T09:06:30.039Z","updated_at":"2026-02-17T12:25:46.020Z","avatar_url":"https://github.com/backplane.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# datetimecalc\n\nA Python library and command-line tool for parsing and computing with natural language datetime and timedelta expressions.\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/github/license/backplane/datetimecalc)](LICENSE.txt)\n\n## Quick Start\n\n```bash\n# Install with uv (recommended)\nuv pip install git+https://github.com/backplane/datetimecalc.git\n\n# Or clone and run directly\ngit clone https://github.com/backplane/datetimecalc.git\ncd datetimecalc\nuv run datetimecalc \"tomorrow + 2 hours\"\n```\n\n```bash\n# Example commands\ndatetimecalc \"2024-01-01 + 1 week\"\ndatetimecalc \"now - 30 days\"\ndatetimecalc \"2025-01-01 - 2024-01-01\"      # Output: 1 year\ndatetimecalc \"2024-01-01 EST @ UTC\"          # Timezone conversion\ndatetimecalc \"1 day == 24 hours\"             # Output: True\n```\n\n## Features\n\n- **Natural language parsing** - \"tomorrow at 3pm\", \"next Friday\", \"in 2 hours\"\n- **Flexible duration syntax** - \"1 day\", \"2h 30m\", \"1.5 hours\", \"90 minutes\"\n- **Timezone support** - IANA timezones, UTC offsets, and conversions with `@`\n- **Date arithmetic** - Add, subtract, and compare dates and durations\n- **Localized output** - Formats durations in 11 languages based on system locale\n- **Python repr() support** - Parse and output Python datetime repr strings\n\n## Installation\n\n### With uv (recommended)\n\n```bash\nuv pip install git+https://github.com/backplane/datetimecalc.git\n```\n\n### With pip\n\n```bash\npip install git+https://github.com/backplane/datetimecalc.git\n```\n\n### From source\n\n```bash\ngit clone https://github.com/backplane/datetimecalc.git\ncd datetimecalc\nuv sync\n```\n\n**Requirements:** Python 3.12+\n\n## Usage\n\n### Command Line\n\n```bash\n# Date arithmetic\ndatetimecalc \"2024-01-01 + 1 day\"\ndatetimecalc \"tomorrow - 2 hours\"\ndatetimecalc \"now + 1 week\"\n\n# Date differences\ndatetimecalc \"2025-01-01 - 2024-01-01\"\n# Output: 1 year\n\n# Timezone conversion\ndatetimecalc \"2024-01-01 12:00 America/New_York @ UTC\"\n# Output: 2024-01-01 17:00:00+00:00\n\n# Comparisons\ndatetimecalc \"1 day == 24 hours\"    # True\ndatetimecalc \"2024-01-01 \u003c now\"     # True/False depending on current date\n\n# Debug mode\ndatetimecalc --debug \"2024-01-01 + 1 week\"\n\n# Python repr output\ndatetimecalc --repr \"2025-01-01 - 2024-01-01\"\n# Output: datetime.timedelta(days=365)\n\n# Multi-word expressions (no quotes needed)\ndatetimecalc tomorrow at 3pm + 2 hours\n```\n\n### Python Library\n\n```python\nfrom datetimecalc.functions import parse_temporal_expr\n\n# Date + duration\nparse_temporal_expr('2022-01-01 12:00 UTC + 1 day')\n# datetime(2022, 1, 2, 12, 0, tzinfo=timezone.utc)\n\n# Date - duration\nparse_temporal_expr('2022-01-01 - 1 week')\n# datetime(2021, 12, 25, 0, 0)\n\n# Date - date (returns timedelta)\nparse_temporal_expr('2025-01-01 - 2024-01-01')\n# timedelta(days=365)\n\n# Timezone conversion\nparse_temporal_expr('2024-01-01 12:00 America/New_York @ UTC')\n# datetime(2024, 1, 1, 17, 0, tzinfo=timezone.utc)\n\n# Comparisons\nparse_temporal_expr('2024-01-01 \u003c 2025-01-01')  # True\nparse_temporal_expr('1 day == 24 hours')        # True\n```\n\n## Operations Reference\n\n| Operation           | Syntax                           | Example                   |\n| ------------------- | -------------------------------- | ------------------------- |\n| Add duration        | `datetime + timedelta`           | `2024-01-01 + 1 day`      |\n| Subtract duration   | `datetime - timedelta`           | `tomorrow - 2 hours`      |\n| Date difference     | `datetime - datetime`            | `2025-01-01 - 2024-01-01` |\n| Convert timezone    | `datetime @ timezone`            | `2024-01-01 EST @ UTC`    |\n| Duration arithmetic | `timedelta +/- timedelta`        | `1 day + 12 hours`        |\n| Comparisons         | `\u003c`, `\u003c=`, `\u003e`, `\u003e=`, `==`, `!=` | `1 day == 24 hours`       |\n\n## Duration Units\n\n| Unit         | Formats                                 |\n| ------------ | --------------------------------------- |\n| Years        | `1 year`, `2 years`, `3y`               |\n| Months       | `1 month`, `2 months`, `3mo`            |\n| Weeks        | `1 week`, `2 weeks`, `3w`               |\n| Days         | `1 day`, `2 days`, `3d`                 |\n| Hours        | `1 hour`, `2 hours`, `3h`, `1.5 hours`  |\n| Minutes      | `1 minute`, `2 minutes`, `3m`, `30 min` |\n| Seconds      | `1 second`, `2 seconds`, `3s`           |\n| Milliseconds | `500ms`, `1 millisecond`                |\n| Microseconds | `500us`, `1 microsecond`                |\n\n**Note:** Years and months use fixed approximations (1 year = 365 days, 1 month = 30 days).\n\n## Localization\n\nDuration output automatically adapts to system locale:\n\n```python\nfrom datetimecalc.timedelta import duration_to_string\nfrom datetime import timedelta\n\nduration_to_string(timedelta(days=2, hours=3))\n# English: \"2 days, 3 hours\"\n# Spanish: \"2 días, 3 horas\"\n# Japanese: \"2日、3時間\"\n```\n\n**Supported languages:** English, Spanish, Chinese, Hindi, Portuguese, Bengali, Russian, Japanese, Vietnamese, Turkish, Marathi\n\n## Development\n\n```bash\n# Setup\ngit clone https://github.com/backplane/datetimecalc.git\ncd datetimecalc\nuv sync\nuv run pre-commit install\n\n# Run tests\nuv run pytest\nuv run pytest -v                    # verbose\nuv run pytest --doctest-modules src # doctests only\n\n# Code quality\nuv run pre-commit run --all-files   # all checks\nuv run black src/                   # format\nuv run mypy src/                    # type check\n\n# Build\nuv build                            # wheel\npyoxidizer build                    # standalone executable\n```\n\n## Project Structure\n\n```\ndatetimecalc/\n├── src/datetimecalc/\n│   ├── __init__.py      # Public API exports\n│   ├── __main__.py      # CLI entry point\n│   ├── functions.py     # Core parsing and expression evaluation\n│   ├── timedelta.py     # Human-readable timedelta formatting (i18n)\n│   └── tz.py            # Timezone detection and parsing\n├── pyproject.toml       # Project configuration\n├── uv.lock              # Dependency lockfile\n└── README.md\n```\n\n## Documentation\n\n- [API Documentation](https://www.backplane.be/datetimecalc/) - Full API reference\n\n## Contributing\n\n1. All tests pass: `uv run pytest`\n2. Code is formatted: `uv run black src/`\n3. Pre-commit hooks pass: `uv run pre-commit run --all-files`\n4. Type hints included for new functions\n5. Doctests included for new functionality\n\n## License\n\nApache License 2.0 - see [LICENSE.txt](LICENSE.txt)\n\n## Acknowledgments\n\n- [parsedatetime](https://github.com/bear/parsedatetime) - Natural language date parsing\n- [uv](https://github.com/astral-sh/uv) - Package management\n- [zoneinfo](https://docs.python.org/3/library/zoneinfo.html) - Timezone data\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackplane%2Fdatetimecalc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackplane%2Fdatetimecalc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackplane%2Fdatetimecalc/lists"}