Any contribution to
ruamel.yaml is welcome, be it in the form of an
email, a question on stackoverflow (I’ll get notified of that when you tag it
ruamel.yaml), an issue or pull-request (PR) on bitbucket.
Contributing via stackoverflow is, for most, easiest to make. When I answer your
question there and the answer warrants an extension to the documentation or
code, I will include it in a documnetation update and/or future (normally the
next) release of
Please don’t post support questions as an issue on Bitbucket.
The documentation for
ruamel.yaml is in YAML, more specifically in ryd ( /rɑɪt/, pronounced like the verb “write”
). This is reStructuredText mixed with Python, each in separate YAML documents
within a single file. If you know a bit of YAML, Python and reStructuredText it
will be clear how that works.
If you want to contribute to the documentation, you can sent me a clear
description of the needed changes, e.g. as a unified diff. If the changes
encompass multiple documents in a
.ryd file, it is best to install
(use a virtualenv!), clone the
ruamel.yaml repository on Bitbucket, edit
ryd --pdf '**/*.ryd'
(quoting might not be necessary depending on your shell), and once the PDF(s) look acceptable, submit a pull-request.
ryd will check your file for single backquotes (my most common mistake going
back and forth between reStructuredText and other mark up).
If you contribute example programs, note that
ryd will automatically run you
program (so it should be correct) and can include the output of the program in
.rst (and PDF) file.
Code changes are welcome as well, but anything beyond a minor change should be
pytest), checked for typing conformance (
mypy) and pass
pep8 conformance (
In my experience it is best to use two
virtualenv environments, one with the
latest Python from the 2.7 series, the other with 3.5 or 3.6. In the
site-packages directory of each virtualenv make a soft link to the ruamel
directory of your (cloned and checked out) copy of the repository. Do not under
any circumstances run
pip install -e . or
python setup.py -e . it will
not work (at least not until these commands are fixed to support packages with
You can install
flake8 in the Python3
virtualenv, or in a
virtualenv of their own. If all of these commands
pass without warning/error, you can create your pull-request.
[flake8] show-source = True max-line-length = 95 ignore = F405
The suppress of F405 is necessary to allow
from xxx import *, which I have
not removed in all places (yet).
First make sure your checked out source passes
flake8 without test (it should).
Then make your changes pass without any warnings/errors.
Whether you add something or fix some bug with your code changes, first add one
or more tests that fail in the unmodified source when running
tox. Once that
is in place add your code, which should have as a result that your added test(s)
no longer fail, and neither should any other existing tests.
If you add methods or functions to
ruamel.yaml, you will need to add Python
2.7 compatible typing information in order for
mypy to pass without error.
mypy from the directory where the (link to) ruamel directory is
mypy --py2 --strict --follow-imports silent ruamel/yaml/*.py
This should give no errors or warnings
I use a minimal environment when developing, void of most artifacts needed for
packaging, testing etc. These artifact files are generated, just before committing to
Bitbucket and pushing to PyPI, with nuances coming from the
__init__.py. Including changes in these files will
automatically be reverted, even assuming your PR is accepted as is.
Consider the following files read-only (if you think changes need to made these, contact me):
setup.py tox.ini LICENSE _ryd/conf.py -ryd/Makefile
If you find a vulnerability in
ruamel.yaml (e.g. that would show the
rt loader are not safe due to a bug in the software)), please contact me
directly via email, or by leaving a comment on StackOverflow (below any of my
posts), without going into the details of the vulnerability. After contact is
estabilished I will work to eliminate the vulnerability in a timely fashion.
After the vulnerability is removed, and affected parties notified to allow them
to update versions, the vulnerability will be published, and your role in
finding/resolving this properly attributed.