Changes between Version 19 and Version 20 of PyYAMLDocumentation


Ignore:
Timestamp:
05/07/06 05:08:48 (9 years ago)
Author:
xi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PyYAMLDocumentation

    v19 v20  
    660660'''Warning: API stability is not guaranteed!''' 
    661661 
     662=== The yaml package === 
     663 
     664{{{ 
     665#!python 
     666scan(stream, Loader=Loader) 
     667}}} 
     668 
     669'''`scan(stream)`''' scans the given `stream` and produces a sequence of tokens. 
     670 
     671{{{ 
     672#!python 
     673parse(stream, Loader=Loader) 
     674 
     675emit(events, stream=None, Dumper=Dumper, 
     676    canonical=None, 
     677    indent=None, 
     678    width=None, 
     679    allow_unicode=None, 
     680    line_break=None) 
     681}}} 
     682 
     683'''`parse(stream)`''' parses the given `stream` and produces a sequence of parsing events. 
     684 
     685'''`emit(events, stream=None)`''' serializes the given sequence of parsing `events` and 
     686write them to the `stream`. if `stream` is `None`, it returns the produced stream. 
     687 
     688{{{ 
     689#!python 
     690compose(stream, Loader=Loader) 
     691compose_all(stream, Loader=Loader) 
     692 
     693serialize(node, stream=None, Dumper=Dumper, 
     694    encoding='utf-8', 
     695    explicit_start=None, 
     696    explicit_end=None, 
     697    version=None, 
     698    tags=None, 
     699    canonical=None, 
     700    indent=None, 
     701    width=None, 
     702    allow_unicode=None, 
     703    line_break=None) 
     704serialize_all(nodes, stream=None, Dumper=Dumper, ...) 
     705}}} 
     706 
     707'''`compose(stream)`''' parses the given `stream` and returns the root of the representation graph 
     708for the first document in the stream. If there are no documents in the stream, it returns `None`. 
     709 
     710'''`compose_all(stream)`''' parses the given `stream` and returns a sequence of representation graphs 
     711corresponding to the documents in the stream. 
     712 
     713'''`serialize(node, stream=None)`''' serializes the given representation graph into the `stream`. 
     714If `stream` is `None`, it returns the produced stream. 
     715 
     716'''`serialize_all(node, stream=None)`''' serializes the given sequence of representation graphs 
     717into the given `stream`. If `stream` is `None`, it returns the produced stream. 
     718 
     719{{{ 
     720#!python 
     721load(stream, Loader=Loader) 
     722load_all(stream, Loader=Loader) 
     723 
     724safe_load(stream) 
     725safe_load_all(stream) 
     726 
     727dump(data, stream=None, Dumper=Dumper, 
     728    default_style=None, 
     729    default_flow_style=None, 
     730    encoding='utf-8', 
     731    explicit_start=None, 
     732    explicit_end=None, 
     733    version=None, 
     734    tags=None, 
     735    canonical=None, 
     736    indent=None, 
     737    width=None, 
     738    allow_unicode=None, 
     739    line_break=None) 
     740dump_all(data, stream=None, Dumper=Dumper, ...) 
     741 
     742safe_dump(data, stream=None, ...) 
     743safe_dump_all(data, stream=None, ...) 
     744}}} 
     745 
     746'''`load(stream)`''' parses the given `stream` and returns a Python object constructed from 
     747for the first document in the stream. If there are no documents in the stream, it returns `None`. 
     748 
     749'''`load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects 
     750corresponding to the documents in the stream. 
     751 
     752'''`safe_load(stream)`''' parses the given `stream` and returns a Python object constructed from 
     753for the first document in the stream. If there are no documents in the stream, it returns `None`. 
     754`safe_load` recognizes only standard YAML tags and cannot construct an arbitrary Python object. 
     755 
     756'''`safe_load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects 
     757corresponding to the documents in the stream. `safe_load_all` recognizes only standard YAML tags 
     758and cannot construct an arbitrary Python object. 
     759 
     760'''`dump(data, stream=None)`''' serializes the given Python object into the `stream`. 
     761If `stream` is `None`, it returns the produced stream. 
     762 
     763'''`dump_all(data, stream=None)`''' serializes the given sequence of Python objects 
     764into the given `stream`. If `stream` is `None`, it returns the produced stream. 
     765Each object is represented as a YAML document. 
     766 
     767'''`safe_dump(data, stream=None)`''' serializes the given Python object into the `stream`. 
     768If `stream` is `None`, it returns the produced stream. `safe_dump` produces only standard YAML 
     769tags and cannot represent an arbitrary Python object. 
     770 
     771'''`safe_dump_all(data, stream=None)`''' serializes the given sequence of Python objects 
     772into the given `stream`. If `stream` is `None`, it returns the produced stream. 
     773Each object is represented as a YAML document.  `safe_dump_all` produces only standard YAML 
     774tags and cannot represent an arbitrary Python object. 
     775 
     776{{{ 
     777#!python 
     778def constructor(loader, node): 
     779    # ... 
     780    return data 
     781 
     782def multi_constructor(loader, tag_suffix, node): 
     783    # ... 
     784    return data 
     785 
     786add_constructor(tag, constructor, Loader=Loader) 
     787add_multi_constructor(tag_prefix, multi_constructor, Loader=Loader) 
     788}}} 
     789 
     790'''`add_constructor(tag, constructor)`''' allows to specify a `constructor` for the given `tag`. 
     791A constructor is a function that converts a node of a YAML representation graph to a native Python object. 
     792A constructor accepts an instance of `Loader` and a node and returns a Python object. 
     793 
     794'''`add_multi_constructor(tag_prefix, multi_constructor)`''' allows to specify a `multi_constructor` 
     795for the given `tag_prefix`. A multi-constructor is a function that converts a node of a YAML 
     796representation graph to a native Python object. A multi-constructor accepts an instance of `Loader`, 
     797the suffix of the node tag, and a node and returns a Python object. 
     798 
     799{{{ 
     800#!python 
     801def representer(dumper, data): 
     802    # ... 
     803    return node 
     804 
     805def multi_representer(dumper, data): 
     806    # ... 
     807    return node 
     808 
     809add_representer(data_type, representer, Dumper=Dumper) 
     810add_multi_representer(base_data_type, multi_representer, Dumper=Dumper) 
     811}}} 
     812 
     813'''`add_representer(data_type, representer)`''' allows to specify a `representer` for Python objects 
     814of the given `data_type`. A representer is a function that converts a native Python object to a node 
     815of a YAML representation graph. A representer accepts an instance of `Dumper` and an object and returns a node. 
     816 
     817'''`add_multi_representer(base_data_type, multi_representer)`''' allows to specify a `multi_representer` 
     818for Python objects of the given `base_data_type` or any of its subclasses. A multi-representer is 
     819a function that converts a native Python object to a node of a YAML representation graph. 
     820A multi-representer accepts an instance of `Dumper` and an object and returns a node. 
     821 
     822{{{ 
     823#!python 
     824add_implicit_resolver(tag, regexp, first, Loader=Loader, Dumper=Dumper) 
     825add_path_resolver(tag, path, kind, Loader=Loader, Dumper=Dumper) 
     826}}} 
     827 
     828'''`add_implicit_resolver(tag, regexp, first)`''' adds an implicit tag resolver for plain scalars. 
     829If the scalar value is matched the given `regexp`, it is assigned the `tag`. `first` is a 
     830list of possible initial characters or `None`. 
     831 
     832'''`add_path_resolver(tag, path, kind)`''' adds a path-based implicit tag resolver. 
     833A `path` is a list of keys that form a path to a node in the representation graph. 
     834Paths elements can be string values, integers, or `None`. The `kind` of a node can 
     835be `str`, `list`, `dict`, or `None`. 
    662836 
    663837=== YAMLError === 
     
    764938BlockMappingStartToken() 
    765939 
     940 
    766941KeyToken() 
    767942ScalarToken(plain=True, style=None, value=u'KeyToken') 
     
    9611136}}} 
    9621137 
    963 '''`BaseLoader`''', '''`SafeLoader`''', and '''`Loader`''' provide the following interfaces: 
    964 ''Scanner'', ''Parser'', ''Composer'', ''Constructor'', ''Resolver''. 
    965   
    9661138'''`Loader(stream)`''' is the most common of the above classes and should be used in most cases. 
    9671139`stream` is an input YAML stream. It can be a string, a Unicode string, an open file, an open Unicode file. 
     
    9781150lists, dictionaries and Unicode strings. 
    9791151 
    980  
    981 ==== Scanner interface ==== 
    982  
    983 {{{ 
    984 #!python 
    985 scan(stream, Loader=Loader) 
    986  
     1152{{{ 
     1153#!python 
    9871154Loader.check_token(*TokenClasses) 
    9881155Loader.peek_token() 
     
    9901157}}} 
    9911158 
    992 '''`scan(stream)`''' scans the given `stream` and produces a sequence of tokens. 
    993  
    9941159'''`Loader.check_token(*TokenClasses)`''' returns `True` if the next token in the stream 
    9951160is an instance of one of the given `TokenClasses`. Otherwise it returns `False`. 
     
    10011166it from the internal token queue. The function returns `None` at the end of the stream. 
    10021167 
    1003  
    1004 ==== Parser interface ==== 
    1005  
    1006 {{{ 
    1007 #!python 
    1008 parse(stream, Loader=Loader) 
    1009  
     1168{{{ 
     1169#!python 
    10101170Loader.check_event(*EventClasses) 
    10111171Loader.peek_event() 
     
    10131173}}} 
    10141174 
    1015 '''`parse(stream)`''' parses the given `stream` and produces a sequence of parsing events. 
    1016  
    10171175'''`Loader.check_event(*EventClasses)`''' returns `True` if the next event in the stream 
    10181176is an instance of one of the given `EventClasses`. Otherwise it returns `False`. 
     
    10241182it from the internal event queue. The function returns `None` at the end of the stream. 
    10251183 
    1026  
    1027 ==== Composer interface ==== 
    1028  
    1029 {{{ 
    1030 #!python 
    1031 compose(stream, Loader=Loader) 
    1032 compose_all(stream, Loader=Loader) 
    1033  
     1184{{{ 
     1185#!python 
    10341186Loader.check_node() 
    10351187Loader.get_node() 
    10361188}}} 
    10371189 
    1038 '''`compose(stream)`''' parses the given `stream` and returns the root of the representation graph 
    1039 for the first document in the stream. If there are no documents in the stream, it returns `None`. 
    1040  
    1041 '''`compose_all(stream)`''' parses the given `stream` and returns a sequence of representation graphs 
    1042 corresponding to the documents in the stream. 
    1043  
    10441190'''`Loader.check_node()`''' returns `True` is there are more documents available in the stream. Otherwise 
    10451191it returns `False`. 
     
    10481194returns its root node. 
    10491195 
    1050  
    1051 ==== Constructor interface ==== 
    1052  
    1053 {{{ 
    1054 #!python 
    1055 load(stream, Loader=Loader) 
    1056 load_all(stream, Loader=Loader) 
    1057  
    1058 safe_load(stream) 
    1059 safe_load_all(stream) 
    1060  
     1196{{{ 
     1197#!python 
    10611198Loader.check_data() 
    10621199Loader.get_data() 
    1063  
    1064 def constructor(loader, node): 
    1065     # ... 
    1066     return data 
    1067  
    1068 def multi_constructor(loader, tag_suffix, node): 
    1069     # ... 
    1070     return data 
    1071  
    1072 add_constructor(tag, constructor, Loader=Loader) 
    1073 add_multi_constructor(tag_prefix, multi_constructor, Loader=Loader) 
    10741200 
    10751201Loader.add_constructor(tag, constructor) # Loader.add_constructor is a class method. 
     
    10811207}}} 
    10821208 
    1083 '''`load(stream)`''' parses the given `stream` and returns a Python object constructed from 
    1084 for the first document in the stream. If there are no documents in the stream, it returns `None`. 
    1085  
    1086 '''`load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects 
    1087 corresponding to the documents in the stream. 
    1088  
    1089 '''`safe_load(stream)`''' parses the given `stream` and returns a Python object constructed from 
    1090 for the first document in the stream. If there are no documents in the stream, it returns `None`. 
    1091 `safe_load` recognizes only standard YAML tags and cannot construct an arbitrary Python object. 
    1092  
    1093 '''`safe_load_all(stream)`''' parses the given `stream` and returns a sequence of Python objects 
    1094 corresponding to the documents in the stream. `safe_load_all` recognizes only standard YAML tags 
    1095 and cannot construct an arbitrary Python object. 
    1096  
    10971209'''`Loader.check_data()`''' returns `True` is there are more documents available in the stream. Otherwise 
    10981210it returns `False`. 
     
    11011213in the stream. 
    11021214 
    1103 '''`add_constructor(tag, constructor)`''' and '''`Loader.add_constructor(tag, constructor)`''' allow 
    1104 to specify a `constructor` for the given `tag`. A constructor is a function that converts a node 
    1105 of a YAML representation graph to a native Python object. A constructor accepts an instance of `Loader` 
    1106 and a node and returns a Python object. 
    1107  
    1108 '''`add_multi_constructor(tag_prefix, multi_constructor)`''' and '''`Loader.add_multi_constructor(tag_prefix, multi_constructor)`''' 
    1109 allow to specify a `multi_constructor` for the given `tag_prefix`. A multi-constructor is a function that converts a node 
    1110 of a YAML representation graph to a native Python object. A multi-constructor accepts an instance of `Loader`, 
    1111 the suffix of the node tag, and a node and returns a Python object. 
     1215'''`Loader.add_constructor(tag, constructor)`''': see `add_constructor`. 
     1216 
     1217'''`Loader.add_multi_constructor(tag_prefix, multi_constructor)`''': see `add_multi_constructor`. 
    11121218 
    11131219'''`Loader.construct_scalar(node)`''' checks that the given `node` is a scalar and returns its value. 
     
    11201226of Python objects corresponding to the node keys and values. This function is intended to be used in constructors. 
    11211227 
    1122  
    1123 ==== Resolver interface ==== 
    1124  
    1125 The ''Resolver'' interfaces of '''`Loader`''' and '''`Dumper`''' are identical. 
    1126  
    1127 {{{ 
    1128 #!python 
    1129 add_implicit_resolver(tag, regexp, first, Loader=Loader, Dumper=Dumper) 
    1130 add_path_resolver(tag, path, kind, Loader=Loader, Dumper=Dumper) 
    1131  
     1228{{{ 
     1229#!python 
    11321230Loader.add_implicit_resolver(tag, regexp, first) # Loader.add_implicit_resolver is a class method. 
    11331231Loader.add_path_resolver(tag, path, kind) # Loader.add_path_resolver is a class method. 
    1134  
    1135 Dumper.add_implicit_resolver(tag, regexp, first) # Dumper.add_implicit_resolver is a class method. 
    1136 Dumper.add_path_resolver(tag, path, kind) # Dumper.add_path_resolver is a class method. 
    1137 }}} 
    1138  
    1139 '''`add_implicit_resolver(tag, regexp, first)`''' adds an implicit tag resolver for plain scalars. 
    1140 If the scalar value is matched the given `regexp`, it is assigned the `tag`. `first` is a 
    1141 list of possible initial characters or `None`. 
    1142  
    1143 '''`add_path_resolver(tag, path, kind)`''' adds a path-based implicit tag resolver. 
    1144 A `path` is a list of keys that form a path to a node in the representation graph. 
    1145 Paths elements can be string values, integers, or `None`. The `kind` of a node can 
    1146 be `str`, `list`, `dict`, or `None`. 
     1232}}} 
     1233 
     1234'''`Loader.add_implicit_resolver(tag, regexp, first)`''': see `add_implicit_resolver`. 
     1235 
     1236'''`Loader.add_path_resolver(tag, path, kind)`''': see `add_path_resolver`. 
    11471237 
    11481238 
     
    11681258}}} 
    11691259 
    1170 '''`BaseDumper`''', '''`SafeDumper`''', and '''`Dumper`''' provide the following interfaces: 
    1171 ''Emitter'', ''Serializer'', ''Representer'', ''Resolver''. 
    1172   
    11731260'''`Dumper(stream)`''' is the most common of the above classes and should be used in most cases. 
    11741261`stream` is an output YAML stream. It can be an open file or an open Unicode file. 
     
    11841271'''`BaseDumper(stream)`''' does not support any tags and is useful only for subclassing. 
    11851272 
    1186  
    1187 ==== Emitter interface ==== 
    1188  
    1189 {{{ 
    1190 #!python 
    1191 emit(events, stream=None, Dumper=Dumper, 
    1192     canonical=None, 
    1193     indent=None, 
    1194     width=None, 
    1195     allow_unicode=None, 
    1196     line_break=None) 
    1197  
    1198 Emitter.emit(event) 
    1199 }}} 
    1200  
    1201 '''`emit(events, stream=None)`''' serializes the given sequence of parsing `events` and 
    1202 write them to the `stream`. if `stream` is `None`, it returns the produced stream. 
    1203  
    1204 '''`Emitter.emit(event)`''' serializes the given `event` and write it to the output stream. 
    1205  
    1206  
    1207 ==== Serializer interface ==== 
    1208  
    1209 {{{ 
    1210 #!python 
    1211 serialize(node, stream=None, Dumper=Dumper, 
    1212     encoding='utf-8', 
    1213     explicit_start=None, 
    1214     explicit_end=None, 
    1215     version=None, 
    1216     tags=None, 
    1217     canonical=None, 
    1218     indent=None, 
    1219     width=None, 
    1220     allow_unicode=None, 
    1221     line_break=None) 
    1222 serialize_all(nodes, stream=None, Dumper=Dumper, ...) 
    1223  
     1273{{{ 
     1274#!python 
     1275Dumper.emit(event) 
     1276}}} 
     1277 
     1278'''`Dumper.emit(event)`''' serializes the given `event` and write it to the output stream. 
     1279 
     1280{{{ 
     1281#!python 
    12241282Dumper.open() 
    12251283Dumper.serialize(node) 
     
    12271285}}} 
    12281286 
    1229 '''`serialize(node, stream=None)`''' serializes the given representation graph into the `stream`. 
    1230 If `stream` is `None`, it returns the produced stream. 
    1231  
    12321287'''`Dumper.open()`''' emits `StreamStartEvent`. 
    12331288 
     
    12361291'''`Dumper.close()`''' emits `StreamEndEvent`. 
    12371292 
    1238  
    1239 ==== Representer interface ==== 
    1240  
    1241 {{{ 
    1242 #!python 
    1243 dump(data, stream=None, Dumper=Dumper, 
    1244     default_style=None, 
    1245     default_flow_style=None, 
    1246     encoding='utf-8', 
    1247     explicit_start=None, 
    1248     explicit_end=None, 
    1249     version=None, 
    1250     tags=None, 
    1251     canonical=None, 
    1252     indent=None, 
    1253     width=None, 
    1254     allow_unicode=None, 
    1255     line_break=None) 
    1256 dump_all(data, stream=None, Dumper=Dumper, ...) 
    1257  
    1258 safe_dump(data, stream=None, ...) 
    1259 safe_dump_all(data, stream=None, ...) 
    1260  
     1293{{{ 
     1294#!python 
    12611295Dumper.represent(data) 
    1262  
    1263 def representer(dumper, data): 
    1264     # ... 
    1265     return node 
    1266  
    1267 def multi_representer(dumper, data): 
    1268     # ... 
    1269     return node 
    1270  
    1271 add_representer(data_type, representer, Dumper=Dumper) 
    1272 add_multi_representer(base_data_type, multi_representer, Dumper=Dumper) 
    12731296 
    12741297Dumper.add_representer(data_type, representer) # Dumper.add_representer is a class method. 
     
    12801303}}} 
    12811304 
    1282 '''`dump(data, stream=None)`''' serializes the given Python object into the `stream`. 
    1283 If `stream` is `None`, it returns the produced stream. 
    1284  
    1285 '''`dump_all(data, stream=None)`''' serializes the given sequence of Python objects 
    1286 into the given `stream`. If `stream` is `None`, it returns the produced stream. 
    1287 Each object is represented as a YAML document. 
    1288  
    1289 '''`safe_dump(data, stream=None)`''' serializes the given Python object into the `stream`. 
    1290 If `stream` is `None`, it returns the produced stream. `safe_dump` produces only standard YAML 
    1291 tags and cannot represent an arbitrary Python object. 
    1292  
    1293 '''`safe_dump_all(data, stream=None)`''' serializes the given sequence of Python objects 
    1294 into the given `stream`. If `stream` is `None`, it returns the produced stream. 
    1295 Each object is represented as a YAML document.  `safe_dump_all` produces only standard YAML 
    1296 tags and cannot represent an arbitrary Python object. 
    1297  
    12981305'''`Dumper.represent(data)`''' serializes the given Python object to the output YAML stream. 
    12991306 
    1300 '''`add_representer(data_type, representer)`''' and '''`Dumper.add_representer(data_type, representer)`''' 
    1301 allow to specify a `representer` for Python objects of the given `data_type`. A representer is a function 
    1302 that converts a native Python object to a node of a YAML representation graph. A representer accepts 
    1303 an instance of `Dumper` and an object and returns a node. 
    1304  
    1305 '''`add_multi_representer(base_data_type, multi_representer)`''' and '''`Dumper.add_multi_representer(base_data_type, multi_representer)`''' 
    1306 allow to specify a `multi_representer` for Python objects of the given `base_data_type` or any of its subclasses. 
    1307 A multi-representer is a function that converts a native Python object to a node of a YAML representation graph. 
    1308 A multi-representer accepts an instance of `Dumper` and an object and returns a node. 
     1307'''`Dumper.add_representer(data_type, representer)`''': see `add_representer`. 
     1308 
     1309'''`Dumper.add_multi_representer(base_data_type, multi_representer)`''': see `add_multi_representer`. 
    13091310 
    13101311'''`Dumper.represent_scalar(tag, value, style=None)`''' returns a scalar node with the given `tag`, `value`, and `style`. 
     
    13171318and subnodes generated from the keys and values of the given `mapping`. 
    13181319 
    1319  
    1320 ==== Resolver interface ==== 
    1321  
    1322 The ''Resolver'' interfaces of '''`Loader`''' and '''`Dumper`''' are identical. Check the corresponding section 
    1323 of the '''`Loader`''' reference. 
     1320{{{ 
     1321#!python 
     1322Dumper.add_implicit_resolver(tag, regexp, first) # Dumper.add_implicit_resolver is a class method. 
     1323Dumper.add_path_resolver(tag, path, kind) # Dumper.add_path_resolver is a class method. 
     1324}}} 
     1325 
     1326'''`Dumper.add_implicit_resolver(tag, regexp, first)`''': see `add_implicit_resolver`. 
     1327 
     1328'''`Dumper.add_path_resolver(tag, path, kind)`''': see `add_path_resolver`. 
    13241329 
    13251330 
    13261331=== YAMLObject === 
    13271332 
    1328  
    1329 === The yaml package === 
    13301333 
    13311334