Property tries to provide the best docstring it finds for its instances. If a user-provided docstring is available, it is preserved on copies. If no docstring is available during property creation, the property will utilize the docstring from the getter if available.
(self)
| 406 | @unittest.skipIf(sys.flags.optimize >= 2, |
| 407 | "Docstrings are omitted with -O2 and above") |
| 408 | def test_docstring_copy2(self): |
| 409 | """ |
| 410 | Property tries to provide the best docstring it finds for its instances. |
| 411 | If a user-provided docstring is available, it is preserved on copies. |
| 412 | If no docstring is available during property creation, the property |
| 413 | will utilize the docstring from the getter if available. |
| 414 | """ |
| 415 | def getter1(self): |
| 416 | return 1 |
| 417 | def getter2(self): |
| 418 | """doc 2""" |
| 419 | return 2 |
| 420 | def getter3(self): |
| 421 | """doc 3""" |
| 422 | return 3 |
| 423 | |
| 424 | # Case-1: user-provided doc is preserved in copies |
| 425 | # of property with undocumented getter |
| 426 | p = property(getter1, None, None, "doc-A") |
| 427 | |
| 428 | p2 = p.getter(getter2) |
| 429 | self.assertEqual(p.__doc__, "doc-A") |
| 430 | self.assertEqual(p2.__doc__, "doc-A") |
| 431 | |
| 432 | # Case-2: user-provided doc is preserved in copies |
| 433 | # of property with documented getter |
| 434 | p = property(getter2, None, None, "doc-A") |
| 435 | |
| 436 | p2 = p.getter(getter3) |
| 437 | self.assertEqual(p.__doc__, "doc-A") |
| 438 | self.assertEqual(p2.__doc__, "doc-A") |
| 439 | |
| 440 | # Case-3: with no user-provided doc new getter doc |
| 441 | # takes precedence |
| 442 | p = property(getter2, None, None, None) |
| 443 | |
| 444 | p2 = p.getter(getter3) |
| 445 | self.assertEqual(p.__doc__, "doc 2") |
| 446 | self.assertEqual(p2.__doc__, "doc 3") |
| 447 | |
| 448 | # Case-4: A user-provided doc is assigned after property construction |
| 449 | # with documented getter. The doc IS NOT preserved. |
| 450 | # It's an odd behaviour, but it's a strange enough |
| 451 | # use case with no easy solution. |
| 452 | p = property(getter2, None, None, None) |
| 453 | p.__doc__ = "user" |
| 454 | p2 = p.getter(getter3) |
| 455 | self.assertEqual(p.__doc__, "user") |
| 456 | self.assertEqual(p2.__doc__, "doc 3") |
| 457 | |
| 458 | # Case-5: A user-provided doc is assigned after property construction |
| 459 | # with UNdocumented getter. The doc IS preserved. |
| 460 | p = property(getter1, None, None, None) |
| 461 | p.__doc__ = "user" |
| 462 | p2 = p.getter(getter2) |
| 463 | self.assertEqual(p.__doc__, "user") |
| 464 | self.assertEqual(p2.__doc__, "user") |
| 465 |
nothing calls this directly
no test coverage detected