Metadata-Version: 2.1
Name: time-int
Version: 0.0.7
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 to represent naive time since epoch.

### 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.

### Important Limitations
* Supported range starts at 0 or TimeInt.MIN on Jan 1, 1970
* Supported range ends at a 32-bit limit or TimeInt.MAX on Apr 2, 2106
* Values are rounded off to the nearest second.
* Values do not track what time-zone they represent.

### 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.





