climatetimer


Nameclimatetimer JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryCompute time block IDs since major climate agreements.
upload_time2025-02-19 14:06:09
maintainerNone
docs_urlNone
authorGuillaume Dion
requires_python>=3.10
licenseNone
keywords climate kyoto agreement paris agreement time blocks timer
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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.

[![PyPI version](https://img.shields.io/pypi/v/climatetimer.svg)](https://pypi.org/project/climatetimer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python Versions](https://img.shields.io/pypi/pyversions/climatetimer.svg)](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[![PyPI version](https://img.shields.io/pypi/v/climatetimer.svg)](https://pypi.org/project/climatetimer/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python Versions](https://img.shields.io/pypi/pyversions/climatetimer.svg)](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"
}
        
Elapsed time: 1.62309s