diff --git a/README.rst b/README.rst index b616616..eb99b31 100644 --- a/README.rst +++ b/README.rst @@ -16,7 +16,7 @@ Summary DateTimeRange is a python library to handle routine work associated with a time range, such as test whether a time is within the time range, -get time range intersection, truncating the time range etc. +get time range intersection, truncating the time range, etc. diff --git a/datetimerange/__init__.py b/datetimerange/__init__.py index 255ede7..ac62258 100644 --- a/datetimerange/__init__.py +++ b/datetimerange/__init__.py @@ -13,17 +13,35 @@ class DateTimeRange(object): """ - :Examples: + The class that represents the time range. + + :param datetime.datetime/str start: |param_start_datetime| + :param datetime.datetime/str end: |param_end_datetime| + + :Examples: .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range .. parsed-literal:: 2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900 + + .. py:attribute:: start_time_format + + Conversion format string for :py:attr:`.start_datetime`. + + .. seealso:: :py:meth:`.get_start_time_str` + + .. py:attribute:: end_time_format + + Conversion format string for :py:attr:`.end_datetime`. + + .. seealso:: :py:meth:`.get_end_time_str` """ __COMMON_DST_TIMEZONE_TABLE = { @@ -103,8 +121,8 @@ def __contains__(self, x): """ :param datetime.datetime/str x: datetime or datetimerange to compare. - Parse and convert to datetime if the value type is string. - :return: ``True`` if the ``x`` is within the time range + Parse and convert to datetime if the value type is ``str``. + :return: |True| if the ``x`` is within the time range :rtype: bool :Examples: @@ -112,10 +130,12 @@ def __contains__(self, x): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print "2015-03-22T10:05:00+0900" in time_range print "2015-03-22T10:15:00+0900" in time_range - time_range_smaller = DateTimeRange("2015-03-22T10:03:00+0900", "2015-03-22T10:07:00+0900") + time_range_smaller = DateTimeRange( + "2015-03-22T10:03:00+0900", "2015-03-22T10:07:00+0900") print time_range_smaller in time_range .. parsed-literal:: @@ -124,8 +144,8 @@ def __contains__(self, x): False .. seealso:: - :py:meth:`validate_time_inversion` + :py:meth:`.validate_time_inversion` """ self.validate_time_inversion() @@ -143,7 +163,7 @@ def __contains__(self, x): @property def start_datetime(self): """ - :return: Start time of the time range + :return: Start time of the time range. :rtype: datetime.datetime :Examples: @@ -151,7 +171,8 @@ def start_datetime(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range.start_datetime .. parsed-literal:: @@ -164,7 +185,7 @@ def start_datetime(self): @property def end_datetime(self): """ - :return: End time of the time range + :return: End time of the time range. :rtype: datetime.datetime :Examples: @@ -172,7 +193,8 @@ def end_datetime(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range.end_datetime .. parsed-literal:: @@ -185,7 +207,8 @@ def end_datetime(self): @property def timedelta(self): """ - :return: (end_time - start_time) as datetime.timedelta + :return: + (|attr_end_datetime| - |attr_start_datetime|) as |timedelta| :rtype: datetime.timedelta :Examples: @@ -193,7 +216,8 @@ def timedelta(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range.timedelta .. parsed-literal:: @@ -205,7 +229,9 @@ def timedelta(self): def is_set(self): """ - :return: True if start_datetime and end_datetime is not None + :return: + |True| if both |attr_start_datetime| and + |attr_end_datetime| were not |None|. :rtype: bool :Examples: @@ -215,7 +241,8 @@ def is_set(self): from datetimerange import DateTimeRange time_range = DateTimeRange() print time_range.is_set() - time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range.set_time_range( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print time_range.is_set() .. parsed-literal:: @@ -233,17 +260,20 @@ def validate_time_inversion(self): """ Check time inversion of the time range. - :raises ValueError: If ``start_time`` is bigger than ``end_time`` + :raises ValueError: + If |attr_start_datetime| is + bigger than |attr_end_datetime|. :raises TypeError: - Any one of ``start_time`` and ``end_time``, - or both, is not a appropriate datetime value. + Any one of |attr_start_datetime| and |attr_end_datetime|, + or both is inappropriate datetime value. :Examples: .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:10:00+0900", "2015-03-22T10:00:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:10:00+0900", "2015-03-22T10:00:00+0900") try: time_range.validate_time_inversion() except ValueError: @@ -265,7 +295,9 @@ def validate_time_inversion(self): def is_valid_timerange(self): """ - :return: ``True`` if the timerange is not null and not time inversion. + :return: + |True| if the time range is + not null and not time inversion. :rtype: bool :Examples: @@ -275,9 +307,11 @@ def is_valid_timerange(self): from datetimerange import DateTimeRange time_range = DateTimeRange() print time_range.is_valid_timerange() - time_range.set_time_range("2015-03-22T10:20:00+0900", "2015-03-22T10:10:00+0900") + time_range.set_time_range( + "2015-03-22T10:20:00+0900", "2015-03-22T10:10:00+0900") print time_range.is_valid_timerange() - time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range.set_time_range( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print time_range.is_valid_timerange() .. parsed-literal:: @@ -288,8 +322,8 @@ def is_valid_timerange(self): .. seealso:: - :py:meth:`is_set` - :py:meth:`validate_time_inversion` + :py:meth:`.is_set` + :py:meth:`.validate_time_inversion` """ try: @@ -301,8 +335,8 @@ def is_valid_timerange(self): def is_intersection(self, x): """ - :param datetime.datetime x: datetime to compare - :return: ``True`` if intersect with ``x`` + :param DateTimeRange x: Value to compare + :return: |True| if intersect with ``x`` :rtype: bool :Examples: @@ -310,17 +344,15 @@ def is_intersection(self, x): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") - x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + x = DateTimeRange( + "2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") time_range.is_intersection(x) .. parsed-literal:: True - - .. seealso:: - - :py:meth:`intersection` """ import copy @@ -333,8 +365,9 @@ def is_intersection(self, x): def get_start_time_str(self): """ :return: - ``start_datetime`` as string formatted with ``start_time_format``. - Return `'NaT'` if invalid datetime or format. + |attr_start_datetime| as |str| formatted with + |attr_start_time_format|. + Return |NaT| if invalid datetime or format. :rtype: str :Examples: @@ -342,7 +375,8 @@ def get_start_time_str(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print time_range.get_start_time_str() time_range.start_time_format = "%Y/%m/%d %H:%M:%S" print time_range.get_start_time_str() @@ -361,8 +395,9 @@ def get_start_time_str(self): def get_end_time_str(self): """ :return: - ``end_datetime`` as string formatted with ``end_time_format``. - Return `'NaT'` if invalid datetime or format. + |attr_end_datetime| as a |str| formatted with + |attr_end_time_format|. + Return |NaT| if invalid datetime or format. :rtype: str :Examples: @@ -370,7 +405,8 @@ def get_end_time_str(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print time_range.get_end_time_str() time_range.end_time_format = "%Y/%m/%d %H:%M:%S" print time_range.get_end_time_str() @@ -388,7 +424,7 @@ def get_end_time_str(self): def get_timedelta_second(self): """ - :return: (end_time - start_time) as seconds + :return: (|attr_end_datetime| - |attr_start_datetime|) as seconds :rtype: float :Examples: @@ -396,7 +432,8 @@ def get_timedelta_second(self): .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range.get_timedelta_second() .. parsed-literal:: @@ -410,10 +447,7 @@ def set_start_datetime(self, value): """ Set the start time of the time range. - :param datetime.datetime/str value: - Value to set. - Parse and convert to datetime if the value type is string. - Parser engine of datetime string is the dateutil.parser. + :param datetime.datetime/str value: |param_start_datetime| :Examples: @@ -441,10 +475,7 @@ def set_end_datetime(self, value): """ Set the end time of the time range. - :param datetime.datetime/str value: - Value to set. - Parse and convert to datetime if the value type is string. - Parser engine of datetime string is the dateutil.parser. + :param datetime.datetime/str value: |param_end_datetime| :Examples: @@ -470,8 +501,8 @@ def set_end_datetime(self, value): def set_time_range(self, start, end): """ - :param datetime.datetime/str start: - :param datetime.datetime/str end: + :param datetime.datetime/str start: |param_start_datetime| + :param datetime.datetime/str end: |param_end_datetime| :Examples: @@ -480,18 +511,14 @@ def set_time_range(self, start, end): from datetimerange import DateTimeRange time_range = DateTimeRange() print time_range - time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range.set_time_range( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") print time_range .. parsed-literal:: NaT - NaT 2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900 - - .. seealso:: - - :py:meth:`set_start_datetime` - :py:meth:`set_end_datetime` """ self.set_start_datetime(start) @@ -566,7 +593,8 @@ def range(self, step): import datetime from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-01-01T00:00:00+0900", "2015-01-04T00:00:00+0900") + time_range = DateTimeRange( + "2015-01-01T00:00:00+0900", "2015-01-04T00:00:00+0900") for value in time_range.range(datetime.timedelta(days=1)): print value @@ -603,17 +631,21 @@ def range(self, step): def intersection(self, x): """ - Newly set a time range that overlaps the input and the current time range. + Newly set a time range that overlaps + the input and the current time range. :param DateTimeRange x: + Value to compute intersection with the current time range. :Examples: .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") - x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + x = DateTimeRange( + "2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") time_range.intersection(x) time_range @@ -637,17 +669,21 @@ def intersection(self, x): def encompass(self, x): """ - Newly set a time range that encompasses the input and the current time range. + Newly set a time range that encompasses + the input and the current time range. :param DateTimeRange x: + Value to compute encompass with the current time range. :Examples: .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") - x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + x = DateTimeRange( + "2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900") time_range.encompass(x) time_range @@ -666,14 +702,15 @@ def truncate(self, percentage): """ Truncate ``percentage`` / 2 [%] of whole time from first and last time. - :param float percentage: Percentage of truncate + :param float percentage: Percentage of truncate. :Examples: .. code:: python from datetimerange import DateTimeRange - time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") + time_range = DateTimeRange( + "2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900") time_range.is_output_elapse = True print time_range time_range.truncate(10) @@ -734,7 +771,7 @@ def __convert_datetime(self, value): def is_datetime(value): """ - :return: ``True`` if type of `value` is datetime.datetime. + :return: |True| if the type of `value` is |datetime|. :rtype: bool """ diff --git a/docs/conf.py b/docs/conf.py index f67078f..91f736e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,8 +12,9 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import pkg_resources +import sys import sphinx_rtd_theme @@ -35,8 +36,11 @@ 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', ] +intersphinx_mapping = {'python': ('http://docs.python.org/', None)} + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -61,9 +65,9 @@ # built documents. # # The short X.Y version. -version = u'' +version = pkg_resources.get_distribution("DateTimeRange").version # The full version, including alpha/beta/rc tags. -release = u'' +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -360,3 +364,43 @@ # If false, no index is generated. #epub_use_index = True + + +# ------------------------------------------------ + +builtin = u""" +.. |False| replace:: :py:obj:`False` +.. |True| replace:: :py:obj:`True` +.. |None| replace:: :py:obj:`None` + +.. |int| replace:: :py:class:`str` +.. |float| replace:: :py:class:`str` +.. |str| replace:: :py:class:`str` +.. |bool| replace:: :py:class:`bool` +""" + +module = u""" +.. |datetime| replace:: :py:class:`datetime.datetime` +.. |timedelta| replace:: :py:class:`datetime.timedelta` +""" + + +rst_prolog = builtin + module + u""" +.. |NaT| replace:: :py:attr:`.NOT_A_TIME_STR` + +.. |attr_start_datetime| replace:: :py:attr:`.start_datetime` +.. |attr_end_datetime| replace:: :py:attr:`.end_datetime` +.. |attr_start_time_format| replace:: :py:attr:`.start_time_format` +.. |attr_end_time_format| replace:: :py:attr:`.end_time_format` + +.. |param_start_datetime| replace:: + Value to set to the **start** time of the time range. + Parse and convert to |datetime| if the value type is |str|. + Parser function of datetime string is the :py:func:`dateutil.parser.parse`. + +.. |param_end_datetime| replace:: + Value to set to the **end** time of the time range. + Parse and convert to |datetime| if the value type is |str|. + Parser function of datetime string is the :py:func:`dateutil.parser.parse`. + +""" diff --git a/docs/index.rst b/docs/index.rst index e8f20f8..24905aa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,13 +6,6 @@ Welcome to DateTimeRange's documentation! ========================================= - -GitHub repository -================= - -https://github.com/thombashi/DateTimeRange - - .. toctree:: :caption: Table of Contents :maxdepth: 4 @@ -23,6 +16,7 @@ https://github.com/thombashi/DateTimeRange pages/examples/index pages/reference/index pages/genindex + pages/links Indices and tables diff --git a/docs/pages/examples/index.rst b/docs/pages/examples/index.rst index 703a986..36a1284 100644 --- a/docs/pages/examples/index.rst +++ b/docs/pages/examples/index.rst @@ -2,7 +2,7 @@ Examples ======== :py:class:`datetime.datetime` instance can be used as an argument value as well as -time-string in the below examples. +time-string in the following examples. .. note:: diff --git a/docs/pages/introduction.rst b/docs/pages/introduction.rst index fd80d06..ade55a5 100644 --- a/docs/pages/introduction.rst +++ b/docs/pages/introduction.rst @@ -16,7 +16,7 @@ Summary DateTimeRange is a python library to handle routine work associated with a time range, such as test whether a time is within the time range, -get time range intersection, truncating the time range etc. +get time range intersection, truncating the time range, etc. diff --git a/docs/pages/links.rst b/docs/pages/links.rst new file mode 100644 index 0000000..8ece393 --- /dev/null +++ b/docs/pages/links.rst @@ -0,0 +1,9 @@ +Links +===== + +- pip: tool for installing python packages + - https://pip.pypa.io/en/stable/ +- GitHub repository + - https://github.com/thombashi/DateTimeRange +- PyPI + - https://pypi.python.org/pypi/DateTimeRange diff --git a/test/test_datetimerange.py b/test/test_datetimerange.py index 995ecbf..7136b4a 100644 --- a/test/test_datetimerange.py +++ b/test/test_datetimerange.py @@ -6,9 +6,8 @@ import datetime -import dateutil -from dateutil.relativedelta import * -from dateutil.parser import * +from dateutil.relativedelta import relativedelta +from dateutil.parser import parse import pytest from datetimerange import DateTimeRange @@ -410,8 +409,18 @@ class Test_DateTimeRange_contains: [END_DATETIME_TEXT, True], [TEST_START_DATETIME, True], [TEST_END_DATETIME, True], - [DateTimeRange("2015-03-22 10:05:00" + TIMEZONE, "2015-03-22 10:06:00" + TIMEZONE), True], - [DateTimeRange("2015-03-22 10:10:01" + TIMEZONE, "2015-03-22 10:11:01" + TIMEZONE), False], + [ + DateTimeRange( + "2015-03-22 10:05:00" + TIMEZONE, + "2015-03-22 10:06:00" + TIMEZONE), + True, + ], + [ + DateTimeRange( + "2015-03-22 10:10:01" + TIMEZONE, + "2015-03-22 10:11:01" + TIMEZONE), + False + ], ["2015-03-22 09:59:59" + TIMEZONE, False], ["2015-03-22 10:10:01" + TIMEZONE, False], ])