Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

PyYAML custom tags

Project description

PyYAML-Tags

Adds to PyYAML custom tags support

Branch CI status
master Build Statuscodecov
develop Build Statuscodecov

Getting Started

PyYAML-Tags is a library for advanced YAML processing in Python. It's built on the mature and full-featured PyYAML library.

It comes with 6 predefined tags and allows you to write your own. Use only those tags that you need or connect all at once with a great and simple decorators and meta API.

Installing

pip install pyyaml-tags

Usage

The most sweet part of the readme.md file :)

Library offers 6 predefined tags: include, env, random_int, randmom_float, random_str, time_now.

API

By default all the PyYAML tags are in the disabled state. It means that they will not work after you install the library.

To use tags you need to require them first. Just run the following code anywhere in your program:

from yaml_tags import tag_registry

tag_registry.require() # enable all tags 
# or
tag_registry.require(tags='__all__') # same as above
# or
tag_registry.require('include,env,random_int') # enable 'include', 'env' and 'random_int' tags
# or
tag_registry.require(tags=['include', 'env']) # enable 'include', 'env' tags
# or
tag_registry.require('include', 'env', 'time_now') # enable 'include', 'env' and 'time_now' tags

then call yaml.load() in your program (anywhere):

import yaml

with open('data/a/b/c.yml') as fh:
    data = yaml.load(fh)

print(data)

and check — it works !

Tags

  • include tag

    include tag allows you to include one yaml files into another.

    Sample:
    humans:
      managers: <% include(path="path/to/managers.yaml") %>
      accountants: <% include(path="path/to/**/accountant*.yaml", recursive=True, encoding='ascii') %>
    aliens: <% include(aliens.txt)
    robots: 
      - <% include(main-robot.yaml) %> 
      - <% include(robots/robot*.yaml) %> 
    
    Signature
    Parameter Required Type Default Description
    path yes str Path to file. Supports glob syntax
    recursive no bool False If glob is used, defines is glob recursive or not
    encoding no str utf-8 Files encoding
  • env tag

    env tag allows you to pass environment variables values into yaml files

    Sample:
    welcome: Hello, <% env('WORLD_VAR') %> !
    java_home: <% env('JAVA_HOME') %>
    
    Signature
    Parameter Required Type Default Description
    var yes str Environment variable name
  • random_int tag

    random_int tag generates random integer values and passes them into yaml file

    Sample:
    rolls:
      - roll_1: <% random_int %> # feel free to omit brackets. It's ok
      - roll_2: And this is <% random_int() %> !! Am I lacky ? 
      - roll_3: <% random_int(0, 10) %> 
      - roll_4: <% random_int(-50) %> 
      - final: Final one: <% random_int(-10, 10) %> 
    
    Signature
    Parameter Required Type Default Description
    a no int 0 Left bound
    b no int sys.maxsize Right bound
  • random_float tag

    random_float tag generates random float values (between 0 and 1) and passes them into yaml file

    Sample:
    rolls:
      - roll_1: <% random_float %> # Feel free to omit brackets
      - roll_2: Is it PI? <% random_float() %> ?? Nope ...
    
  • random_str tag

    random_str tag generates random str values of desired length and passes them into yaml file

    Sample:
    rolls:
      - roll_1: <% random_str %> # Feel free to omit brackets
      - roll_2: <% random_str(10) %>
      - roll_3: My value is <% random_str(5, True) %>
      - roll_5: And mine is <% random_str(20, False, True) %>
      - roll_6: <% random_str(uppercase=True) %>
      - roll_7: Hoho !!! <% random_str(10, lowercase=True) %> Haha !!!
    
    Signature
    Parameter Required Type Default Description
    length no int 10 String length
    uppercase no bool False Convert text to uppercase
    lowercase no bool False Convert text to lowercase
  • time_now tag

    time_now tag gets current timestamp in a desired format and passes it into yaml file

    Sample:
    context:
      - timestamp: <% time_now %> # Feel free to omit brackets
      - datetime: <% time_now(False) %> 
      - datetime_fmt: <% time_now(timestamp=False, fmt="%Y-%m-%d %H:%M:%S") %> 
    
    Signature
    Parameter Required Type Default Description
    timestamp no bool True Paste raw timestamp
    fmt no str %Y-%m-%d %H:%M:%S Format to use when timestamp=False

Write your own tags

To write your own tag use one of the following Python templates:

  • Using tag_registry

    from yaml_tags import BaseTag, tag_registry
    
    @tag_registry.register('my_own_tag') # you can set tag name here
    class MyOwnTag(BaseTag):
        # tag_name = 'my_own_tag' # or set it here as alternative
    
        def _from_yaml(self, _loader, _work_dir, _prefix, _suffix,
                   param1=None, param2=None, param3=False, param4='utf-8',
                   *args, **kwargs):
    
            if not param1:
                raise ValueError("Param1 is required")
    
            # your computations here
            result = "smth"
    
            if some_condition(result): # it doesn't matter what condition is this
                return result # w/o prefix and suffix
    
            return _prefix + result + _suffix
    
  • Using TagAutoRegister meta class. tag_name attribute is mandatory here.

    from six import with_metaclass
    from yaml_tags import BaseTag, TagAutoRegister
    
    class MyOwnTag(with_metaclass(TagAutoRegister(), BaseTag)):
        tag_name = 'my_own_tag' # tag name
    
        def _from_yaml(self, _loader, _work_dir, _prefix, _suffix,
                   param1=None, param2=None, param3=False, param4='utf-8',
                   *args, **kwargs):
    
            if not param1:
                raise ValueError("Param1 is required")
    
            # your computations here
            result = "smth"
    
            if some_condition(result): # it doesn't matter what condition is this
                return result # w/o prefix and suffix
    
            return _prefix + result + _suffix
    

Then just require your own tag somewhere:

from yaml_tags import tag_registry

tag_registry.require('my_own_tag')
# or
tag_registry.require(tags='__all__') # require all

And use it in your yaml files like this:

my_own_data: <% my_own_tag(param1="test", param2=2, param3=True, param4='ascii') %>

That's all !

Running the tests

We are using Tox. It is a generic virtualenv management and test command line tool.

Unit tests

  • To run tests just type tox in the command shell.
  • To run tests for a specific Python version use the following commands:
    • For Python 2: tox -e py2 (or py27)
    • For Python 3: tox -e py3 (or py34, py35, py36, py37)

Coding style tests

To check your codestyle just run tox -e pep8 in your command shell.

Coverage

For coverage use tox -e codecov command.

Built With

  • PyYAML - Full-featured YAML framework for the Python programming language.
  • AST - Helps Python applications to process trees of the Python abstract syntax grammar.
  • Path.py - Path objects for the Python 2.x

Contributing

You are welcome to contribute ! Just submit your PR and become a part of PyYAML community!

Please read contributing.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

  • Vadim Fedorenko - Meiblorn -Initial work

See also the list of authors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

  • It's my first Python opensource project. Hah. Vadim Fedorenko - Meiblorn - Initial work
  • 1.0.0 — First release. Added include, env, random_int, random_float, random_str and time_now tags.

  • 1.0.1 - Added readme.md and contributing.md files. Changed authors.md and changelog.md files

  • 1.0.2 - Changed configuration for the Travis CI PyPI deployment

  • 1.0.3 - Changed Travis CI PyPI deployment destination Python version. Reconfigured 'deploy_on' condition.

  • 1.0.4 - Updated setup.py flow. Added coverage badges to readme.md file. Fixed tags link in the readme.md file.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyyaml-tags, version 1.0.4
Filename, size File type Python version Upload date Hashes
Filename, size pyyaml_tags-1.0.4-py2.py3-none-any.whl (11.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size pyyaml-tags-1.0.4.tar.gz (21.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page