Audit all docstrings for style, typos and outdated info

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 <tz-expr>`.  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')
-            <Arrow [2013-05-05T00:00:00+00:00]>
+            datetime.datetime(2021, 4, 7, 13, 48, tzinfo=tzfile('/usr/share/zoneinfo/US/Pacific'))
+            >>> arrow.Arrow.fromdatetime(dt)
+            <Arrow [2021-04-07T13:48:00-07:00]>
 
         """
 
@@ -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 <arrow.arrow.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 <tz-expr>`.  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 <tz-expr>`.  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 <arrow.arrow.Arrow>` objects, representing the timespan
+        """Returns a tuple of two new :class:`Arrow <arrow.arrow.Arrow>` objects, representing the timespan
         of the :class:`Arrow <arrow.arrow.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')
             <Arrow [2013-05-09T03:00:00+00:00]>
+
         """
 
         return self.span(frame)[0]
@@ -605,6 +608,7 @@ def ceil(self, frame: _T_FRAMES) -> "Arrow":
 
             >>> arrow.utcnow().ceil('hour')
             <Arrow [2013-05-09T03:59:59.999999+00:00]>
+
         """
 
         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,16 +853,16 @@ def timestamp(self) -> float:
 
         Usage::
 
-            >>> arrow.utcnow().timestamp
-            1548260567
+            >>> arrow.utcnow().timestamp()
+            1616882340.256501
 
         """
 
         return self._datetime.timestamp()
 
     @property
     def int_timestamp(self) -> int:
-        """Returns a timestamp representation of the :class:`Arrow <arrow.arrow.Arrow>` object, in
+        """Returns an integer timestamp representation of the :class:`Arrow <arrow.arrow.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 <arrow.arrow.Arrow>`
+        """Returns a floating-point timestamp representation of the :class:`Arrow <arrow.arrow.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 <arrow.arrow.Arrow>` object is ambiguous."""
+        """Indicates whether the :class:`Arrow <arrow.arrow.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 <arrow.arrow.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 <arrow.arrow.Arrow>` object is between
+        the start and end limits.
 
         :param start: an :class:`Arrow <arrow.arrow.Arrow>` object.
         :param end: an :class:`Arrow <arrow.arrow.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]
 
 

arrow/constants.py

@@ -1,3 +1,5 @@
+"""Constants used internally in arrow."""
+
 import sys
 from datetime import datetime
 

arrow/factory.py

@@ -107,11 +107,6 @@ def get(self, *args: Any, **kwargs: Any) -> Arrow:
             >>> arrow.get()
             <Arrow [2013-05-08T05:51:43.316458+00:00]>
 
-        **None** to also get current UTC time::
-
-            >>> arrow.get(None)
-            <Arrow [2013-05-08T05:51:49.016458+00:00]>
-
         **One** :class:`Arrow <arrow.arrow.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'])
             <Arrow [2013-05-05T12:30:45+00:00]>
 
-        **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)
             <Arrow [2013-05-05T12:30:45+00:00]>

arrow/formatter.py

@@ -1,3 +1,5 @@
+"""Provides the :class:`Arrow <arrow.formatter.DateTimeFormatter>` class, an improved formatter for datetimes."""
+
 import re
 import sys
 from datetime import datetime, timedelta

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 (

arrow/parser.py

@@ -1,3 +1,5 @@
+"""Provides the :class:`Arrow <arrow.parser.DateTimeParser>` class, a better way to parse datetime strings."""
+
 import re
 import sys
 from datetime import datetime, timedelta

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.")