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
|
from __future__ import annotations
import datetime as _datetime
from typing import TYPE_CHECKING, overload, TypeVar, Any
from . import (
DecodeError as _DecodeError,
convert as _convert,
to_builtins as _to_builtins,
)
if TYPE_CHECKING:
from typing import Callable, Optional, Type, Union, Literal
from typing_extensions import Buffer
__all__ = ("encode", "decode")
def __dir__():
return __all__
def _import_tomllib():
try:
import tomllib # type: ignore
return tomllib
except ImportError:
pass
try:
import tomli # type: ignore
return tomli
except ImportError:
raise ImportError(
"`msgspec.toml.decode` requires `tomli` be installed.\n\n"
"Please either `pip` or `conda` install it as follows:\n\n"
" $ python -m pip install tomli # using pip\n"
" $ conda install tomli # or using conda"
) from None
def _import_tomli_w():
try:
import tomli_w # type: ignore
return tomli_w
except ImportError:
raise ImportError(
"`msgspec.toml.encode` requires `tomli_w` be installed.\n\n"
"Please either `pip` or `conda` install it as follows:\n\n"
" $ python -m pip install tomli_w # using pip\n"
" $ conda install tomli_w # or using conda"
) from None
def encode(
obj: Any,
*,
enc_hook: Optional[Callable[[Any], Any]] = None,
order: Literal[None, "deterministic", "sorted"] = None,
) -> bytes:
"""Serialize an object as TOML.
Parameters
----------
obj : Any
The object to serialize.
enc_hook : callable, optional
A callable to call for objects that aren't supported msgspec types.
Takes the unsupported object and should return a supported object, or
raise a ``NotImplementedError`` if unsupported.
order : {None, 'deterministic', 'sorted'}, optional
The ordering to use when encoding unordered compound types.
- ``None``: All objects are encoded in the most efficient manner
matching their in-memory representations. The default.
- `'deterministic'`: Unordered collections (sets, dicts) are sorted to
ensure a consistent output between runs. Useful when
comparison/hashing of the encoded binary output is necessary.
- `'sorted'`: Like `'deterministic'`, but *all* object-like types
(structs, dataclasses, ...) are also sorted by field name before
encoding. This is slower than `'deterministic'`, but may produce more
human-readable output.
Returns
-------
data : bytes
The serialized object.
See Also
--------
decode
"""
toml = _import_tomli_w()
msg = _to_builtins(
obj,
builtin_types=(_datetime.datetime, _datetime.date, _datetime.time),
str_keys=True,
enc_hook=enc_hook,
order=order,
)
return toml.dumps(msg).encode("utf-8")
T = TypeVar("T")
@overload
def decode(
buf: Union[Buffer, str],
*,
strict: bool = True,
dec_hook: Optional[Callable[[type, Any], Any]] = None,
) -> Any:
pass
@overload
def decode(
buf: Union[Buffer, str],
*,
type: Type[T] = ...,
strict: bool = True,
dec_hook: Optional[Callable[[type, Any], Any]] = None,
) -> T:
pass
@overload
def decode(
buf: Union[Buffer, str],
*,
type: Any = ...,
strict: bool = True,
dec_hook: Optional[Callable[[type, Any], Any]] = None,
) -> Any:
pass
def decode(buf, *, type=Any, strict=True, dec_hook=None):
"""Deserialize an object from TOML.
Parameters
----------
buf : bytes-like or str
The message to decode.
type : type, optional
A Python type (in type annotation form) to decode the object as. If
provided, the message will be type checked and decoded as the specified
type. Defaults to `Any`, in which case the message will be decoded
using the default TOML types.
strict : bool, optional
Whether type coercion rules should be strict. Setting to False enables
a wider set of coercion rules from string to non-string types for all
values. Default is True.
dec_hook : callable, optional
An optional callback for handling decoding custom types. Should have
the signature ``dec_hook(type: Type, obj: Any) -> Any``, where ``type``
is the expected message type, and ``obj`` is the decoded representation
composed of only basic TOML types. This hook should transform ``obj``
into type ``type``, or raise a ``NotImplementedError`` if unsupported.
Returns
-------
obj : Any
The deserialized object.
See Also
--------
encode
"""
toml = _import_tomllib()
if isinstance(buf, str):
str_buf = buf
elif isinstance(buf, (bytes, bytearray)):
str_buf = buf.decode("utf-8")
else:
# call `memoryview` first, since `bytes(1)` is actually valid
str_buf = bytes(memoryview(buf)).decode("utf-8")
try:
obj = toml.loads(str_buf)
except toml.TOMLDecodeError as exc:
raise _DecodeError(str(exc)) from None
if type is Any:
return obj
return _convert(
obj,
type,
builtin_types=(_datetime.datetime, _datetime.date, _datetime.time),
str_keys=True,
strict=strict,
dec_hook=dec_hook,
)
|
