yatiml 0.4.2

A library for making YAML-based file formats

YAtiML

YAtiML is a small Python library that works with ruamel.yaml, adding functions for automatic type recognition to it. YAtiML is not a schema language like XSD and Relax-NG are for XML, or JSON Schema is for JSON. YAtiML is also not an Object/YAML mapper (YAML is already an object serialisation system, so you don’t need an extra library for that). However, YAtiML does solve the same kind of problems, and more, so if you are looking for a schema language for YAML, YAtiML may actually be what you need.

If you use YAtiML for scientific work, we ask that you cite it. We have provided a CITATION.cff file to help you do so quickly and easily.

How it works

YAML-based file formats can be very handy, as YAML is easy to write by humans, and parsing support for it is widely available. Just read your YAML file into a document structure (a tree of nested dicts and lists), and manipulate that in your code.

While this works fine for simple file formats, it does not scale very well to more complex file formats such as the Common Workflow Language (CWL) or the Multiscale Computing Language (yMCL). Manual error-checking is lots of work and error-prone, defaults are not set automatically (which is especially tricky if you have multiple nested optional objects), and the file format often ends up somewhat underspecified.

Furthermore, a small collection of nested dicts and lists may work fine, but for more complex file formats, this becomes unwieldy and a set of objects is a better choice. Although it is not often used this way, YAML is actually a fully fledged object-to-text serialisation protocol. The Python yaml and ruamel.yaml libraries will actually construct objects for you, but the class names need to be put in the YAML file for that to work, which makes those files harder to read and write for humans.

With YAtiML, you describe your file format by defining a set of ordinary Python classes. You then create a Loader class, which you can then use with the normal ruamel.yaml.load(). However, objects of the types you have defined will now be recognised automatically in the input YAML text, a type check will be performed so that you can be sure that you’re getting what you were expecting, and the resulting data structure will consist of instances of your classes. Also, with a few lines of extra code, you can add some syntactic sugar to the YAML text format, making it easier for your users to write files in your format by hand in a variety of ways, while you still get consistent objects. Of course, YAtiML supports the reverse as well, making a Dumper for you to use with yaml.dump(), which ensures an easy-to-read, clean YAML output.

There are still some limitations on round-tripping data, so reading a YAML file and then saving it again may change the order of attributes, and will strip comments. Round-trip support is still in development in ruamel.yaml, and there is not much YAtiML can do to improve this at the moment. YAtiML does contribute a small but important feature to generating YAML files by your software: attributes will be written out in the order in which you’ve defined them, rather than in random order, which really improves the readability of the result (assuming that the order of your definition is logical, of course.)

YAtiML supports Python 3.4 and later.

Documentation and Help

Instructions on how to install and use YAtiML can be found in the YAtiML documentation.

Code of Conduct

Before describing where to ask questions or report bugs, we’d like to point out that this project is governed by a code of conduct, as described in CODE_OF_CONDUCT.rst, and we expect you to adhere to it. Please be nice to your fellow humans.

Questions

If you have a question that the documentation does not answer for you, then you have found a bug in the documentation. We’d love to fix it, but we need a bit of help from you to do so. Please do the following:

1. use the search functionality to see if someone already filed the same issue;

2. if your issue search did not yield any relevant results, make a new issue;

3. apply the “Question” label; apply other labels when relevant.

We’ll answer your question, and improve the documentation where necessary.

Bugs

Like most software, YAtiML is made by humans, and we make mistakes. If you think you’ve found a bug in YAtiML, please let us know! Reporting bugs goes as follows.

1. Use the search functionality to see if someone already filed the same issue.

2. If your issue search did not yield any relevant results, make a new issue.

   Please explain:

   • what you were trying to achieve,

   • what you did to make that happen,

   • what you expected the result to be,

   • what happened instead.

It really helps to have the actual code for a simple example that demonstrates the issue, but excerpts and error messages and a description are welcome too.

1. Finally, apply any relevant labels to the newly created issue.

With that, we should be able to fix the problem.

License

YAtiML is Copyright 2018, Netherlands eScience Center, University of Amsterdam, and VU University Amsterdam

Distributed under the Apache Software License 2.0.