version: 0.2
text: smd
pdf: false
order:
- overview.ryd
- install.ryd
- basicuse.ryd
- dumpcls.ryd
- detail.ryd
- example.ryd
- cve.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
  - cve.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 |

--- |

Starting with 0.19.0 `ruamel.yaml` no longer has `ruamel.yaml.clib` as a dependency,
as this has been replaced with `ruamel.yaml.clibz`.
The C sources are functionally unchanged,
but they are now always compiled (using `setuptools-zig` and `ziglang`) on your system,
instead of being downloaded as pre-compiled wheels (if available).
For this to function properly your Python (virtual) environment needs to have
an up-to-date version of `setuptools` and `wheels` pre-installed.

If you run into trouble, you can install `ruamel.yaml.clib` explicitly, without
using `ruamel.yaml.clibz` at all, using:

```
    python -m pip install --no-deps ruamel.yaml ruamel.yaml.clib

```

The code to load `ruamel.yaml.clib` has priority over `ruamel.yaml.clibz`
if both are installed (so `--no-deps` is not strictly necessary.
This compatibility will at least be available during the 0.19 `ruamel.yaml` series
(so pin your usage of `ruamel.yaml` if necessary and report any problems).

The motivitation for this change is the availability,
and easy of use, of Zig as the toolchain
(in the form of `ziglang` on PyPi), so lenghty, non-optimized,
pre-compilation and uploading to PyPI,
is no longer necessary.
The time spent on creating ~60 wheels
and even more time wasted on dealing with CI providers (Appveyor
not being updated to support 3.14, Github CI being slow,
and charging for the use of your own computer,
etc).

The split out of `ruamel.yaml.clib` after the 0.15.100 release,
was also motivated by the time spent
on generating .whl files even if only Python code was changed.
The use of `ziglang` and `setuptools-zig` does make re-integration of the C sources
into `ruamel.yaml` feasable, but there are no plans yet to make this happen.

The test matrix for `ruamel.yaml.clibz`, of course still has many dimensions:
```
    Python versions: 3.9 - 3.14
    OS-es:           Linux, Alpine (musl), macOS, Windows
    Architectures:   Intel/AMD, Arm (and others), in 64 and some also in 32 bit versions
    Zig version:     ziglang < 0.16 is taken from PyPI
```

I try to test as much of the combinations as possible,
trying at least all supported Python versions,
including freethreading,
on macOS-arm64,
Linux arm64 (via docker containers),
Ubuntu Linux-Intel,
Linux musl intel (docker).
And at least one Python version along each of the indicated positions of the
dimensions above (e.g. Windows10 64bit was tested with Python 3.14, but I
could not test the RISC-V architecture).
As with generating .whl files previously
(which I could not all test myself)
I partly have to rely on the process of compilation/generation being likely correct,
and feedback from actual users,
of exotic (for me) platforms, is of course welcome.

There is new section,
in the documentation,
on the security of processing unchecked input.

-------

The potentially breaking change announced for the 0.18 series, in that `YAML(typ='unsafe')`
was going to be deprecated (now pending), has not yet  been implemented, but is still considered.
If you only use `unsafe` 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.*

-------

Version 0.18.16 was the last one tested to be working with Python 3.8.
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.
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 of 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/)
# [![image](https://readthedocs.org/projects/yaml/badge/?version=latest)](https://yaml.readthedocs.org/en/latest?badge=latest)
# [![image](https://bestpractices.coreinfrastructure.org/projects/1128/badge)](https://bestpractices.coreinfrastructure.org/projects/1128)
# [![image](https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/_doc/_static/license.svg?format=raw)](https://opensource.org/licenses/MIT)
# [![image](https://sourceforge.net/p/ruamel-yaml/code/ci/default/tree/_doc/_static/pypi.svg?format=raw)](https://pypi.org/project/ruamel.yaml/)
# [![image](https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw)](https://pypi.org/project/oitnb/)
# [![image](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
# [![image](https://img.shields.io/pepy/dt/ruamel.yaml.svg)](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)
