Metadata-Version: 2.1
Name: time-int
Version: 0.0.8
Summary: Subclass of integer representing seconds since UNIX epoch
Home-page: https://github.com/aallaire/time-int
License: MIT
Author: Andrew Allaire
Author-email: andrew.allaire@gmail.com
Requires-Python: >=3.5,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: magic-kind (>=0.2.2,<0.3.0)
Requires-Dist: pytest (>=5.4.2,<6.0.0)
Project-URL: Repository, https://github.com/aallaire/time-int
Description-Content-Type: text/markdown

# time-int
Integer subclass for number of seconds since the epoch in UTC

### The Idea
UNIX has a venerable tradition of representing time as seconds since the
start of 1970. This has its limitations, but it is sometimes desirably
simple. This package sub-classes int to give a little handy functionality
to this simple approach.

#### More robust resources
For uses beyond this rather specific functionality, the standard python
distribution includes powerful time related packages such as `datetime`,
`time` and `calendar`. Also other packages installable time related
packages such as `pytz` and `timeutil`.

### Important Limitations of TimeInt objects.
* Values are always treated as relative to UTC.
* Values are rounded down to the second.
* Supported range starts at Jan 1, 1970 (UTC): 0
* Supported range ends at Jan 1, 3000 (UTC): 32,503,680,000
* The supported range might need to be different on other systems, have only tested on windows.
* This package is not far enough along in development to be safe from errors or major feature changes.

### Quick Example
```python
from time_int import TimeInt

start_time = TimeInt.utcnow()
some_slow_operation()
end_time = TimeInt.utcnow()

print(f"Operation started at {start_time.get_pretty()}")
print(f"Operation ended  at  {end_time.get_pretty()}")
print(f"Operation took {end_time - start_time} seconds")
```

### The trunc_\<unit\> Methods
Some trunc_\<unit\> methods are available for rounding down times to the
year, month, week, day, hour, or minute. One can also round down to units based
on some number of these units. For example to round a time int to the fifteen
minute period it falls in:
```python
from time_int import TimeInt
from datetime import datetime

dt = datetime(year=2001, month=5, day=16, hour=10, minute=53)
time = TimeInt.from_datetime(dt)

quarter_hour_time = time.trunc_minute(num=15)
``` 
The `quater_hour_time` will round down 10:53am to 10:45am.
Note that the 15 minute periods rounded to are based on when the hour started, as
one might intuitively suspect. For numbers of hours the `trunc_day` method is based
on start of the day. Such that if you round down to units of 6 hours, you will round
down to ether midnight, 6am, noon, or 6pm. Weeks do not have this grouping feature because
there is no obvious place I can see to start counting groups of weeks from. For
days they are based on start of month. For months on start of year, and for years
on a fictional year 0 (which technically does not exist). Sometimes there will be
oddly sized groups with less than the number of units, for example if you choose to
round to units of 7 hours, you will get either midnight, 7am, 2pm, or 9pm. With 9pm
to midnight only being the left over 3 hours. When the time unit is groups of 2 or
more days, this is bound to happen due to the way months vary from 28 to 31 days.

##### trunc method
There is a generic `trunc` method that wraps all the `trunc_<unit>` methods so
one can specify the basic time unit as an argument. For example to find the start
of the start of the current quarter year in UTC:

```python
from time_int import TimeInt, TimeTruncUnit

current_time = TimeInt.utcnow()
start_of_quarter = current_time.trunc(TimeTruncUnit.MONTH, num=3)
```
Of course in this example one would probably just use `trunc_month(num=3)` which
does the same thing.





