Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/pyaml-20.4.0.dist-info/METADATA @ 5:9b1c78e6ba9c draft default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit 6c0a8142489327ece472c84e558c47da711a9142"
author shellac
date Mon, 01 Jun 2020 08:59:25 -0400
parents 79f47841a781
children
comparison
equal deleted inserted replaced
4:79f47841a781 5:9b1c78e6ba9c
1 Metadata-Version: 2.1
2 Name: pyaml
3 Version: 20.4.0
4 Summary: PyYAML-based module to produce pretty and readable YAML-serialized data
5 Home-page: https://github.com/mk-fg/pretty-yaml
6 Author: Mike Kazantsev
7 Author-email: mk.fraggod@gmail.com
8 License: WTFPL
9 Keywords: yaml serialization pretty print format human readable readability
10 Platform: UNKNOWN
11 Classifier: Development Status :: 4 - Beta
12 Classifier: Intended Audience :: Developers
13 Classifier: Programming Language :: Python
14 Classifier: Programming Language :: Python :: 2.7
15 Classifier: Programming Language :: Python :: 3.5
16 Classifier: Topic :: Software Development
17 Classifier: Topic :: Software Development :: Libraries :: Python Modules
18 Requires-Dist: PyYAML
19
20 pretty-yaml (or pyaml)
21 ======================
22
23 PyYAML-based python module to produce pretty and readable YAML-serialized data.
24
25 This module is for serialization only, see `ruamel.yaml`_ module for literate
26 YAML parsing (keeping track of comments, spacing, line/column numbers of values, etc).
27
28 [note: to dump stuff parsed by ruamel.yaml with this module, use only ``YAML(typ='safe')`` there]
29
30 .. contents::
31 :backlinks: none
32
33
34 Warning
35 -------
36
37 Prime goal of this module is to produce human-readable output that can be easily
38 manipulated and re-used, but maybe with some occasional caveats.
39
40 One good example of such "caveat" is that e.g. ``{'foo': '123'}`` will serialize
41 to ``foo: 123``, which for PyYAML would be a bug, as 123 will then be read back
42 as an integer from that, but here it's a feature.
43
44 So please do not rely on the thing to produce output that can always be
45 deserialized exactly to what was exported, at least - use PyYAML (e.g. with
46 options from the next section) for that.
47
48
49 What this module does and why
50 -----------------------------
51
52 YAML is generally nice and easy format to read *if* it was written by humans.
53
54 PyYAML can a do fairly decent job of making stuff readable, and the best
55 combination of parameters for such output that I've seen so far is probably this one::
56
57 >>> m = [123, 45.67, {1: None, 2: False}, u'some text']
58 >>> data = dict(a=u'asldnsa\nasldpáknsa\n', b=u'whatever text', ma=m, mb=m)
59 >>> yaml.safe_dump(data, sys.stdout, allow_unicode=True, default_flow_style=False)
60 a: 'asldnsa
61
62 asldpáknsa
63
64 '
65 b: whatever text
66 ma: &id001
67 - 123
68 - 45.67
69 - 1: null
70 2: false
71 - some text
72 mb: *id001
73
74 pyaml tries to improve on that a bit, with the following tweaks:
75
76 * Most human-friendly representation options in PyYAML (that I know of) get
77 picked as defaults.
78
79 * Does not dump "null" values, if possible, replacing these with just empty
80 strings, which have the same meaning but reduce visual clutter and are easier
81 to edit.
82
83 * Dicts, sets, OrderedDicts, defaultdicts, namedtuples, etc are representable
84 and get sorted on output (OrderedDicts and namedtuples keep their ordering),
85 so that output would be as diff-friendly as possible, and not arbitrarily
86 depend on python internals.
87
88 It appears that at least recent PyYAML versions also do such sorting for
89 python dicts.
90
91 * List items get indented, as they should be.
92
93 * bytestrings that can't be auto-converted to unicode raise error, as yaml has
94 no "binary bytes" (i.e. unix strings) type.
95
96 * Attempt is made to pick more readable string representation styles, depending
97 on the value, e.g.::
98
99 >>> yaml.safe_dump(cert, sys.stdout)
100 cert: '-----BEGIN CERTIFICATE-----
101
102 MIIH3jCCBcagAwIBAgIJAJi7AjQ4Z87OMA0GCSqGSIb3DQEBCwUAMIHBMRcwFQYD
103
104 VQQKFA52YWxlcm9uLm5vX2lzcDEeMBwGA1UECxMVQ2VydGlmaWNhdGUgQXV0aG9y
105 ...
106
107 >>> pyaml.p(cert):
108 cert: |
109 -----BEGIN CERTIFICATE-----
110 MIIH3jCCBcagAwIBAgIJAJi7AjQ4Z87OMA0GCSqGSIb3DQEBCwUAMIHBMRcwFQYD
111 VQQKFA52YWxlcm9uLm5vX2lzcDEeMBwGA1UECxMVQ2VydGlmaWNhdGUgQXV0aG9y
112 ...
113
114 * "force_embed" option to avoid having &id stuff scattered all over the output
115 (which might be beneficial in some cases, hence the option).
116
117 * "&id" anchors, if used, get labels from the keys they get attached to,
118 not just use meaningless enumerators.
119
120 * "string_val_style" option to only apply to strings that are values, not keys,
121 i.e::
122
123 >>> pyaml.p(data, string_val_style='"')
124 key: "value\nasldpáknsa\n"
125 >>> yaml.safe_dump(data, sys.stdout, allow_unicode=True, default_style='"')
126 "key": "value\nasldpáknsa\n"
127
128 * "sort_dicts=False" option to leave dict item ordering to python, and not
129 force-sort them in yaml output, which can be important for python 3.6+ where
130 they retain ordering info.
131
132 * Has an option to add vertical spacing (empty lines) between keys on different
133 depths, to make output much more seekable.
134
135 Result for the (rather meaningless) example above (without any additional
136 tweaks)::
137
138 >>> pyaml.p(data)
139 a: |
140 asldnsa
141 asldpáknsa
142 b: 'whatever text'
143 ma: &ma
144 - 123
145 - 45.67
146 - 1:
147 2: false
148 - 'some text'
149 mb: *ma
150
151 ----------
152
153 Extended example::
154
155 >>> pyaml.dump(conf, sys.stdout, vspacing=[2, 1]):
156 destination:
157
158 encoding:
159 xz:
160 enabled: true
161 min_size: 5120
162 options:
163 path_filter:
164 - \.(gz|bz2|t[gb]z2?|xz|lzma|7z|zip|rar)$
165 - \.(rpm|deb|iso)$
166 - \.(jpe?g|gif|png|mov|avi|ogg|mkv|webm|mp[34g]|flv|flac|ape|pdf|djvu)$
167 - \.(sqlite3?|fossil|fsl)$
168 - \.git/objects/[0-9a-f]+/[0-9a-f]+$
169
170 result:
171 append_to_file:
172 append_to_lafs_dir:
173 print_to_stdout: true
174
175 url: http://localhost:3456/uri
176
177
178 filter:
179 - /(CVS|RCS|SCCS|_darcs|\{arch\})/$
180 - /\.(git|hg|bzr|svn|cvs)(/|ignore|attributes|tags)?$
181 - /=(RELEASE-ID|meta-update|update)$
182
183
184 http:
185
186 ca_certs_files: /etc/ssl/certs/ca-certificates.crt
187
188 debug_requests: false
189
190 request_pool_options:
191 cachedConnectionTimeout: 600
192 maxPersistentPerHost: 10
193 retryAutomatically: true
194
195
196 logging:
197
198 formatters:
199 basic:
200 datefmt: '%Y-%m-%d %H:%M:%S'
201 format: '%(asctime)s :: %(name)s :: %(levelname)s: %(message)s'
202
203 handlers:
204 console:
205 class: logging.StreamHandler
206 formatter: basic
207 level: custom
208 stream: ext://sys.stderr
209
210 loggers:
211 twisted:
212 handlers:
213 - console
214 level: 0
215
216 root:
217 handlers:
218 - console
219 level: custom
220
221 Note that unless there are many moderately wide and deep trees of data, which
222 are expected to be read and edited by people, it might be preferrable to
223 directly use PyYAML regardless, as it won't introduce another (rather pointless
224 in that case) dependency and a point of failure.
225
226
227 Some Tricks
228 -----------
229
230 * Pretty-print any yaml or json (yaml subset) file from the shell::
231
232 % python -m pyaml /path/to/some/file.yaml
233 % curl -s https://www.githubstatus.com/api/v2/summary.json | python -m pyaml
234
235 * Process and replace json/yaml file in-place::
236
237 % python -m pyaml -r file-with-json.data
238
239 * Easier "debug printf" for more complex data (all funcs below are aliases to
240 same thing)::
241
242 pyaml.p(stuff)
243 pyaml.pprint(my_data)
244 pyaml.pprint('----- HOW DOES THAT BREAKS!?!?', input_data, some_var, more_stuff)
245 pyaml.print(data, file=sys.stderr) # needs "from __future__ import print_function"
246
247 * Force all string values to a certain style (see info on these in
248 `PyYAML docs`_)::
249
250 pyaml.dump(many_weird_strings, string_val_style='|')
251 pyaml.dump(multiline_words, string_val_style='>')
252 pyaml.dump(no_want_quotes, string_val_style='plain')
253
254 Using ``pyaml.add_representer()`` (note \*p\*yaml) as suggested in
255 `this SO thread`_ (or `github-issue-7`_) should also work.
256
257 * Control indent and width of the results::
258
259 pyaml.dump(wide_and_deep, indent=4, width=120)
260
261 These are actually keywords for PyYAML Emitter (passed to it from Dumper),
262 see more info on these in `PyYAML docs`_.
263
264 * Dump multiple yaml documents into a file: ``pyaml.dump_all([data1, data2, data3], dst_file)``
265
266 explicit_start=True is implied, unless explicit_start=False is passed.
267
268 .. _PyYAML docs: http://pyyaml.org/wiki/PyYAMLDocumentation#Scalars
269 .. _this SO thread: http://stackoverflow.com/a/7445560
270 .. _github-issue-7: https://github.com/mk-fg/pretty-yaml/issues/7
271
272
273 Installation
274 ------------
275
276 It's a regular package for Python (3.x or 2.x).
277
278 Module uses PyYAML_ for processing of the actual YAML files and should pull it
279 in as a dependency.
280
281 Dependency on unidecode_ module is optional and should only be necessary if
282 same-id objects or recursion is used within serialized data.
283
284 Be sure to use python3/python2, pip3/pip2, easy_install-... binaries below,
285 based on which python version you want to install the module for, if you have
286 several on the system (as is norm these days for py2-py3 transition).
287
288 Using pip_ is the best way::
289
290 % pip install pyaml
291
292 (add --user option to install into $HOME for current user only)
293
294 Or, if you don't have "pip" command::
295
296 % python -m ensurepip
297 % python -m pip install --upgrade pip
298 % python -m pip install pyaml
299
300 (same suggestion wrt "install --user" as above)
301
302 On a very old systems, one of these might work::
303
304 % curl https://bootstrap.pypa.io/get-pip.py | python
305 % pip install pyaml
306
307 % easy_install pyaml
308
309 % git clone --depth=1 https://github.com/mk-fg/pretty-yaml
310 % cd pretty-yaml
311 % python setup.py install
312
313 (all of install-commands here also have --user option,
314 see also `pip docs "installing" section`_)
315
316 Current-git version can be installed like this::
317
318 % pip install 'git+https://github.com/mk-fg/pretty-yaml#egg=pyaml'
319
320 Note that to install stuff to system-wide PATH and site-packages (without
321 --user), elevated privileges (i.e. root and su/sudo) are often required.
322
323 Use "...install --user", `~/.pydistutils.cfg`_ or virtualenv_ to do unprivileged
324 installs into custom paths.
325
326 More info on python packaging can be found at `packaging.python.org`_.
327
328 .. _ruamel.yaml: https://bitbucket.org/ruamel/yaml/
329 .. _PyYAML: http://pyyaml.org/
330 .. _unidecode: http://pypi.python.org/pypi/Unidecode
331 .. _pip: http://pip-installer.org/
332 .. _pip docs "installing" section: http://www.pip-installer.org/en/latest/installing.html
333 .. _~/.pydistutils.cfg: http://docs.python.org/install/index.html#distutils-configuration-files
334 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
335 .. _packaging.python.org: https://packaging.python.org/installing/
336
337