Metadata-Version: 2.1
Name: OpenDateRange
Version: 1.0.1
License: MIT License        
        Copyright (c) 2022 tlie03        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.        
Project-URL: Homepage, https://github.com/tlie03/OpenDateRange
Requires-Python: >=2.7.18
Description-Content-Type: text/markdown
License-File: LICENSE

# OpenDateRange
This is a Python package that provides date ranges which allows open borders.
Thereby it is possible to create date ranges that contain all dates 
up to a certain date or all dates from a certain date on. Of course date ranges 
with concrete dates as borders are supported as well.

## Technical information
The package was developed with python 2.7.18 and only uses the build in 
python packages abc and datetime.

## Installation
``$ pip install OpenDateRange``

## Description of the provided Interface
This package provides only one class which is the DateRange class.
The following sections describe how to use this class and how to 
interact with its instances.
* [Date formats](#date-formats)
* [Creating date ranges](#creating-date-ranges)
* [Contains operator](#contains-operator)
* [Intersection between date ranges](#intersection-between-date-ranges)
* [Infinite date ranges](#infinite-date-ranges)
* [Date range iterator](#date-range-iterator)
* [Date range length](#date-range-length)

### Date formats
The package supports all date formats that are supported by the 
build in datetime package. The date format can be changed via 
the static attribute DATE_FORMAT that belongs to the DateRange class and
is predefined as "%Y-%m-%d". When the date format is changed 
all dates that are involved in interactions with instances of the DateRange
class must match the new date format. Furthermore, all dates that are returned
by any methods of the DateRange class match the new format as well.
#### Example

```python
from openDateRange import DateRange

# change date format from %Y-%m-%d to %Y/%m/%d
DateRange.DATE_FORMAT = "%Y/%m/%d"
```
All DateRange instances now only accept and output dates in %Y/%m/%d format.

### Creating date ranges
A DateRange instance takes two parameters. A date from where the range
should start and a date up to which the range should go. If one of 
these parameters is set to None the corresponding border will be
an open border. Both, the start and the end date are included in the date range.
#### Example

```python
from openDateRange import DateRange

# holds all dates from 2000-12-12 up to 2001-12-12
dr1 = DateRange(date_from="2000-12-12", date_to="2001-12-12")

# holds all dates from 2000-12-12 on
dr2 = DateRange(date_from="2000-12-12", date_to=None)

# holds all dates up to 2001-12-12
dr3 = DateRange(date_from=None, date_to="2001-12-12")

# holds all dates
dr4 = DateRange(date_from=None, date_to=None)
```

### Contains operator
Pythons `in` operator can be used to proof whether a date is contained in
a date range.
#### Example

```python
from openDateRange import DateRange

dr = DateRange(date_from="2000-12-12", date_to=None)
# true
print("2000-12-12" in dr)
# true
print("2040-12-12" in dr)
# false
print("1990-12-12" in dr)
```

### Intersection between date ranges
The `intersects` method of the DateRange class takes in
two borders that span a date range and proofs if the two date
ranges intersect. The method returns true if at least 
one date is contained in both date ranges.
#### Example

```python
from openDateRange import DateRange

dr = DateRange(date_from="2000-12-12", date_to="2001-12-12")
# true
dr.intersects(date_from="2001-05-05", date_to="2002-06-06")
# false
dr.intersects(date_from="2002-12-12", date_to="2003-12-12")
```

### Infinite date ranges
Date ranges that have at least one open border are called to be infinite.
The following functions can not be called on infinite date ranges. These
include the iterator functionality and the len() function. Due to the fact
that an iterator on an infinite date range would be an endless loop and
the length of an infinite date range is not defined. The `is_infinite()` 
method of the DateRange class proofs whether a DateRange instance is infinite.

### Date range iterator
If a date range is finite it is possible to iterate over the date range
using the build in iterator functionalities. The iterator returns
each date as a String of the format that is currently set.
#### Example

```python
from openDateRange import DateRange

dr = DateRange(date_from="2000-12-12", date_to="2000-12-15")

print([date for date in dr])
# output: ["2000-12-21", "2000-12-13", "2000-12-14", "2000-12-15"]
```

### Date range length
A finite date range also has a length which is just the number of dates
it contains. The length can be determined with the build in len() function.
Note that the length of a date range can not change so the length of 
a date range is calculated in the first call of the len() function and 
is just read from memory in the following calls. Due to this implementation the first call 
of the len() function may be a little slower especially for very 
long date ranges.

