https://github.com/thombashi/DateTimeRange
DateTimeRange is a Python library to handle a time range. e.g. check whether a time is within the time range, get the intersection of time ranges, truncate a time range, iterate through a time range, and so forth.
https://github.com/thombashi/DateTimeRange
datetime datetime-range python-library time-range
Last synced: 9 months ago
JSON representation
DateTimeRange is a Python library to handle a time range. e.g. check whether a time is within the time range, get the intersection of time ranges, truncate a time range, iterate through a time range, and so forth.
- Host: GitHub
- URL: https://github.com/thombashi/DateTimeRange
- Owner: thombashi
- License: mit
- Created: 2016-02-19T05:15:09.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2024-12-29T12:35:06.000Z (about 1 year ago)
- Last Synced: 2025-04-27T10:01:53.705Z (9 months ago)
- Topics: datetime, datetime-range, python-library, time-range
- Language: Python
- Homepage: https://datetimerange.rtfd.io/
- Size: 359 KB
- Stars: 109
- Watchers: 4
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
.. contents:: **DateTimeRange**
:backlinks: top
:depth: 2
Summary
=========
`DateTimeRange `__ is a Python library to handle a time range. e.g. check whether a time is within the time range, get the intersection of time ranges, truncate a time range, iterate through a time range, and so forth.
|PyPI pkg ver| |conda pkg ver| |Supported Python ver| |CI status| |Test coverage| |CodeQL|
.. |PyPI pkg ver| image:: https://badge.fury.io/py/DateTimeRange.svg
:target: https://badge.fury.io/py/DateTimeRange
:alt: PyPI package version
.. |conda pkg ver| image:: https://anaconda.org/conda-forge/datetimerange/badges/version.svg
:target: https://anaconda.org/conda-forge/datetimerange
:alt: conda-forge package version
.. |Supported Python ver| image:: https://img.shields.io/pypi/pyversions/DateTimeRange.svg
:target: https://pypi.org/project/DateTimeRange
:alt: Supported Python versions
.. |CI status| image:: https://github.com/thombashi/DateTimeRange/actions/workflows/ci.yml/badge.svg
:target: https://github.com/thombashi/DateTimeRange/actions/workflows/ci.yml
:alt: CI status of Linux/macOS/Windows
.. |Test coverage| image:: https://coveralls.io/repos/github/thombashi/DateTimeRange/badge.svg?branch=master
:target: https://coveralls.io/github/thombashi/DateTimeRange?branch=master
:alt: Test coverage
.. |CodeQL| image:: https://github.com/thombashi/DateTimeRange/actions/workflows/github-code-scanning/codeql/badge.svg
:target: https://github.com/thombashi/DateTimeRange/actions/workflows/github-code-scanning/codeql
:alt: CodeQL
Installation
============
Installation: pip
------------------------------
::
pip install DateTimeRange
Installation: conda
------------------------------
::
conda install -c conda-forge datetimerange
Dependencies
============
- Python 3.9+
- `Python package dependencies (automatically installed) `__
Features
============
Features of ``DateTimeRange`` class include:
- Supported operations:
- Equation
- Addition
- Subtraction
- Intersection
- Union
- Contains
- Truncate
- Split
- Iteration
- Timezone support
- Daylight saving time support
Examples
==========
Create a DateTimeRange instance from start and end datetime
-----------------------------------------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
str(time_range)
:Output:
::
'2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900'
Create a DateTimeRange instance from a range text
-----------------------------------------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange.from_range_text("2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900")
str(time_range)
:Output:
::
'2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900'
Get an iterator
------------------------
:Sample Code 1:
.. code:: python
import datetime
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-01-01T00:00:00+0900", "2015-01-04T00:00:00+0900")
for value in time_range.range(datetime.timedelta(days=1)):
print(value)
:Output 1:
::
2015-01-01 00:00:00+09:00
2015-01-02 00:00:00+09:00
2015-01-03 00:00:00+09:00
2015-01-04 00:00:00+09:00
:Sample Code 2:
.. code:: python
from datetimerange import DateTimeRange
from dateutil.relativedelta import relativedelta
time_range = DateTimeRange("2015-01-01T00:00:00+0900", "2016-01-01T00:00:00+0900")
for value in time_range.range(relativedelta(months=+4)):
print(value)
:Output 2:
::
2015-01-01 00:00:00+09:00
2015-05-01 00:00:00+09:00
2015-09-01 00:00:00+09:00
2016-01-01 00:00:00+09:00
Test whether a value within the time range
------------------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print("2015-03-22T10:05:00+0900" in time_range)
print("2015-03-22T10:15:00+0900" in time_range)
time_range_smaller = DateTimeRange("2015-03-22T10:03:00+0900", "2015-03-22T10:07:00+0900")
print(time_range_smaller in time_range)
:Output:
::
True
False
True
Test whether a value intersects the time range
----------------------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.is_intersection(x)
:Output:
::
True
Make an intersected time range
------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.intersection(x)
:Output:
::
2015-03-22T10:05:00+0900 - 2015-03-22T10:10:00+0900
Make an encompassed time range
------------------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.encompass(x)
:Output:
::
2015-03-22T10:00:00+0900 - 2015-03-22T10:15:00+0900
Truncate time range
-------------------
:Sample Code:
.. code:: python
from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.is_output_elapse = True
print("before truncate: ", time_range)
time_range.truncate(10)
print("after truncate: ", time_range)
:Output:
::
before truncate: 2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900 (0:10:00)
after truncate: 2015-03-22T10:00:30+0900 - 2015-03-22T10:09:30+0900 (0:09:00)
For more information
----------------------
More examples are available at
https://datetimerange.rtfd.io/en/latest/pages/examples/index.html
Examples with Jupyter Notebook are also available at `DateTimeRange.ipynb `__
Documentation
===============
https://datetimerange.rtfd.io/
Sponsors
====================================
|chasbecker| |shiguredo| |b4tman| |Arturi0| |github|
.. |chasbecker| image:: https://avatars.githubusercontent.com/u/44389260?s=48&u=6da7176e51ae2654bcfd22564772ef8a3bb22318&v=4
:target: https://github.com/chasbecker
:alt: ex-sponsor: Charles Becker (chasbecker)
.. |shiguredo| image:: https://avatars.githubusercontent.com/u/2549434?s=48&v=4
:target: https://github.com/shiguredo
:alt: ex-sponsor: æéšć (shiguredo)
.. |b4tman| image:: https://avatars.githubusercontent.com/u/3658062?s=48&v=4
:target: https://github.com/b4tman
:alt: onetime: Dmitry Belyaev (b4tman)
.. |Arturi0| image:: https://avatars.githubusercontent.com/u/46711571?s=48&u=57687c0e02d5d6e8eeaf9177f7b7af4c9f275eb5&v=4
:target: https://github.com/Arturi0
:alt: onetime: Arturi0
.. |github| image:: https://avatars.githubusercontent.com/u/9919?s=48&v=4
:target: https://github.com/github
:alt: onetime: GitHub (github)
`Become a sponsor `__