Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 22 days ago
JSON representation

Host: GitHub
URL: https://github.com/thombashi/datetimerange
Owner: thombashi
License: mit
Created: 2016-02-19T05:15:09.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2024-05-02T11:23:14.000Z (6 months ago)
Last Synced: 2024-05-17T00:01:45.244Z (6 months ago)
Topics: datetime, datetime-range, python-library, time-range
Language: Python
Homepage: https://datetimerange.rtfd.io/
Size: 376 KB
Stars: 100
Watchers: 5
Forks: 17
Open Issues: 3
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.7+

- `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 `__