From 3ada92fbf1c7c3bb84e6d8d9a3ee254d6385f12f Mon Sep 17 00:00:00 2001
From: Christophe de Vienne <cdevienne@gmail.com>
Date: Fri, 24 Aug 2012 10:37:08 +0200
Subject: [PATCH] Documents the File type

---
 doc/changes.rst   |  2 +-
 doc/types.rst     | 15 ++++++++++-----
 wsme/sphinxext.py | 13 +++++++++++--
 wsme/types.py     | 16 +++++++++++++++-
 4 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/doc/changes.rst b/doc/changes.rst
index 68483d1..f7c1f15 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -8,7 +8,7 @@ Changes
 
 *   String types handling is clearer.
 
-*   New FileType type.
+*   New File type.
 
 *   Supports cross-referenced types.
 
diff --git a/doc/types.rst b/doc/types.rst
index 5c8ecec..51ef157 100644
--- a/doc/types.rst
+++ b/doc/types.rst
@@ -50,11 +50,6 @@ The native types are :
     
             A time (:py:class:`datetime.time`)
 
-    -   .. wsme:type:: Filetype
-
-            A file (:py:class:`wsme.types.Filetype`). Currently FileType is
-            supported only as input type on protocols that accept form inputs.
-
     -   Arrays -- This is a special case. When stating a list
         datatype, always state its content type as the unique element
         of a list. Example::
@@ -239,3 +234,13 @@ A few things you should know about complex types:
 
             class B(object):
                 a = wsattr(A)
+
+
+Predefined Types
+~~~~~~~~~~~~~~~~
+
+.. default-domain:: wsme
+
+-   .. autotype:: wsme.types.File
+        :members:
+
diff --git a/wsme/sphinxext.py b/wsme/sphinxext.py
index 50c29eb..aec4d78 100644
--- a/wsme/sphinxext.py
+++ b/wsme/sphinxext.py
@@ -22,6 +22,12 @@ import wsme.types
 field_re = re.compile(r':(?P<field>\w+)(\s+(?P<name>\w+))?:')
 
 
+def datatypename(datatype):
+    if isinstance(datatype, wsme.types.UserType):
+        return datatype.name
+    return datatype.__name__
+
+
 def make_sample_object(datatype):
     if datatype is wsme.types.bytes:
         return 'samplestring'
@@ -210,7 +216,10 @@ class AttributeDocumenter(autodoc.AttributeDocumenter):
         return success
 
     def add_content(self, more_content, no_docstring=False):
-        self.add_line(u':type: %s' % self.datatype.__name__, '<wsme.sphinxext>')
+        self.add_line(
+            u':type: %s' % datatypename(self.datatype),
+            '<wsme.sphinxext>'
+        )
         self.add_line(u'', '<wsme.sphinxext>')
         super(AttributeDocumenter, self).add_content(
             more_content, no_docstring)
@@ -341,7 +350,7 @@ class FunctionDocumenter(autodoc.MethodDocumenter):
         for arg in self.wsme_fd.arguments:
             content = [
                 u':type  %s: :wsme:type:`%s`' % (
-                    arg.name, arg.datatype.__name__)
+                    arg.name, datatypename(arg.datatype))
             ]
             if arg.name not in found_params:
                 content.insert(0, u':param %s: ' % (arg.name))
diff --git a/wsme/types.py b/wsme/types.py
index a131040..63c821e 100644
--- a/wsme/types.py
+++ b/wsme/types.py
@@ -79,6 +79,7 @@ class DictType(object):
 
 class UserType(object):
     basetype = None
+    name = None
 
     def validate(self, value):
         return
@@ -99,11 +100,16 @@ class BinaryType(UserType):
     A user type that use base64 strings to carry binary data.
     """
     basetype = bytes
+    name = 'binary'
 
     def tobasetype(self, value):
+        if value is None:
+            return None
         return base64.encodestring(value)
 
     def frombasetype(self, value):
+        if value is None:
+            return None
         return base64.decodestring(value)
 
 #: The binary almost-native type
@@ -125,9 +131,13 @@ class Enum(UserType):
         Specie = Enum(str, 'cat', 'dog')
 
     """
-    def __init__(self, basetype, *values):
+    def __init__(self, basetype, *values, **kw):
         self.basetype = basetype
         self.values = set(values)
+        name = kw.pop('name')
+        if name is None:
+            name = "Enum(%s)" % ', '.join((str(v) for v in values))
+        self.name = name
 
     def validate(self, value):
         if value not in self.values:
@@ -506,7 +516,10 @@ class File(Base):
     In the particular case of protocol accepting form encoded data as
     input, File can be loaded from a form file field.
     """
+    #: The file name
     filename = wsattr(text)
+
+    #: Mime type of the content
     contenttype = wsattr(text)
 
     def _get_content(self):
@@ -518,6 +531,7 @@ class File(Base):
         self._content = value
         self._file = None
 
+    #: File content
     content = wsproperty(binary, _get_content, _set_content)
 
     def __init__(self, filename=None, file=None, content=None,