Implement PEP 3118 struct changes - Code Review (original) (raw)

OLD

NEW

1 :mod:`struct` --- Interpret bytes as packed binary data

2 =======================================================

4 .. module:: struct

5 :synopsis: Interpret bytes as packed binary data.

7 .. index::

8 pair: C; structures

9 triple: packing; binary; data

(...skipping 58 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

69 .. function:: calcsize(fmt)

71 Return the size of the struct (and hence of the bytes object produced by

72 ``pack(fmt, ...)``) corresponding to the format string *fmt*.

74 .. _struct-format-strings:

76 Format Strings

77 --------------

79 .. productionlist::

80 format_string: `byte_order_specifier`? `format_string_body`

81 format_string_body: (`count`? `type_string`)*

82 type_string: `character_code` | `structure`

83 count: `decimalinteger`

79 Format strings are the mechanism used to specify the expected layout when

85 Format strings are the mechanism used to specify the expected layout when

80 packing and unpacking data. They are built up from :ref:`format-characters`,

86 packing and unpacking data. They are built up from :ref:`format-characters`,

81 which specify the type of data being packed/unpacked. In addition, there are

87 which specify the type of data being packed/unpacked. There are special

82 special characters for controlling the :ref:`struct-alignment`.

88 characters for controlling the :ref:`struct-alignment`. In addition,

89 the layout of nested :ref:`structure-layout` may be specified.

85 .. _struct-alignment:

92 .. _struct-alignment:

87 Byte Order, Size, and Alignment

94 Byte Order, Size, and Alignment

88 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

95 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

97 .. productionlist::

98 byte_order_specifier: "!" | "@" | "=" | ">" | "<" | "^"

90 By default, C types are represented in the machine's native format and byte

100 By default, C types are represented in the machine's native format and byte

91 order, and properly aligned by skipping pad bytes if necessary (according to the

101 order, and properly aligned by skipping pad bytes if necessary (according to the

92 rules used by the C compiler).

102 rules used by the C compiler).

103

94 Alternatively, the first character of the format string can be used to indicate

104 Alternatively, the first character of the format string can be used to indicate

95 the byte order, size and alignment of the packed data, according to the

105 the byte order, size and alignment of the packed data, according to the

96 following table:

106 following table:

107

98 +-----------+------------------------+----------+-----------+

108 +-----------+------------------------+----------+-----------+

(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

132 There is no way to indicate non-native byte order (force byte-swapping); use the

142 There is no way to indicate non-native byte order (force byte-swapping); use the

133 appropriate choice of ``'<'`` or ``'>'``.

143 appropriate choice of ``'<'`` or ``'>'``.

134

144

135 Notes:

145 Notes:

136

146

137 (1) Padding is only automatically added between successive structure members.

147 (1) Padding is only automatically added between successive structure members.

138 No padding is added at the beginning or the end of the encoded struct.

148 No padding is added at the beginning or the end of the encoded struct.

139

149

140 (2) No padding is added when using non-native size and alignment, e.g.

150 (2) No padding is added when using non-native size and alignment, e.g.

141 with '<', '>', '=', and '!'.

151 with '<', '>', '=', and '!'.

142

152

143 (3) To align the end of a structure to the alignment requirement of a

153 (3) To align the end of a structure to the alignment requirement of a

144 particular type, end the format with the code for that type with a repeat

154 particular type, end the format with the code for that type with a repeat

145 count of zero. See :ref:`struct-examples`.

155 count of zero. See :ref:`struct-examples`.

146

156

147

157

158 .. _structure-layout:

159

160 Structure Layout

161 ^^^^^^^^^^^^^^^^

162 ·

163 .. productionlist::

164 structure: "T" "{" `format_string_body` "}"

165

166 The structure layout format string provides a way to specify layouts which

167 may be arbitrarily nested (with limits, see note). Packing a structure layout

168 requires a nested tuple with the same shape as the structure layout being

169 packed. Similarly, unpacking produces a nested structure with the same shape

170 as the structure layout being unpacked.

171

172 .. note::

173 The allowable nesting depth of structures is limited. It is guaranteed

174 that at least 63 nesting levels are allowed.

175 ·

148 .. _format-characters:

176 .. _format-characters:

149

177

150 Format Characters

178 Format Characters

151 ^^^^^^^^^^^^^^^^^

179 ^^^^^^^^^^^^^^^^^

152

180

181 .. productionlist::

182 character_code: "x" | "c" | "b" | "B" | "?" | "h" | "H" | "i" | "I" | "l"·

183 : | "L" | "q" | "Q" | "f" | "d" | "s" | "p" | "P" | "t" | "g" | "u"·

184 : | "w" | "O" | "Z"

185

153 Format characters have the following meaning; the conversion between C and

186 Format characters have the following meaning; the conversion between C and

154 Python values should be obvious given their types. The 'Standard size' column

187 Python values should be obvious given their types. The 'Standard size' column

155 refers to the size of the packed value in bytes when using standard size; that

188 refers to the size of the packed value in bytes when using standard size; that

156 is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or

189 is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or

157 ``'='``. When using native size, the size of the packed value is

190 ``'='``. When using native size, the size of the packed value is

158 platform-dependent.

191 platform-dependent.

159

192

160 +--------+--------------------------+--------------------+----------------+----- -------+

193 +--------+--------------------------+--------------------+----------------+----- -------+

162 +========+==========================+====================+================+===== =======+

195 +========+==========================+====================+================+===== =======+

(...skipping 153 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

316

349

317 The following format ``'llh0l'`` specifies two pad bytes at the end, assuming

350 The following format ``'llh0l'`` specifies two pad bytes at the end, assuming

318 longs are aligned on 4-byte boundaries::

351 longs are aligned on 4-byte boundaries::

319

352

320 >>> pack('llh0l', 1, 2, 3)

353 >>> pack('llh0l', 1, 2, 3)

321 b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

354 b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

322

355

323 This only works when native size and alignment are in effect; standard size and

356 This only works when native size and alignment are in effect; standard size and

324 alignment does not enforce any alignment.

357 alignment does not enforce any alignment.

325

358

359 In addition to primitive character codes, nested structure layouts can be·

360 packed::

361 ·

362 >>> pack('c T { iii T { h } }', '*', (1, 2, 3, (4,)))

363 '*\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04\x00'

364

365 and unpacked::

366

367 >>> unpack('T{ c T{ c } c}', 'rgb')

368 (('r', ('g',), 'b'),)

369

370 Empty structures are allowed, but note that they must be packed with empty

371 tuples::

372

373 >>> pack('T{}', ())

374 b''

375 >>> pack('T{T{}}', ((),))

376 b''

377 >>> pack('T{}')

378 Traceback (most recent call last):

379 File "", line 1, in

380 struct.error: pack requires exactly 1 arguments

381

326

382

327 .. seealso::

383 .. seealso::

328

384

329 Module :mod:`array`

385 Module :mod:`array`

330 Packed binary storage of homogeneous data.

386 Packed binary storage of homogeneous data.

331

387

332 Module :mod:`xdrlib`

388 Module :mod:`xdrlib`

333 Packing and unpacking of XDR data.

389 Packing and unpacking of XDR data.

334

390

335

391

(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

376

432

377 .. attribute:: format

433 .. attribute:: format

378

434

379 The format string used to construct this Struct object.

435 The format string used to construct this Struct object.

380

436

381 .. attribute:: size

437 .. attribute:: size

382

438

383 The calculated size of the struct (and hence of the bytes object produced

439 The calculated size of the struct (and hence of the bytes object produced

384 by the :meth:`pack` method) corresponding to :attr:`format`.

440 by the :meth:`pack` method) corresponding to :attr:`format`.

385

441

OLD

NEW