Standardize locales and improve locale validation (arrow-py#954)

* Progress toward locale validation

* standardize and validate locales

* Add tests

* Clean up tests

* Use new locale name in error

* Remove useless comments

* Address comments

* English

* Remove default locale from test_parser

README.rst

@@ -105,8 +105,8 @@ Example Usage
     >>> local.humanize()
     'an hour ago'
 
-    >>> local.humanize(locale='ko_kr')
-    '1시간 전'
+    >>> local.humanize(locale='ko-kr')
+    '한시간 전'
 
 .. end-inclusion-marker-do-not-remove
 

arrow/api.py

@@ -10,6 +10,7 @@
 from typing import Any, List, Optional, Tuple, Type, Union, overload
 
 from arrow.arrow import TZ_EXPR, Arrow
+from arrow.constants import DEFAULT_LOCALE
 from arrow.factory import ArrowFactory
 
 # internal default factory.
@@ -22,7 +23,7 @@
 @overload
 def get(
     *,
-    locale: str = "en_us",
+    locale: str = DEFAULT_LOCALE,
     tzinfo: Optional[TZ_EXPR] = None,
     normalize_whitespace: bool = False,
 ) -> Arrow:
@@ -32,7 +33,7 @@ def get(
 @overload
 def get(
     *args: int,
-    locale: str = "en_us",
+    locale: str = DEFAULT_LOCALE,
     tzinfo: Optional[TZ_EXPR] = None,
     normalize_whitespace: bool = False,
 ) -> Arrow:
@@ -53,7 +54,7 @@ def get(
         Tuple[int, int, int],
     ],
     *,
-    locale: str = "en_us",
+    locale: str = DEFAULT_LOCALE,
     tzinfo: Optional[TZ_EXPR] = None,
     normalize_whitespace: bool = False,
 ) -> Arrow:
@@ -65,7 +66,7 @@ def get(
     __arg1: Union[datetime, date],
     __arg2: TZ_EXPR,
     *,
-    locale: str = "en_us",
+    locale: str = DEFAULT_LOCALE,
     tzinfo: Optional[TZ_EXPR] = None,
     normalize_whitespace: bool = False,
 ) -> Arrow:
@@ -77,7 +78,7 @@ def get(
     __arg1: str,
     __arg2: Union[str, List[str]],
     *,
-    locale: str = "en_us",
+    locale: str = DEFAULT_LOCALE,
     tzinfo: Optional[TZ_EXPR] = None,
     normalize_whitespace: bool = False,
 ) -> Arrow:

arrow/arrow.py

@@ -32,6 +32,7 @@
 from dateutil.relativedelta import relativedelta
 
 from arrow import formatter, locales, parser, util
+from arrow.constants import DEFAULT_LOCALE
 from arrow.locales import TimeFrameLiteral
 
 if sys.version_info < (3, 8):  # pragma: no cover
@@ -1087,7 +1088,9 @@ def to(self, tz: TZ_EXPR) -> "Arrow":
 
     # string output and formatting
 
-    def format(self, fmt: str = "YYYY-MM-DD HH:mm:ssZZ", locale: str = "en_us") -> str:
+    def format(
+        self, fmt: str = "YYYY-MM-DD HH:mm:ssZZ", locale: str = DEFAULT_LOCALE
+    ) -> str:
         """Returns a string representation of the :class:`Arrow <arrow.arrow.Arrow>` object,
         formatted according to the provided format string.
 
@@ -1115,15 +1118,15 @@ def format(self, fmt: str = "YYYY-MM-DD HH:mm:ssZZ", locale: str = "en_us") -> s
     def humanize(
         self,
         other: Union["Arrow", dt_datetime, None] = None,
-        locale: str = "en_us",
+        locale: str = DEFAULT_LOCALE,
         only_distance: bool = False,
         granularity: Union[_GRANULARITY, List[_GRANULARITY]] = "auto",
     ) -> str:
         """Returns a localized, humanized representation of a relative difference in time.
 
         :param other: (optional) an :class:`Arrow <arrow.arrow.Arrow>` or ``datetime`` object.
             Defaults to now in the current :class:`Arrow <arrow.arrow.Arrow>` object's timezone.
-        :param locale: (optional) a ``str`` specifying a locale.  Defaults to 'en_us'.
+        :param locale: (optional) a ``str`` specifying a locale.  Defaults to 'en-us'.
         :param only_distance: (optional) returns only time difference eg: "11 seconds" without "in" or "ago" part.
         :param granularity: (optional) defines the precision of the output. Set it to strings 'second', 'minute',
                            'hour', 'day', 'week', 'month' or 'year' or a list of any combination of these strings

arrow/constants.py

@@ -34,3 +34,5 @@
 
 MAX_ORDINAL: Final[int] = datetime.max.toordinal()
 MIN_ORDINAL: Final[int] = 1
+
+DEFAULT_LOCALE: Final[str] = "en-us"

arrow/factory.py

@@ -16,6 +16,7 @@
 
 from arrow import parser
 from arrow.arrow import TZ_EXPR, Arrow
+from arrow.constants import DEFAULT_LOCALE
 from arrow.util import is_timestamp, iso_to_gregorian
 
 
@@ -36,7 +37,7 @@ def __init__(self, type: Type[Arrow] = Arrow) -> None:
     def get(
         self,
         *,
-        locale: str = "en_us",
+        locale: str = DEFAULT_LOCALE,
         tzinfo: Optional[TZ_EXPR] = None,
         normalize_whitespace: bool = False,
     ) -> Arrow:
@@ -57,7 +58,7 @@ def get(
             Tuple[int, int, int],
         ],
         *,
-        locale: str = "en_us",
+        locale: str = DEFAULT_LOCALE,
         tzinfo: Optional[TZ_EXPR] = None,
         normalize_whitespace: bool = False,
     ) -> Arrow:
@@ -69,7 +70,7 @@ def get(
         __arg1: Union[datetime, date],
         __arg2: TZ_EXPR,
         *,
-        locale: str = "en_us",
+        locale: str = DEFAULT_LOCALE,
         tzinfo: Optional[TZ_EXPR] = None,
         normalize_whitespace: bool = False,
     ) -> Arrow:
@@ -81,7 +82,7 @@ def get(
         __arg1: str,
         __arg2: Union[str, List[str]],
         *,
-        locale: str = "en_us",
+        locale: str = DEFAULT_LOCALE,
         tzinfo: Optional[TZ_EXPR] = None,
         normalize_whitespace: bool = False,
     ) -> Arrow:
@@ -90,7 +91,7 @@ def get(
     def get(self, *args: Any, **kwargs: Any) -> Arrow:
         """Returns an :class:`Arrow <arrow.arrow.Arrow>` object based on flexible inputs.
 
-        :param locale: (optional) a ``str`` specifying a locale for the parser. Defaults to 'en_us'.
+        :param locale: (optional) a ``str`` specifying a locale for the parser. Defaults to 'en-us'.
         :param tzinfo: (optional) a :ref:`timezone expression <tz-expr>` or tzinfo object.
             Replaces the timezone unless using an input form that is explicitly UTC or specifies
             the timezone in a positional argument. Defaults to UTC.
@@ -192,7 +193,7 @@ def get(self, *args: Any, **kwargs: Any) -> Arrow:
         """
 
         arg_count = len(args)
-        locale = kwargs.pop("locale", "en_us")
+        locale = kwargs.pop("locale", DEFAULT_LOCALE)
         tz = kwargs.get("tzinfo", None)
         normalize_whitespace = kwargs.pop("normalize_whitespace", False)
 

arrow/formatter.py

@@ -8,6 +8,7 @@
 from dateutil import tz as dateutil_tz
 
 from arrow import locales
+from arrow.constants import DEFAULT_LOCALE
 
 if sys.version_info < (3, 8):  # pragma: no cover
     from typing_extensions import Final
@@ -39,7 +40,7 @@ class DateTimeFormatter:
 
     locale: locales.Locale
 
-    def __init__(self, locale: str = "en_us") -> None:
+    def __init__(self, locale: str = DEFAULT_LOCALE) -> None:
 
         self.locale = locales.get_locale(locale)