tests/test_docstring.py

   1 from __future__ import absolute_import
   2
   3 import unittest
   4
   5 import gi.docstring
   6
   7 from gi.repository import Regress
   8 from gi.repository import GIMarshallingTests
   9 from gi.repository import Gio
  10 from gi.repository import GObject
  11 from gi.repository import GLib
  12
  13 try:
  14     from gi.repository import Gtk
  15 except ImportError:
  16     Gtk = None
  17
  18
  19 class Test(unittest.TestCase):
  20     def test_api(self):
  21         new_func = lambda info: 'docstring test'
  22         old_func = gi.docstring.get_doc_string_generator()
  23
  24         gi.docstring.set_doc_string_generator(new_func)
  25         self.assertEqual(gi.docstring.get_doc_string_generator(),
  26                          new_func)
  27         self.assertEqual(gi.docstring.generate_doc_string(None),
  28                          'docstring test')
  29
  30         # Set back to original generator
  31         gi.docstring.set_doc_string_generator(old_func)
  32         self.assertEqual(gi.docstring.get_doc_string_generator(),
  33                          old_func)
  34
  35     def test_final_signature_with_full_inout(self):
  36         self.assertEqual(GIMarshallingTests.Object.full_inout.__doc__,
  37                          'full_inout(object:GIMarshallingTests.Object) -> object:GIMarshallingTests.Object')
  38
  39     def test_overridden_doc_is_not_clobbered(self):
  40         self.assertEqual(GIMarshallingTests.OverridesObject.method.__doc__,
  41                          'Overridden doc string.')
  42
  43     def test_allow_none_with_user_data_defaults(self):
  44         g_file_copy_doc = 'copy(self, destination:Gio.File, ' \
  45                           'flags:Gio.FileCopyFlags, ' \
  46                           'cancellable:Gio.Cancellable=None, ' \
  47                           'progress_callback:Gio.FileProgressCallback=None, ' \
  48                           'progress_callback_data=None) -> bool'
  49
  50         self.assertEqual(Gio.File.copy.__doc__, g_file_copy_doc)
  51
  52     def test_array_length_arg(self):
  53         self.assertEqual(GIMarshallingTests.array_in.__doc__,
  54                          'array_in(ints:list)')
  55
  56     def test_init_function(self):
  57         # This tests implicit array length args along with skipping a
  58         # boolean return
  59         self.assertEqual(GIMarshallingTests.init_function.__doc__,
  60                          'init_function(argv:list=None) -> bool, argv:list')
  61
  62     def test_boolean_return(self):
  63         self.assertEqual(GIMarshallingTests.boolean_return_true.__doc__,
  64                          'boolean_return_true() -> bool')
  65
  66     @unittest.skipUnless((GLib.MAJOR_VERSION, GLib.MINOR_VERSION) >= (2, 42),
  67                          "nullable was added in newer glib/gi")
  68     # https://bugzilla.gnome.org/show_bug.cgi?id=740301
  69     def test_may_return_none(self):
  70         self.assertEqual(Gio.File.get_basename.__doc__,
  71                          'get_basename(self) -> str or None')
  72
  73     def test_class_doc_constructors(self):
  74         doc = GIMarshallingTests.Object.__doc__
  75         self.assertTrue('new(int_:int)' in doc)
  76
  77     def test_struct_doc_constructors(self):
  78         doc = GIMarshallingTests.BoxedStruct.__doc__
  79         self.assertTrue('new()' in doc)
  80         self.assertTrue('BoxedStruct()' in doc)
  81
  82     def test_private_struct_constructors(self):
  83         # Structs without a size or constructor should have no constructor docs.
  84         doc = Regress.TestBoxedPrivate.__doc__
  85         self.assertEqual(doc, '')
  86
  87     def test_array_inout_etc(self):
  88         self.assertEqual(GIMarshallingTests.array_inout_etc.__doc__,
  89                          'array_inout_etc(first:int, ints:list, last:int) -> ints:list, sum:int')
  90
  91     def test_array_out_etc(self):
  92         self.assertEqual(GIMarshallingTests.array_out_etc.__doc__,
  93                          'array_out_etc(first:int, last:int) -> ints:list, sum:int')
  94
  95     @unittest.skipUnless(Gtk, 'no Gtk')
  96     def test_shared_array_length_with_prior_out_arg(self):
  97         # Test the 'iter' out argument does not effect length argument skipping.
  98         self.assertEqual(Gtk.ListStore.insert_with_valuesv.__doc__,
  99                          'insert_with_valuesv(self, position:int, columns:list, values:list) -> iter:Gtk.TreeIter')
 100
 101     def test_sub_class_doc(self):
 102         class A(GObject.Object):
 103             """first doc"""
 104             pass
 105
 106         class B(A):
 107             """second doc"""
 108             pass
 109
 110         self.assertEqual(A.__doc__, "first doc")
 111         self.assertEqual(B.__doc__, "second doc")
 112
 113     def test_sub_class_no_doc(self):
 114         class A(GObject.Object):
 115             pass
 116
 117         class B(A):
 118             """sub-class doc"""
 119
 120         self.assertEqual(A.__doc__, None)
 121         self.assertEqual(B.__doc__, "sub-class doc")
 122
 123     @unittest.expectedFailure  # https://bugzilla.gnome.org/show_bug.cgi?id=734926
 124     def test_sub_class_doc_setattr(self):
 125         class A(GObject.Object):
 126             pass
 127
 128         class B(A):
 129             pass
 130
 131         A.__doc__ = 'custom doc'
 132
 133         self.assertEqual(A.__doc__, "custom doc")
 134         self.assertEqual(B.__doc__, "custom doc")