source: pysyck/trunk/README.txt @ 65

Revision 65, 25.7 KB checked in by xi, 8 years ago (diff)

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