Project: yorm

Automatic object-YAML mapping for Python.

Project Details

Latest version
1.6.2
Home Page
https://github.com/jacebrowning/yorm
PyPI Page
https://pypi.org/project/yorm/

Project Popularity

PageRank
0.003777600253746213
Number of downloads
101032

| |Build Status| | |Coverage Status| | |Scrutinizer Code Quality| | |PyPI Version|

Overview

| YORM enables automatic, bidirectional, human-friendly mappings of object attributes to YAML files. | Uses beyond typical object serialization and relational mapping include:

  • bidirectional conversion between basic YAML and Python types
  • attribute creation and type inference for new attributes
  • storage of content in text files optimized for version control
  • extensible converters to customize formatting on complex classes

View the talk from PyOhio 2015 <https://www.youtube.com/watch?v=0woNEKf-wAo>__.

Requirements

  • Python 3.5+

Installation

Install YORM with pip:

.. code:: sh

$ pip install YORM

or directly from the source code:

.. code:: sh

$ git clone https://github.com/jacebrowning/yorm.git
$ cd yorm
$ python setup.py install

Usage

Simply take an existing class:

.. code:: python

class Student:
    def __init__(self, name, school, number, year=2009):
        self.name = name
        self.school = school
        self.number = number
        self.year = year
        self.gpa = 0.0

and define an attribute mapping:

.. code:: python

import yorm
from yorm.types import String, Integer, Float

@yorm.attr(name=String, year=Integer, gpa=Float)
@yorm.sync("students/{self.school}/{self.number}.yml")
class Student:
    ...

Modifications to each object's mapped attributes:

.. code:: python

>>> s1 = Student("John Doe", "GVSU", 123)
>>> s2 = Student("Jane Doe", "GVSU", 456, year=2014)
>>> s1.gpa = 3

are automatically reflected on the filesytem:

.. code:: sh

$ cat students/GVSU/123.yml
name: John Doe
gpa: 3.0
school: GVSU
year: 2009

Modifications and new content in each mapped file:

.. code:: sh

$ echo "name: John Doe
> gpa: 1.8
> year: 2010
" > students/GVSU/123.yml

are automatically reflected in their corresponding object:

.. code:: python

>>> s1.gpa
1.8

.. |Build Status| image:: http://img.shields.io/travis/jacebrowning/yorm/master.svg :target: https://travis-ci.org/jacebrowning/yorm .. |Coverage Status| image:: http://img.shields.io/coveralls/jacebrowning/yorm/master.svg :target: https://coveralls.io/r/jacebrowning/yorm .. |Scrutinizer Code Quality| image:: http://img.shields.io/scrutinizer/g/jacebrowning/yorm.svg :target: https://scrutinizer-ci.com/g/jacebrowning/yorm/?branch=master .. |PyPI Version| image:: http://img.shields.io/pypi/v/yorm.svg :target: https://pypi.python.org/pypi/yorm

Revision History

1.6.2 (2019-03-23)

  • Fixed YAMLLoadWarning by using yaml.safe_load().

1.6.1 (2019-03-22)

  • Updated PyYAML to 5.1 for security fixes.

1.6 (2018-09-07)

  • Added Number (and NullableNumber) type for floats that store as integers when possible.

1.5.1 (2018-03-07)

  • Fixed the List converter to accept tuples as lists.

1.5 (2017-10-22)

  • Implemented match utility (credit: @astronouth7303 <https://github.com/astronouth7303>__).
  • Including file contents in parse exceptions.
  • Added sync parameter auto_resolve to clean up file conflicts automatically.

1.4 (2017-04-02)

  • Removed warnings about calling save/load unnecessarily.

  • Now allowing keyword arguments to be passed to class construction via create and find utilities.

  • Now adding additional attributes from __init__ on AttributeDictionary.

    • NOTE: For this feature to work, __init__ must not use positional arguments.
  • DEPRECIATION: Renamed ModelMixin.new to ModelMixin.create.

1.3 (2017-01-24)

  • Optimized the formatting of empty lists to create consistent diffs.
  • Added ModelMixin to add ORM methods to mapped classes.

1.2 (2017-01-06)

  • Updated base class to hide pytest traceback in wrapped methods.

1.1 (2016-10-22)

  • Added data property to Mapper as a hook for other serialization libraries.

1.0.1 (2016-09-23)

  • Fixed handling of mutation methods on list and dict.

1.0 (2016-05-22)

  • Initial stable release.

0.8.1 (2016-04-28)

  • Now invoking __init__ in Dictionary converters to run custom validations.

0.8 (2016-04-14)

  • Replaced all utility functions with ORM-like tools.
  • Removed the ability to check for existing files in sync().
  • Renamed and consolidated custom exceptions.
  • Renamed sync parameter auto=True to auto_save=True.
  • Renamed sync parameter strict=True to auto_track=False.
  • Added sync parameter auto_create to defer file creation to ORM functions.

0.7.2 (2016-03-30)

  • Now preserving order of attr decorators on Dictionary converters.

0.7.1 (2016-03-30)

  • Updated String to fetch true and false as strings.

0.7 (2016-03-29)

  • Now preserving order of attr decorators.
  • Now limiting attr decorator to a single argument.
  • Added List.of_type() factory to create lists with less boilerplate.

0.6.1 (2015-02-23)

  • Fixed handling of None in NullableString.

0.6 (2015-02-23)

  • Added preliminary support for JSON serialization. (credit: @pr0xmeh)
  • Renamed yorm.converters to yorm.types.
  • Now maintaining the signature on mapped objects.
  • Disabled attribute inference unless strict=False.
  • Fixed formatting of String to only use quotes if absolutely necessary.

0.5 (2015-09-25)

  • Renamed yorm.base to yorm.bases.
  • Stopped creating files on instantiation when auto=False.
  • Now automatically storing on fetch after initial store.

0.4.1 (2015-06-19)

  • Fixed attribute loss in non-\ dict when conversion to dict.
  • Now automatically adding missing attributes to mapped objects.

0.4 (2015-05-16)

  • Moved all converters into the yorm.converters package.
  • Renamed container to containers.
  • Renamed Converter to Convertible for mutable types
  • Added a new Converter class for immutable types
  • Removed the context manager in mapped objects.
  • Fixed automatic mapping of nested attributes.

0.3.2 (2015-04-07)

  • Fixed object overwrite when calling utilities.update.

0.3.1 (2015-04-06)

  • Fixed infinite recursion with properties that rely on other mapped attributes.

0.3 (2015-03-10)

  • Updated mapped objects to only read from the filesystem if there are changes.
  • Renamed store to sync_object.
  • Renamed store_instances to sync_instances.
  • Renamed map_attr to attr.
  • Added sync to call sync_object or sync_instances as needed.
  • Added update_object and update_file to force synchronization.
  • Added update to call update_object and/or update_file as needed.

0.2.1 (2015-02-12)

  • Container types now extend their builtin type.
  • Added None<Type> extended types with None as a default.
  • Added AttributeDictionary with keys available as attributes.
  • Added SortedList that sorts when dumped.

0.2 (2014-11-30)

  • Allowing map_attr and store to be used together.
  • Allowing Dictionary containers to be used as attributes.
  • Fixed method resolution order for modified classes.
  • Added a yorm.settings.fake option to bypass the filesystem.

0.1.1 (2014-10-20)

  • Fixed typos in examples.

0.1 (2014-09-29)

  • Initial release.