isinstance.rst 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  1. .. _isinstance-calls:
  2. isinstance
  3. ----------
  4. The following tests all pass on Python 3::
  5. >>> assert isinstance(2**62, int)
  6. >>> assert isinstance(2**63, int)
  7. >>> assert isinstance(b'my byte-string', bytes)
  8. >>> assert isinstance(u'unicode string 1', str)
  9. >>> assert isinstance('unicode string 2', str)
  10. However, two of these normally fail on Python 2::
  11. >>> assert isinstance(2**63, int)
  12. Traceback (most recent call last):
  13. File "<stdin>", line 1, in <module>
  14. AssertionError
  15. >>> assert isinstance(u'my unicode string', str)
  16. Traceback (most recent call last):
  17. File "<stdin>", line 1, in <module>
  18. AssertionError
  19. And if this import is in effect on Python 2::
  20. >>> from __future__ import unicode_literals
  21. then the fifth test fails too::
  22. >>> assert isinstance('unicode string 2', str)
  23. Traceback (most recent call last):
  24. File "<stdin>", line 1, in <module>
  25. AssertionError
  26. After importing the builtins from ``future``, all these tests pass on
  27. Python 2 as on Python 3::
  28. >>> from builtins import bytes, int, str
  29. >>> assert isinstance(10, int)
  30. >>> assert isinstance(10**100, int)
  31. >>> assert isinstance(b'my byte-string', bytes)
  32. >>> assert isinstance(u'unicode string 1', str)
  33. However, note that the last test requires that ``unicode_literals`` be imported to succeed.::
  34. >>> from __future__ import unicode_literals
  35. >>> assert isinstance('unicode string 2', str)
  36. This works because the backported types ``int``, ``bytes`` and ``str``
  37. (and others) have metaclasses that override ``__instancecheck__``. See `PEP 3119
  38. <http://www.python.org/dev/peps/pep-3119/#overloading-isinstance-and-issubclass>`_
  39. for details.
  40. Passing data to/from Python 2 libraries
  41. ---------------------------------------
  42. If you are passing any of the backported types (``bytes``, ``int``, ``dict,
  43. ``str``) into brittle library code that performs type-checks using ``type()``,
  44. rather than ``isinstance()``, or requires that you pass Python 2's native types
  45. (rather than subclasses) for some other reason, it may be necessary to upcast
  46. the types from ``future`` to their native superclasses on Py2.
  47. The ``native`` function in ``future.utils`` is provided for this. Here is how
  48. to use it. (The output showing is from Py2)::
  49. >>> from builtins import int, bytes, str
  50. >>> from future.utils import native
  51. >>> a = int(10**20) # Py3-like long int
  52. >>> a
  53. 100000000000000000000
  54. >>> type(a)
  55. future.types.newint.newint
  56. >>> native(a)
  57. 100000000000000000000L
  58. >>> type(native(a))
  59. long
  60. >>> b = bytes(b'ABC')
  61. >>> type(b)
  62. future.types.newbytes.newbytes
  63. >>> native(b)
  64. 'ABC'
  65. >>> type(native(b))
  66. str
  67. >>> s = str(u'ABC')
  68. >>> type(s)
  69. future.types.newstr.newstr
  70. >>> native(s)
  71. u'ABC'
  72. >>> type(native(s))
  73. unicode
  74. On Py3, the :func:`native` function is a no-op.
  75. Native string type
  76. ------------------
  77. Some library code, include standard library code like the ``array.array()``
  78. constructor, require native strings on Python 2 and Python 3. This means that
  79. there is no simple way to pass the appropriate string type when the
  80. ``unicode_literals`` import from ``__future__`` is in effect.
  81. The objects ``native_str`` and ``native_bytes`` are available in
  82. ``future.utils`` for this case. These are equivalent to the ``str`` and
  83. ``bytes`` objects in ``__builtin__`` on Python 2 or in ``builtins`` on Python 3.
  84. The functions ``native_str_to_bytes`` and ``bytes_to_native_str`` are also
  85. available for more explicit conversions.