summaryrefslogtreecommitdiffstats
path: root/python/macholib/doc/ptypes.rst
blob: ade2ac84719eb74068c4d63a84468920b3c29ee2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
:mod:`macholib.ptypes` --- Packable types
=========================================

.. module:: macholib.ptypes
   :synopsis: Serializable types

The module :mod:`macholib.ptypes` defines types that can be serialized into
byte arrays, both for basic types and structured types (C ``struct`` values).

Utility functions
-----------------

.. function:: sizeof(value)

   Returns the size in bytes of an object when packed, raises :exc:`ValueError`
   for inappropriate values.

.. function:: pypackable(name, pytype, format)

   Returns a packable type that is a subclass of the Python type
   *pytype*. The value is converted to and from the packed format using
   the struct *format*.



Packable types
--------------


.. class:: BasePackable

   All packable types are a subclass of :class:`BasePackable`, which defines
   the basic interface but is itself an abstract base class.

   .. data:: _endian_

      The byteorder of a packed value. This will be ``"<"` for 
      little endian values and ``">"`` for big-endian ones.

      .. note:: the endianness option is a public value to be
         able to support both big- and little-endian file formats.

         The name suggests that this attribute is private, this
         is partically for historical reasons and partially to
         avoid conflicts with field names in C structs.

   .. method:: from_mmap(mmap, ptr, \**kw)

      This class method constructs the value from a subview of a 
      :class:`mmap.mmap` object. It uses bytes starting at offset *ptr* and 
      reads just enough bytes to read the entire object.

   .. method:: from_fileobj(fp, \**kw)

      This class method constructs the value by reading just enough bytes
      from a file-like object.

      .. note:: The file must be opened in binary mode, that is read calls
         should return byte-strings and not unicode-strings.

   .. method:: from_str(value, \**kw)

      This class method construct the value by using the struct module
      to parse the given bytes.

      .. note:: contrary to what the name suggests the argument to this
         method is a byte-string, not a unicode-string.

   .. method:: from_tuple(fp, \**kw)

      This class method constructs the object from a tuple with all fields.


   .. method:: to_str()

      Returns a byte representation of the value. 

      .. note:: there is no default implementation for this method

   .. method:: to_fileobj(fp)

      Write a byte representation of the value to the given file-like
      object. The file should be opened in binary mode.

   .. method:: to_mmap(mmap, ptr)

      Write the byte representation of the value to a :class:`mmap.mmap` 
      object, starting at offset *ptr*.


.. class:: Structure(...)

   .. data:: _fields_

      This class attribute is a list that contains the fields of the 
      structure in the right order. Every item of this list is a tuple 
      with 2 arguments: the first element is the name of the field, and 
      the second the packable type for the field.

      Every subclass of :class:`Structure` must define *_fields_* to be
      usefull, and the value of *_fields_* should not be changed after
      class construction.


Basic packables
---------------

Other than the core functionality this module defines a number of 
:func:`pypackable` types that correspond to useful basic C types.

.. class:: p_char([value])

   A byte string of length 1

.. class:: p_int8

   An 8-bit signed integer

.. class:: p_uint8

   An 8-bit unsigned integer

.. class:: p_int16

   An 16-bit signed integer

.. class:: p_uint16

   An 16-bit unsigned integer

.. class:: p_int32

   An 32-bit signed integer

.. class:: p_uint32

   An 32-bit unsigned integer

.. class:: p_int64

   An 64-bit signed integer

.. class:: p_uint64

   An 64-bit unsigned integer

.. class:: p_float

   An floating point value of type ``float``

.. class:: p_double

   An floating point value of type ``double``

.. note:: the module exports a number of other types with
   names starting with ``p_``, such as ``p_int``. Those types
   are deprecated and should not be used.