# HG changeset patch
# User cmlenz
# Date 1181329851 0
# Node ID e0bb7dce49ea58a8d840bc09452ebcafe0d59a4d
# Parent  27f01e7626ea8e6bd352a236f51f1b45f0f5519e
More explicit module-level function names in `babel.core`. Added `Locale.negotiate` class method.

diff --git a/babel/core.py b/babel/core.py
--- a/babel/core.py
+++ b/babel/core.py
@@ -11,13 +11,14 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://babel.edgewall.org/log/.
 
-"""Core locale representation and locale data access gateway."""
+"""Core locale representation and locale data access."""
 
 import os
 
 from babel import localedata
 
-__all__ = ['UnknownLocaleError', 'Locale', 'getdefault', 'negotiate', 'parse']
+__all__ = ['UnknownLocaleError', 'Locale', 'default_locale', 'negotiate_locale',
+           'parse_locale']
 __docformat__ = 'restructuredtext en'
 
 
@@ -105,9 +106,29 @@
                  (``LANGUAGE``, ``LC_ALL``, ``LC_CTYPE``, and ``LANG``)
         :rtype: `Locale`
         """
-        return cls(getdefault(category))
+        return cls(default_locale(category))
     default = classmethod(default)
 
+    def negotiate(cls, preferred, available, sep='_'):
+        """Find the best match between available and requested locale strings.
+    
+        >>> Locale.negotiate(['de_DE', 'en_US'], ['de_DE', 'de_AT'])
+        <Locale "de_DE">
+        >>> Locale.negotiate(['de_DE', 'en_US'], ['en', 'de'])
+        <Locale "de">
+        >>> Locale.negotiate(['de_DE', 'de'], ['en_US'])
+    
+        :param preferred: the list of locale identifers preferred by the user
+        :param available: the list of locale identifiers available
+        :return: the `Locale` object for the best match, or `None` if no match
+                 was found
+        :rtype: `Locale`
+        """
+        identifier = negotiate_locale(preferred, available, sep=sep)
+        if identifier:
+            return Locale.parse(identifier)
+    negotiate = classmethod(negotiate)
+
     def parse(cls, identifier, sep='_'):
         """Create a `Locale` instance for the given locale identifier.
         
@@ -132,9 +153,12 @@
         """
         if type(identifier) is cls:
             return identifier
-        return cls(*parse(identifier, sep=sep))
+        return cls(*parse_locale(identifier, sep=sep))
     parse = classmethod(parse)
 
+    def __eq__(self, other):
+        return str(self) == str(other)
+
     def __repr__(self):
         return '<Locale "%s">' % str(self)
 
@@ -473,14 +497,14 @@
         """)
 
 
-def getdefault(category=None):
+def default_locale(category=None):
     """Returns the system default locale for a given category, based on
     environment variables.
     
     >>> for name in ['LANGUAGE', 'LC_ALL', 'LC_CTYPE']:
     ...     os.environ[name] = ''
     >>> os.environ['LANG'] = 'fr_FR.UTF-8'
-    >>> getdefault('LC_MESSAGES')
+    >>> default_locale('LC_MESSAGES')
     'fr_FR'
     
     :param category: one of the ``LC_XXX`` environment variable names
@@ -493,18 +517,20 @@
     for name in filter(None, varnames):
         locale = os.getenv(name)
         if locale:
-            return '_'.join(filter(None, parse(locale)))
+            return '_'.join(filter(None, parse_locale(locale)))
 
-def negotiate(preferred, available):
+def negotiate_locale(preferred, available, sep='_'):
     """Find the best match between available and requested locale strings.
     
-    >>> negotiate(['de_DE', 'en_US'], ['de_DE', 'de_AT'])
+    >>> negotiate_locale(['de_DE', 'en_US'], ['de_DE', 'de_AT'])
     'de_DE'
-    >>> negotiate(['de_DE', 'en_US'], ['en', 'de'])
+    >>> negotiate_locale(['de_DE', 'en_US'], ['en', 'de'])
     'de'
     
     :param preferred: the list of locale strings preferred by the user
     :param available: the list of locale strings available
+    :param sep: character that separates the different parts of the locale
+                strings
     :return: the locale identifier for the best match, or `None` if no match
              was found
     :rtype: `str`
@@ -512,22 +538,22 @@
     for locale in preferred:
         if locale in available:
             return locale
-        parts = locale.split('_')
+        parts = locale.split(sep)
         if len(parts) > 1 and parts[0] in available:
             return parts[0]
     return None
 
-def parse(identifier, sep='_'):
+def parse_locale(identifier, sep='_'):
     """Parse a locale identifier into a ``(language, territory, variant)``
     tuple.
     
-    >>> parse('zh_CN')
+    >>> parse_locale('zh_CN')
     ('zh', 'CN', None)
     
     The default component separator is "_", but a different separator can be
     specified using the `sep` parameter:
     
-    >>> parse('zh-CN', sep='-')
+    >>> parse_locale('zh-CN', sep='-')
     ('zh', 'CN', None)
     
     :param identifier: the locale identifier string
diff --git a/babel/dates.py b/babel/dates.py
--- a/babel/dates.py
+++ b/babel/dates.py
@@ -24,14 +24,14 @@
 from datetime import date, datetime, time, timedelta, tzinfo
 import re
 
-from babel.core import getdefault, Locale
+from babel.core import default_locale, Locale
 from babel.util import UTC
 
 __all__ = ['format_date', 'format_datetime', 'format_time', 'parse_date',
            'parse_datetime', 'parse_time']
 __docformat__ = 'restructuredtext en'
 
-LC_TIME = getdefault('LC_TIME')
+LC_TIME = default_locale('LC_TIME')
 
 # Aliases for use in scopes where the modules are shadowed by local variables
 date_ = date
diff --git a/babel/numbers.py b/babel/numbers.py
--- a/babel/numbers.py
+++ b/babel/numbers.py
@@ -24,14 +24,14 @@
 
 import re
 
-from babel.core import getdefault, Locale
+from babel.core import default_locale, Locale
 
 __all__ = ['format_number', 'format_decimal', 'format_currency',
            'format_percent', 'format_scientific', 'parse_number',
            'parse_decimal', 'NumberFormatError']
 __docformat__ = 'restructuredtext en'
 
-LC_NUMERIC = getdefault('LC_NUMERIC')
+LC_NUMERIC = default_locale('LC_NUMERIC')
 
 def get_decimal_symbol(locale=LC_NUMERIC):
     """Return the symbol used by the locale to separate decimal fractions.