Context Navigation

Changes between Version 19 and Version 20 of PyYAMLDocumentation

Timestamp:: 05/07/06 05:08:48 (7 years ago)
Author:: xi
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

PyYAMLDocumentation

-                      v19
+                      v20
 '''Warning: API stability is not guaranteed!'''
+=== The yaml package ===
+{{{
+#!python
+scan(stream, Loader=Loader)
+}}}
+'''`scan(stream)`''' scans the given `stream` and produces a sequence of tokens.
+{{{
+#!python
+parse(stream, Loader=Loader)
+emit(events, stream=None, Dumper=Dumper,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+}}}
+'''`parse(stream)`''' parses the given `stream` and produces a sequence of parsing events.
+'''`emit(events, stream=None)`''' serializes the given sequence of parsing `events` and
+write them to the `stream`. if `stream` is `None`, it returns the produced stream.
+{{{
+#!python
+compose(stream, Loader=Loader)
+compose_all(stream, Loader=Loader)
+serialize(node, stream=None, Dumper=Dumper,
+    encoding='utf-8',
+    explicit_start=None,
+    explicit_end=None,
+    version=None,
+    tags=None,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+serialize_all(nodes, stream=None, Dumper=Dumper, ...)
+}}}
+'''`compose(stream)`''' parses the given `stream` and returns the root of the representation graph
+for the first document in the stream. If there are no documents in the stream, it returns `None`.
+'''`compose_all(stream)`''' parses the given `stream` and returns a sequence of representation graphs
+corresponding to the documents in the stream.
+'''`serialize(node, stream=None)`''' serializes the given representation graph into the `stream`.
+If `stream` is `None`, it returns the produced stream.
+'''`serialize_all(node, stream=None)`''' serializes the given sequence of representation graphs
+into the given `stream`. If `stream` is `None`, it returns the produced stream.
+{{{
+#!python
+load(stream, Loader=Loader)
+load_all(stream, Loader=Loader)
+safe_load(stream)
+safe_load_all(stream)
+dump(data, stream=None, Dumper=Dumper,
+    default_style=None,
+    default_flow_style=None,
+    encoding='utf-8',
+    explicit_start=None,
+    explicit_end=None,
+    version=None,
+    tags=None,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+dump_all(data, stream=None, Dumper=Dumper, ...)
+safe_dump(data, stream=None, ...)
+safe_dump_all(data, stream=None, ...)
+}}}
+'''`load(stream)`''' parses the given `stream` and returns a Python object constructed from
+for the first document in the stream. If there are no documents in the stream, it returns `None`.
+'''`load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects
+corresponding to the documents in the stream.
+'''`safe_load(stream)`''' parses the given `stream` and returns a Python object constructed from
+for the first document in the stream. If there are no documents in the stream, it returns `None`.
+`safe_load` recognizes only standard YAML tags and cannot construct an arbitrary Python object.
+'''`safe_load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects
+corresponding to the documents in the stream. `safe_load_all` recognizes only standard YAML tags
+and cannot construct an arbitrary Python object.
+'''`dump(data, stream=None)`''' serializes the given Python object into the `stream`.
+If `stream` is `None`, it returns the produced stream.
+'''`dump_all(data, stream=None)`''' serializes the given sequence of Python objects
+into the given `stream`. If `stream` is `None`, it returns the produced stream.
+Each object is represented as a YAML document.
+'''`safe_dump(data, stream=None)`''' serializes the given Python object into the `stream`.
+If `stream` is `None`, it returns the produced stream. `safe_dump` produces only standard YAML
+tags and cannot represent an arbitrary Python object.
+'''`safe_dump_all(data, stream=None)`''' serializes the given sequence of Python objects
+into the given `stream`. If `stream` is `None`, it returns the produced stream.
+Each object is represented as a YAML document.  `safe_dump_all` produces only standard YAML
+tags and cannot represent an arbitrary Python object.
+{{{
+#!python
+def constructor(loader, node):
+    # ...
+    return data
+def multi_constructor(loader, tag_suffix, node):
+    # ...
+    return data
+add_constructor(tag, constructor, Loader=Loader)
+add_multi_constructor(tag_prefix, multi_constructor, Loader=Loader)
+}}}
+'''`add_constructor(tag, constructor)`''' allows to specify a `constructor` for the given `tag`.
+A constructor is a function that converts a node of a YAML representation graph to a native Python object.
+A constructor accepts an instance of `Loader` and a node and returns a Python object.
+'''`add_multi_constructor(tag_prefix, multi_constructor)`''' allows to specify a `multi_constructor`
+for the given `tag_prefix`. A multi-constructor is a function that converts a node of a YAML
+representation graph to a native Python object. A multi-constructor accepts an instance of `Loader`,
+the suffix of the node tag, and a node and returns a Python object.
+{{{
+#!python
+def representer(dumper, data):
+    # ...
+    return node
+def multi_representer(dumper, data):
+    # ...
+    return node
+add_representer(data_type, representer, Dumper=Dumper)
+add_multi_representer(base_data_type, multi_representer, Dumper=Dumper)
+}}}
+'''`add_representer(data_type, representer)`''' allows to specify a `representer` for Python objects
+of the given `data_type`. A representer is a function that converts a native Python object to a node
+of a YAML representation graph. A representer accepts an instance of `Dumper` and an object and returns a node.
+'''`add_multi_representer(base_data_type, multi_representer)`''' allows to specify a `multi_representer`
+for Python objects of the given `base_data_type` or any of its subclasses. A multi-representer is
+a function that converts a native Python object to a node of a YAML representation graph.
+A multi-representer accepts an instance of `Dumper` and an object and returns a node.
+{{{
+#!python
+add_implicit_resolver(tag, regexp, first, Loader=Loader, Dumper=Dumper)
+add_path_resolver(tag, path, kind, Loader=Loader, Dumper=Dumper)
+}}}
+'''`add_implicit_resolver(tag, regexp, first)`''' adds an implicit tag resolver for plain scalars.
+If the scalar value is matched the given `regexp`, it is assigned the `tag`. `first` is a
+list of possible initial characters or `None`.
+'''`add_path_resolver(tag, path, kind)`''' adds a path-based implicit tag resolver.
+A `path` is a list of keys that form a path to a node in the representation graph.
+Paths elements can be string values, integers, or `None`. The `kind` of a node can
+be `str`, `list`, `dict`, or `None`.
 === YAMLError ===
 …
 BlockMappingStartToken()
 KeyToken()
 ScalarToken(plain=True, style=None, value=u'KeyToken')
 …
 }}}
-'''`BaseLoader`''', '''`SafeLoader`''', and '''`Loader`''' provide the following interfaces:
-''Scanner'', ''Parser'', ''Composer'', ''Constructor'', ''Resolver''.
 '''`Loader(stream)`''' is the most common of the above classes and should be used in most cases.
 `stream` is an input YAML stream. It can be a string, a Unicode string, an open file, an open Unicode file.
 …
 lists, dictionaries and Unicode strings.
+==== Scanner interface ====
+{{{
+#!python
+scan(stream, Loader=Loader)
+{{{
+#!python
 Loader.check_token(*TokenClasses)
 Loader.peek_token()
 …
 }}}
-'''`scan(stream)`''' scans the given `stream` and produces a sequence of tokens.
 '''`Loader.check_token(*TokenClasses)`''' returns `True` if the next token in the stream
 is an instance of one of the given `TokenClasses`. Otherwise it returns `False`.
 …
 it from the internal token queue. The function returns `None` at the end of the stream.
+==== Parser interface ====
+{{{
+#!python
+parse(stream, Loader=Loader)
+{{{
+#!python
 Loader.check_event(*EventClasses)
 Loader.peek_event()
 …
 }}}
-'''`parse(stream)`''' parses the given `stream` and produces a sequence of parsing events.
 '''`Loader.check_event(*EventClasses)`''' returns `True` if the next event in the stream
 is an instance of one of the given `EventClasses`. Otherwise it returns `False`.
 …
 it from the internal event queue. The function returns `None` at the end of the stream.
+==== Composer interface ====
+{{{
+#!python
+compose(stream, Loader=Loader)
+compose_all(stream, Loader=Loader)
+{{{
+#!python
 Loader.check_node()
 Loader.get_node()
 }}}
-'''`compose(stream)`''' parses the given `stream` and returns the root of the representation graph
-for the first document in the stream. If there are no documents in the stream, it returns `None`.
-'''`compose_all(stream)`''' parses the given `stream` and returns a sequence of representation graphs
-corresponding to the documents in the stream.
 '''`Loader.check_node()`''' returns `True` is there are more documents available in the stream. Otherwise
 it returns `False`.
 …
 returns its root node.
+==== Constructor interface ====
+{{{
+#!python
+load(stream, Loader=Loader)
+load_all(stream, Loader=Loader)
+safe_load(stream)
+safe_load_all(stream)
+{{{
+#!python
 Loader.check_data()
 Loader.get_data()
-def constructor(loader, node):
-    # ...
-    return data
-def multi_constructor(loader, tag_suffix, node):
-    # ...
-    return data
-add_constructor(tag, constructor, Loader=Loader)
-add_multi_constructor(tag_prefix, multi_constructor, Loader=Loader)
 Loader.add_constructor(tag, constructor) # Loader.add_constructor is a class method.
 …
 }}}
-'''`load(stream)`''' parses the given `stream` and returns a Python object constructed from
-for the first document in the stream. If there are no documents in the stream, it returns `None`.
-'''`load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects
-corresponding to the documents in the stream.
-'''`safe_load(stream)`''' parses the given `stream` and returns a Python object constructed from
-for the first document in the stream. If there are no documents in the stream, it returns `None`.
-`safe_load` recognizes only standard YAML tags and cannot construct an arbitrary Python object.
-'''`safe_load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects
-corresponding to the documents in the stream. `safe_load_all` recognizes only standard YAML tags
-and cannot construct an arbitrary Python object.
 '''`Loader.check_data()`''' returns `True` is there are more documents available in the stream. Otherwise
 it returns `False`.
 …
 in the stream.
+'''`add_constructor(tag, constructor)`''' and '''`Loader.add_constructor(tag, constructor)`''' allow
+to specify a `constructor` for the given `tag`. A constructor is a function that converts a node
+of a YAML representation graph to a native Python object. A constructor accepts an instance of `Loader`
+and a node and returns a Python object.
+'''`add_multi_constructor(tag_prefix, multi_constructor)`''' and '''`Loader.add_multi_constructor(tag_prefix, multi_constructor)`'''
+allow to specify a `multi_constructor` for the given `tag_prefix`. A multi-constructor is a function that converts a node
+of a YAML representation graph to a native Python object. A multi-constructor accepts an instance of `Loader`,
+the suffix of the node tag, and a node and returns a Python object.
+'''`Loader.add_constructor(tag, constructor)`''': see `add_constructor`.
+'''`Loader.add_multi_constructor(tag_prefix, multi_constructor)`''': see `add_multi_constructor`.
 '''`Loader.construct_scalar(node)`''' checks that the given `node` is a scalar and returns its value.
 …
 of Python objects corresponding to the node keys and values. This function is intended to be used in constructors.
+==== Resolver interface ====
+The ''Resolver'' interfaces of '''`Loader`''' and '''`Dumper`''' are identical.
+{{{
+#!python
+add_implicit_resolver(tag, regexp, first, Loader=Loader, Dumper=Dumper)
+add_path_resolver(tag, path, kind, Loader=Loader, Dumper=Dumper)
+{{{
+#!python
 Loader.add_implicit_resolver(tag, regexp, first) # Loader.add_implicit_resolver is a class method.
 Loader.add_path_resolver(tag, path, kind) # Loader.add_path_resolver is a class method.
+Dumper.add_implicit_resolver(tag, regexp, first) # Dumper.add_implicit_resolver is a class method.
+Dumper.add_path_resolver(tag, path, kind) # Dumper.add_path_resolver is a class method.
+}}}
+'''`add_implicit_resolver(tag, regexp, first)`''' adds an implicit tag resolver for plain scalars.
+If the scalar value is matched the given `regexp`, it is assigned the `tag`. `first` is a
+list of possible initial characters or `None`.
+'''`add_path_resolver(tag, path, kind)`''' adds a path-based implicit tag resolver.
+A `path` is a list of keys that form a path to a node in the representation graph.
+Paths elements can be string values, integers, or `None`. The `kind` of a node can
+be `str`, `list`, `dict`, or `None`.
+}}}
+'''`Loader.add_implicit_resolver(tag, regexp, first)`''': see `add_implicit_resolver`.
+'''`Loader.add_path_resolver(tag, path, kind)`''': see `add_path_resolver`.
 …
 }}}
-'''`BaseDumper`''', '''`SafeDumper`''', and '''`Dumper`''' provide the following interfaces:
-''Emitter'', ''Serializer'', ''Representer'', ''Resolver''.
 '''`Dumper(stream)`''' is the most common of the above classes and should be used in most cases.
 `stream` is an output YAML stream. It can be an open file or an open Unicode file.
 …
 '''`BaseDumper(stream)`''' does not support any tags and is useful only for subclassing.
+==== Emitter interface ====
+{{{
+#!python
+emit(events, stream=None, Dumper=Dumper,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+Emitter.emit(event)
+}}}
+'''`emit(events, stream=None)`''' serializes the given sequence of parsing `events` and
+write them to the `stream`. if `stream` is `None`, it returns the produced stream.
+'''`Emitter.emit(event)`''' serializes the given `event` and write it to the output stream.
+==== Serializer interface ====
+{{{
+#!python
+serialize(node, stream=None, Dumper=Dumper,
+    encoding='utf-8',
+    explicit_start=None,
+    explicit_end=None,
+    version=None,
+    tags=None,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+serialize_all(nodes, stream=None, Dumper=Dumper, ...)
+{{{
+#!python
+Dumper.emit(event)
+}}}
+'''`Dumper.emit(event)`''' serializes the given `event` and write it to the output stream.
+{{{
+#!python
 Dumper.open()
 Dumper.serialize(node)
 …
 }}}
-'''`serialize(node, stream=None)`''' serializes the given representation graph into the `stream`.
-If `stream` is `None`, it returns the produced stream.
 '''`Dumper.open()`''' emits `StreamStartEvent`.
 …
 '''`Dumper.close()`''' emits `StreamEndEvent`.
+==== Representer interface ====
+{{{
+#!python
+dump(data, stream=None, Dumper=Dumper,
+    default_style=None,
+    default_flow_style=None,
+    encoding='utf-8',
+    explicit_start=None,
+    explicit_end=None,
+    version=None,
+    tags=None,
+    canonical=None,
+    indent=None,
+    width=None,
+    allow_unicode=None,
+    line_break=None)
+dump_all(data, stream=None, Dumper=Dumper, ...)
+safe_dump(data, stream=None, ...)
+safe_dump_all(data, stream=None, ...)
+{{{
+#!python
 Dumper.represent(data)
-def representer(dumper, data):
-    # ...
-    return node
-def multi_representer(dumper, data):
-    # ...
-    return node
-add_representer(data_type, representer, Dumper=Dumper)
-add_multi_representer(base_data_type, multi_representer, Dumper=Dumper)
 Dumper.add_representer(data_type, representer) # Dumper.add_representer is a class method.
 …
 }}}
-'''`dump(data, stream=None)`''' serializes the given Python object into the `stream`.
-If `stream` is `None`, it returns the produced stream.
-'''`dump_all(data, stream=None)`''' serializes the given sequence of Python objects
-into the given `stream`. If `stream` is `None`, it returns the produced stream.
-Each object is represented as a YAML document.
-'''`safe_dump(data, stream=None)`''' serializes the given Python object into the `stream`.
-If `stream` is `None`, it returns the produced stream. `safe_dump` produces only standard YAML
-tags and cannot represent an arbitrary Python object.
-'''`safe_dump_all(data, stream=None)`''' serializes the given sequence of Python objects
-into the given `stream`. If `stream` is `None`, it returns the produced stream.
-Each object is represented as a YAML document.  `safe_dump_all` produces only standard YAML
-tags and cannot represent an arbitrary Python object.
 '''`Dumper.represent(data)`''' serializes the given Python object to the output YAML stream.
+'''`add_representer(data_type, representer)`''' and '''`Dumper.add_representer(data_type, representer)`'''
+allow to specify a `representer` for Python objects of the given `data_type`. A representer is a function
+that converts a native Python object to a node of a YAML representation graph. A representer accepts
+an instance of `Dumper` and an object and returns a node.
+'''`add_multi_representer(base_data_type, multi_representer)`''' and '''`Dumper.add_multi_representer(base_data_type, multi_representer)`'''
+allow to specify a `multi_representer` for Python objects of the given `base_data_type` or any of its subclasses.
+A multi-representer is a function that converts a native Python object to a node of a YAML representation graph.
+A multi-representer accepts an instance of `Dumper` and an object and returns a node.
+'''`Dumper.add_representer(data_type, representer)`''': see `add_representer`.
+'''`Dumper.add_multi_representer(base_data_type, multi_representer)`''': see `add_multi_representer`.
 '''`Dumper.represent_scalar(tag, value, style=None)`''' returns a scalar node with the given `tag`, `value`, and `style`.
 …
 and subnodes generated from the keys and values of the given `mapping`.
+==== Resolver interface ====
+The ''Resolver'' interfaces of '''`Loader`''' and '''`Dumper`''' are identical. Check the corresponding section
+of the '''`Loader`''' reference.
+{{{
+#!python
+Dumper.add_implicit_resolver(tag, regexp, first) # Dumper.add_implicit_resolver is a class method.
+Dumper.add_path_resolver(tag, path, kind) # Dumper.add_path_resolver is a class method.
+}}}
+'''`Dumper.add_implicit_resolver(tag, regexp, first)`''': see `add_implicit_resolver`.
+'''`Dumper.add_path_resolver(tag, path, kind)`''': see `add_path_resolver`.
 === YAMLObject ===
-=== The yaml package ===