From 48f99ca1aff47c96a7b1b4ffcb5c9a6d5dcf2a47 Mon Sep 17 00:00:00 2001 From: Matěj Cepl Date: Wed, 14 Mar 2012 13:13:20 +0100 Subject: Fix the module documentation string. --- NEWS.txt | 5 ++- yamlish.py | 118 ++++++++++++++++++++++++++++++------------------------------- 2 files changed, 63 insertions(+), 60 deletions(-) diff --git a/NEWS.txt b/NEWS.txt index f929262..b36d1ef 100644 --- a/NEWS.txt +++ b/NEWS.txt @@ -10,4 +10,7 @@ * Also fixing python setup.py test so that it actually does something. 0.4 2012-03-09 - * Missing requires field in setup.py \ No newline at end of file + * Missing requires field in setup.py + +0.5 2012-03-14 + * Make the module documentation string at least a bit presentable. \ No newline at end of file diff --git a/yamlish.py b/yamlish.py index 80e6d27..f3ef610 100644 --- a/yamlish.py +++ b/yamlish.py @@ -1,52 +1,39 @@ # -*- coding: utf-8 -*- -from __future__ import absolute_import, print_function, unicode_literals +#Copyright (C) 2012 Red Hat, Inc. +# +#Permission is hereby granted, free of charge, to any person obtaining a copy of +#this software and associated documentation files (the "Software"), to deal in +#the Software without restriction, including without limitation the rights to +#use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +#of the Software, and to permit persons to whom the Software is furnished to do +#so, subject to the following conditions: +# +#The above copyright notice and this permission notice shall be included in all +#copies or substantial portions of the Software. +# +#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +#SOFTWARE. """ -Easy YAML serialisation compatible with TAP (http://testanything.org/) format. -Copyright (C) 2012 Red Hat, Inc. - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -of the Software, and to permit persons to whom the Software is furnished to do -so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. ----------------------------------- - -Available on https://github.com/AndyA/Data--YAML - -=head1 DESCRIPTION - -In the spirit of L, L and -L provide lightweight, dependency-free YAML -handling. While C is designed principally for working with -configuration files C concentrates on the transparent round- -tripping of YAML serialized Perl data structures. - -As an example of why this distinction matters consider that -C doesn't handle hashes with keys containing non-printable -characters. This is fine for configuration files but likely to cause -problems when handling arbitrary Perl data structures. C -handles exotic hash keys correctly. - -The syntax accepted by C is a subset of YAML. Specifically -it is the same subset of YAML that L produces. See -L for more information. - -=head2 YAML syntax - -Although YAML appears to be a simple language the entire YAML -specification is huge. C implements a small subset of the +Easy YAML serialisation compatible with TAP format. + +Port of `Data::YAML Perl module `, +satisfying all its tests, intended to be used for support of +`TAP ` data format. Port of the original +documentation follows. + +The syntax accepted by this module is a subset of `YAML `. + +=========== +YAML syntax +=========== + +Although YAML appears to be a simple language, the entire YAML +specification is huge. This module implements a small subset of the complete syntax trading completeness for compactness and simplicity. This restricted syntax is known (to me at least) as 'YAMLish'. @@ -55,17 +42,23 @@ These examples demonstrates the full range of supported syntax. All YAML documents must begin with '---' and end with a line containing '...'. +:: + --- Simple scalar ... Unprintable characters are represented using standard escapes in double quoted strings. - --- "\t\x01\x02\n" +:: + + --- "\\t\\x01\\x02\\n" ... Array and hashes are represented thusly +:: + --- - "This" - "is" @@ -80,6 +73,8 @@ Array and hashes are represented thusly Structures may nest arbitrarily +:: + --- - name: 'Hash one' @@ -91,30 +86,35 @@ Structures may nest arbitrarily Undef is a tilde +:: + --- ~ ... -=head2 Uses +==== +Uses +==== -Use C may be used any time you need to freeze and thaw Perl +This module may be used any time you need to freeze and thaw Python data structures into a human readable format. The output from -C should be readable by any YAML parser. +`yamlish.dump()` should be readable by any YAML parser. -C was originally written to allow machine-readable +The original Perl module was originally written to allow machine-readable diagnostic information to be passed from test scripts to -L. That means that if you're writing a testing system that -needs to output TAP version 13 or later syntax you might find -C useful. +the Perl module `TAP::Harness`. That means that if you're writing +a testing system that needs to output TAP version 13 or later +syntax you might find this module useful. -Read more about TAP and YAMLish here: L +Read more about TAP and YAMLish on `` """ - +from __future__ import absolute_import, print_function, unicode_literals import logging import yaml -__version__ = "0.4" -__author__ = "Matěj Cepl " +__docformat__ = 'reStructuredText' +__version__ = "0.5" +__author__ = "Matej Cepl " class _YamlishLoader(yaml.loader.SafeLoader): """ -- cgit