File: api.rst

package info (click to toggle)
python-rapidjson 1.4-3
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 7,368 kB
  • sloc: cpp: 3,332; python: 1,990; makefile: 106
file content (253 lines) | stat: -rw-r--r-- 7,996 bytes parent folder | download | duplicates (2)
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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
.. -*- coding: utf-8 -*-
.. :Project:   python-rapidjson -- API documentation
.. :Author:    Lele Gaifax <lele@metapensiero.it>
.. :License:   MIT License
.. :Copyright: © 2016, 2017, 2018, 2019, 2020 Lele Gaifax
..

===============================
 Exposed functions and symbols
===============================

.. currentmodule:: rapidjson

.. toctree::
   :maxdepth: 2

   dumps
   dump
   loads
   load
   encoder
   decoder
   validator
   rawjson

.. data:: __author__

   The authors of the module.

.. data:: __version__

   The version of the module.

.. data:: __rapidjson_version__

   The version of the RapidJSON_ library this module is built with.

.. data:: __rapidjson_exact_version__

   The *exact* version of the RapidJSON library, as determined by ``git describe``.


.. rubric:: `datetime_mode` related constants

.. data:: DM_NONE

   This is the default `datetime_mode`: *neither* :class:`date` *nor* :class:`datetime`
   *nor* :class:`time` instances are recognized by :func:`dumps` and :func:`loads`.

.. data:: DM_ISO8601

   In this `datetime_mode` mode :func:`dumps` and :func:`loads` handle :class:`date`,
   :class:`datetime` *and* :class:`date` instances representing those values using the
   `ISO 8601`_ format.

.. data:: DM_UNIX_TIME

   This mode tells RapidJSON to serialize :class:`date`, :class:`datetime` and
   :class:`time` as *numeric timestamps*: for the formers it is exactly the result of
   their :meth:`timestamp` method, that is as the number of seconds passed since
   ``EPOCH``; ``date`` instances are serialized as the corresponding ``datetime`` instance
   with all the `time` slots set to 0; ``time`` instances are serialized as the number of
   seconds since midnight.

   Since this is obviously *irreversible*, this flag is usable **only** for :func:`dumps`:
   an error is raised when passed to :func:`loads`.

.. data:: DM_ONLY_SECONDS

   This is usable in combination with :data:`DM_UNIX_TIME` so that an integer
   representation is used, ignoring *microseconds*.

.. data:: DM_IGNORE_TZ

   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to ignore
   the value's timezones.

.. data:: DM_NAIVE_IS_UTC

   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to tell
   RapidJSON that the naïve values (that is, without an explicit timezone) are already in
   UTC_ timezone.

.. data:: DM_SHIFT_TO_UTC

   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to always
   *shift* values the UTC_ timezone.


.. rubric:: `uuid_mode` related constants

.. data:: UM_NONE

   This is the default `uuid_mode`: :class:`UUID` instances are *not* recognized by
   :func:`dumps` and :func:`loads`.

.. data:: UM_CANONICAL

   In this `uuid_mode`, :func:`loads` recognizes string values containing the
   ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` canonical representation as :class:`UUID`
   instances; :func:`dumps` emits same kind of representation for :class:`UUID` instances
   as a string value.

.. data:: UM_HEX

   In this `uuid_mode` :func:`loads` recognizes string values containing exactly 32 hex
   digits *or* the ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` canonical representation as
   :class:`UUID` instances; :func:`dumps` emits the 32 hex digits of :class:`UUID`
   instances as a string value.


.. rubric:: `number_mode` related constants

.. data:: NM_NONE

   This is the default `number_mode`: numeric values can be as wide as the memory allows.

.. data:: NM_DECIMAL

   In this `number_mode` :func:`loads` will return floating point values as
   :class:`Decimal` instances instead of :class:`float`; :func:`dumps` will serialize
   :class:`Decimal` instances like any other :class:`float` number.

.. data:: NM_NAN

   This enables *non-numbers* (i.e. ``nan``, ``+inf`` and ``-inf``) handling in both
   directions.

.. data:: NM_NATIVE

   In this alternative `number_mode` numeric values must fit into the underlying C library
   limits, with a considerable speed benefit.


.. rubric:: `parse_mode` related constants

.. data:: PM_NONE

   This is the default `parse_mode`: with the exception of the *NaN and Infinite*
   recognition active by default, the parser is in *strict mode*.

.. data:: PM_COMMENTS

   In this `parse_mode`, the parser allows and ignores one-line ``// ...`` and multi-line
   ``/* ... */`` comments

.. data:: PM_TRAILING_COMMAS

   In this `parse_mode`, the parser allows and ignores trailing commas at the end of
   *arrays* and *objects*.


.. rubric:: `bytes_mode` related constants

.. data:: BM_NONE

   This disables the default handling mode (:data:`BM_UTF8`) of :class:`bytes` instances:
   they won't be treated in any special way and will raise a ``TypeError`` exception when
   encountered. On the other hand, in this mode they can be managed by a `default`
   handler.

.. data:: BM_UTF8

   This is the default setting for `bytes_mode`: any :class:`bytes` instance will be
   assumed to be an ``UTF-8`` encoded string, and decoded accordingly.


.. rubric:: `iterable_mode` related constants

.. data:: IM_ANY_ITERABLE

   This is the default setting for `iterable_mode`: any iterable will be dumped as a
   ``JSON`` array.

.. data:: IM_ONLY_LISTS

   This disables the default handling mode (:data:`IM_ANY_ITERABLE`) of `iterable` values
   (with the exception of ``str``\ ings and ``list``\ s): they won't be treated in any
   special way and will raise a ``TypeError`` exception when encountered. On the other
   hand, in this mode they can be managed by a `default` handler.

.. _mapping_mode:
.. rubric:: `mapping_mode` related constants

.. data:: MM_ANY_MAPPING

   This is the default setting for `mapping_mode`: any mapping will be dumped as a
   ``JSON`` object.

.. data:: MM_ONLY_DICTS

   This disables the default handling mode (:data:`MM_ANY_MAPPING`) of generic `mapping`
   values, they won't be treated like ``dict``\ s and will raise a ``TypeError`` exception
   when encountered. On the other hand, in this mode they can be managed by a `default`
   handler.

.. data:: MM_COERCE_KEYS_TO_STRINGS

   Since ``JSON`` objects require that all keys must be of type string, when a mapping
   contains *non-string* keys, it will be processed by the `default` handler if available,
   otherwise a ``TypeError`` exception is raised.

   Alternatively, you can use the this option to automatically render such keys as their
   ``str()`` representation.

.. data:: MM_SKIP_NON_STRING_KEYS

   In this mode, dict keys that are not of a basic type (:class:`str`, :class:`int`,
   :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
   :exc:`TypeError`.

.. data:: MM_SORT_KEYS

   Alphabetically order dictionary keys.

.. rubric:: Exceptions

.. exception:: JSONDecodeError

   A subclass of :exc:`ValueError`, raised when trying to parse an invalid ``JSON``,
   either by :class:`Validator` objects or by :func:`loads` function.

.. exception:: ValidationError

   Exception raised by :class:`Validator` objects, a subclass of :exc:`ValueError`.

   Its `args` attribute is a tuple with three string values, respectively the *schema
   keyword* that generated the failure, its *JSON pointer* and a *JSON pointer* to the
   error location in the (invalid) document.


.. rubric:: `write_mode` related constants

.. data:: WM_COMPACT

   The default dump mode, without any extra whitespace.

.. data:: WM_PRETTY

   This selects the RapidJSON ``PrettyWriter``, to produce more readable ``JSON``: each
   array's item and object's key will be preceded by a newline, and nested structures will
   be indented.

.. data:: WM_SINGLE_LINE_ARRAY

   This tells the ``PrettyWriter`` to emit arrays on a single line, instead of separating
   items with a newline.


.. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601
.. _RapidJSON: http://rapidjson.org/
.. _UTC: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
.. _Unix time: https://en.wikipedia.org/wiki/Unix_time