Skip to main content

A sober python base library

Project description

A sober python base library for python 2.7 or python 3. (Full Documentation)

Caution!

EXPERIMENTAL CODE. The interface to this library is not yet stable. At this time, improvements will be made to the interface without regard to backward compatibility. Backward-incompatible changes will not necessarily be documented in the changelog, and changes may be added which eat your puppy.

Due to the experimental status of this code, all ideas, suggestions, or comments are welcome and encouraged — now is the time to break things!

A Generic Serializable Object

The primary product of this module is a base python object class designed for easy serialization. JSON serialization and de-serialization come for free for attributes of (most of the) core python object types.

A Basic Class:

from amethyst.core import Object, Attr

class MyObject(Object):
    foo = Attr(int)
    bar = Attr(isa=str).strip()

myobj = MyObject( dict(foo=23) )
print(myobj.foo)      # => 23

Validation / Coersion

Important

Attributes are validated and coerced only when processed by certain methods. This is a somewhat controvercial choice, but allows us to only pay the validation costs when loading from external/untrusted sources.

class MyObject(Object):
    amethyst_verifyclass = False  # don't check json for class name
    foo = Attr(int)               # coerce to int
    bar = Attr(isa=str).strip()   # ensure str then strip whitespace

Validated

  • dictionary constructor

    myobj = MyObject({ "foo": "23", "bar": "Hello " })
    print(isinstance(myobj.foo, int))       # True
    print(myobj.bar)                        # "Hello"
    
  • set and load_data methods

    myobj.setdefault("foo", "Not an int")   # Raises exception if foo unset
    myobj.set("foo", "Not an int")          # Raises exception
    
    # Converts and trims
    myobj.load_data({"foo": "23", "bar": "Hello "})
    
  • loading from JSON

    # Converts and trims
    myobj = MyObject.newFromJSON('{"foo": "23", "bar": "Hello "}')
    myobj.fromJSON('{"foo": "23", "bar": "Hello "}')
    

Not Validated

  • kwargs constructor

    myobj = MyObject(foo="23", bar="Hello ")
    print(isinstance(myobj.foo, int))       # False
    print(myobj.bar)                        # "Hello "
    
  • assignment

    myobj.foo = "Not an int"                # Not an exception!
    myobj["foo"] = "Not an int"             # Not an exception!
    
  • update method

    myobj.update(foo="Not an int")          # Not an exception!
    

Serialization

We immediately get instantiation and loading from JSON or from vanilla dictionaries:

myobj = MyObject.newFromJSON(
    '{"foo":23, "bar":" plugh  "}',
    verifyclass=False
)
print(myobj.bar)      # => "plugh"  (spaces stripped)

JSON gets some special treatment, but anything that produces an appropriate dictionary will work for serialization.

myobj = MyObject()
myobj.load_data(yaml.load(open("myobject.yaml")))

By default, import and export try to make sure that the object is a serialization of the correct type of object. Metadata are automatically, injected into the serialization to identify the proper type fo the data. This can be disabled on a per-call basis as seen above with the verifyclass keyword argument, or on a per-class basis by setting some attributes.

This metadata can be encoded in two different ways depending on what you find most convenient for your situation (the “flat” style is the default):

myobj = MyObject(foo=23)

print(myobj.toJSON())     # The default, style="flat"
# => {"__class__": "__mymodule.MyObject__", "foo": 23}

print(myobj.toJSON(style="single-key"))
# => {"__mymodule.MyObject__": {"foo": 23}}

print(myobj.toJSON(includeclass=False))
# => { "foo": 23 }

If you want no munging or class verification at all, set class parameters:

class MyObject(Object):
    amethyst_includeclass  = False
    amethyst_verifyclass   = False

    foo = Attr(int)
    bar = Attr(isa=str).strip()

# No extra class info due to modified defaults:
myobj = MyObject.newFromJSON('{"foo":"23", "bar":" plugh  "}')
print(myobj.toJSON())
# => { "foo": 23, "bar": "plugh" }

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 amethyst-core, version 0.6.4
Filename, size File type Python version Upload date Hashes
Filename, size amethyst_core-0.6.4-py2-none-any.whl (20.8 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size amethyst_core-0.6.4-py3-none-any.whl (20.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size amethyst-core-0.6.4.tar.gz (23.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page