From 9af5080cfe78cd2d56dff982ed76ee78711b8063 Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Thu, 4 Mar 2021 19:07:58 +0000 Subject: [PATCH 1/9] Start working through docstrings --- arrow/arrow.py | 22 ++++++++++------------ arrow/factory.py | 7 +------ arrow/util.py | 19 +++++++++++++++++-- 3 files changed, 28 insertions(+), 20 deletions(-) diff --git a/arrow/arrow.py b/arrow/arrow.py index dda7b4056..e5d78846f 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -91,7 +91,7 @@ class Arrow: :param second: (optional) the second, Defaults to 0. :param microsecond: (optional) the microsecond. Defaults to 0. :param tzinfo: (optional) A timezone expression. Defaults to UTC. - :param fold: (optional) 0 or 1, used to disambiguate repeated times. Defaults to 0. + :param fold: (optional) 0 or 1, used to disambiguate repeated wall times. Defaults to 0. .. _tz-expr: @@ -245,6 +245,7 @@ def fromtimestamp( :param timestamp: an ``int`` or ``float`` timestamp, or a ``str`` that converts to either. :param tzinfo: (optional) a ``tzinfo`` object. Defaults to local time. + """ if tzinfo is None: @@ -305,13 +306,6 @@ def fromdatetime(cls, dt: dt_datetime, tzinfo: Optional[TZ_EXPR] = None) -> "Arr :param tzinfo: (optional) A :ref:`timezone expression `. Defaults to ``dt``'s timezone, or UTC if naive. - If you only want to replace the timezone of naive datetimes:: - - >>> dt - datetime.datetime(2013, 5, 5, 0, 0, tzinfo=tzutc()) - >>> arrow.Arrow.fromdatetime(dt, dt.tzinfo or 'US/Pacific') - - """ if tzinfo is None: @@ -335,10 +329,11 @@ def fromdatetime(cls, dt: dt_datetime, tzinfo: Optional[TZ_EXPR] = None) -> "Arr @classmethod def fromdate(cls, date: date, tzinfo: Optional[TZ_EXPR] = None) -> "Arrow": """Constructs an :class:`Arrow ` object from a ``date`` and optional - replacement timezone. Time values are set to 0. + replacement timezone. All time values are set to 0. :param date: the ``date`` :param tzinfo: (optional) A :ref:`timezone expression `. Defaults to UTC. + """ if tzinfo is None: @@ -354,7 +349,7 @@ def strptime( in the style of ``datetime.strptime``. Optionally replaces the parsed timezone. :param date_str: the date string. - :param fmt: the format string. + :param fmt: the format string using datetime format codes. :param tzinfo: (optional) A :ref:`timezone expression `. Defaults to the parsed timezone if ``fmt`` contains a timezone directive, otherwise UTC. @@ -438,7 +433,7 @@ def range( iterating. As such, either call with naive objects and ``tz``, or aware objects from the same timezone and no ``tz``. - Supported frame values: year, quarter, month, week, day, hour, minute, second. + Supported frame values: year, quarter, month, week, day, hour, minute, second, microsecond. Recognized datetime expressions: @@ -505,7 +500,7 @@ def span( bounds: _BOUNDS = "[)", exact: bool = False, ) -> Tuple["Arrow", "Arrow"]: - """Returns two new :class:`Arrow ` objects, representing the timespan + """Returns a tuple of two new :class:`Arrow ` objects, representing the timespan of the :class:`Arrow ` object in a given timeframe. :param frame: the timeframe. Can be any ``datetime`` property (day, hour, minute...). @@ -589,6 +584,7 @@ def floor(self, frame: _T_FRAMES) -> "Arrow": >>> arrow.utcnow().floor('hour') + """ return self.span(frame)[0] @@ -605,10 +601,12 @@ def ceil(self, frame: _T_FRAMES) -> "Arrow": >>> arrow.utcnow().ceil('hour') + """ return self.span(frame)[1] + # NOTE progress marker @classmethod def span_range( cls, diff --git a/arrow/factory.py b/arrow/factory.py index 231510f58..1484796eb 100644 --- a/arrow/factory.py +++ b/arrow/factory.py @@ -107,11 +107,6 @@ def get(self, *args: Any, **kwargs: Any) -> Arrow: >>> arrow.get() - **None** to also get current UTC time:: - - >>> arrow.get(None) - - **One** :class:`Arrow ` object, to get a copy. >>> arw = arrow.utcnow() @@ -189,7 +184,7 @@ def get(self, *args: Any, **kwargs: Any) -> Arrow: >>> arrow.get('2013-05-05 12:30:45', ['MM/DD/YYYY', 'YYYY-MM-DD HH:mm:ss']) - **Three or more** arguments, as for the constructor of a ``datetime``:: + **Three or more** arguments, as for the direct constructor of an ``Arrow`` object:: >>> arrow.get(2013, 5, 5, 12, 30, 45) diff --git a/arrow/util.py b/arrow/util.py index 8679131ee..c5313c4f5 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -1,3 +1,8 @@ +""" +Helpful functions used internally within Arrow. + +""" + import datetime from typing import Any, Optional, cast @@ -57,7 +62,11 @@ def is_timestamp(value: Any) -> bool: def validate_ordinal(value: Any) -> None: - """Raise the corresponding exception if value is an invalid Gregorian ordinal.""" + """Raise an exception if value is an invalid Gregorian ordinal. + + :param value: the input to be checked + + """ if isinstance(value, bool) or not isinstance(value, int): raise TypeError(f"Ordinal must be an integer (got type {type(value)}).") if not (MIN_ORDINAL <= value <= MAX_ORDINAL): @@ -78,7 +87,13 @@ def normalize_timestamp(timestamp: float) -> float: # Credit to https://stackoverflow.com/a/1700069 def iso_to_gregorian(iso_year: int, iso_week: int, iso_day: int) -> datetime.date: - """Converts an ISO week date tuple into a datetime object.""" + """Converts an ISO week date into a datetime object. + + :param iso_year: the year + :param iso_week: the week number + :param iso_day: the day numbered 1 through 7, beginning with Monday + + """ if not 1 <= iso_week <= 53: raise ValueError("ISO Calendar week value must be between 1-53.") From 907a87e0bf059533340b67c87ae8f1ae0a2be6ca Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Sun, 14 Mar 2021 20:19:11 +0000 Subject: [PATCH 2/9] Further work on module docstrings --- arrow/constants.py | 4 ++++ arrow/formatter.py | 5 +++++ arrow/locales.py | 5 +++++ arrow/parser.py | 5 +++++ arrow/util.py | 3 ++- 5 files changed, 21 insertions(+), 1 deletion(-) diff --git a/arrow/constants.py b/arrow/constants.py index 22ffe55dc..4497f31f2 100644 --- a/arrow/constants.py +++ b/arrow/constants.py @@ -1,3 +1,7 @@ +""" +Constants that vary between operating systems. +""" + import sys from datetime import datetime diff --git a/arrow/formatter.py b/arrow/formatter.py index 14eb44a20..b26d862de 100644 --- a/arrow/formatter.py +++ b/arrow/formatter.py @@ -1,3 +1,8 @@ +""" +Provides the :class:`Arrow ` class, an improved formatter for datetimes. + +""" + import re import sys from datetime import datetime, timedelta diff --git a/arrow/locales.py b/arrow/locales.py index d801f9d63..8e7696bfd 100644 --- a/arrow/locales.py +++ b/arrow/locales.py @@ -1,3 +1,8 @@ +""" +Provides internationalization for arrow in over 60 languages and dialects. + +""" + import inspect import sys from math import trunc diff --git a/arrow/parser.py b/arrow/parser.py index a6a617dbc..e87e370ef 100644 --- a/arrow/parser.py +++ b/arrow/parser.py @@ -1,3 +1,8 @@ +""" +Provides the :class:`Arrow ` class, a better parsing for datetime strings. + +""" + import re import sys from datetime import datetime, timedelta diff --git a/arrow/util.py b/arrow/util.py index c5313c4f5..b6cb8305e 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -1,5 +1,5 @@ """ -Helpful functions used internally within Arrow. +Helpful functions used internally within arrow. """ @@ -85,6 +85,7 @@ def normalize_timestamp(timestamp: float) -> float: return timestamp +# NOTE finish the params # Credit to https://stackoverflow.com/a/1700069 def iso_to_gregorian(iso_year: int, iso_week: int, iso_day: int) -> datetime.date: """Converts an ISO week date into a datetime object. From 3d6d673e3c5cec63a9ce102cf18f877e8cfddf14 Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Sat, 20 Mar 2021 17:25:12 +0000 Subject: [PATCH 3/9] Further work on docstrings --- arrow/constants.py | 3 ++- arrow/parser.py | 2 +- arrow/util.py | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/arrow/constants.py b/arrow/constants.py index 4497f31f2..a991ae27f 100644 --- a/arrow/constants.py +++ b/arrow/constants.py @@ -1,5 +1,6 @@ """ -Constants that vary between operating systems. +Constants used internally in arrow.. + """ import sys diff --git a/arrow/parser.py b/arrow/parser.py index e87e370ef..ecf01a297 100644 --- a/arrow/parser.py +++ b/arrow/parser.py @@ -1,5 +1,5 @@ """ -Provides the :class:`Arrow ` class, a better parsing for datetime strings. +Provides the :class:`Arrow ` class, a better way to parse datetime strings. """ diff --git a/arrow/util.py b/arrow/util.py index b6cb8305e..fa4a9eb5e 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -91,7 +91,7 @@ def iso_to_gregorian(iso_year: int, iso_week: int, iso_day: int) -> datetime.dat """Converts an ISO week date into a datetime object. :param iso_year: the year - :param iso_week: the week number + :param iso_week: the week number, each year has either 52 or 53 weeks :param iso_day: the day numbered 1 through 7, beginning with Monday """ From c600454ddbc942dc7e5a229266184b4a46eab80f Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Sat, 27 Mar 2021 22:01:45 +0000 Subject: [PATCH 4/9] Continue review of arrow.py and fix #946 --- arrow/arrow.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/arrow/arrow.py b/arrow/arrow.py index e5d78846f..dc921908c 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -606,7 +606,6 @@ def ceil(self, frame: _T_FRAMES) -> "Arrow": return self.span(frame)[1] - # NOTE progress marker @classmethod def span_range( cls, @@ -643,7 +642,7 @@ def span_range( iterating. As such, either call with naive objects and ``tz``, or aware objects from the same timezone and no ``tz``. - Supported frame values: year, quarter, month, week, day, hour, minute, second. + Supported frame values: year, quarter, month, week, day, hour, minute, second, microsecond. Recognized datetime expressions: @@ -847,8 +846,8 @@ def timestamp(self) -> float: Usage:: - >>> arrow.utcnow().timestamp - 1548260567 + >>> arrow.utcnow().timestamp() + 1616882340.256501 """ @@ -856,7 +855,7 @@ def timestamp(self) -> float: @property def int_timestamp(self) -> int: - """Returns a timestamp representation of the :class:`Arrow ` object, in + """Returns a integer timestamp representation of the :class:`Arrow ` object, in UTC time. Usage:: @@ -870,7 +869,7 @@ def int_timestamp(self) -> int: @property def float_timestamp(self) -> float: - """Returns a floating-point representation of the :class:`Arrow ` + """Returns a floating-point timestamp representation of the :class:`Arrow ` object, in UTC time. Usage:: @@ -890,7 +889,10 @@ def fold(self) -> int: @property def ambiguous(self) -> bool: - """ Returns a boolean indicating whether the :class:`Arrow ` object is ambiguous.""" + """Indicates whether the :class:`Arrow ` object is a repeated wall time in the current + timezone. + + """ return dateutil_tz.datetime_ambiguous(self._datetime) @@ -1067,7 +1069,7 @@ def to(self, tz: TZ_EXPR) -> "Arrow": def format(self, fmt: str = "YYYY-MM-DD HH:mm:ssZZ", locale: str = "en_us") -> str: """Returns a string representation of the :class:`Arrow ` object, - formatted according to a format string. + formatted according to the provided format string. :param fmt: the format string. :param locale: the locale to format. @@ -1281,8 +1283,8 @@ def is_between( end: "Arrow", bounds: _BOUNDS = "()", ) -> bool: - """Returns a boolean denoting whether the specified date and time is between - the start and end dates and times. + """Returns a boolean denoting whether the :class:`Arrow ` object is between + the start and end limits. :param start: an :class:`Arrow ` object. :param end: an :class:`Arrow ` object. @@ -1620,7 +1622,7 @@ def __le__(self, other: Any) -> bool: return self._datetime <= self._get_datetime(other) # internal methods - + # Progress marker @staticmethod def _get_tzinfo(tz_expr: Optional[TZ_EXPR]) -> dt_tzinfo: From 3453a764a4d33455110fb6432f6d70ba93e232d2 Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Mon, 29 Mar 2021 21:27:49 +0100 Subject: [PATCH 5/9] Finish off arrow.py --- arrow/arrow.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/arrow/arrow.py b/arrow/arrow.py index dc921908c..f8ad7ce2d 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -1622,10 +1622,9 @@ def __le__(self, other: Any) -> bool: return self._datetime <= self._get_datetime(other) # internal methods - # Progress marker @staticmethod def _get_tzinfo(tz_expr: Optional[TZ_EXPR]) -> dt_tzinfo: - + """Get normalized tzinfo object from various inputs.""" if tz_expr is None: return dateutil_tz.tzutc() if isinstance(tz_expr, dt_tzinfo): @@ -1640,7 +1639,7 @@ def _get_tzinfo(tz_expr: Optional[TZ_EXPR]) -> dt_tzinfo: def _get_datetime( cls, expr: Union["Arrow", dt_datetime, int, float, str] ) -> dt_datetime: - """Get datetime object for a specified expression.""" + """Get datetime object from a specified expression.""" if isinstance(expr, Arrow): return expr.datetime elif isinstance(expr, dt_datetime): @@ -1653,7 +1652,11 @@ def _get_datetime( @classmethod def _get_frames(cls, name: _T_FRAMES) -> Tuple[str, str, int]: + """Finds relevant timeframe and steps for use in range and span methods. + + Returns a 3 element tuple in the form ("day", "days", 1.) + """ if name in cls._ATTRS: return name, f"{name}s", 1 elif name[-1] == "s" and name[:-1] in cls._ATTRS: @@ -1682,7 +1685,7 @@ def _get_frames(cls, name: _T_FRAMES) -> Tuple[str, str, int]: @classmethod def _get_iteration_params(cls, end: Any, limit: Optional[int]) -> Tuple[Any, int]: - + """Sets default end and limit values for range method.""" if end is None: if limit is None: @@ -1697,6 +1700,7 @@ def _get_iteration_params(cls, end: Any, limit: Optional[int]) -> Tuple[Any, int @staticmethod def _is_last_day_of_month(date: "Arrow") -> bool: + """Returns a boolean indicating whether the datetime is the last day of the month.""" return date.day == calendar.monthrange(date.year, date.month)[1] From 525da7946d2543f93e04bd2a40de8f5bcfef5d15 Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Mon, 29 Mar 2021 21:31:39 +0100 Subject: [PATCH 6/9] Remove comment --- arrow/util.py | 1 - 1 file changed, 1 deletion(-) diff --git a/arrow/util.py b/arrow/util.py index fa4a9eb5e..9350ed831 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -85,7 +85,6 @@ def normalize_timestamp(timestamp: float) -> float: return timestamp -# NOTE finish the params # Credit to https://stackoverflow.com/a/1700069 def iso_to_gregorian(iso_year: int, iso_week: int, iso_day: int) -> datetime.date: """Converts an ISO week date into a datetime object. From 5afaf4e2efe62e29a53c9f5c67031c635a78a0da Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Wed, 7 Apr 2021 19:50:02 +0100 Subject: [PATCH 7/9] Suggested changes --- arrow/arrow.py | 4 ++-- arrow/constants.py | 5 +---- arrow/formatter.py | 5 +---- arrow/locales.py | 5 +---- arrow/parser.py | 5 +---- arrow/util.py | 2 +- 6 files changed, 7 insertions(+), 19 deletions(-) diff --git a/arrow/arrow.py b/arrow/arrow.py index f8ad7ce2d..a87a3101e 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -855,7 +855,7 @@ def timestamp(self) -> float: @property def int_timestamp(self) -> int: - """Returns a integer timestamp representation of the :class:`Arrow ` object, in + """Returns an integer timestamp representation of the :class:`Arrow ` object, in UTC time. Usage:: @@ -1654,7 +1654,7 @@ def _get_datetime( def _get_frames(cls, name: _T_FRAMES) -> Tuple[str, str, int]: """Finds relevant timeframe and steps for use in range and span methods. - Returns a 3 element tuple in the form ("day", "days", 1.) + Returns a 3 element tuple in the form (frame, plural frame, step), for example ("day", "days", 1) """ if name in cls._ATTRS: diff --git a/arrow/constants.py b/arrow/constants.py index a991ae27f..f59b50183 100644 --- a/arrow/constants.py +++ b/arrow/constants.py @@ -1,7 +1,4 @@ -""" -Constants used internally in arrow.. - -""" +"""Constants used internally in arrow.""" import sys from datetime import datetime diff --git a/arrow/formatter.py b/arrow/formatter.py index b26d862de..1744faec4 100644 --- a/arrow/formatter.py +++ b/arrow/formatter.py @@ -1,7 +1,4 @@ -""" -Provides the :class:`Arrow ` class, an improved formatter for datetimes. - -""" +"""Provides the :class:`Arrow ` class, an improved formatter for datetimes.""" import re import sys diff --git a/arrow/locales.py b/arrow/locales.py index d2b802956..055af7ca4 100644 --- a/arrow/locales.py +++ b/arrow/locales.py @@ -1,7 +1,4 @@ -""" -Provides internationalization for arrow in over 60 languages and dialects. - -""" +"""Provides internationalization for arrow in over 60 languages and dialects.""" import inspect import sys diff --git a/arrow/parser.py b/arrow/parser.py index ecf01a297..ca0eac18c 100644 --- a/arrow/parser.py +++ b/arrow/parser.py @@ -1,7 +1,4 @@ -""" -Provides the :class:`Arrow ` class, a better way to parse datetime strings. - -""" +"""Provides the :class:`Arrow ` class, a better way to parse datetime strings.""" import re import sys diff --git a/arrow/util.py b/arrow/util.py index 9350ed831..667925679 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -62,7 +62,7 @@ def is_timestamp(value: Any) -> bool: def validate_ordinal(value: Any) -> None: - """Raise an exception if value is an invalid Gregorian ordinal. + """Raise an exception if value is an invalid Gregorian ordinal. :param value: the input to be checked From ae65daf4f7e2b4cf8ce73edb95d1e6d3abe844da Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Thu, 8 Apr 2021 20:33:06 +0100 Subject: [PATCH 8/9] New example for fromdatetime() --- arrow/arrow.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/arrow/arrow.py b/arrow/arrow.py index a87a3101e..f116e1dd2 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -306,6 +306,13 @@ def fromdatetime(cls, dt: dt_datetime, tzinfo: Optional[TZ_EXPR] = None) -> "Arr :param tzinfo: (optional) A :ref:`timezone expression `. Defaults to ``dt``'s timezone, or UTC if naive. + Usage:: + + >>> dt + datetime.datetime(2021, 4, 7, 13, 48) + >>> arrow.Arrow.fromdatetime(dt) + + """ if tzinfo is None: From 996d0475cb6d83ace0ff7a939298b8215a6d0dd5 Mon Sep 17 00:00:00 2001 From: Chris Brown <30196510+systemcatch@users.noreply.github.com> Date: Sun, 11 Apr 2021 19:28:29 +0100 Subject: [PATCH 9/9] Minor changes --- arrow/arrow.py | 4 ++-- arrow/util.py | 5 +---- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/arrow/arrow.py b/arrow/arrow.py index f116e1dd2..90257bb34 100644 --- a/arrow/arrow.py +++ b/arrow/arrow.py @@ -309,9 +309,9 @@ def fromdatetime(cls, dt: dt_datetime, tzinfo: Optional[TZ_EXPR] = None) -> "Arr Usage:: >>> dt - datetime.datetime(2021, 4, 7, 13, 48) + datetime.datetime(2021, 4, 7, 13, 48, tzinfo=tzfile('/usr/share/zoneinfo/US/Pacific')) >>> arrow.Arrow.fromdatetime(dt) - + """ diff --git a/arrow/util.py b/arrow/util.py index 667925679..f3eaa21c9 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -1,7 +1,4 @@ -""" -Helpful functions used internally within arrow. - -""" +"""Helpful functions used internally within arrow.""" import datetime from typing import Any, Optional, cast