diff options
Diffstat (limited to '')
| -rw-r--r-- | _doc/README.ryd | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/_doc/README.ryd b/_doc/README.ryd new file mode 100644 index 0000000..f728607 --- /dev/null +++ b/_doc/README.ryd @@ -0,0 +1,120 @@ +version: 0.2 +text: md +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.readthedocs.io +repository: https://sourceforge.net/projects/ruamel-yaml +pypi: https://pypi.org/project/ruamel.yaml +--- | + +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. defaultin 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 inappriate, 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.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. + +--- !toc +level: 3 +# prefix: http://yaml.readthedocs.io/en/latest/ +--- | + +[](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/) + +# ChangeLog + +--- !changelog +CHANGES +--- | + +------------------------------------------------------------------------ + +For older changes see the file +[CHANGES](https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/CHANGES) |