Metadata-Version: 2.1
Name: time-utility
Version: 0.1.0
Summary: Time utility functions
Home-page: https://github.com/ramtinabadi/python-time-utility.git
Author: Ramtin Abadi
Author-email: Ramtin.Abadi@gmail.com
License: UNKNOWN
Description: # Time Utility 0.1.0
        
        Time utility is a series of utility methods regarding date and time for python.
        
        ```text
        Note: This package requires python 3.6 and higher
        ```
        
        ## Installation
        ```text
        pip3 install time_utility
        ```
        
        ## Import
        ```python
        from time_utility import TimeUtility
        ```
        
        ## Usage
        The following are the methods available in TimeUtility
        
        <br><br>
        * ###`is_naive(target_datetime)`
        Checks if the given datetime object is naive.
        
        Parameters:<br>
        1. `target_datetime: datetime.datetime` => The target datetime to be checked
        
        Returns: `bool`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        is_it_naive = TimeUtility.is_naive(TimeUtility.now())
        ```
        
        
        
        
        
        <br><br>
        * ###`is_aware(target_datetime)`
        Checks if the given datetime object is aware
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        is_it_aware = TimeUtility.is_aware(TimeUtility.now())
        ```
        
        
        
        
        
        
        <br><br>
        * ####`make_aware(target_datetime, timezone=pytz.utc)`
        Returns an aware datetime object based on the naive target_datetime
        
        Parameters:<br>
        1. `target_datetime: datetime.datetime` => The target datetime
        2. `timezone` [optional] => The preferred timezone. [default: UTC] 
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        from datetime import datetime
        
        aware = TimeUtility.make_aware(datetime.now())
        ```
        
        
        
        
        
        
        <br><br>
        * ####`now(timezone=pytz.utc)`
        Returns an aware instance of the current datetime
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        now = TimeUtility.now()
        ```
        
        
        
        
        
        <br><br>
        * ####`today(timezone=pytz.utc)`
        Returns an aware instance of today's date
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        
        returns `datetime.date`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        today = TimeUtility.today()
        ```
        
        
        
        
        
        <br><br>
        * ####`get_date_start(timezone=pytz.utc, year = None, month = None, day = None)`
        Returns the date and time of the beginning of the day with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        3. `month: int` => The target month. [default: None (will be set to current month)]
        4. `day: int` => The target day. [default: None (will be set to current day)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_date_start(year=2020, month=5)
        ```
        
        
        
        
        <br><br>
        * ####`get_date_end(timezone=pytz.utc, year = None, month = None, day = None)`
        Returns the date and time of the ending of the day with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        3. `month: int` => The target month. [default: None (will be set to current month)]
        4. `day: int` => The target day. [default: None (will be set to current day)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_date_end(year=2020, month=5)
        ```
        
        
        
        
        <br><br>
        * ####`get_month_start(timezone=pytz.utc, year = None, month = None)`
        Returns the date and time of the beginning of the month with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        3. `month: int` => The target month. [default: None (will be set to current month)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_month_start(year=2020, month=5)
        ```
        
        
        
        <br><br>
        * ####`get_month_end(timezone=pytz.utc, year = None, month = None)`
        Returns the date and time of the ending of the month with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        3. `month: int` => The target month. [default: None (will be set to current month)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_month_end(year=2020, month=5)
        ```
        
        
        
        <br><br>
        * ####`get_year_start(timezone=pytz.utc, year = None)`
        Returns the date and time of the beginning of the year with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_year_start(year=2020)
        ```
        
        
        
        <br><br>
        * ####`get_year_end(timezone=pytz.utc, year = None)`
        Returns the date and time of the ending of the year with the given timezone
        
        Parameters:<br>
        1. `timezone` [Optional] => The preferred timezone [default: UTC]
        2. `year: int` => The target year. [default: None (will be set to current year)]
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        day_start = TimeUtility.get_year_end(year=2020)
        ```
        
        
        
        
        
        <br><br>
        * ####`adjust_offset(original_datetime, offset, local_to_utc)`
        Creates and returns a new datetime object using the given datetime object with the given offset in minutes.
        The offset should be positive for timezones ahead of UTC (e.g. India) and negative for timezones before UTC (e.g. US) <br>
        Note that the offset obtained in Javascript via `new Date().getTimezoneOffset()` should be multiplied by -1.
        
        Parameters:<br>
        1. `original_datetime: datetime.datetime` => The original datetime to be adjusted
        2. `offset: int` => The offset in minutes
        3. `local_to_utc` => Set to True if the original datetime is in local time and set to False if the original datetime is in UTC time
        
        returns `datetime.datetime`
        
        Example:
        ```python
        from time_utility import TimeUtility
        from datetime import datetime
        
        adjusted_datetime = TimeUtility.adjust_offset(TimeUtility.make_aware(datetime.now()), 330, True)
        ```
        
        
        
        
        <br><br>
        * ####`get_period(year, month, day, period, offset = 0)`
        Gets the start and the end datetime of a selected period
        
        Parameters:<br>
        1. `year: int` => The selected year
        2. `month: int` => The selected month
        3. `day: int` => The selected day
        4. `period: str` => The selected period. Your options are: `TimeUtility.DAILY`, `TimeUtility.MONTHLY`, and `TimeUtility.ANNUAL`
        5. `offset: int` [optional] => The offset from UTC to adjust the start and the end [default: 0]
        
        returns `(datetime.datetime, datetime.datetime)`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        start, end = TimeUtility.get_period(year=2020, month=2, day=10, period=TimeUtility.MONTHLY, offset=330)
        ```
        
        
        
        
        <br><br>
        * ####`difference(large_time, small_time, time_span = TimeUtility.SECOND)`
        Calculates the difference between two datetime object based on the given time-span
        
        Parameters:<br>
        1. `large_time: datetime.datetime` => The bigger datetime object of the two
        2. `small_time: datetime.datetime` => The smaller datetime object of the two
        3. `time_span: str` [Optional] => The time-span unit of time to calculate the difference. The options are `TimeUtility.MICROSECOND`, `TimeUtility.SECOND`, `TimeUtility.MINUTE`, `TimeUtility.HOUR`, `TimeUtility.DAY`. [default: TimeUtility.SECOND] 
        
        returns `int`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        difference = TimeUtility.difference(TimeUtility.adjust_offset(TimeUtility.now(), 120, False), TimeUtility.now(), TimeUtility.MINUTE)
        ```
        
        
        
        
        <br><br>
        * ####`is_leap_year(year = None)`
        Checks if the given year is a leap year or not
        
        Parameters:<br>
        1. `year: int` [Optional] => The target year [default: None (will be set to current year)]
        
        returns `bool`
        
        Example:
        ```python
        from time_utility import TimeUtility
        
        is_leap = TimeUtility.is_leap_year(year=2020)
        ```
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
