source: pyyaml/trunk/lib3/yaml/__init__.py @ 353

Revision 353, 8.9 KB checked in by xi, 5 years ago (diff)

Fixed a typo in docstring.

Line 
1
2from .error import *
3
4from .tokens import *
5from .events import *
6from .nodes import *
7
8from .loader import *
9from .dumper import *
10
11__version__ = '3.08'
12try:
13    from .cyaml import *
14    __with_libyaml__ = True
15except ImportError:
16    __with_libyaml__ = False
17
18import io
19
20def scan(stream, Loader=Loader):
21    """
22    Scan a YAML stream and produce scanning tokens.
23    """
24    loader = Loader(stream)
25    while loader.check_token():
26        yield loader.get_token()
27
28def parse(stream, Loader=Loader):
29    """
30    Parse a YAML stream and produce parsing events.
31    """
32    loader = Loader(stream)
33    while loader.check_event():
34        yield loader.get_event()
35
36def compose(stream, Loader=Loader):
37    """
38    Parse the first YAML document in a stream
39    and produce the corresponding representation tree.
40    """
41    loader = Loader(stream)
42    return loader.get_single_node()
43
44def compose_all(stream, Loader=Loader):
45    """
46    Parse all YAML documents in a stream
47    and produce corresponding representation trees.
48    """
49    loader = Loader(stream)
50    while loader.check_node():
51        yield loader.get_node()
52
53def load(stream, Loader=Loader):
54    """
55    Parse the first YAML document in a stream
56    and produce the corresponding Python object.
57    """
58    loader = Loader(stream)
59    return loader.get_single_data()
60
61def load_all(stream, Loader=Loader):
62    """
63    Parse all YAML documents in a stream
64    and produce corresponding Python objects.
65    """
66    loader = Loader(stream)
67    while loader.check_data():
68        yield loader.get_data()
69
70def safe_load(stream):
71    """
72    Parse the first YAML document in a stream
73    and produce the corresponding Python object.
74    Resolve only basic YAML tags.
75    """
76    return load(stream, SafeLoader)
77
78def safe_load_all(stream):
79    """
80    Parse all YAML documents in a stream
81    and produce corresponding Python objects.
82    Resolve only basic YAML tags.
83    """
84    return load_all(stream, SafeLoader)
85
86def emit(events, stream=None, Dumper=Dumper,
87        canonical=None, indent=None, width=None,
88        allow_unicode=None, line_break=None):
89    """
90    Emit YAML parsing events into a stream.
91    If stream is None, return the produced string instead.
92    """
93    getvalue = None
94    if stream is None:
95        stream = io.StringIO()
96        getvalue = stream.getvalue
97    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
98            allow_unicode=allow_unicode, line_break=line_break)
99    for event in events:
100        dumper.emit(event)
101    if getvalue:
102        return getvalue()
103
104def serialize_all(nodes, stream=None, Dumper=Dumper,
105        canonical=None, indent=None, width=None,
106        allow_unicode=None, line_break=None,
107        encoding=None, explicit_start=None, explicit_end=None,
108        version=None, tags=None):
109    """
110    Serialize a sequence of representation trees into a YAML stream.
111    If stream is None, return the produced string instead.
112    """
113    getvalue = None
114    if stream is None:
115        if encoding is None:
116            stream = io.StringIO()
117        else:
118            stream = io.BytesIO()
119        getvalue = stream.getvalue
120    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
121            allow_unicode=allow_unicode, line_break=line_break,
122            encoding=encoding, version=version, tags=tags,
123            explicit_start=explicit_start, explicit_end=explicit_end)
124    dumper.open()
125    for node in nodes:
126        dumper.serialize(node)
127    dumper.close()
128    if getvalue:
129        return getvalue()
130
131def serialize(node, stream=None, Dumper=Dumper, **kwds):
132    """
133    Serialize a representation tree into a YAML stream.
134    If stream is None, return the produced string instead.
135    """
136    return serialize_all([node], stream, Dumper=Dumper, **kwds)
137
138def dump_all(documents, stream=None, Dumper=Dumper,
139        default_style=None, default_flow_style=None,
140        canonical=None, indent=None, width=None,
141        allow_unicode=None, line_break=None,
142        encoding=None, explicit_start=None, explicit_end=None,
143        version=None, tags=None):
144    """
145    Serialize a sequence of Python objects into a YAML stream.
146    If stream is None, return the produced string instead.
147    """
148    getvalue = None
149    if stream is None:
150        if encoding is None:
151            stream = io.StringIO()
152        else:
153            stream = io.BytesIO()
154        getvalue = stream.getvalue
155    dumper = Dumper(stream, default_style=default_style,
156            default_flow_style=default_flow_style,
157            canonical=canonical, indent=indent, width=width,
158            allow_unicode=allow_unicode, line_break=line_break,
159            encoding=encoding, version=version, tags=tags,
160            explicit_start=explicit_start, explicit_end=explicit_end)
161    dumper.open()
162    for data in documents:
163        dumper.represent(data)
164    dumper.close()
165    if getvalue:
166        return getvalue()
167
168def dump(data, stream=None, Dumper=Dumper, **kwds):
169    """
170    Serialize a Python object into a YAML stream.
171    If stream is None, return the produced string instead.
172    """
173    return dump_all([data], stream, Dumper=Dumper, **kwds)
174
175def safe_dump_all(documents, stream=None, **kwds):
176    """
177    Serialize a sequence of Python objects into a YAML stream.
178    Produce only basic YAML tags.
179    If stream is None, return the produced string instead.
180    """
181    return dump_all(documents, stream, Dumper=SafeDumper, **kwds)
182
183def safe_dump(data, stream=None, **kwds):
184    """
185    Serialize a Python object into a YAML stream.
186    Produce only basic YAML tags.
187    If stream is None, return the produced string instead.
188    """
189    return dump_all([data], stream, Dumper=SafeDumper, **kwds)
190
191def add_implicit_resolver(tag, regexp, first=None,
192        Loader=Loader, Dumper=Dumper):
193    """
194    Add an implicit scalar detector.
195    If an implicit scalar value matches the given regexp,
196    the corresponding tag is assigned to the scalar.
197    first is a sequence of possible initial characters or None.
198    """
199    Loader.add_implicit_resolver(tag, regexp, first)
200    Dumper.add_implicit_resolver(tag, regexp, first)
201
202def add_path_resolver(tag, path, kind=None, Loader=Loader, Dumper=Dumper):
203    """
204    Add a path based resolver for the given tag.
205    A path is a list of keys that forms a path
206    to a node in the representation tree.
207    Keys can be string values, integers, or None.
208    """
209    Loader.add_path_resolver(tag, path, kind)
210    Dumper.add_path_resolver(tag, path, kind)
211
212def add_constructor(tag, constructor, Loader=Loader):
213    """
214    Add a constructor for the given tag.
215    Constructor is a function that accepts a Loader instance
216    and a node object and produces the corresponding Python object.
217    """
218    Loader.add_constructor(tag, constructor)
219
220def add_multi_constructor(tag_prefix, multi_constructor, Loader=Loader):
221    """
222    Add a multi-constructor for the given tag prefix.
223    Multi-constructor is called for a node if its tag starts with tag_prefix.
224    Multi-constructor accepts a Loader instance, a tag suffix,
225    and a node object and produces the corresponding Python object.
226    """
227    Loader.add_multi_constructor(tag_prefix, multi_constructor)
228
229def add_representer(data_type, representer, Dumper=Dumper):
230    """
231    Add a representer for the given type.
232    Representer is a function accepting a Dumper instance
233    and an instance of the given data type
234    and producing the corresponding representation node.
235    """
236    Dumper.add_representer(data_type, representer)
237
238def add_multi_representer(data_type, multi_representer, Dumper=Dumper):
239    """
240    Add a representer for the given type.
241    Multi-representer is a function accepting a Dumper instance
242    and an instance of the given data type or subtype
243    and producing the corresponding representation node.
244    """
245    Dumper.add_multi_representer(data_type, multi_representer)
246
247class YAMLObjectMetaclass(type):
248    """
249    The metaclass for YAMLObject.
250    """
251    def __init__(cls, name, bases, kwds):
252        super(YAMLObjectMetaclass, cls).__init__(name, bases, kwds)
253        if 'yaml_tag' in kwds and kwds['yaml_tag'] is not None:
254            cls.yaml_loader.add_constructor(cls.yaml_tag, cls.from_yaml)
255            cls.yaml_dumper.add_representer(cls, cls.to_yaml)
256
257class YAMLObject(metaclass=YAMLObjectMetaclass):
258    """
259    An object that can dump itself to a YAML stream
260    and load itself from a YAML stream.
261    """
262
263    __slots__ = ()  # no direct instantiation, so allow immutable subclasses
264
265    yaml_loader = Loader
266    yaml_dumper = Dumper
267
268    yaml_tag = None
269    yaml_flow_style = None
270
271    @classmethod
272    def from_yaml(cls, loader, node):
273        """
274        Convert a representation node to a Python object.
275        """
276        return loader.construct_yaml_object(node, cls)
277
278    @classmethod
279    def to_yaml(cls, dumper, data):
280        """
281        Convert a Python object to a representation node.
282        """
283        return dumper.represent_yaml_object(cls.yaml_tag, data, cls,
284                flow_style=cls.yaml_flow_style)
285
Note: See TracBrowser for help on using the repository browser.