Added docs for i18n and bumped version to 1.10.0

- Added docs for peng3d.i18n module
- Bumped version from 1.9.0a1 to 1.10.0
- Updated versioning schema to prevent PyPI from marking all releases as beta
- Updated tox version in use
- Added official support for Python 3.5 and 3.6, 3.6 is now the main version

Author: not-na

docs/api/peng3d.i18n.rst

@@ -0,0 +1,7 @@
+
+``peng3d.i18n`` - Lightweight Translation Manager
+=================================================
+
+.. automodule:: peng3d.i18n
+   :members:
+   :synopsis: Lightweight Translation Manager

docs/api/peng3d.rst

@@ -28,6 +28,7 @@ Note that for compatibility reasons, peng3d.window is not available by default a
    gui/text
    gui/slider
    peng3d.resource
+   peng3d.i18n
    peng3d.model
    peng3d.camera
    peng3d.world

docs/configoption.rst

@@ -241,6 +241,27 @@ Resource Options
 
    By default set to 1024.
 
+.. _cfg-i18n:
+
+Translation Options
+-------------------
+
+.. confval:: i18n.enable
+   
+   Enables or Disables the i18n module.
+   
+   By default enabled.
+
+.. confval:: i18n.lang
+   
+   Determines the default language selected upon startup.
+   
+   Note that setting this config option after creating the first window will have
+   no effect. Use :py:meth:`~peng3d.i18n.TranslationManager.setLang()` instead.
+   
+   Currently defaults to ``en``\ , but may be changed to operating system language
+   in the future.
+
 Event Options
 -------------
 

docs/events.rst

@@ -163,6 +163,25 @@ signal that either the manager itself was modified or a resource was changed.
 
    Additional parameters are ``name`` set to the name of the model.
 
+.. _events-i18n:
+
+``peng3d:i18n.*`` Events Category
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. seealso::
+   
+   See :py:class:`~peng3d.i18n.TranslationManager()` for more information about the translation system.
+
+.. peng3d:event:: peng3d.i18n.set_lang
+   
+   Sent whenever the default language is set.
+   
+   Note that this event is sent regardless of whether or not the language actually changed.
+   
+   Additional parameters are ``i18n``\ , set to the translation manager, and ``lang``
+   set to the new language.
+
+
 ``peng3d:keybind.*`` Events Category
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

peng3d/i18n.py

@@ -31,7 +31,32 @@
 
 from .util import ActionDispatcher
 
+# TODO: add test cases for translations
 class TranslationManager(ActionDispatcher):
+    """
+    Manages sets of translation files in multiple languages.
+    
+    This Translation System uses language codes to identify languages, there is
+    no requirement to follow a specific standard, but it is recommended to use
+    simple 2-digit codes like ``en`` and ``de``\ , adding an underscore to
+    define sub-languages like ``en_gb`` and ``en_us``\ .
+    
+    Whenever a new translation file is needed, it will be parsed and then cached.
+    This speeds up access times and also practically eliminates load times when
+    switching languages.
+    
+    Several events are sent by this class, see :ref:`events-i18n`\ .
+    
+    Most of these events are also sent as actions, these actions are described
+    in the methods that cause them.
+    
+    There are also severale config options that determine the behaviour of this class.
+    See :ref:`cfg-i18n` for more information.
+    
+    
+    This Manager requires the :py:class:`~peng3d.resource.ResourceManager()` to
+    be already initialized.
+    """
     def __init__(self,peng):
         if not peng.cfg["rsrc.enable"]:
             raise RuntimeError("ResourceManager needs to be enabled to use Translations")
@@ -48,6 +73,25 @@ def __init__(self,peng):
         self.setLang(self.peng.cfg["i18n.lang"])
 
     def setLang(self,lang):
+        """
+        Sets the default language for all domains.
+        
+        For recommendations regarding the format of the language code, see
+        :py:class:`TranslationManager`\ .
+        
+        Note that the ``lang`` parameter of both :py:meth:`translate()` and
+        :py:meth:`translate_lazy()` will override this setting.
+        
+        Also note that the code won't be checked for existence or plausibility.
+        This may cause the fallback strings to be displayed instead if the language
+        does not exist.
+        
+        Calling this method will cause the ``setlang`` action and the
+        :peng3d:event`peng3d:i18n.set_lang` event to be triggered. Note that both
+        action and event will be triggered even if the language did not actually change.
+        
+        This method also automatically updates the :confval:`i18n.lang` config value.
+        """
         self.lang = lang
         self.peng.cfg["i18n.lang"] = lang
 
@@ -58,6 +102,17 @@ def setLang(self,lang):
         self.peng.sendEvent("peng3d:i18n.set_lang",{"lang":self.lang,"i18n":self})
 
     def discoverLangs(self,domain="*"):
+        """
+        Generates a list of languages based on files found on disk.
+        
+        The optional ``domain`` argument may specify a domain to use when checking
+        for files. By default, all domains are checked.
+        
+        This internally uses the :py:mod:`glob` built-in module and the
+        :confval:`i18n.lang.format` config option to find suitable filenames.
+        It then applies the regex in :confval:`i18n.discover_regex` to extract the
+        language code.
+        """
         rsrc = self.peng.cfg["i18n.lang.format"].format(domain=domain,lang="*")
         pattern = self.peng.rsrcMgr.resourceNameToPath(rsrc,self.peng.cfg["i18n.lang.ext"])
         files = glob.iglob(pattern)

peng3d/util/__init__.py

@@ -63,6 +63,19 @@ def __setitem__(self,*args):
             c = self.callback()(self)
 
 def register_pyglet_handler(peng,func,event,raiseErrors=False):
+    """
+    Registers the given pyglet-style event handler for the given pyglet event.
+    
+    This function allows pyglet-style event handlers to receive events bridged
+    through the peng3d event system. Internally, this function creates a lambda
+    function that decodes the arguments and then calls the pyglet-style event handler.
+    
+    The ``raiseErrors`` flag is passed through to the peng3d event system and will
+    cause any errors raised by this handler to be ignored.
+    
+    .. seealso::
+       See :py:meth:`~peng3d.peng.Peng.addEventListener()` for more information.
+    """
     peng.addEventListener("pyglet:%s"%event,(lambda data:func(*data["args"])),raiseErrors)
 
 class ActionDispatcher(object):

peng3d/version.py

@@ -24,11 +24,10 @@
 
 __all__ = ["VERSION","RELEASE"]
 
-VERSION = "1.9.0a1"
+VERSION = "1.10.0"
 """
-Full version number of format ``MAJOR.MINOR.BUGFIX(a|b|pre)SUBRELEASE`` where major is increased only on very major feature changes.
+Full version number of format ``MAJOR.MINOR.BUGFIX`` where major is increased only on very major feature changes.
 Minor is changed if a new feature is introduced or an API change is made, while bugfix only changes if an important fix for a bug needs to be provided before the next release.
-Either a, b, or pre follows depending on the type of release, e.g. a for alpha, b for beta and pre for prereleases.
 
 Used to display the version in the title of the documentation.
 
@@ -38,9 +37,9 @@
 
 """
 
-RELEASE = "1.9.0"
+RELEASE = "1.10.0"
 """
-Same as :py:data:`VERSION` but without the subrelease.
+Currently the same as :py:data:`VERSION`\ .
 
 Used to display the version on the top-right of the documentation.
 """

requirements.txt

@@ -2,7 +2,7 @@ bidict==0.14.2
 future==0.15.2
 #pyglet==1.3.0a1
 https://bitbucket.org/pyglet/pyglet/get/f48574e6c61c.zip
-tox==2.3.1
+tox==3.7.0
 virtualenv==15.0.2
 pytest==3.2.3
 py>=1.4.33

setup.py

@@ -97,6 +97,8 @@ def load_module(name):
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.3",
         "Programming Language :: Python :: 3.4",
+        "Programming Language :: Python :: 3.5",
+        "Programming Language :: Python :: 3.6",
 
         "Topic :: Games/Entertainment",
         "Topic :: Multimedia :: Graphics :: 3D Rendering",

tests/test_version.py

@@ -28,7 +28,7 @@
 
 import peng3d
 
-VERSION_PATTERN = r"[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{0,2}[a-z][0-9]{1,2}"
+VERSION_PATTERN = r"[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{0,2}"
 
 RELEASE_PATTERN = r"[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{0,2}"