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

Side by Side Diff: Doc/library/stdtypes.rst

Issue 15573: Support unknown formats in memoryview comparisons
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:
View unified diff | Download patch
« no previous file with comments | « no previous file | Doc/whatsnew/3.3.rst » ('j') | Doc/whatsnew/3.3.rst » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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 2481 matching lines...) Expand 10 before | Expand all | Expand 10 after
2492 >>> y.tolist() 2492 >>> y.tolist()
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
2503 .. method:: __eq__()
2504
2505 Abstract definition of equality: Two memoryviews v and w compare equal
2506 if v.tolist() == w.tolist(). Contrary to the current implementation of
2507 :meth:`tolist`, all format strings in :mod:`struct` syntax are handled
2508 in comparisons.
loewis 2012/08/14 16:50:53 Proposal for rephrasing the last sentence: "While
skrah 2012/08/14 18:30:59 Yes, I don't like the original either. Also, the d
Nick Coghlan 2012/08/15 06:13:09 Proposed wording that tries to be both accurate an
skrah 2012/08/15 16:45:02 Sounds good to me. In the new patch I changed "two
2509
2510 If a format string is not in :mod:`struct` syntax or if unpacking a
2511 value results in a struct error, the result of the comparison is
2512 "not equal". Example: ::
2513
2514 >>> from ctypes import BigEndianStructure, c_long
2515 >>> class BEPoint(BigEndianStructure):
2516 ... _fields_ = [("x", c_long), ("y", c_long)]
2517 ...
2518 >>> point = BEPoint(100, 200)
2519 >>> a = memoryview(point)
2520 >>> b = memoryview(point)
2521 >>> a == b
2522 False
2523
2524 .. versionchanged:: 3.3
2502 2525
2503 .. method:: tobytes() 2526 .. method:: tobytes()
2504 2527
2505 Return the data in the buffer as a bytestring. This is equivalent to 2528 Return the data in the buffer as a bytestring. This is equivalent to
2506 calling the :class:`bytes` constructor on the memoryview. :: 2529 calling the :class:`bytes` constructor on the memoryview. ::
2507 2530
2508 >>> m = memoryview(b"abc") 2531 >>> m = memoryview(b"abc")
2509 >>> m.tobytes() 2532 >>> m.tobytes()
2510 b'abc' 2533 b'abc'
2511 >>> bytes(m) 2534 >>> bytes(m)
2512 b'abc' 2535 b'abc'
2513 2536
2514 For non-contiguous arrays the result is equal to the flattened list 2537 For non-contiguous arrays the result is equal to the flattened list
2515 representation with all elements converted to bytes. 2538 representation with all elements converted to bytes. :meth:`tobytes`
2539 supports all format strings, including those that are not in
2540 :mod:`struct` module syntax.
2516 2541
2517 .. method:: tolist() 2542 .. method:: tolist()
2518 2543
2519 Return the data in the buffer as a list of elements. :: 2544 Return the data in the buffer as a list of elements. ::
2520 2545
2521 >>> memoryview(b'abc').tolist() 2546 >>> memoryview(b'abc').tolist()
2522 [97, 98, 99] 2547 [97, 98, 99]
2523 >>> import array 2548 >>> import array
2524 >>> a = array.array('d', [1.1, 2.2, 3.3]) 2549 >>> a = array.array('d', [1.1, 2.2, 3.3])
2525 >>> m = memoryview(a) 2550 >>> m = memoryview(a)
2526 >>> m.tolist() 2551 >>> m.tolist()
2527 [1.1, 2.2, 3.3] 2552 [1.1, 2.2, 3.3]
2553
2554 :meth:`tolist` is currently restricted to single character native formats
2555 in :mod:`struct` module syntax.
2528 2556
2529 .. method:: release() 2557 .. method:: release()
2530 2558
2531 Release the underlying buffer exposed by the memoryview object. Many 2559 Release the underlying buffer exposed by the memoryview object. Many
2532 objects take special actions when a view is held on them (for example, 2560 objects take special actions when a view is held on them (for example,
2533 a :class:`bytearray` would temporarily forbid resizing); therefore, 2561 a :class:`bytearray` would temporarily forbid resizing); therefore,
2534 calling release() is handy to remove these restrictions (and free any 2562 calling release() is handy to remove these restrictions (and free any
2535 dangling resources) as soon as possible. 2563 dangling resources) as soon as possible.
2536 2564
2537 After this method has been called, any further operation on the view 2565 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 2586 ValueError: operation forbidden on released memoryview object
2559 2587
2560 .. versionadded:: 3.2 2588 .. versionadded:: 3.2
2561 2589
2562 .. method:: cast(format[, shape]) 2590 .. method:: cast(format[, shape])
2563 2591
2564 Cast a memoryview to a new format or shape. *shape* defaults to 2592 Cast a memoryview to a new format or shape. *shape* defaults to
2565 ``[byte_length//new_itemsize]``, which means that the result view 2593 ``[byte_length//new_itemsize]``, which means that the result view
2566 will be one-dimensional. The return value is a new memoryview, but 2594 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 2595 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 2596 and C-contiguous -> 1D.
2597
2598 Both formats are restricted to single element native formats in
2599 :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 2600 ('B', 'b' or 'c'). The byte length of the result must be the same
2570 as the original length. 2601 as the original length.
2571 2602
2572 Cast 1D/long to 1D/unsigned bytes:: 2603 Cast 1D/long to 1D/unsigned bytes::
2573 2604
2574 >>> import array 2605 >>> import array
2575 >>> a = array.array('l', [1,2,3]) 2606 >>> a = array.array('l', [1,2,3])
2576 >>> x = memoryview(a) 2607 >>> x = memoryview(a)
2577 >>> x.format 2608 >>> x.format
2578 'l' 2609 'l'
(...skipping 117 matching lines...) Expand 10 before | Expand all | Expand 10 after
2696 2727
2697 .. attribute:: readonly 2728 .. attribute:: readonly
2698 2729
2699 A bool indicating whether the memory is read only. 2730 A bool indicating whether the memory is read only.
2700 2731
2701 .. attribute:: format 2732 .. attribute:: format
2702 2733
2703 A string containing the format (in :mod:`struct` module style) for each 2734 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 2735 element in the view. A memoryview can be created from exporters with
2705 arbitrary format strings, but some methods (e.g. :meth:`tolist`) are 2736 arbitrary format strings, but some methods (e.g. :meth:`tolist`) are
2706 restricted to native single element formats. Special care must be taken 2737 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 2738
2726 .. attribute:: itemsize 2739 .. attribute:: itemsize
2727 2740
2728 The size in bytes of each element of the memoryview:: 2741 The size in bytes of each element of the memoryview::
2729 2742
2730 >>> import array, struct 2743 >>> import array, struct
2731 >>> m = memoryview(array.array('H', [32000, 32001, 32002])) 2744 >>> m = memoryview(array.array('H', [32000, 32001, 32002]))
2732 >>> m.itemsize 2745 >>> m.itemsize
2733 2 2746 2
2734 >>> m[0] 2747 >>> 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 3138 .. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0] ``, and
3126 similarly for tuples. 3139 similarly for tuples.
3127 3140
3128 .. [3] They must have since the parser can't tell the type of the operands. 3141 .. [3] They must have since the parser can't tell the type of the operands.
3129 3142
3130 .. [4] Cased characters are those with general category property being one of 3143 .. [4] Cased characters are those with general category property being one of
3131 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecas e). 3144 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecas e).
3132 3145
3133 .. [5] To format only a tuple you should therefore provide a singleton tuple who se only 3146 .. [5] To format only a tuple you should therefore provide a singleton tuple who se only
3134 element is the tuple to be formatted. 3147 element is the tuple to be formatted.
OLDNEW
« no previous file with comments | « no previous file | Doc/whatsnew/3.3.rst » ('j') | Doc/whatsnew/3.3.rst » ('J')

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