source: trunk/README.txt @ 30

Revision 30, 24.8 KB checked in by xi, 9 years ago (diff)

Final touches before the release.

RevLine 
[26]1
2============================================================
3PySyck: Python bindings for the Syck YAML parser and emitter
4============================================================
5
6:Author: Kirill Simonov
7:Contact: xi@resolvent.net
8:Web site: http://xitology.org/pysyck/
9
10.. contents::
11
[29]12
[26]13Overview
14========
15
16YAML_ is a data serialization format designed for human readability and
17interaction with scripting languages.
18
19Syck_ is an extension for reading and writing YAML in scripting languages. Syck
20provides bindings to the Python_ programming language, but they are somewhat
21limited and leak memory.
22
23PySyck_ is aimed to update the current Python bindings for Syck. The new
[30]24bindings provide a wrapper for the Syck emitter and give access to YAML
25representation graphs. Hopefully it will not leak memory as well.
[26]26
[29]27PySyck_ may be used for various tasks, in particular, as a replacement of the
28module pickle_. Please be aware that PySyck_ is a beta-quality software and
29is not ready yet for production use.
30
[26]31.. _YAML: http://yaml.org/
32.. _Syck: http://whytheluckystiff.net/syck/
33.. _Python: http://python.org/
34.. _PySyck: http://xitology.org/pysyck/
[29]35.. _pickle: http://docs.python.org/lib/module-pickle.html
[26]36
37Requirements
38============
39
40PySyck requires Syck 0.55 or higher and Python 2.3 or higher. Python 2.2 is
41supported to some extent.
42
[29]43
[26]44Installation
45============
46
[30]47Please note that Syck 0.55 or higher must be installed. If you install PySyck
48from source, unpack the source tarball and type::
[26]49
[29]50  $ python setup.py install
[26]51
52Windows binaries for Python 2.2, 2.3, and 2.4 are provided.
53
[29]54
[26]55Usage
56=====
57
[30]58The documentation is still rough and incomplete. See `the source code`_ for
59more information.
[26]60
[29]61.. _the source code: http://trac.xitology.org/pysyck/browser/
62
63Quick Example
64-------------
65
66::
67
68  >>> from syck import *
69  >>> print load("""
70  ... - foo
71  ... - bar
72  ... - baz
73  ... """)
74  ['foo', 'bar', 'baz']
75  >>> print dump(['foo', 'bar', 'baz'])
76  ---
77  - foo
78  - bar
79  - baz
80
81YAML syntax
82-----------
83
84We do not describe the YAML syntax here. Please check http://yaml.org/ for the
85reference.
86
87In addition to the tags defined in `the YAML types repository`_, PySyck understands
88the following Python-specific tags:
89
90* ``tag:python.yaml.org,2002:none``,
91* ``tag:python.yaml.org,2002:bool``,
92* ``tag:python.yaml.org,2002:int``,
93* ``tag:python.yaml.org,2002:float``,
94* ``tag:python.yaml.org,2002:str``,
95* ``tag:python.yaml.org,2002:unicode``,
96* ``tag:python.yaml.org,2002:list``,
97* ``tag:python.yaml.org,2002:tuple``,
98* ``tag:python.yaml.org,2002:dict``,
99* ``tag:python.yaml.org,2002:name:...``,
100* ``tag:python.yaml.org,2002:object:...``,
101* ``tag:python.yaml.org,2002:new:...``,
102* ``tag:python.yaml.org,2002:apply:...``.
103
104Most of these tags are self-explanatory. The tags ``!python/name:...``,
105``!python/object:...``, ``!python/new:...``, and ``!python/apply:...`` are used
106for constructing Python functions, classes, and objects. See the sections `Use
[30]107Python-specific tags in YAML documents`_ and `Use Python-specific tags to
[29]108construct Python objects`_ for some examples.
109
110.. _the YAML types repository: http://yaml.org/type/index.html
111
112Common Tasks
113------------
114
115Import the module
116~~~~~~~~~~~~~~~~~
117
118::
119
120  >>> from syck import *
121
122or
123
124::
125
126  >>> import syck
127
128Load a document from a string
129~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130
131::
132
133  >>> source = "..."
134  >>> object = load(source)
135
136Load a document from a file
137~~~~~~~~~~~~~~~~~~~~~~~~~~~
138
139::
140
141  >>> source = file(..., 'r')
142  >>> object = load(source)
143
144Convert a Python object to a YAML document
145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146
147::
148
149  >>> object = ...
150  >>> document = dump(object)
151
152Dump a Python object to a YAML stream
153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154
155::
156
157  >>> object = ...
158  >>> output = file(..., 'w')
159  >>> dump(object, output)
160
161Format the output YAML stream
162~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163
164::
165
166  >>> object = ...
167  >>> output = file(..., 'w')
168  >>> dump(object, output,
169  ...     headless=False, use_header=False, use_version=False,
170  ...     explicit_typing=True, style=None, best_width=80, indent=2)
171
172Load several documents from a YAML stream
173~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
174
175::
176
177  >>> source = ...
178  >>> objects = load_documents(source)
179  >>> for object in objects:
180  ...     # ...
181
182Create several documents in a YAML stream
183~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
184
185::
186
187  >>> objects = [...]
188  >>> output = file(..., 'w')
189  >>> dump_documents(objects, output)
190
[30]191Construct a representation tree of a YAML document
192~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[29]193
194::
195
196  >>> source = ...
197  >>> root_node = parse(source)
198
199Convert a representation tree to a YAML document
200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
202::
203
204  >>> scalar_node = Scalar('...', tag='tag:...',
205  ...     style='...', indent=.., width=..)
206  >>> sequence_node = Seq(list_of_nodes, tag='tag:...', inline=..)
207  >>> mapping_node = Map(dictionary_of_nodes, tag='tag:...', inline=..)
208  >>> root_node = ...
209  >>> output = file(..., 'w')
210  >>> emit(root_node, output)
211
212Use PySyck as a pickle replacement
213~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
214
215::
216
217  >>> object = ...
218  >>> stream = ...
219  >>> dump(object, stream)
220 
221  >>> stream = ...
222  >>> object = load(stream)
223
224Use PySyck to display the structure of a complex object
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227::
228
229  >>> object = ...
230  >>> print dump(object)
231
232Use PySyck to display a YAML representation graph
233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234
235::
236
237  >>> source = ...
238  >>> node = parse(source)
239  >>> print dump(node)
240
[30]241Use Python-specific tags in YAML documents
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[29]243
244::
245
246  --- %YAML:1.0
247  - !python/none ''       # You may also use '!null'.
248  - !python/bool 'False'  # You may also use '!bool'.
249  - !python/int '123'     # You may also use '!int'.
250  - !python/long '1234567890'
251  - !python/float '123.456789'  # Also '!float'.
252  - !python/str 'a string'      # Also '!str'.
253  - !python/unicode 'a unicode string encoded in utf-8'
254  - !python/list [1, 2, 3]      # The same as '!seq' or no tag.
255  - !python/tuple [1, 2, 3]
256  - !python/dict { 1: foo, 2: bar } # The same as '!map' or no tag.
257
258Use Python-specific tags to construct functions or classes
259~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260
261::
262
263  --- %YAML:1.0
264  - !python/name:package.module.function_name ''
265  - !python/name:package.module.class_name ''
266
267Use Python-specific tags to construct Python objects
268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
269
270::
271
272  --- %YAML:1.0
273  - !python/object:package.module.type
274    attribute1: value1
275    attribute2: value2
276    # ...
277  - !python/new:package.module.type
278    - parameter1
279    - parameter2
280    # ...
281  - !python/new:package.module.type
282    args: [parameter1, parameter2, ...]
283    kwds: {kwd1: val1, kwd2: val2, ...}
284    state: {attr1: val1, attr2: val2, ...}
285    # ...
286  - !python/apply:package.module.function
287    - parameter1
288    - parameter2
289    # ...
290  - !python/apply:package.module.function
291    args: [parameter1, parameter2, ...]
292    kwds: {kwd1: val1, kwd2: val2, ...}
293    state: {attr1: val1, attr2: val2, ...}
294    # ...
295
296Use application specific tags
297~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298
299::
300
301  >>> class MyClass:
302  ...   # ...
303
304  >>> class MyLoader(Loader):
305  ...     def construct_private_my_tag(self, node):
306  ...         # ...
307  ...         return MyClass(...)
308
309  >>> class MyDumper(Dumper):
310  ...     def represent_MyDumper(self, object):
311  ...         # ...
312  ...         return Map(...)
313
314  >>> source = """--- !!my_tag { ... }"""
315  >>> my_instance = load(source, Loader=MyLoader)
316
317  >>> my_instance = MyClass(...)
318  >>> output = dump(my_instance, Dumper=MyDumper)
319
320Reference
321---------
322
323Functions
324~~~~~~~~~
325
326``load`` : function
327  ``load(source, Loader=Loader, **parameters)``
328
329  The function ``load()`` returns a Python object corresponding to the first
330  document in the source. If the source is empty, ``load()`` returns ``None``.
331  ``source`` must be a string or a file-like object that has the method
332  ``read(max_length)``.
333
334  By default, the function ``load()`` uses an instance of the class ``Loader``
335  for parsing. You may use another class or pass additional parameters to the
336  class constructor. See the section Parser_ for more details.
337
338  Example::
339
340    >>> load("""
341    ... - foo
342    ... - bar
343    ... - baz
344    ... """)
345    ['foo', 'bar', 'baz']
346
347``parse`` : function
348  ``parse(source, Loader=Loader, **parameters)``
349
350  The function ``parse()`` parses the source and returns a representation tree
351  of the first document. ``source`` must be a string or a file-like object
352  that has the method ``read(max_length)``.
353
354  By default, the function ``parse()`` uses an instance of the class ``Loader``
355  for parsing. You may use another class or pass additional parameters to the
356  class constructor. See the section Parser_ for more details.
357
358  Example::
359
360    >>> parse("""
361    ... - foo
362    ... - bar
363    ... - baz
364    ... """)
365    <_syck.Seq object at 0xb7a3f2fc>
366
367``load_documents`` : function
368  ``load_documents(source, Loader=Loader, **parameters)``
369
370  The function ``load_documents()`` parses the source and an iterator.  The
371  iterator produces Python objects corresponding the documents of the source
372  stream. ``source`` must be a string or a file-like object that has the method
373  ``read(max_length)``.
374
375  By default, the function ``load_documents()`` uses an instance of the class
376  ``Loader`` for parsing. You may use another class or pass additional
377  parameters to the class constructor. See the section Parser_ for more
378  details.
379
380  Example::
381
382    >>> source = """
383    ... --- >
384    ... This is the
385    ... first document.
386    ... --- >
387    ... This is the
388    ... next document.
389    ... --- >
390    ... This is the
391    ... last document.
392    ... """
393    >>> for object in load_documents(source): print object
394    ...
395    This is the first document.
396
397    This is the next document.
398
399    This is the last document.
400
401``parse_documents`` : function
402  ``parse_documents(source, Loader=Loader, **parameters)``
403
404  The function ``parse_documents()`` is similar to ``load_documents()``, but
405  produces representation graphs for all documents in the source.
406 
407``dump`` : function
408  ``dump(object, output=None, Dumper=Dumper, **parameters)``
409
410  The function ``dump()`` converts ``object`` to a representation graph
411  and write it to ``output``. ``output`` must be ``None`` or a file-like
412  object that has the method ``write(data)``. If ``output`` is ``None``,
413  ``dump()`` returns the generated document.
414
415  By default, the function ``dump()`` uses an instance of the class ``Dumper``
416  for emitting. You may use another class or pass additional parameters to the
417  class constructor. See the section Emitter_ for more details.
418
419  Example::
420
421    >>> object = ['foo', 'bar', ['baz']]
422    >>> dump(object, sys.stdout)
423    ---
424    - foo
425    - bar
426    - - baz
427    >>> print dump(object)
428    ---
429    - foo
430    - bar
431    - - baz
432
433    >>> print dump(object, use_version=True, indent=5)
434    --- %YAML:1.0
435    - foo
436    - bar
437    -    - baz
438
439``emit`` : function
440  ``emit(node, output=None, Dumper=Dumper, **parameters)``
441
442  The function ``emit()`` write the representation graph to the output stream.
443  ``output`` must be ``None`` or a file-like object that has the method
444  ``write(data)``. If ``output`` is ``None``, ``emit()`` returns the generated
445  document.
446
447  By default, the function ``emit()`` uses an instance of the class ``Dumper``
448  for emitting. You may use another class or pass additional parameters to the
449  class constructor. See the section Emitter_ for more details.
450
451  Example::
452
453    >>> foo = Scalar('a string')
454    >>> bar = Scalar('a unicode string', tag="tag:python.yaml.org,2002:unicode")
455    >>> baz = Scalar('12345', tag="tag:yaml.org,2002:int")
456    >>> seq = Seq([foo, bar, baz], tag="tag:python.taml.org,2002:tuple")
457    >>> print emit(seq, use_version=True)
458    --- %YAML:1.0 !python.taml.org,2002/tuple
459    - a string
460    - !python/unicode a unicode string
461    - 12345
462
463``dump_documents`` : function
464  ``dump_documents(objects, output=None, Dumper=Dumper, **parameters)``
465
466  The function ``dump_documents()`` takes a list of objects and converts
467  each object to a YAML document. If ``output`` is ``None``, it returns
468  the produced documents. Otherwise it writes down them to ``output``,
469  which must be a file-like object with the method ``write(data)``.
470
471  By default, the function ``dump_documents()`` uses an instance of the class
472  ``Dumper`` for emitting. You may use another class or pass additional
473  parameters to the class constructor. See the section Emitter_ for more
474  details.
475
476  Example::
477
478    >>> print dump_documents(['foo', 'bar', 'baz'])
479    --- foo
480    --- bar
481    --- baz
482
483``emit_documents`` : function
484  ``emit_documents(nodes, output=None, Dumper=Dumper, **parameters)``
485
486  The function ``emit_documents()`` is similar to ``dump_documents()``, but
487  it requires a list of representation graphs.
488
489Exceptions
490~~~~~~~~~~
491
492``error`` : exception
493  This exception is raised by the Syck parser when it detects a syntax error.
494
495  The attribute ``args`` of the exception is a triple: *message*, *row*,
496  *column*.
497
498  Example::
499
500    >>> load("""---
501    ... - foo
502    ... - '''
503    ... - bar
504    ... """)
505    Traceback (most recent call last):
506      File "<stdin>", line 1, in ?
507      File "build/lib.linux-i686-2.3/syck/loaders.py", line 384, in load
508      File "build/lib.linux-i686-2.3/syck/loaders.py", line 42, in load
509    _syck.error: ('syntax error', 4, 2)
510
511Nodes
512~~~~~
513
514The following four classes represents nodes in the YAML representation graph:
515
516``Node`` : class
517  ``Node`` is an abstract class; you cannot create an instance of the class
518  ``Node``. ``Node`` is the base class of ``Scalar``, ``Seq``, and ``Map``.
519
520``Scalar`` : subclass of ``Node``
521  ``Scalar`` represents a scalar node. Its value is a string.
522
523``Seq`` : subclass of ``Node``
524  ``Seq`` represents a sequence node. Its value is a list of nodes.
525
526``Map`` : subclass of ``Node``
527  ``Map`` represents a mapping node. Its value is a list of pairs or a
528  dictionary.
529
530All instances of ``Scalar``, ``Seq``, and ``Map`` have the following
531attributes:
532
533``kind`` : string
534  ``'scalar'``, ``'seq'``, or ``'map'``; read-only.
535
536``anchor`` : string or ``None``
537  The node anchor.
538
539``tag`` : string or ``None``
540  The node tag.
541
542``value``
543  The node value. For scalar nodes, it should be a string. For sequence nodes,
544  it should be a list. For mapping nodes, it should be a list of pairs or a
545  dictionary.
546
547``Scalar`` instances have additional attributes:
548
549``style`` : string or ``None``
550  The node style. Possible values are ``None`` (means literal or plain),
551  ``'1quote'``, ``'2quote'``, ``'fold'``, ``'literal'``, ``'plain'``.
552
553``indent`` : integer
554  The node indentation. ``0`` means the default value.
555
556``width`` : integer
557  The width of the node field. Longer scalars will be broken on several lines
558  to fit the field. ``0`` means the default value.
559
560``chomp`` : string or ``None``
561  The chomping method. Possible values are ``None`` (clip), ``'-'`` (strip),
562  ``'+'`` (keep).
563
564``Seq`` and ``Map`` instances have an additional attribute:
565
566``inline`` : boolean
567  The block/flow flag.
568
569For example, let us create a representation graph and transform it into a YAML
570stream::
571
572  >>> # Create three scalar nodes:
573  >>> foo = Scalar('foo', tag="tag:example.com,2005:foo", style='fold',
574  ...     indent=5)
575  >>> bar = Scalar('bar', style='1quote')
576  >>> baz = Scalar('baz')
577
578  >>> # Create a sequence node:
579  >>> seq = Seq([foo, bar, baz], tag="x-private:seq")
580
581  >>> # Emit it into a YAML stream:
582  >>> print emit(seq)
583  --- !!seq
584  - !example.com,2005/foo >-
585       foo
586  - 'bar'
587  - baz
588
589Now let us construct a representation graph from a YAML document::
590
591  >>> # The function 'parse' generates a representation graph:
592  >>> root = parse("""
593  ... - foo
594  ... - bar
595  ... - baz
596  ... """)
597
598  >>> # The object 'root' is a sequence node:
599  >>> root
600  <_syck.Seq object at 0xb7e124b4>
601
602  >>> # We can transform 'root' back into a YAML stream:
603  >>> print emit(root)
604  ---
605  - foo
606  - bar
607  - baz
608
609  >>> # We can also display the structure of the representation tree using a
610  >>> # clever trick:
611  >>> print dump(root)
612  --- !python/object:_syck.Seq
613  value:
614  - !python/object:_syck.Scalar
615    value: foo
616    tag: tag:yaml.org,2002:str
617  - !python/object:_syck.Scalar
618    value: bar
619    tag: tag:yaml.org,2002:str
620  - !python/object:_syck.Scalar
621    value: baz
622    tag: tag:yaml.org,2002:str
623
624Parser
625~~~~~~
626
627``Parser`` : class
628  The class ``Parser`` is a low-level wrapper of a Syck YAML parser. It can
629  generate a representation graph from a YAML stream.
630
631  The class constructor has the following arguments:
632
633  * ``Parser(source, implicit_typing=True, taguri_expansion=True)``.
634
635  The parameter ``source`` is a YAML stream. It must be a string
636  or a file-like object. If it is not a string, it should have a
637  method named ``read(max_length)`` that returns a string.
638
639  It is not recommended to change the default values of the parameters
640  ``implicit_typing`` and ``taguri_expansion``. See the Syck documentation
641  for more details about them.
642
643  The class defines a single method:
644
645  * ``Parser.parse()``.
646
647  It parses the source and returns the root node of the corresponding
648  representation graph. If the stream is finished, it returns ``None`` and
649  set the flag ``eof`` on.
650
651``GenericLoader`` : subclass of ``Parser``
652  The subclass ``GenericLoader`` defines two additional methods:
653
654  * ``GenericLoader.load()``,
655
656  * ``GenericLoader.construct(node)``.
657
658  The method ``load()`` parses the source and constructs the corresponding
659  Python object. To generate an object by a node, ``load()`` uses the
660  ``construct()`` method. The ``construct()`` method defined in
661  ``GenericLoader`` just returns the value of the node: a string, a list,
662  or a dictionary.
663
664``Loader`` : subclass of ``GenericLoader``
665 
666  ``Loader`` redefines the method
667
668  * ``Loader.construct(node)``,
669
670  defines an additional method:
671
672  * ``Loader.find_constructor(node)``,
673
674  and add many other auxiliary methods for constructing Python objects.
675
676  ``Loader.construct()`` calls ``find_constructor()`` for the given node,
677  and uses the returned constructor to generate a Python object.
678
679  ``Loader.find_constructor()`` determines the constructor of a node by
680  the following rules:
681
682  * If the node tag has the form ``tag:yaml.org,2002:type_id``, returns the
683    method ``Loader.construct_type_id``.
684
685  * If the node tag has the form ``tag:python.yaml.org,2002:type_id``, returns
686    the method ``Loader.construct_python_type_id``.
687
688  * If the node tag has the form ``x-private:type_id``, returns
689    ``Loader.construct_private_type_id``.
690
691  * If the node tag has the form ``tag:domain.tld,year:type_id``, returns
692    ``Loader.construct_domain_tld_year_type_id``.
693
694  See the source for more details.
695
696Let us show how ``Parser``, ``GenericLoader``, and ``Loader`` parse the same
697document::
698
699  >>> # The source stream includes PySyck specific tags '!python/tuple'
700  >>> # and '!python/unicode'. It also includes implicitly typed integer
701  >>> # '12345'
702  >>> source = """--- !python/tuple
703  ... - a string
704  ... - !python/unicode a unicode string
705  ... - 12345
706  ... """
707
708  >>> # 'Parser.parse()' returns the root node of the representation tree:
709  >>> p = Parser(source)
710  >>> print p.parse()
711  <_syck.Seq object at 0xb7a33f54>
712
713  >>> # 'GenericLoader.load()' returns a Python object, but ignores the tags:
714  >>> gl = GenericLoader(source)
715  >>> print gl.load()
716  ['a string', 'a unicode string', '12345']
717
718  >>> # 'Loader.load()' is aware of the tags:
719  >>> l = Loader(source)
720  >>> print l.load()
721  ('a string', u'a unicode string', 12345)
722
723Emitter
724~~~~~~~
725
726``Emitter`` : class
727  The class ``Emitter`` is a low-level wrapper of a Syck YAML emitter. It can
728  generate a YAML stream from a representation graph.
729
730  The class constructor has the following signature:
731
732  * ``Emitter(output, headless=False, use_header=False, use_version=False,
733    explicit_typing=True, style=None, best_width=80, indent=2)``.
734
735  The parameter ``output`` must be a file-like object that provides a method
736  ``write(data)``. The other parameters describe the formatting of the output
737  document.
738
739  The class defines a single method:
740
741  * ``emit(node)``.
742
743  The parameter ``node`` must be the root node of a YAML representation graph.
744  The method ``emit()`` writes the generated YAML document to the ``output``
745  stream.
746
747``GenericDumper`` : subclass of ``Emitter``
748  The subclass ``GenericDumper`` adds the following methods:
749
750  * ``GenericDumper.dump(object)``,
751
752  * ``GenericDumper.represent(object)``,
753
754  * ``GenericDumper.allow_aliases(object)``.
755
756  The method ``dump()`` converts the given object into a representation graph,
757  generates a YAML document, and writes it to the ``output`` stream. It uses
758  the method ``represent()`` to convert an object to a representation node.
759  The method ``represent()`` defined in ``GenericDumper`` generates a sequence
760  node for a list object and a mapping node for a dictionary object. Otherwise
761  it generates a scalar node with the value equal to ``str(object)``.
762
763  The Syck YAML emitter automatically detects if the same object is reffered
764  from different parts of the graph and generates aliases for it. Unfortunately
765  it does not work well with immutable Python objects such as strings, numbers,
766  and tuples. To prevent generating unnecessary aliases, the method
767  ``allow_aliases()`` is used. If ``allow_aliases()`` for a given object
768  returns ``False``, the alias will never be generated.
769
770  The ``allow_aliases()`` method defined in ``GenericDumper`` always returns
771  ``True``.
772
773``Dumper`` : subclass of ``GenericDumper``
774  The subclass ``Dumpers`` redefines the methods:
775
776  * ``Dumper.represent(object)``,
777
778  * ``Dumper.allow_aliases(object)``,
779
780  defines the method
781
782  * ``Dumper.find_representer(object)``,
783
784  and add many other auxiliary methods for representing objects as nodes.
785
786  ``Dumper.find_representer()`` finds a method that can represent the given
787  object as a node in a representation tree. ``find_representer()`` checks the
788  class of the object. If the class has the form ``package.module.type``,
789  ``find_representer()`` returns the method
790  ``Dumper.represent_package_module_type`` if it exists. If this method does
791  not exists, ``find_representer()`` consults its base class, and so on.
792
793  ``Dumper.represent()`` calls ``Dumper.find_representer()`` for the given
794  object and uses the returned method to generate a representation node.
795
796  See the source for more details.
797
798Let us show how ``Emitter``, ``GenericDumper``, and ``Dumper`` work::
799
800  >>> # For our demonstration, we define a representation tree named 'seq'
801  >>> # and a Python tuple named 'object':
802  >>> foo = Scalar('a string')
803  >>> bar = Scalar('a unicode string', tag="tag:python.yaml.org,2002:unicode")
804  >>> baz = Scalar('12345', tag="tag:yaml.org,2002:int")
805  >>> seq = Seq([foo, bar, baz], tag="tag:python.taml.org,2002:tuple")
806  >>> object = ('a string', u'a unicode string', 12345)
807
808  >>> # An 'Emitter' instance can dump a representation tree into a stream,
809  >>> # but obviously failed to dump a Python object:
810  >>> e = Emitter(sys.stdout)
811  >>> e.emit(seq)
812  --- !python.taml.org,2002/tuple
813  - a string
814  - !python/unicode a unicode string
815  - 12345
816  >>> e.emit(object)
817  Traceback (most recent call last):
818    File "<stdin>", line 1, in ?
819  TypeError: Node instance is required
820
821  >>> # A 'GenericDumper' instance dumps almost everything as a scalar:
822  >>> gd = GenericDumper(sys.stdout)
823  >>> gd.dump(seq)
824  --- <_syck.Seq object at 0xb7a3c2fc>
825  >>> gd.dump(object)
826  --- ('a string', u'a unicode string', 12345)
827
828  >>> # Finally, a 'Dumper' instance dumps a representation tree as a complex
829  >>> # Python object:
830  >>> d = Dumper(sys.stdout)
831  >>> d.dump(seq)
832  --- !python/object:_syck.Seq
833  value:
834  - !python/object:_syck.Scalar
835    value: a string
836  - !python/object:_syck.Scalar
837    value: a unicode string
838    tag: tag:python.yaml.org,2002:unicode
839  - !python/object:_syck.Scalar
840    value: "12345"
841    tag: tag:yaml.org,2002:int
842  tag: tag:python.taml.org,2002:tuple
843  >>> # It also dumps the 'object' object as expected:
844  >>> d.dump(object)
845  --- !python/tuple
846  - a string
847  - !python/unicode a unicode string
848  - 12345
849
850
[26]851Development and Bug Reports
852===========================
853
854You may check out the PySyck_ source code from `PySyck SVN repository`_.
855
856If you find a bug in PySyck_, please file a bug report to `PySyck BTS`_. You
857may review open bugs on `the list of active tickets`_.
858
[29]859You may use `YAML-core mailing list`_ for discussions of PySyck_.
860
[26]861.. _PySyck SVN repository: http://svn.xitology.org/pysyck/
862.. _PySyck BTS: http://trac.xitology.org/pysyck/newticket
863.. _the list of active tickets: http://trac.xitology.org/pysyck/report/1
[29]864.. _YAML-core mailing list: http://lists.sourceforge.net/lists/listinfo/yaml-core
[26]865
[29]866
867Known Bugs
868==========
869
870To many to list all of them; see `the list of active tickets`_. If you find
871another bug, please submit it via `PySyck BTS`_.
872
873
874History
875=======
876
[30]877* PySyck-0.55.1 (2005-08-30): Initial release.
[29]878
879
[26]880Author and Copyright
881====================
882
883The PySyck_ module was written by `Kirill Simonov`_.
884
885PySyck_ is released under the BSD license as Syck_ itself.
886
887.. _Kirill Simonov: mailto:xi@resolvent.net
888
[29]889..
890  vim: ft=rst:
Note: See TracBrowser for help on using the repository browser.