Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(1)

Delta Between Two Patch Sets: Doc/library/stdtypes.rst

Issue 15573: Support unknown formats in memoryview comparisons
Left Patch Set: Created 7 years, 7 months ago
Right Patch Set: Created 7 years, 7 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Doc/whatsnew/3.3.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
(no file at all)
1 .. XXX: reference/datamodel and this have quite a few overlaps! 1 .. XXX: reference/datamodel and this have quite a few overlaps!
2 2
3 3
4 .. _bltin-types: 4 .. _bltin-types:
5 5
6 ************** 6 **************
7 Built-in Types 7 Built-in Types
8 ************** 8 **************
9 9
10 The following sections describe the standard types that are built into the 10 The following sections describe the standard types that are built into the
(...skipping 2482 matching lines...) Expand 10 before | Expand all | Expand 10 after
2493 [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] 2493 [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
2494 >>> hash(x) == hash(y) == hash(y.tobytes()) 2494 >>> hash(x) == hash(y) == hash(y.tobytes())
2495 True 2495 True
2496 2496
2497 .. versionchanged:: 3.3 2497 .. versionchanged:: 3.3
2498 Memoryview objects are now hashable. 2498 Memoryview objects are now hashable.
2499 2499
2500 2500
2501 :class:`memoryview` has several methods: 2501 :class:`memoryview` has several methods:
2502 2502
2503 .. method:: __eq__(exporter)
2504
2505 A memoryview and a :pep:`3118` exporter are equal if their shapes are
2506 equivalent and if all corresponding values are equal when the operands'
2507 respective format codes are interpreted using :mod:`struct` syntax.
2508
2509 For the subset of :mod:`struct` format strings currently supported by
2510 :meth:`tolist`, ``v`` and ``w`` are equal if ``v.tolist() == w.tolist()``: :
2511
2512 >>> import array
2513 >>> a = array.array('I', [1, 2, 3, 4, 5])
2514 >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
2515 >>> c = array.array('b', [5, 3, 1])
2516 >>> x = memoryview(a)
2517 >>> y = memoryview(b)
2518 >>> x == a == y == b
2519 True
2520 >>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
2521 True
2522 >>> z = y[::-2]
2523 >>> z == c
2524 True
2525 >>> z.tolist() == c.tolist()
2526 True
2527
2528 If either format string is not supported by the :mod:`struct` module,
2529 then the objects will always compare as unequal (even if the format
2530 strings and buffer contents are identical)::
2531
2532 >>> from ctypes import BigEndianStructure, c_long
2533 >>> class BEPoint(BigEndianStructure):
2534 ... _fields_ = [("x", c_long), ("y", c_long)]
2535 ...
2536 >>> point = BEPoint(100, 200)
2537 >>> a = memoryview(point)
2538 >>> b = memoryview(point)
2539 >>> a == point
2540 False
2541 >>> a == b
2542 False
2543
2544 Note that, as with floating point numbers, ``v is w`` does *not* imply
2545 ``v == w`` for memoryview objects.
2546
2547 .. versionchanged:: 3.3
2548
2503 .. method:: tobytes() 2549 .. method:: tobytes()
2504 2550
2505 Return the data in the buffer as a bytestring. This is equivalent to 2551 Return the data in the buffer as a bytestring. This is equivalent to
2506 calling the :class:`bytes` constructor on the memoryview. :: 2552 calling the :class:`bytes` constructor on the memoryview. ::
2507 2553
2508 >>> m = memoryview(b"abc") 2554 >>> m = memoryview(b"abc")
2509 >>> m.tobytes() 2555 >>> m.tobytes()
2510 b'abc' 2556 b'abc'
2511 >>> bytes(m) 2557 >>> bytes(m)
2512 b'abc' 2558 b'abc'
2513 2559
2514 For non-contiguous arrays the result is equal to the flattened list 2560 For non-contiguous arrays the result is equal to the flattened list
2515 representation with all elements converted to bytes. 2561 representation with all elements converted to bytes. :meth:`tobytes`
2562 supports all format strings, including those that are not in
2563 :mod:`struct` module syntax.
2516 2564
2517 .. method:: tolist() 2565 .. method:: tolist()
2518 2566
2519 Return the data in the buffer as a list of elements. :: 2567 Return the data in the buffer as a list of elements. ::
2520 2568
2521 >>> memoryview(b'abc').tolist() 2569 >>> memoryview(b'abc').tolist()
2522 [97, 98, 99] 2570 [97, 98, 99]
2523 >>> import array 2571 >>> import array
2524 >>> a = array.array('d', [1.1, 2.2, 3.3]) 2572 >>> a = array.array('d', [1.1, 2.2, 3.3])
2525 >>> m = memoryview(a) 2573 >>> m = memoryview(a)
2526 >>> m.tolist() 2574 >>> m.tolist()
2527 [1.1, 2.2, 3.3] 2575 [1.1, 2.2, 3.3]
2576
2577 :meth:`tolist` is currently restricted to single character native formats
2578 in :mod:`struct` module syntax.
2528 2579
2529 .. method:: release() 2580 .. method:: release()
2530 2581
2531 Release the underlying buffer exposed by the memoryview object. Many 2582 Release the underlying buffer exposed by the memoryview object. Many
2532 objects take special actions when a view is held on them (for example, 2583 objects take special actions when a view is held on them (for example,
2533 a :class:`bytearray` would temporarily forbid resizing); therefore, 2584 a :class:`bytearray` would temporarily forbid resizing); therefore,
2534 calling release() is handy to remove these restrictions (and free any 2585 calling release() is handy to remove these restrictions (and free any
2535 dangling resources) as soon as possible. 2586 dangling resources) as soon as possible.
2536 2587
2537 After this method has been called, any further operation on the view 2588 After this method has been called, any further operation on the view
(...skipping 20 matching lines...) Expand all
2558 ValueError: operation forbidden on released memoryview object 2609 ValueError: operation forbidden on released memoryview object
2559 2610
2560 .. versionadded:: 3.2 2611 .. versionadded:: 3.2
2561 2612
2562 .. method:: cast(format[, shape]) 2613 .. method:: cast(format[, shape])
2563 2614
2564 Cast a memoryview to a new format or shape. *shape* defaults to 2615 Cast a memoryview to a new format or shape. *shape* defaults to
2565 ``[byte_length//new_itemsize]``, which means that the result view 2616 ``[byte_length//new_itemsize]``, which means that the result view
2566 will be one-dimensional. The return value is a new memoryview, but 2617 will be one-dimensional. The return value is a new memoryview, but
2567 the buffer itself is not copied. Supported casts are 1D -> C-contiguous 2618 the buffer itself is not copied. Supported casts are 1D -> C-contiguous
2568 and C-contiguous -> 1D. One of the formats must be a byte format 2619 and C-contiguous -> 1D.
2620
2621 Both formats are restricted to single element native formats in
2622 :mod:`struct` syntax. One of the formats must be a byte format
2569 ('B', 'b' or 'c'). The byte length of the result must be the same 2623 ('B', 'b' or 'c'). The byte length of the result must be the same
2570 as the original length. 2624 as the original length.
2571 2625
2572 Cast 1D/long to 1D/unsigned bytes:: 2626 Cast 1D/long to 1D/unsigned bytes::
2573 2627
2574 >>> import array 2628 >>> import array
2575 >>> a = array.array('l', [1,2,3]) 2629 >>> a = array.array('l', [1,2,3])
2576 >>> x = memoryview(a) 2630 >>> x = memoryview(a)
2577 >>> x.format 2631 >>> x.format
2578 'l' 2632 'l'
(...skipping 117 matching lines...) Expand 10 before | Expand all | Expand 10 after
2696 2750
2697 .. attribute:: readonly 2751 .. attribute:: readonly
2698 2752
2699 A bool indicating whether the memory is read only. 2753 A bool indicating whether the memory is read only.
2700 2754
2701 .. attribute:: format 2755 .. attribute:: format
2702 2756
2703 A string containing the format (in :mod:`struct` module style) for each 2757 A string containing the format (in :mod:`struct` module style) for each
2704 element in the view. A memoryview can be created from exporters with 2758 element in the view. A memoryview can be created from exporters with
2705 arbitrary format strings, but some methods (e.g. :meth:`tolist`) are 2759 arbitrary format strings, but some methods (e.g. :meth:`tolist`) are
2706 restricted to native single element formats. Special care must be taken 2760 restricted to native single element formats.
2707 when comparing memoryviews. Since comparisons are required to return a
2708 value for ``==`` and ``!=``, two memoryviews referencing the same
2709 exporter can compare as not-equal if the exporter's format is not
2710 understood::
2711
2712 >>> from ctypes import BigEndianStructure, c_long
2713 >>> class BEPoint(BigEndianStructure):
2714 ... _fields_ = [("x", c_long), ("y", c_long)]
2715 ...
2716 >>> point = BEPoint(100, 200)
2717 >>> a = memoryview(point)
2718 >>> b = memoryview(point)
2719 >>> a == b
2720 False
2721 >>> a.tolist()
2722 Traceback (most recent call last):
2723 File "<stdin>", line 1, in <module>
2724 NotImplementedError: memoryview: unsupported format T{>l:x:>l:y:}
2725 2761
2726 .. attribute:: itemsize 2762 .. attribute:: itemsize
2727 2763
2728 The size in bytes of each element of the memoryview:: 2764 The size in bytes of each element of the memoryview::
2729 2765
2730 >>> import array, struct 2766 >>> import array, struct
2731 >>> m = memoryview(array.array('H', [32000, 32001, 32002])) 2767 >>> m = memoryview(array.array('H', [32000, 32001, 32002]))
2732 >>> m.itemsize 2768 >>> m.itemsize
2733 2 2769 2
2734 >>> m[0] 2770 >>> m[0]
(...skipping 390 matching lines...) Expand 10 before | Expand all | Expand 10 after
3125 .. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0] ``, and 3161 .. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0] ``, and
3126 similarly for tuples. 3162 similarly for tuples.
3127 3163
3128 .. [3] They must have since the parser can't tell the type of the operands. 3164 .. [3] They must have since the parser can't tell the type of the operands.
3129 3165
3130 .. [4] Cased characters are those with general category property being one of 3166 .. [4] Cased characters are those with general category property being one of
3131 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecas e). 3167 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecas e).
3132 3168
3133 .. [5] To format only a tuple you should therefore provide a singleton tuple who se only 3169 .. [5] To format only a tuple you should therefore provide a singleton tuple who se only
3134 element is the tuple to be formatted. 3170 element is the tuple to be formatted.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+