1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
version: 0.2
text: smd
pdf: false
order:
- overview.ryd
- install.ryd
- basicuse.ryd
- dumpcls.ryd
- detail.ryd
- example.ryd
- api.ryd
- pyyaml.ryd
- contributing.ryd
toc: False # don't index this file or put in mkdocs.nav
mkdocs:
site_name: yaml
docs_dir: _doc
site_author: Anthon van der Neut
nav:
- overview.md
- install.md
- basicuse.md
- dumpcls.md
- detail.md
- example.md
- api.md
- pyyaml.md
- contributing.md
theme:
name: readthedocs
exclude_docs: |
*.ryd
*.rst
markdown_extensions:
- toc:
permalink: true
--- |
# ruamel.yaml
`ruamel.yaml` is a YAML 1.2 loader/dumper package for Python.
--- !table
version: !Env version
updated: !Env date
documentation: https://yaml.dev/doc/ruamel.yaml
repository: https://sourceforge.net/projects/ruamel-yaml
pypi: https://pypi.org/project/ruamel.yaml
--- !python-hidden |
import os
from textwrap import dedent
if os.environ.get('GEN_README_MD'):
print(dedent("""\
## breaking changes, that may make future uploads to PyPI impossible
*If you are interested in future upgrades of `ruamel.yaml`
please check the [documentation on installing](https://yaml.dev/doc/ruamel.yaml/install/),
since at some point I might not be able to upload a new version to PyPI with updated information.*
`ruamel.yaml` was intentionally named as `yaml` in a namespace `ruamel`. The namespace allows the installation
name to correspond unchanged to how the package is imported, reduces the number of links I have to create
in site-packages of a Python install during development, as well as providing a recognisable set of packages
my company releases to the public.
However, after uploading version 0.18.7, I got an email from PyPI, about having to change the project name
to `ruamel_yaml` to comply with PEP 625, sometime in the future. The email doesn't say if namespace packages are
no longer allowed, or how to deal with the very real clash with the pre-existing package `ruamel_yaml`.
I might not be able to adapt `ruamel.yaml`, in
a way that does not negatively affect the 0.5 million daily downloads (and my own usage of the package) in time.
My experience with other such service downgrades (Bitbucket, Readthedocs), has not been entirely positive.
-----
"""))
--- !stdout-raw |
--- |
As announced, in 0.18.0, the old PyYAML functions have been deprecated.
(`scan`, `parse`, `compose`, `load`, `emit`, `serialize`, `dump` and their variants
(`_all`, `safe_`, `round_trip_`, etc)). If you only read this after your program has
stopped working: I am sorry to hear that, but that also means you, or the person
developing your program, has not tested with warnings on (which is the recommendation
in PEP 565, and e.g. defaulting when using `pytest`). If you have troubles, explicitly use
```
pip install "ruamel.yaml<0.18.0"
```
or put something to that effects in your requirments, to give yourself
some time to solve the issue.
There will be at least one more potentially breaking change in the 0.18 series: `YAML(typ='unsafe')`
now has a pending deprecation warning and is going to be deprecated, probably before the end of 2023.
If you only use it to dump, please use the new `YAML(typ='full')`, the result of that can be *safely*
loaded with a default instance `YAML()`, as that will get you inspectable, tagged, scalars, instead of
executed Python functions/classes. (You should probably add constructors for what you actually need,
but I do consider adding a `ruamel.yaml.unsafe` package that will re-add the `typ='unsafe'` option.
*Please adjust/pin your dependencies accordingly if necessary.*
There seems to be a CVE on `ruamel.yaml`, stating that the `load()` function could be abused
because of unchecked input. `load()` was never the default function (that was `round_trip_load()`
before the new API came into existence. So the creator of that CVE was ill informed and
probably lazily assumed that since `ruamel.yaml` is a derivative of PyYAML (for which
a similar CVE exists), the same problem would still exist, without checking.
So the CVE was always inappropriate, now just more so, as the call
to the function `load()` with any input will terminate your program with an error message. If you
(have to) care about such things as this CVE, my recommendation is to stop using Python
completely, as `pickle.load()` can be abused in the same way as `load()` (and like unlike `load()`
is only documented to be unsafe, without development-time warning.
Version 0.18.9 was the last one tested to be working with Python 3.7
Version 0.17.21 was the last one tested to be working on Python 3.5 and 3.6<BR>
The 0.16.13 release was the last that was tested to be working on Python 2.7.
There are two extra plug-in packages
(`ruamel.yaml.bytes` and `ruamel.yaml.string`)
for those not wanting to do the streaming to a
`io.BytesIO/StringIO` buffer themselves.
If your package uses `ruamel.yaml` and is not listed on PyPI, drop me an
email, preferably with some information on how you use the package (or a
link to the repository) and I'll keep you informed when the status of
the API is stable enough to make the transition.
For packaging purposes you can use a download of the [tar balls oof tagged source](https://yaml.dev/ruamel-dl-tagged-releases)
--- !comment |
# # ToDo 2024-12
# --- !toc
# level: 3
# # prefix: http://yaml.readthedocs.io/en/latest/
--- |
```=html
<a href="https://bestpractices.coreinfrastructure.org/projects/1128"><img src="https://bestpractices.coreinfrastructure.org/projects/1128/badge"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/_doc/_static/license.svg?format=raw"></a>
<a href="https://pypi.org/project/ruamel.yaml/"><img src="https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/_doc/_static/pypi.svg?format=raw"></a>
<a href="https://pypi.org/project/oitnb/"><img src="https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw"></a>
<a href="http://mypy-lang.org/"><img src="http://www.mypy-lang.org/static/mypy_badge.svg"></a>
<a href="https://www.pepy.tech/projects/ruamel.yaml"><img src="https://img.shields.io/pepy/dt/ruamel.yaml.svg"></a>
```
--- !comment |
[]($image.url('https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw'))
[bla]($link.url("https://pypi.org/project/oitnb/"))
[[]($image.url('https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw'))]($link.url("https://pypi.org/project/oitnb/"))
[($image.url('https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw').linked(true))]
[($image.url('https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw'))](https://pypi.org/project/oitnb/)
# [](https://yaml.readthedocs.org/en/latest?badge=latest)
# [](https://bestpractices.coreinfrastructure.org/projects/1128)
# [](https://opensource.org/licenses/MIT)
# [](https://pypi.org/project/ruamel.yaml/)
# [](https://pypi.org/project/oitnb/)
# [](http://mypy-lang.org/)
# [](https://www.pepy.tech/projects/ruamel.yaml)
# ChangeLog
--- !changelog
CHANGES
--- |
------------------------------------------------------------------------
For older changes see the file
[CHANGES](https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/CHANGES)
|
