Metadata-Version: 2.1
Name: timespan
Version: 0.2.0
Summary: Utilities for Asterisk and Microsoft .Net timespans
Home-page: https://github.com/jart/timespan
Author: Justine Tunney
Author-email: jtunney@gmail.com
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Requires-Python: >=2.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS

# timespan

Utilities for working with popular timespan formats.

## .Net Timespans

Functions are provided for converting between .NET 7.0 TimeSpan objects
(with format specifiers) and Python's `datetime.timedelta` objects.

### `timespan.from_string(str) -> timedelta`

Converts a TimeSpan string in the current locale to a
`datetime.timedelta` object, e.g.

    >>> import timespan
    >>> timespan.c(3, 17, 25, 30, 500)
    '3.17:25:30.5000000'
    >>> timespan.from_string('3.17:25:30.5000000')
    datetime.timedelta(days=3, seconds=62730, microseconds=500000)

#### Parameters

- `timespan_string`: TimeSpan string of any format and locale.

#### Return Value

A timedelta object.

### `timespan.to_string(specifier: str, *args: tuple) -> str`

Converts date\time information (variable-length tuple) to a TimeSpan
string in the current locale.

#### Parameters

- `specifier`: format specifier. Options are 'c', 'g' and 'G'.
- `args`: variable-length tuple (size 1, 3, 4 or 5) specifying
  components of date and time.

#### Return Value

A TimeSpan string

### Notes

See the switch case of `_args_to_seconds()` in
[src/timespan/dotnet.py](src/timespan/dotnet.py) for full coverage of
all input types.

## Asterisk Timespans

Asterisk style timespans allow you to check if a timestamp falls within
a specified list of boundaries. For example, you might want to program
your phone system to only accept calls Mon-Fri from 9 a.m. to 5 p.m.
except on holidays like Christmas.

Timespans are specified in the form of `times|daysofweek|days|months`.
If your timespan starts with `!`, it'll only match if the timestamps
falls outside the given range.

Basic example:

    import timespan
    from datetime import datetime

    business_hours = [
        '9:00-17:00|mon-fri|*|*',  # is between 9 a.m. to 5 p.m. on Mon to Fri
        '!*|*|1|jan',              # not new years
        '!*|*|25|dec',             # not christmas
        '!*|thu|22-28|nov',        # not thanksgiving
    ]

    if timespan.match(business_hours, datetime.now()):
        print "we're open for business!"
    else:
        print "sorry, we're closed :("

For more examples, see the documentation or source code.
