Merge pull request #234 from samueljsb/deprecate-private-functions

src/humanize/i18n.py

@@ -1,6 +1,7 @@
 """Activate, get and deactivate translations."""
 import gettext as gettext_module
 import os.path
+import warnings
 from threading import local
 
 __all__ = ["activate", "deactivate", "gettext", "ngettext", "thousands_separator"]
@@ -66,7 +67,7 @@ def deactivate():
     _CURRENT.locale = None
 
 
-def gettext(message):
+def _gettext(message):
     """Get translation.
 
     Args:
@@ -78,7 +79,27 @@ def gettext(message):
     return get_translation().gettext(message)
 
 
-def pgettext(msgctxt, message):
+def gettext(message):
+    """Get translation.
+
+    Args:
+        message (str): Text to translate.
+
+    Returns:
+        str: Translated text.
+
+    WARNING: This function has been deprecated. It is still available as the private
+    member `_gettext`.
+    """
+    warnings.warn(
+        "`gettext` has been deprecated. "
+        "It is still available as the private member `_gettext`.",
+        DeprecationWarning,
+    )
+    return _gettext(message)
+
+
+def _pgettext(msgctxt, message):
     """Fetches a particular translation.
 
     It works with `msgctxt` .po modifiers and allows duplicate keys with different
@@ -103,8 +124,32 @@ def pgettext(msgctxt, message):
         return message if translation == key else translation
 
 
-def ngettext(message, plural, num):
-    """Plural version of gettext.
+def pgettext(msgctxt, message):
+    """Fetches a particular translation.
+
+    It works with `msgctxt` .po modifiers and allows duplicate keys with different
+    translations.
+
+    Args:
+        msgctxt (str): Context of the translation.
+        message (str): Text to translate.
+
+    Returns:
+        str: Translated text.
+
+    WARNING: This function has been deprecated. It is still available as the private
+    member `_pgettext`.
+    """
+    warnings.warn(
+        "`pgettext` has been deprecated. "
+        "It is still available as the private member `_pgettext`.",
+        DeprecationWarning,
+    )
+    return _pgettext(msgctxt, message)
+
+
+def _ngettext(message, plural, num):
+    """Plural version of _gettext.
 
     Args:
         message (str): Singular text to translate.
@@ -118,14 +163,37 @@ def ngettext(message, plural, num):
     return get_translation().ngettext(message, plural, num)
 
 
-def gettext_noop(message):
+def ngettext(msgctxt, message):
+    """Plural version of gettext.
+
+    Args:
+        message (str): Singular text to translate.
+        plural (str): Plural text to translate.
+        num (str): The number (e.g. item count) to determine translation for the
+            respective grammatical number.
+
+    Returns:
+        str: Translated text.
+
+    WARNING: This function has been deprecated. It is still available as the private
+    member `_ngettext`.
+    """
+    warnings.warn(
+        "`ngettext` has been deprecated. "
+        "It is still available as the private member `_ngettext`.",
+        DeprecationWarning,
+    )
+    return _ngettext(msgctxt, message)
+
+
+def _gettext_noop(message):
     """Mark a string as a translation string without translating it.
 
     Example usage:
     ```python
-    CONSTANTS = [gettext_noop('first'), gettext_noop('second')]
+    CONSTANTS = [_gettext_noop('first'), _gettext_noop('second')]
     def num_name(n):
-        return gettext(CONSTANTS[n])
+        return _gettext(CONSTANTS[n])
     ```
 
     Args:
@@ -137,14 +205,41 @@ def num_name(n):
     return message
 
 
-def ngettext_noop(singular, plural):
+def gettext_noop(message):
+    """Mark a string as a translation string without translating it.
+
+    Example usage:
+    ```python
+    CONSTANTS = [_gettext_noop('first'), _gettext_noop('second')]
+    def num_name(n):
+        return _gettext(CONSTANTS[n])
+    ```
+
+    Args:
+        message (str): Text to translate in the future.
+
+    Returns:
+        str: Original text, unchanged.
+
+    WARNING: This function has been deprecated. It is still available as the private
+    member `_gettext_noop`.
+    """
+    warnings.warn(
+        "`gettext_noop` has been deprecated. "
+        "It is still available as the private member `_gettext_noop`.",
+        DeprecationWarning,
+    )
+    return _gettext_noop(message)
+
+
+def _ngettext_noop(singular, plural):
     """Mark two strings as pluralized translations without translating them.
 
     Example usage:
     ```python
     CONSTANTS = [ngettext_noop('first', 'firsts'), ngettext_noop('second', 'seconds')]
     def num_name(n):
-        return ngettext(*CONSTANTS[n])
+        return _ngettext(*CONSTANTS[n])
     ```
 
     Args:
@@ -157,6 +252,34 @@ def num_name(n):
     return (singular, plural)
 
 
+def ngettext_noop(singular, plural):
+    """Mark two strings as pluralized translations without translating them.
+
+    Example usage:
+    ```python
+    CONSTANTS = [ngettext_noop('first', 'firsts'), ngettext_noop('second', 'seconds')]
+    def num_name(n):
+        return _ngettext(*CONSTANTS[n])
+    ```
+
+    Args:
+        singular (str): Singular text to translate in the future.
+        plural (str): Plural text to translate in the future.
+
+    Returns:
+        tuple: Original text, unchanged.
+
+    WARNING: This function has been deprecated. It is still available as the private
+    member `_ngettext_noop`.
+    """
+    warnings.warn(
+        "`ngettext_noop` has been deprecated. "
+        "It is still available as the private member `_ngettext_noop`.",
+        DeprecationWarning,
+    )
+    return _ngettext_noop(singular, plural)
+
+
 def thousands_separator() -> str:
     """Return the thousands separator for a locale, default to comma.
 

src/humanize/number.py

@@ -6,10 +6,10 @@
 import re
 from fractions import Fraction
 
-from .i18n import gettext as _
-from .i18n import ngettext
-from .i18n import ngettext_noop as NS_
-from .i18n import pgettext as P_
+from .i18n import _gettext as _
+from .i18n import _ngettext
+from .i18n import _ngettext_noop as NS_
+from .i18n import _pgettext as P_
 from .i18n import thousands_separator
 
 
@@ -201,12 +201,12 @@ def intword(value, format="%.1f"):
                 chopped = value / float(powers[ordinal])
                 singular, plural = human_powers[ordinal]
                 return (
-                    " ".join([format, ngettext(singular, plural, math.ceil(chopped))])
+                    " ".join([format, _ngettext(singular, plural, math.ceil(chopped))])
                 ) % chopped
             else:
                 singular, plural = human_powers[ordinal - 1]
                 return (
-                    " ".join([format, ngettext(singular, plural, math.ceil(chopped))])
+                    " ".join([format, _ngettext(singular, plural, math.ceil(chopped))])
                 ) % chopped
     return str(value)