tests/test_docstring.py

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