Repository: kivy/kivy

Issue:
unicode is reserved by language, shouldn't be used as identifier
see http://kivy.org./docs/api-kivy.core.window.html?highlight=etype#kivy.core.window.WindowBase.on_key_down for example

setting this to 2.0 since it's api change :)



Discussion:
By default, unicode is set to None, so I'm having a hard time (especially with lacking documentation) understanding what that argument is supposed to do. Identifying what it is supposed to do might help to come up with a new name, assuming that is the only hold up in fixing this.

A good way to implement this in 1.x might be to raise a DeprecationWarning[1]. This would allow unicode to work in old code, and continue to work, though being discouraged, and finally removed from 2.0:

```
import warnings
def on_key_down(self, key, scancode=None, unicode_repacement=None, modifier=None, **args):
    if args.get('unicode'):
        unicode_replacement = unicode_replacement or unicode
        warning.warn("unicode is a __builtin__, and as such is being deprecated. "
            "Please consider using unicode_replacement instead", DeprecationWarning)
```

By default, this is unintrusive, as it doesn't show the warning. Those that want to make sure they are only using the recommended API can pass -Wd to the interpreter, or add it as a shebang line in their files:

```
#!/usr/bin/env python -Wd
```

[1] http://docs.python.org/library/exceptions.html#exceptions.DeprecationWarning

As said on irc, i think here unicode should contain the codepoint of the character sent by keyboard, but that require checking, don't take my word for it :), if so, then maybe `codepoint` would be a good parameter.

I also agree about the deprecation warning, that allows to make things correctly sooner, and provide a smooth transition. :)

Per [Pygame Documentation](http://www.pygame.org/docs/ref/key.html), unicode is a single character unicode string representing the key pressed, taking into account shift and composition characters. Given that its a single character, `codepoint` would be spot on, I think. I'll write and test a patch for this.


Resolving patch:
diff --git a/kivy/core/window/__init__.py b/kivy/core/window/__init__.py
--- a/kivy/core/window/__init__.py
+++ b/kivy/core/window/__init__.py
@@ -10,7 +10,6 @@
 
 from os.path import join, exists
 from os import getcwd
-from warnings import warn
 
 from kivy.core import core_select_lib
 from kivy.clock import Clock
@@ -761,26 +760,26 @@ def on_keyboard(self, key,
             Some providers may omit `scancode`, `codepoint` and/or `modifier`!
         '''
         if 'unicode' in kwargs:
-            warn("The use of the unicode parameter is deprecated, and will be "
-                 "removed in future versions. Use codepoint instead, which "
-                 "has identical semantics.")
+            Logger.warning("The use of the unicode parameter is deprecated, "
+                "and will be removed in future versions. Use codepoint "
+                "instead, which has identical semantics.")
 
 
     def on_key_down(self, key,
         scancode=None, codepoint=None, modifier=None, **kwargs):
         '''Event called when a key is down (same arguments as on_keyboard)'''
         if 'unicode' in kwargs:
-            warn("The use of the unicode parameter is deprecated, and will be "
-                 "removed in future versions. Use codepoint instead, which "
-                 "has identical semantics.")
+            Logger.warning("The use of the unicode parameter is deprecated, "
+                "and will be removed in future versions. Use codepoint "
+                "instead, which has identical semantics.")
 
     def on_key_up(self, key,
         scancode=None, codepoint=None, modifier=None, **kwargs):
         '''Event called when a key is up (same arguments as on_keyboard)'''
         if 'unicode' in kwargs:
-            warn("The use of the unicode parameter is deprecated, and will be "
-                 "removed in future versions. Use codepoint instead, which "
-                 "has identical semantics.")
+            Logger.warning("The use of the unicode parameter is deprecated, "
+                "and will be removed in future versions. Use codepoint "
+                "instead, which has identical semantics.")
 
     def on_dropfile(self, filename):
         '''Event called when a file is dropped on the application.
diff --git a/kivy/core/window/window_pygame.py b/kivy/core/window/window_pygame.py
--- a/kivy/core/window/window_pygame.py
+++ b/kivy/core/window/window_pygame.py
@@ -194,7 +194,7 @@ def on_keyboard(self, key,
             self.close()  #not sure what to do here
             return True
         super(WindowPygame, self).on_keyboard(key, scancode,
-            unicode=codepoint, modifier=modifier)
+            codepoint=codepoint, modifier=modifier)
 
     def flip(self):
         pygame.display.flip()


Test patch: