Add poyo.load() and poyo.load_all() for compatibility with PyYAML

[gvalkov]

This change makes using poyo in place of pyyaml even easier. For many use cases, all it takes is a:

import poyo as yaml

[hackebrot]

Hi @gvalkov! 👋

Thanks for the PR. When I started Poyo I decided against sticking to the known API to make sure that people understand that this is not a fully-fledged replacement.

Not sure how I feel about it now. Maybe it's okay to support load and load_all 😖

[hackebrot]

CI fails due to flake8 issues btw:

poyo/parser.py:185:1: E302 expected 2 blank lines, found 1
poyo/parser.py:188:1: E302 expected 2 blank lines, found 1
tests/test_parser.py:13:1: E302 expected 2 blank lines, found 1

[gvalkov]

That's a reasonable stance indeed. I think it's pretty clear from the readme that Poyo supports only a subset of the yaml spec. Maybe it's worth mentioning that parsing only the basic Python types is supported (this can be more or less inferred by the example).

If you chose to merge this PR, then it might also be a good idea to add poyo.dump() and poyo.dumps() and have them explicitly raise NotImplementedError('poyo does not support object dumping').

[hackebrot]

Indeed, if we decide to add load, load_all, we should probably also add the other support API methods raising a NotImplementedError (or even implement it).

Up to now I only know of Cookiecutter to use Poyo. I'll think about it and maybe play with the writing side of it if I have some free time.

[gvalkov]

Sure thing - just added dump and dump_all() and made them raise NotImplentedError. Making Poyo support dumping to yaml is quite an interesting problem and I hope you get time to hack on it :+1: Imho, the standard library json/encoder.py module might be a good inspiration for such a thing.

I also first learned about Poyo from cookiecutter and was recently reminded about it from this discussion on the distutils-sig mailing lists.

[hackebrot]

Sorry for being slow to reply on this one. I've been thinking about the API of Poyo quite a bit, especially after reading through the discussion that you've linked (thanks for that 🙇). I'm a bit surprised no one got in touch with me to ask whether I think Poyo is suited to be vendored in pip. 😕

Frankly, I do not intend to replicate PyYAML or ruamel.yaml. This project started as a drop-in replacement for Cookiecutter (which supports not more than three values) and seems to work just fine for that purpose.

DEFAULT_CONFIG = {
    'cookiecutters_dir': os.path.expanduser('~/.cookiecutters/'),
    'replay_dir': os.path.expanduser('~/.cookiecutter_replay/'),
    'default_context': {}
}

I tried to look up the exact API in PyYAML (including load, safe_load etc.) and see what args and kwargs do - but the imports are meh (* imports all over and I have to ag everything) and I feel like I'm wasting time. 🙊

Long story short, for now I'd rather stick to the current API of parse_string but keep your branch if you don't mind. Thank you for your help!

[gvalkov]

That's alright @hackebrot :) At least I took part in reinforcing your position on the PyYAML API support. My only argument is that dump(s) and load(s) are common among Python APIs that serializes and deserialize (e.g. pickle, yaml, json, toml). I just liked the idea of doing a import poyo as yaml and running my test suite to see if everything was ok :)

Too bad about the distutils-sig discussion. Poyo is certainly good enough for most configuration file use cases, imho. The fact that it's easy to vendor and that you don't have to worry about safety is a nice bonus.