diff --git a/arrow/arrow.py b/arrow/arrow.py index dda7b405..90257bb3 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,12 +306,12 @@ 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:: + Usage:: >>> dt - datetime.datetime(2013, 5, 5, 0, 0, tzinfo=tzutc()) - >>> arrow.Arrow.fromdatetime(dt, dt.tzinfo or 'US/Pacific') - + datetime.datetime(2021, 4, 7, 13, 48, tzinfo=tzfile('/usr/share/zoneinfo/US/Pacific')) + >>> arrow.Arrow.fromdatetime(dt) + """ @@ -335,10 +336,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 +356,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 +440,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 +507,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 +591,7 @@ def floor(self, frame: _T_FRAMES) -> "Arrow": >>> arrow.utcnow().floor('hour') + """ return self.span(frame)[0] @@ -605,6 +608,7 @@ def ceil(self, frame: _T_FRAMES) -> "Arrow": >>> arrow.utcnow().ceil('hour') + """ return self.span(frame)[1] @@ -645,7 +649,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: @@ -849,8 +853,8 @@ def timestamp(self) -> float: Usage:: - >>> arrow.utcnow().timestamp - 1548260567 + >>> arrow.utcnow().timestamp() + 1616882340.256501 """ @@ -858,7 +862,7 @@ def timestamp(self) -> float: @property def int_timestamp(self) -> int: - """Returns a timestamp representation of the :class:`Arrow ` object, in + """Returns an integer timestamp representation of the :class:`Arrow ` object, in UTC time. Usage:: @@ -872,7 +876,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:: @@ -892,7 +896,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) @@ -1069,7 +1076,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. @@ -1283,8 +1290,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. @@ -1622,10 +1629,9 @@ def __le__(self, other: Any) -> bool: return self._datetime <= self._get_datetime(other) # internal methods - @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 +1646,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 +1659,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 (frame, plural frame, step), for example ("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 +1692,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 +1707,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] diff --git a/arrow/constants.py b/arrow/constants.py index 22ffe55d..f59b5018 100644 --- a/arrow/constants.py +++ b/arrow/constants.py @@ -1,3 +1,5 @@ +"""Constants used internally in arrow.""" + import sys from datetime import datetime diff --git a/arrow/factory.py b/arrow/factory.py index 231510f5..1484796e 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/formatter.py b/arrow/formatter.py index 14eb44a2..1744faec 100644 --- a/arrow/formatter.py +++ b/arrow/formatter.py @@ -1,3 +1,5 @@ +"""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 5942bd85..e00a63c7 100644 --- a/arrow/locales.py +++ b/arrow/locales.py @@ -1,3 +1,5 @@ +"""Provides internationalization for arrow in over 60 languages and dialects.""" + import sys from math import trunc from typing import ( diff --git a/arrow/parser.py b/arrow/parser.py index a6a617db..ca0eac18 100644 --- a/arrow/parser.py +++ b/arrow/parser.py @@ -1,3 +1,5 @@ +"""Provides the :class:`Arrow ` class, a better way to parse datetime strings.""" + import re import sys from datetime import datetime, timedelta diff --git a/arrow/util.py b/arrow/util.py index 8679131e..f3eaa21c 100644 --- a/arrow/util.py +++ b/arrow/util.py @@ -1,3 +1,5 @@ +"""Helpful functions used internally within arrow.""" + import datetime from typing import Any, Optional, cast @@ -57,7 +59,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 +84,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, each year has either 52 or 53 weeks + :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.")