_locale (Jython API documentation)
Date: 2024-08-18

org.python.modules._locale

## Class _locale

- java.lang.Object
- - org.python.modules._locale._locale

- All Implemented Interfaces:
    ClassDictInit

      public class _locale
      extends java.lang.Object
      implements ClassDictInit

  Java native implementation of underlying locale functions, fitting the interface defined or implied by the Python locale module. Functional documentation can be found in the Python module docstring. This class depends on registry key `RegistryKey.PYTHON_LOCALE_CONTROL`. Additional implementation details for users of this class are captured below.

  Unicode. In general, Java and its locale settings are quite unicode heavy, making rich use of different symbols for e.g. currencies. This solution allows some of that to leak through by encoding the Java locale value with the current character encoding. The Python locale module is quite conservative and tends to keep things as solely strings. Python 2.x usually supports only string / ascii by default in many cases, and only unicode when asked. This is a little less conservative while only allowing values consistent with the current encoding.

  An example of this is some Python implementations using EUR rather than the Euro symbol € (`'u20ac'`), probably because € is only available in Unicode. In the Java implementation, if UTF-8 encoding is set, the resulting entry in `localeconv()['currency_code']` is `'\xe2\x82\xac'`. This can be used by `print()` and related functions directly. Encoding failures for `currency_symbol` fall back to `int_curr_symbol` (eg EUR). Encoding failures for `negative_sign`, which are sometimes unicode, fall back to an ANSI hyphen ('-'). Other encoding failures fallback to the 'C' locale values, where possible.

  The C emulation locale uses only ANSI characters in non-unicode strings, in keeping with it being the locale of last resort and maximum compatibility.

  Positive sign position (`p_sign_posn`) is not a distinguished concept in Java and so this is hardcoded to 3.

  This class ensures read/write consistency, when changing locales via `setlocale(PyInteger,PyString)`, by declaring private variable `currentLocale` as volatile, and only assigning it immutable objects. It does not lock to guarantee sequencing of `setLocale()` calls from separate threads. In the rare cases where that would be needed, it is the responsibility of the calling code.

  Since:
    Jython 2.7.2

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PyString` | `__doc__`
    `static PyString` | `__doc___localeconv`
    `static PyString` | `__doc___setlocale`
    `static PyString` | `__doc___strcoll`
    `static PyString` | `__doc___strxfrm`
    `static PyString` | `C_LOCALE_PY_STRING`
    `static int` | `CHAR_MAX`
    `static PyInteger` | `CHAR_MAX_PY_INT`
    `static PyObject` | `Error` The `locale` module exposes `_locale.Error` as `locale.Error`.
    `static PyInteger` | `LC_ALL`
    `static PyInteger` | `LC_COLLATE`
    `static PyInteger` | `LC_CTYPE`
    `static PyInteger` | `LC_MESSAGES`
    `static PyInteger` | `LC_MONETARY`
    `static PyInteger` | `LC_NUMERIC`
    `static PyInteger` | `LC_TIME`
    `static java.lang.String` | `LOCALE_CONTROL_JYTHON2_LEGACY`
    `static java.lang.String` | `LOCALE_CONTROL_SETTABLE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `_locale()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `classDictInit(PyObject dict)`
    `static DateSymbolLocale` | `getDateSymbolLocale()` Current `DateSymbolLocale` used by the Python interpreter.
    `static void` | `initClassExceptions(PyObject exceptions)`
    `static PyDictionary` | `localeconv()`
    `static PyException` | `LocaleException(java.lang.String message)`
    `static PyString` | `setlocale(PyInteger category)`
    `static PyString` | `setlocale(PyInteger category, PyString locale)` Java Locale loading behaviour is quite forgiving, or uninformative, depending on your perspective.
    `static int` | `strcoll(PyString str1, PyString str2)`
    `static PyString` | `strxfrm(PyString str1)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### Error

          public static PyObject Error

      The `locale` module exposes `_locale.Error` as `locale.Error`. Some Python functions, including `strptime()`, depend on `locale.Error`, making it part of the public API for native locale implementations.

    - #### __doc__

          public static final PyString __doc__

    - #### LOCALE_CONTROL_SETTABLE

          public static final java.lang.String LOCALE_CONTROL_SETTABLE

      See Also:
        Constant Field Values

    - #### LOCALE_CONTROL_JYTHON2_LEGACY

          public static final java.lang.String LOCALE_CONTROL_JYTHON2_LEGACY

      See Also:
        Constant Field Values

    - #### LC_CTYPE

          public static final PyInteger LC_CTYPE

    - #### LC_NUMERIC

          public static final PyInteger LC_NUMERIC

    - #### LC_TIME

          public static final PyInteger LC_TIME

    - #### LC_COLLATE

          public static final PyInteger LC_COLLATE

    - #### LC_MONETARY

          public static final PyInteger LC_MONETARY

    - #### LC_MESSAGES

          public static final PyInteger LC_MESSAGES

    - #### LC_ALL

          public static final PyInteger LC_ALL

    - #### CHAR_MAX

          public static final int CHAR_MAX

      See Also:
        Constant Field Values

    - #### CHAR_MAX_PY_INT

          public static final PyInteger CHAR_MAX_PY_INT

    - #### C_LOCALE_PY_STRING

          public static final PyString C_LOCALE_PY_STRING

    - #### __doc___localeconv

          public static PyString __doc___localeconv

    - #### __doc___strcoll

          public static PyString __doc___strcoll

    - #### __doc___strxfrm

          public static PyString __doc___strxfrm

    - #### __doc___setlocale

          public static PyString __doc___setlocale

  - ### Constructor Detail

    - #### _locale

          public _locale()

  - ### Method Detail

    - #### LocaleException

          public static PyException LocaleException(java.lang.String message)

    - #### initClassExceptions

          public static void initClassExceptions(PyObject exceptions)

    - #### classDictInit

          public static void classDictInit(PyObject dict)

    - #### localeconv

          public static PyDictionary localeconv()

    - #### strcoll

          public static int strcoll(PyString str1,
                                    PyString str2)

    - #### strxfrm

          public static PyString strxfrm(PyString str1)

    - #### setlocale

          public static PyString setlocale(PyInteger category)

    - #### setlocale

          public static PyString setlocale(PyInteger category,
                                           PyString locale)

      Java Locale loading behaviour is quite forgiving, or uninformative, depending on your perspective. It will return a dummy locale for any language tag that fits the syntax, or make various attempts to approximate a locale. This solution instead follows the stricter Python behaviour of requiring a particular locale to be installed.

    - #### getDateSymbolLocale

          public static DateSymbolLocale getDateSymbolLocale()

      Current `DateSymbolLocale` used by the Python interpreter. This object will no longer reflect the current state after subsequent calls to `setlocale`.

Jython homepage