{"id":16771522,"url":"https://github.com/meysam81/timeframe","last_synced_at":"2025-07-29T01:35:29.308Z","repository":{"id":46010143,"uuid":"330786554","full_name":"meysam81/timeframe","owner":"meysam81","description":"Python library datetime wrapper for calculating time ranges, manipulations and calculations","archived":false,"fork":false,"pushed_at":"2025-07-21T17:54:48.000Z","size":175,"stargazers_count":8,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-21T19:38:06.926Z","etag":null,"topics":["datetime","package","python","python3","timedelta","timeframe"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/timeframe/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meysam81.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":"meysam81","ko_fi":"meysam","patreon":"meysam81","custom":["https://www.buymeacoffee.com/meysam/"]}},"created_at":"2021-01-18T21:04:27.000Z","updated_at":"2025-05-26T10:40:08.000Z","dependencies_parsed_at":"2022-09-26T18:41:09.991Z","dependency_job_id":"fc1b7407-ab6e-4383-b514-424b05713284","html_url":"https://github.com/meysam81/timeframe","commit_stats":{"total_commits":48,"total_committers":2,"mean_commits":24.0,"dds":0.3125,"last_synced_commit":"640a3f78bd5ba8add215c544e83f1cc8655cf97a"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/meysam81/timeframe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Ftimeframe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Ftimeframe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Ftimeframe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Ftimeframe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meysam81","download_url":"https://codeload.github.com/meysam81/timeframe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Ftimeframe/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267616702,"owners_count":24116160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["datetime","package","python","python3","timedelta","timeframe"],"created_at":"2024-10-13T06:28:21.750Z","updated_at":"2025-07-29T01:35:29.290Z","avatar_url":"https://github.com/meysam81.png","language":"Python","readme":"# TimeFrame\n\n[![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://developer.mend.io/github/meysam81/timeframe)\n[![codecov](https://codecov.io/gh/meysam81/timeframe/branch/main/graph/badge.svg?token=NM0LMWP0X2)](https://codecov.io/gh/meysam81/timeframe)\n[![License](https://img.shields.io/github/license/meysam81/timeframe)](./LICENSE)\n[![Stars](https://img.shields.io/github/stars/meysam81/timeframe?label=GitHub%20stars\u0026style=flat)](https://github.com/meysam81/timeframe/stargazers)\n[![Downloads](https://img.shields.io/pypi/dm/timeframe)](https://pypi.org/project/timeframe/)\n[![Open Issues](https://img.shields.io/github/issues-raw/meysam81/timeframe)](https://github.com/meysam81/timeframe/issues)\n[![Open PRs](https://img.shields.io/github/issues-pr-raw/meysam81/timeframe)](https://github.com/meysam81/timeframe/pulls)\n[![Contributors](https://img.shields.io/github/contributors/meysam81/timeframe)](https://github.com/meysam81/timeframe/graphs/contributors)\n[![Version](https://img.shields.io/pypi/v/timeframe)](https://pypi.org/project/timeframe/)\n[![Python](https://img.shields.io/pypi/pyversions/timeframe)](https://pypi.org/project/timeframe/)\n[![Wheel](https://img.shields.io/pypi/wheel/timeframe)](https://pypi.org/project/timeframe/)\n[![Repo Size](https://img.shields.io/github/repo-size/meysam81/timeframe)](https://github.com/meysam81/timeframe/)\n[![Code Size](https://img.shields.io/github/languages/code-size/meysam81/timeframe)](https://github.com/meysam81/timeframe/)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [TimeFrame](#timeframe)\n  - [Introduction](#introduction)\n  - [Install](#install)\n  - [Examples](#examples)\n    - [Inclusion](#inclusion)\n      - [New API](#new-api)\n      - [Deprecated](#deprecated)\n    - [Duration](#duration)\n    - [Comparison](#comparison)\n    - [Overlap](#overlap)\n    - [Summation (union)](#summation-union)\n    - [Minus](#minus)\n  - [Acknowledgment](#acknowledgment)\n  - [Contribution](#contribution)\n  - [Stargazers over time](#stargazers-over-time)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Introduction\n\nThis package makes the following calculations on `datetime`:\n\n* Adding two time frames, resulting in one bigger time frame or two disjoint one.\n* Multiplying two time frames, resuling in either an overlapped time frame or\nan empty one, depending on the two time frames.\n* Substracting two time frames, resuling in one or several time frames.\n\n## Install\n\nInstalling the package is as simple as running the following command inside\nyour terminal:\n\n```bash\npip install timeframe\n```\n\n## Examples\n\n**NOTE**: You can always take a look at the test cases in the [tests](./test)\ndirectory to get a sense of how to use the package, but consider the below\nexamples first, because it's fairly easy to use.\n\nYou need to import `datetime` as well as `TimeFrame`:\n\n```python\nfrom datetime import datetime\nfrom timeframe import TimeFrame\n```\n\n### Inclusion\n\n#### New API\n\n```python\n\u003e\u003e\u003e tf1 = TimeFrame(datetime(2021, 1, 1), datetime(2021, 1, 2))\n\u003e\u003e\u003e tf2 = TimeFrame(datetime(2021, 1, 1, 12), datetime(2021, 1, 1, 13))\n\u003e\u003e\u003e tf2 in tf1\nTrue\n```\n\n#### Deprecated\n\nThis implies whether or not one time frame includes another; it can also be\nused to check if a `datetime` is inside one `TimeFrame`.\n\nWhen you want to check if a `datetime` is inside a `TimeFrame`:\n\n```python\ntf1 = TimeFrame(datetime(2021, 1, 26, 19), datetime(2021, 1, 26, 20))\ntf1.includes(datetime(2021, 1, 26, 19, 30))\n# output: True\n```\n\nWhen You want to check if an instance of `TimeFrame` is inside another one:\n\n```python\ntf2 = TimeFrame(datetime(2021, 1, 26, 19, 30), datetime(2021, 1, 26, 19, 40))\ntf1.includes(tf2)\n# output: True\n```\n\n```python\ntf3 = TimeFrame(datetime(2021, 1, 26, 19, 45), datetime(2021, 1, 26, 21, 30))\ntf1.includes(tf3)\n# output: False\n```\n\n### Duration\n\n`TimeFrame` has a property named `duration` which can be used to retrieve the\ntotal amount of seconds that `TimeFrame` has:\n\n```python\ntf1.duration\n# output: 3600.0\n```\n\n```python\ntf2.duration\n# output: 600.0\n```\n\n```python\ntf3.duration\n# output: 6300.0\n```\n\n### Comparison\n\nYou can always compare two `TimeFrame` to see if one is greater than the other or not.\nThis comparison is based on the `end` of one `TimeFrame` and the `start` of the other.\n\n```python\ntf1 \u003e tf2\n# output: False\n```\n\n```python\ntf3 \u003e tf2\n# output: True\n```\n\nYou can also compare equality using either greater-equal sign, or a simple equal.\n\n```python\ntf1 == tf2\n# output: False\n```\n\n```python\ntf3 \u003e= tf2\n# output: True\n```\n\n### Overlap\n\nWhen you want to know how much two time frames have in common, use multiply sign:\n\n```python\ntf1 * tf2\n# output: 2021-01-26T19:30:00#2021-01-26T19:40:00\n```\n\n```python\ntf2 * tf3\n# output: Empty TimeFrame\n```\n\nYou can also check their duration as well:\n\n```python\n(tf1 * tf2).duration\n# output: 600.0\n```\n\n```python\n(tf2 * tf3).duration\n# output: 0.0\n```\n\n### Summation (union)\n\nThe summation sign is used to get the union of two time frames:\n\n```python\ntf1 + tf2\n# output: 2021-01-26T19:00:00#2021-01-26T20:00:00\n```\n\n```python\n(tf1 + tf2).duration\n# output: 3600.0\n```\n\n```python\ntf1 + tf3\n# output: 2021-01-26T19:00:00#2021-01-26T21:30:00\n```\n\n```python\n(tf1 + tf3).duration\n# output: 9000.0\n```\n\n### Minus\n\nYou can also substract one time frame from the other, which will ultimately\nresult in either two disjoint time frames, or one unified time frame, depending\non the time frames.\n\n```python\ntf1 - tf2\n# output:\n# 2021-01-26T19:00:00#2021-01-26T19:29:59.999999\n# 2021-01-26T19:40:00.000001#2021-01-26T20:00:00\n```\n\n```python\n(tf1 - tf2).duration\n# output: 2999.999998\n```\n\nSubstracting two disjoint time frames will return the first time frame as a result.\n\n```python\ntf2 - tf3\n# output: 2021-01-26T19:30:00#2021-01-26T19:40:00\n```\n\n```python\n(tf2 - tf3).duration\n# output: 600.0\n```\n\n```python\n(tf2 - tf3) == tf2\n# output: True\n```\n\n## Acknowledgment\n\nThank you for showing interest in this package. Feel free to contact me if you\nfeel like it. 🥂\n\n## Contribution\n\nAny contribution of any size is greatly appreciated. Feel free to open a PR or\nissue in the github page at any time. 🤗\n\n## Stargazers over time\n\n[![Star History Chart](https://api.star-history.com/svg?repos=meysam81/timeframe\u0026type=Date)](https://star-history.com/#meysam81/timeframe\u0026Date)\n","funding_links":["https://github.com/sponsors/meysam81","https://ko-fi.com/meysam","https://patreon.com/meysam81","https://www.buymeacoffee.com/meysam/"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeysam81%2Ftimeframe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeysam81%2Ftimeframe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeysam81%2Ftimeframe/lists"}