# ClimateTimer
**ClimateTimer** is a pure-Python library that computes **time block IDs** and **time periods** based on elapsed time units (seconds, minutes, quarters, hours, days, weeks, etc.) since major climate agreements.
It supports two reference points:
- **Paris Agreement** (April 22, 2016, UTC)
- **Kyoto Protocol** (February 16, 2005, UTC)
This package is designed for Python 3, is OS independent, and is licensed under the MIT License.
[](https://pypi.org/project/climatetimer/)
[](LICENSE)
[](https://pypi.org/project/climatetimer/)
## Features
- **Flexible Reference Selection:** Choose between the Paris Agreement and the Kyoto Protocol as your starting point.
- **Time Block Calculations:** Compute block IDs and corresponding time periods for various units:
- Seconds
- Minutes
- Quarters (15-minute intervals)
- Hours
- Days
- Weeks
- **Simple API:** Two main methods:
- `blockid(date, *, block_type)`: Compute the time block ID for a given datetime.
- `period(block_id, *, block_type)`: Retrieve the start and end datetimes for a specific time block.
- **Modern Packaging:** Built with a pyproject.toml–only configuration.
## Installation
### Using pip
```bash
pip install climatetimer
```
### From Source
Clone the repository and install:
```
git clone https://github.com/cameraink/climatetimer.git
cd climatetimer
pip install .
```
# Quick Start
```
from climatetimer import ClimateTimer
from datetime import datetime, timezone
# Initialize using the Paris Agreement reference
timer = ClimateTimer("paris")
# Compute the block ID for the current hour
block_id = timer.blockid(datetime.utcnow(), block_type="hour")
print(f"Current hour block ID: {block_id}")
# Retrieve the start and end times for that block
start, end = timer.period(block_id, block_type="hour")
print(f"Block {block_id} starts at {start} and ends at {end}")
```
# Usage
## Initializing ClimateTimer
You must specify the reference as a positional argument:
```
# For Paris Agreement
timer_paris = ClimateTimer("paris")
# For Kyoto Protocol
timer_kyoto = ClimateTimer("kyoto")
```
## Computing a Block ID
Pass a timezone-aware datetime and specify the block type:
```
block_id = timer_paris.blockid(datetime(2023, 5, 10, 15, 30, tzinfo=timezone.utc), block_type="hour")
```
## Retrieving a Time Block Period
```
start, end = timer_paris.period(block_id, block_type="hour")
```
## Testing
This project uses pytest for unit testing. To run the tests and see a coverage report:
```
pytest --cov=climatetimer
```
Raw data
{
"_id": null,
"home_page": null,
"name": "climatetimer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Climate, Kyoto Agreement, Paris Agreement, Time Blocks, Timer",
"author": "Guillaume Dion",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/eb/71/51f0d215b19f122d35981a295ba4b6c7684dd9de988219dc41bd708f1250/climatetimer-0.1.0.tar.gz",
"platform": null,
"description": "# ClimateTimer\n\n**ClimateTimer** is a pure-Python library that computes **time block IDs** and **time periods** based on elapsed time units (seconds, minutes, quarters, hours, days, weeks, etc.) since major climate agreements.\n\nIt supports two reference points:\n- **Paris Agreement** (April 22, 2016, UTC)\n- **Kyoto Protocol** (February 16, 2005, UTC)\n\nThis package is designed for Python 3, is OS independent, and is licensed under the MIT License.\n\n[](https://pypi.org/project/climatetimer/)\n[](LICENSE)\n[](https://pypi.org/project/climatetimer/)\n\n## Features\n\n- **Flexible Reference Selection:** Choose between the Paris Agreement and the Kyoto Protocol as your starting point.\n- **Time Block Calculations:** Compute block IDs and corresponding time periods for various units:\n - Seconds\n - Minutes\n - Quarters (15-minute intervals)\n - Hours\n - Days\n - Weeks\n- **Simple API:** Two main methods:\n - `blockid(date, *, block_type)`: Compute the time block ID for a given datetime.\n - `period(block_id, *, block_type)`: Retrieve the start and end datetimes for a specific time block.\n- **Modern Packaging:** Built with a pyproject.toml\u2013only configuration.\n\n## Installation\n\n### Using pip\n```bash\npip install climatetimer\n```\n\n### From Source\nClone the repository and install:\n```\ngit clone https://github.com/cameraink/climatetimer.git\ncd climatetimer\npip install .\n```\n\n# Quick Start\n```\nfrom climatetimer import ClimateTimer\nfrom datetime import datetime, timezone\n\n# Initialize using the Paris Agreement reference\ntimer = ClimateTimer(\"paris\")\n\n# Compute the block ID for the current hour\nblock_id = timer.blockid(datetime.utcnow(), block_type=\"hour\")\nprint(f\"Current hour block ID: {block_id}\")\n\n# Retrieve the start and end times for that block\nstart, end = timer.period(block_id, block_type=\"hour\")\nprint(f\"Block {block_id} starts at {start} and ends at {end}\")\n```\n\n# Usage\n## Initializing ClimateTimer\nYou must specify the reference as a positional argument:\n```\n# For Paris Agreement\ntimer_paris = ClimateTimer(\"paris\")\n# For Kyoto Protocol\ntimer_kyoto = ClimateTimer(\"kyoto\")\n```\n\n## Computing a Block ID\nPass a timezone-aware datetime and specify the block type:\n```\nblock_id = timer_paris.blockid(datetime(2023, 5, 10, 15, 30, tzinfo=timezone.utc), block_type=\"hour\")\n```\n\n## Retrieving a Time Block Period\n```\nstart, end = timer_paris.period(block_id, block_type=\"hour\")\n```\n\n## Testing\nThis project uses pytest for unit testing. To run the tests and see a coverage report:\n```\npytest --cov=climatetimer\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Compute time block IDs since major climate agreements.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/cameraink/climatetimer",
"Repository": "https://github.com/cameraink/climatetimer"
},
"split_keywords": [
"climate",
" kyoto agreement",
" paris agreement",
" time blocks",
" timer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "df04b60964440f7da79af90d8ad0d4102cd85a7ed726de5e2cd6b97787fe0abb",
"md5": "28312824474ea096f7b7fa1459191ee6",
"sha256": "35fdfe6b08bf624911fa97243e19fe06a8c1a602d5be4e628b5068f51c6ee62a"
},
"downloads": -1,
"filename": "climatetimer-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28312824474ea096f7b7fa1459191ee6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5215,
"upload_time": "2025-02-19T14:06:08",
"upload_time_iso_8601": "2025-02-19T14:06:08.080996Z",
"url": "https://files.pythonhosted.org/packages/df/04/b60964440f7da79af90d8ad0d4102cd85a7ed726de5e2cd6b97787fe0abb/climatetimer-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb7151f0d215b19f122d35981a295ba4b6c7684dd9de988219dc41bd708f1250",
"md5": "735828cb8aadd8d0e33c9c8a2a9276cb",
"sha256": "2b3c8421cdf8cfe256df92496bf707275ade1a5f4ef9dca3c27d591d5c8bcfde"
},
"downloads": -1,
"filename": "climatetimer-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "735828cb8aadd8d0e33c9c8a2a9276cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11269,
"upload_time": "2025-02-19T14:06:09",
"upload_time_iso_8601": "2025-02-19T14:06:09.303539Z",
"url": "https://files.pythonhosted.org/packages/eb/71/51f0d215b19f122d35981a295ba4b6c7684dd9de988219dc41bd708f1250/climatetimer-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 14:06:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameraink",
"github_project": "climatetimer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "climatetimer"
}
JSON
