Skip to main content

Automatic object-YAML mapping for Python.

Project description

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.

Requirements

  • Python 3.3+

Installation

Install YORM with pip:

$ pip install YORM

or directly from the source code:

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

Usage

Simply take an existing class:

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:

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:

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

are automatically reflected on the filesytem:

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

Modifications and new content in each mapped file:

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

are automatically reflected in their corresponding object:

>>> s1.gpa
1.8

Revision History

1.6 (unreleased)

  • 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).

  • 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.

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

YORM-1.6a1.tar.gz (42.3 kB view details)

Uploaded Source

Built Distribution

YORM-1.6a1-py3-none-any.whl (46.8 kB view details)

Uploaded Python 3

File details

Details for the file YORM-1.6a1.tar.gz.

File metadata

  • Download URL: YORM-1.6a1.tar.gz
  • Upload date:
  • Size: 42.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for YORM-1.6a1.tar.gz
Algorithm Hash digest
SHA256 d1dc28f516b4818fd44b3adf71a6a99eaae2ae42ee0b7168531e04114c31c4a6
MD5 f400108bbf63064df5f7e82dfa76fd6e
BLAKE2b-256 6e3a95643228fea08a1c31aca46418ba14a25add6253447de95b3e1821e22a2e

See more details on using hashes here.

File details

Details for the file YORM-1.6a1-py3-none-any.whl.

File metadata

File hashes

Hashes for YORM-1.6a1-py3-none-any.whl
Algorithm Hash digest
SHA256 683e318d1cd3240affc51cb022c6ef82bb7894d5a1147e61c5ec41e83d74aa75
MD5 eb865c8f5817e5a365178793b858ba32
BLAKE2b-256 3ab5454bd7534b2b4f8b296792794c81311bb1e26128ff49d3ff0b04c1e02a4c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page