Description:
pyyamltags 1.0.4
PyYAML-Tags
Adds to PyYAML custom tags support
Branch
CI status
master
develop
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.
License
For personal and professional use. You cannot resell or redistribute these repositories in their original state.
Customer Reviews
There are no reviews.
