versionedobj
+versionedobj
Contents:
-
@@ -85,24 +85,69 @@
All existing unit tests pass (run tests via
python setup.py test)
@@ -683,7 +728,7 @@ - diff --git a/docs/searchindex.js b/docs/searchindex.js index 14da00f..e9b6f26 100644 --- a/docs/searchindex.js +++ b/docs/searchindex.js @@ -1 +1 @@ -Search.setIndex({"docnames": ["index", "modules", "versionedobj"], "filenames": ["index.rst", "modules.rst", "versionedobj.rst"], "titles": ["versionedobj", "versionedobj", "versionedobj package"], "terms": {"packag": [0, 1], "i": [0, 2], "allow": [0, 2], "complex": 0, "can": [0, 2], "from": [0, 2], "string": [0, 2], "dict": [0, 2], "json": [0, 2], "file": [0, 2], "also": 0, "provid": [0, 2], "mechan": 0, "track": 0, "chang": [0, 2], "structur": 0, "across": 0, "time": [0, 2], "between": 0, "differ": 0, "see": 0, "api": 0, "document": 0, "pip": 0, "defin": [0, 2], "new": 0, "class": [0, 2], "inherit": 0, "versionedobject": [0, 1, 2], "set": [0, 2], "import": 0, "versionedobjbect": [0, 2], "userconfig": 0, "v1": 0, "0": 0, "usernam": 0, "john": 0, "smith": 0, "friend_list": 0, "user1": 0, "user2": 0, "user3": 0, "nest": [0, 2], "simpli": 0, "assign": 0, "anoth": [0, 2], "displayconfig": 0, "display_mod": 0, "window": 0, "resolut": 0, "1920x1080": 0, "volum": 0, "66": 0, "popul": [0, 2], "build": 0, "display_config": 0, "either": 0, "wai": [0, 2], "behav": 0, "same": [0, 2], "The": 0, "serv": 0, "when": 0, "automat": 0, "match": [0, 2], "copi": 0, "over": 0, "obj": [0, 2], "print": 0, "look": 0, "like": 0, "thi": [0, 2], "As": 0, "well": 0, "regular": 0, "dot": 0, "notat": 0, "treat": 0, "individu": 0, "full": 0, "kei": [0, 2], "fullscreen": 0, "iter": 0, "all": [0, 2], "would": 0, "attr_nam": 0, "f": 0, "to_fil": [0, 1, 2], "from_fil": [0, 1, 2], "method": [0, 2], "our": 0, "user_config": 0, "indent": [0, 2], "4": 0, "obj_as_json": 0, "to_json": [0, 1, 2], "from_json": [0, 1, 2], "Or": 0, "obj_as_dict": 0, "to_dict": [0, 1, 2], "from_dict": [0, 1, 2], "For": 0, "conveni": 0, "pass": [0, 2], "futur": 0, "oper": 0, "so": 0, "don": [0, 2], "t": [0, 2], "everi": 0, "shown": 0, "previou": 0, "howev": 0, "requir": [0, 2], "option": 0, "want": [0, 2], "objecta": 0, "ag": 0, "44": 0, "objectb": 0, "last_login_tim": 0, "12345678": 0, "enabl": 0, "fals": [0, 2], "each": 0, "b": 0, "both": [0, 2], "a_jsonstr": 0, "b_jsonstr": 0, "onli": [0, 2], "certain": 0, "paramet": [0, 2], "specifi": 0, "which": 0, "should": [0, 2], "effect": 0, "jane": 0, "doe": 0, "ignor": [0, 2], "exclud": [0, 2], "except": [0, 1], "list": [0, 2], "exactli": 0, "follow": 0, "subclass": 0, "mai": [0, 2], "ad": [0, 2], "valueerror": 0, "rais": [0, 2], "otherwis": [0, 2], "hold": 0, "need": 0, "variabl": [0, 2], "size": 0, "collect": 0, "ar": [0, 2], "runtim": 0, "userdata": 0, "30": 0, "user": 0, "alluserdata": 0, "all_user_data": 0, "add": [0, 2], "some": [0, 2], "append": 0, "initial_valu": [0, 2], "sam": 0, "salli": 0, "28": 0, "out": 0, "If": [0, 2], "back": [0, 2], "fileload": [0, 1, 2], "entri": [0, 2], "return": [0, 2], "exit": [0, 2], "worri": 0, "about": 0, "forget": 0, "re": 0, "done": 0, "recip": 0, "ingredient_1": 0, "onion": 0, "ingredient_2": 0, "tomato": 0, "ingredient_3": 0, "garlic": 0, "alreadi": 0, "exist": [0, 2], "someth": [0, 2], "celeri": 0, "now": 0, "A": 0, "ani": [0, 2], "although": 0, "typic": 0, "e": 0, "g": 0, "3": 0, "support": [0, 2], "older": [0, 2], "event": 0, "format": 0, "let": 0, "": 0, "take": 0, "config": 0, "top": 0, "level": [0, 2], "imagin": 0, "ve": 0, "releas": 0, "code": 0, "world": 0, "peopl": 0, "thei": 0, "gener": [0, 2], "sit": 0, "comput": 0, "featur": 0, "remov": 0, "entir": 0, "float": 0, "delet": 0, "call": [0, 2], "right": 0, "send": 0, "fail": [0, 2], "sinc": 0, "those": 0, "we": 0, "similarli": 0, "gone": 0, "been": 0, "replac": 0, "situat": 0, "what": 0, "becom": 0, "write": [0, 2], "function": [0, 2], "transform": 0, "decor": [0, 2], "regist": [0, 2], "ha": [0, 2], "def": 0, "migrate_100_to_101": 0, "attr": [0, 2], "del": 0, "after": [0, 2], "downsid": 0, "approach": 0, "manual": 0, "udpat": 0, "anytim": 0, "upsid": 0, "cours": 0, "rel": 0, "easili": 0, "current": [0, 2], "just": 0, "never": 0, "run": 0, "where": 0, "later": 0, "handl": [0, 2], "none": [0, 2], "add_migr": [0, 1, 2], "from_vers": [0, 2], "migrate_none_to_100": 0, "actual": [0, 2], "validate_dict": [0, 1, 2], "rcp": 0, "carrot": 0, "inputvalidationerror": [0, 1, 2], "becaus": [0, 2], "miss": [0, 2], "ingredient_12": 0, "cumin": 0, "reset_to_default": [0, 1, 2], "two": 0, "check": 0, "other": 0, "rcp1": 0, "rcp2": 0, "true": [0, 2], "ginger": 0, "In": 0, "order": 0, "consid": 0, "condit": 0, "must": 0, "uniqu": 0, "base": [0, 2], "builtin": 0, "mean": 0, "person": 0, "31": 0, "p1": 0, "p2": 0, "32": 0, "d": 0, "particular": 0, "keyword": 0, "p": 0, "imag": 0, "performance_test": 0, "big_class_performance_test": 0, "py": 0, "script": 0, "increment": 0, "increas": 0, "simultan": 0, "depth": 0, "point": 0, "graph": 0, "repres": 0, "measur": 0, "taken": 0, "It": 0, "worth": 0, "mention": 0, "veri": 0, "case": 0, "addit": 0, "parser": [0, 2], "o": 0, "overhead": 0, "That": 0, "why": 0, "wa": [0, 2], "execut": 0, "system": 0, "intel": 0, "core": 0, "i7": 0, "debian": 0, "gnu": 0, "linux": 0, "10": 0, "buster": 0, "19": 0, "21": 0, "amd64": 0, "welcom": 0, "pleas": 0, "open": 0, "pull": 0, "request": 0, "http": 0, "github": 0, "com": 0, "eriknyquist": 0, "ensur": 0, "unit": 0, "via": 0, "setup": 0, "cover": 0, "code_coverag": 0, "coverag": 0, "abov": 0, "98": 0, "develop": 0, "dev_requir": 0, "txt": 0, "r": 0, "question": 0, "help": 0, "contact": 0, "erik": 0, "eknyquist": 0, "gmail": 0, "index": 0, "modul": [0, 1], "search": 0, "page": 0, "submodul": 1, "object": 1, "customvalu": [1, 2], "migrationresult": [1, 2], "__init__": [1, 2], "migrat": [1, 2], "invalidfiltererror": [1, 2], "invalidversionattributeerror": [1, 2], "loadobjecterror": [1, 2], "serial": 1, "content": 1, "sourc": 2, "abstract": 2, "sub": 2, "you": 2, "deseri": 2, "custom": 2, "standard": 2, "load": 2, "instanc": 2, "valu": 2, "data": 2, "convert": 2, "suitabl": 2, "dump": 2, "singl": 2, "type": 2, "old_vers": 2, "target_vers": 2, "version_reach": 2, "success": 2, "partial": 2, "perform": 2, "version": 2, "befor": 2, "attempt": 2, "target": 2, "bool": 2, "save": 2, "map": 2, "initi": 2, "field": 2, "name": 2, "migration_func": 2, "cl": 2, "to_vers": 2, "an": 2, "us": 2, "one": 2, "equival": 2, "altern": 2, "objbect": 2, "callabl": 2, "previous": 2, "had": 2, "number": 2, "here": 2, "whenev": 2, "valid": 2, "filter": 2, "attribut": 2, "cannot": 2, "error": 2, "instance_or_class": 2, "filenam": 2, "context": 2, "manag": 2, "modifi": 2, "contain": 2, "unset": 2, "instead": 2, "pre": 2, "skip": 2, "input": 2, "mess": 2, "whitelist": 2, "blacklist": 2, "describ": 2, "peform": 2, "were": 2, "str": 2, "pars": 2, "jsonstr": 2, "reset": 2, "default": 2, "librari": 2, "int": 2, "column": 2, "everyth": 2, "line": 2, "form": 2, "against": 2, "found": 2}, "objects": {"": [[2, 0, 0, "-", "versionedobj"]], "versionedobj": [[2, 0, 0, "-", "exceptions"], [2, 0, 0, "-", "object"], [2, 0, 0, "-", "serializer"]], "versionedobj.exceptions": [[2, 1, 1, "", "InputValidationError"], [2, 1, 1, "", "InvalidFilterError"], [2, 1, 1, "", "InvalidVersionAttributeError"], [2, 1, 1, "", "LoadObjectError"]], "versionedobj.object": [[2, 2, 1, "", "CustomValue"], [2, 2, 1, "", "MigrationResult"], [2, 2, 1, "", "VersionedObject"], [2, 4, 1, "", "add_migration"], [2, 4, 1, "", "migration"]], "versionedobj.object.CustomValue": [[2, 3, 1, "", "from_dict"], [2, 3, 1, "", "to_dict"]], "versionedobj.object.MigrationResult": [[2, 3, 1, "", "__init__"]], "versionedobj.object.VersionedObject": [[2, 3, 1, "", "__init__"]], "versionedobj.serializer": [[2, 2, 1, "", "FileLoader"], [2, 2, 1, "", "Serializer"]], "versionedobj.serializer.FileLoader": [[2, 3, 1, "", "__init__"]], "versionedobj.serializer.Serializer": [[2, 3, 1, "", "__init__"], [2, 3, 1, "", "from_dict"], [2, 3, 1, "", "from_file"], [2, 3, 1, "", "from_json"], [2, 3, 1, "", "reset_to_defaults"], [2, 3, 1, "", "to_dict"], [2, 3, 1, "", "to_file"], [2, 3, 1, "", "to_json"], [2, 3, 1, "", "validate_dict"]]}, "objtypes": {"0": "py:module", "1": "py:exception", "2": "py:class", "3": "py:method", "4": "py:function"}, "objnames": {"0": ["py", "module", "Python module"], "1": ["py", "exception", "Python exception"], "2": ["py", "class", "Python class"], "3": ["py", "method", "Python method"], "4": ["py", "function", "Python function"]}, "titleterms": {"versionedobj": [0, 1, 2], "content": [0, 2], "object": [0, 2], "serial": [0, 2], "version": 0, "framework": 0, "python": 0, "3x": 0, "instal": 0, "get": 0, "start": 0, "definit": 0, "creat": 0, "instanc": 0, "access": 0, "attribut": 0, "de": 0, "us": 0, "one": 0, "multipl": 0, "type": 0, "filter": 0, "deseri": 0, "output": 0, "whitelist": 0, "field": 0, "name": 0, "blacklist": 0, "listfield": 0, "store": 0, "sequenc": 0, "singl": 0, "context": 0, "manag": 0, "load": 0, "edit": 0, "save": 0, "data": 0, "migrat": 0, "make": 0, "number": 0, "exampl": 0, "scenario": 0, "part": 0, "1": 0, "you": 0, "have": 0, "beauti": 0, "2": 0, "updat": 0, "your": 0, "softwar": 0, "modifi": 0, "uh": 0, "oh": 0, "problem": 0, "solut": 0, "an": 0, "unvers": 0, "valid": 0, "input": 0, "without": 0, "reset": 0, "default": 0, "valu": 0, "test": 0, "equal": 0, "hash": 0, "whether": 0, "contain": 0, "specif": 0, "perform": 0, "stress": 0, "visual": 0, "contribut": 0, "indic": 0, "tabl": 0, "packag": 2, "submodul": 2, "modul": 2, "except": 2}, "envversion": {"sphinx.domains.c": 2, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 8, "sphinx.domains.index": 1, "sphinx.domains.javascript": 2, "sphinx.domains.math": 2, "sphinx.domains.python": 3, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.viewcode": 1, "sphinx": 57}, "alltitles": {"versionedobj": [[1, "versionedobj"], [0, "versionedobj"]], "versionedobj package": [[2, "versionedobj-package"]], "Submodules": [[2, "submodules"]], "versionedobj.object module": [[2, "module-versionedobj.object"]], "versionedobj.exceptions module": [[2, "module-versionedobj.exceptions"]], "versionedobj.serializer module": [[2, "module-versionedobj.serializer"]], "Module contents": [[2, "module-versionedobj"]], "Contents:": [[0, null]], "Object serialization & versioning framework for python 3x": [[0, "object-serialization-versioning-framework-for-python-3x"]], "Installing": [[0, "installing"]], "Getting started": [[0, "getting-started"]], "Object definition": [[0, "object-definition"]], "Creating object instances and accessing object attributes": [[0, "creating-object-instances-and-accessing-object-attributes"]], "Serializing and de-serializing": [[0, "serializing-and-de-serializing"]], "Using one Serializer instance with multiple object types": [[0, "using-one-serializer-instance-with-multiple-object-types"]], "Filtering serialization/deserialization output": [[0, "filtering-serialization-deserialization-output"]], "Whitelisting by field name": [[0, "whitelisting-by-field-name"]], "Blacklisting by field name": [[0, "blacklisting-by-field-name"]], "versionedobj.ListField: store a sequence of objects in a single field": [[0, "versionedobj-listfield-store-a-sequence-of-objects-in-a-single-field"]], "Context manager for loading & editing saved object data": [[0, "context-manager-for-loading-editing-saved-object-data"]], "Migrations: making use of the version number": [[0, "migrations-making-use-of-the-version-number"]], "Example scenario, part 1: you have created a beautiful versioned object": [[0, "example-scenario-part-1-you-have-created-a-beautiful-versioned-object"]], "Example scenario, part 2: you update your software, modifying the versioned object": [[0, "example-scenario-part-2-you-update-your-software-modifying-the-versioned-object"]], "Uh-oh, you have a problem\u2026": [[0, "uh-oh-you-have-a-problem"]], "Solution\u2013 migrations!": [[0, "solution-migrations"]], "Migrations: migrating an unversioned object": [[0, "migrations-migrating-an-unversioned-object"]], "Validating input data without deserializing": [[0, "validating-input-data-without-deserializing"]], "Resetting object instance to default values": [[0, "resetting-object-instance-to-default-values"]], "Testing object instance equality": [[0, "testing-object-instance-equality"]], "Object instance hashing": [[0, "object-instance-hashing"]], "Testing whether object instances contain specific values": [[0, "testing-whether-object-instances-contain-specific-values"]], "Performance/stress test visualization": [[0, "performance-stress-test-visualization"]], "Contributions": [[0, "contributions"]], "Indices and tables": [[0, "indices-and-tables"]]}, "indexentries": {"customvalue (class in versionedobj.object)": [[2, "versionedobj.object.CustomValue"]], "fileloader (class in versionedobj.serializer)": [[2, "versionedobj.serializer.FileLoader"]], "inputvalidationerror": [[2, "versionedobj.exceptions.InputValidationError"]], "invalidfiltererror": [[2, "versionedobj.exceptions.InvalidFilterError"]], "invalidversionattributeerror": [[2, "versionedobj.exceptions.InvalidVersionAttributeError"]], "loadobjecterror": [[2, "versionedobj.exceptions.LoadObjectError"]], "migrationresult (class in versionedobj.object)": [[2, "versionedobj.object.MigrationResult"]], "serializer (class in versionedobj.serializer)": [[2, "versionedobj.serializer.Serializer"]], "versionedobject (class in versionedobj.object)": [[2, "versionedobj.object.VersionedObject"]], "__init__() (versionedobj.object.migrationresult method)": [[2, "versionedobj.object.MigrationResult.__init__"]], "__init__() (versionedobj.object.versionedobject method)": [[2, "versionedobj.object.VersionedObject.__init__"]], "__init__() (versionedobj.serializer.fileloader method)": [[2, "versionedobj.serializer.FileLoader.__init__"]], "__init__() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.__init__"]], "add_migration() (in module versionedobj.object)": [[2, "versionedobj.object.add_migration"]], "from_dict() (versionedobj.object.customvalue method)": [[2, "versionedobj.object.CustomValue.from_dict"]], "from_dict() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.from_dict"]], "from_file() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.from_file"]], "from_json() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.from_json"]], "migration() (in module versionedobj.object)": [[2, "versionedobj.object.migration"]], "module": [[2, "module-versionedobj"], [2, "module-versionedobj.exceptions"], [2, "module-versionedobj.object"], [2, "module-versionedobj.serializer"]], "reset_to_defaults() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.reset_to_defaults"]], "to_dict() (versionedobj.object.customvalue method)": [[2, "versionedobj.object.CustomValue.to_dict"]], "to_dict() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.to_dict"]], "to_file() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.to_file"]], "to_json() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.to_json"]], "validate_dict() (versionedobj.serializer.serializer method)": [[2, "versionedobj.serializer.Serializer.validate_dict"]], "versionedobj": [[2, "module-versionedobj"]], "versionedobj.exceptions": [[2, "module-versionedobj.exceptions"]], "versionedobj.object": [[2, "module-versionedobj.object"]], "versionedobj.serializer": [[2, "module-versionedobj.serializer"]]}}) \ No newline at end of file +Search.setIndex({"docnames": ["index", "modules", "versionedobj"], "filenames": ["index.rst", "modules.rst", "versionedobj.rst"], "titles": ["versionedobj", "versionedobj", "versionedobj package"], "terms": {"packag": [0, 1], "i": [0, 2], "allow": [0, 2], "complex": 0, "can": [0, 2], "from": [0, 2], "string": [0, 2], "dict": [0, 2], "json": [0, 2], "file": [0, 2], "also": 0, "provid": [0, 2], "mechan": 0, "track": 0, "chang": [0, 2], "structur": 0, "across": 0, "time": [0, 2], "between": 0, "differ": 0, "see": 0, "api": 0, "document": 0, "pip": 0, "defin": [0, 2], "new": 0, "class": [0, 2], "inherit": 0, "versionedobject": [0, 1, 2], "set": [0, 2], "import": 0, "versionedobjbect": [0, 2], "userconfig": 0, "v1": 0, "0": 0, "usernam": 0, "john": 0, "smith": 0, "friend_list": 0, "user1": 0, "user2": 0, "user3": 0, "nest": [0, 2], "simpli": 0, "assign": 0, "anoth": [0, 2], "displayconfig": 0, "display_mod": 0, "window": 0, "resolut": 0, "1920x1080": 0, "volum": 0, "66": 0, "popul": [0, 2], "build": 0, "display_config": 0, "either": 0, "wai": [0, 2], "behav": 0, "same": [0, 2], "The": 0, "serv": 0, "when": 0, "automat": 0, "match": [0, 2], "copi": 0, "over": 0, "obj": [0, 2], "print": 0, "look": 0, "like": 0, "thi": [0, 2], "As": 0, "well": 0, "regular": 0, "dot": 0, "notat": 0, "treat": 0, "individu": 0, "full": 0, "kei": [0, 2], "fullscreen": 0, "iter": 0, "all": [0, 2], "would": 0, "attr_nam": 0, "f": 0, "to_fil": [0, 1, 2], "from_fil": [0, 1, 2], "method": [0, 2], "our": 0, "user_config": 0, "indent": [0, 2], "4": 0, "obj_as_json": 0, "to_json": [0, 1, 2], "from_json": [0, 1, 2], "Or": 0, "obj_as_dict": 0, "to_dict": [0, 1, 2], "from_dict": [0, 1, 2], "For": 0, "conveni": 0, "pass": [0, 2], "futur": 0, "oper": 0, "so": 0, "don": [0, 2], "t": [0, 2], "everi": 0, "shown": 0, "previou": 0, "howev": 0, "requir": [0, 2], "option": 0, "want": [0, 2], "objecta": 0, "ag": 0, "44": 0, "objectb": 0, "last_login_tim": 0, "12345678": 0, "enabl": 0, "fals": [0, 2], "each": 0, "b": 0, "both": [0, 2], "a_jsonstr": 0, "b_jsonstr": 0, "onli": [0, 2], "certain": 0, "paramet": [0, 2], "specifi": 0, "which": 0, "should": [0, 2], "effect": 0, "jane": 0, "doe": 0, "ignor": [0, 2], "exclud": [0, 2], "except": [0, 1], "list": [0, 2], "exactli": 0, "follow": 0, "subclass": 0, "mai": [0, 2], "ad": [0, 2], "valueerror": 0, "rais": [0, 2], "otherwis": [0, 2], "hold": 0, "need": 0, "variabl": [0, 2], "size": 0, "collect": 0, "ar": [0, 2], "runtim": 0, "userdata": 0, "30": 0, "user": 0, "alluserdata": 0, "all_user_data": 0, "add": [0, 2], "some": [0, 2], "append": 0, "initial_valu": [0, 2], "sam": 0, "salli": 0, "28": 0, "out": 0, "If": [0, 2], "back": [0, 2], "fileload": [0, 1, 2], "entri": [0, 2], "return": [0, 2], "exit": [0, 2], "worri": 0, "about": 0, "forget": 0, "re": 0, "done": 0, "recip": 0, "ingredient_1": 0, "onion": 0, "ingredient_2": 0, "tomato": 0, "ingredient_3": 0, "garlic": 0, "alreadi": 0, "exist": [0, 2], "someth": [0, 2], "celeri": 0, "now": 0, "A": 0, "ani": [0, 2], "although": 0, "typic": 0, "e": 0, "g": 0, "3": 0, "support": [0, 2], "older": [0, 2], "event": 0, "format": 0, "let": 0, "": 0, "take": 0, "config": 0, "top": 0, "level": [0, 2], "imagin": 0, "ve": 0, "releas": 0, "code": 0, "world": 0, "peopl": 0, "thei": 0, "gener": [0, 2], "sit": 0, "comput": 0, "featur": 0, "remov": 0, "entir": 0, "float": 0, "delet": 0, "call": [0, 2], "right": 0, "send": 0, "fail": [0, 2], "sinc": 0, "those": 0, "we": 0, "similarli": 0, "gone": 0, "been": 0, "replac": 0, "situat": 0, "what": 0, "becom": 0, "write": [0, 2], "function": [0, 2], "transform": 0, "decor": [0, 2], "regist": [0, 2], "ha": [0, 2], "def": 0, "migrate_100_to_101": 0, "attr": [0, 2], "del": 0, "after": [0, 2], "downsid": 0, "approach": 0, "manual": 0, "udpat": 0, "anytim": 0, "upsid": 0, "cours": 0, "rel": 0, "easili": 0, "current": [0, 2], "just": 0, "never": 0, "run": 0, "where": 0, "later": 0, "handl": [0, 2], "none": [0, 2], "add_migr": [0, 1, 2], "from_vers": [0, 2], "migrate_none_to_100": 0, "actual": [0, 2], "validate_dict": [0, 1, 2], "rcp": 0, "carrot": 0, "inputvalidationerror": [0, 1, 2], "becaus": [0, 2], "miss": [0, 2], "ingredient_12": 0, "cumin": 0, "reset_to_default": [0, 1, 2], "two": 0, "check": 0, "other": 0, "rcp1": 0, "rcp2": 0, "true": [0, 2], "ginger": 0, "In": 0, "order": 0, "consid": 0, "condit": 0, "must": 0, "uniqu": 0, "base": [0, 2], "builtin": 0, "mean": 0, "person": 0, "31": 0, "p1": 0, "p2": 0, "32": 0, "d": 0, "particular": 0, "keyword": 0, "p": 0, "imag": 0, "performance_test": 0, "big_class_performance_test": 0, "py": 0, "script": 0, "increment": 0, "increas": 0, "simultan": 0, "depth": 0, "point": 0, "graph": 0, "repres": 0, "measur": 0, "taken": 0, "It": 0, "worth": 0, "mention": 0, "veri": 0, "case": 0, "addit": 0, "parser": [0, 2], "o": 0, "overhead": 0, "That": 0, "why": 0, "wa": [0, 2], "execut": 0, "system": 0, "intel": 0, "core": 0, "i7": 0, "debian": 0, "gnu": 0, "linux": 0, "10": 0, "buster": 0, "19": 0, "21": 0, "amd64": 0, "welcom": 0, "pleas": 0, "open": 0, "pull": 0, "request": 0, "http": 0, "github": 0, "com": 0, "eriknyquist": 0, "ensur": 0, "unit": 0, "via": 0, "setup": 0, "cover": 0, "code_coverag": 0, "coverag": 0, "abov": 0, "98": 0, "develop": 0, "dev_requir": 0, "txt": 0, "r": 0, "question": 0, "help": 0, "contact": 0, "erik": 0, "eknyquist": 0, "gmail": 0, "index": 0, "modul": [0, 1], "search": 0, "page": 0, "submodul": 1, "object": 1, "customvalu": [1, 2], "migrationresult": [1, 2], "__init__": [1, 2], "migrat": [1, 2], "invalidfiltererror": [1, 2], "invalidversionattributeerror": [1, 2], "loadobjecterror": [1, 2], "serial": 1, "content": 1, "sourc": 2, "abstract": 2, "sub": 2, "you": 2, "deseri": 2, "custom": 2, "standard": 2, "load": 2, "instanc": 2, "valu": 2, "data": 2, "convert": 2, "suitabl": 2, "dump": 2, "singl": 2, "type": 2, "old_vers": 2, "target_vers": 2, "version_reach": 2, "success": 2, "partial": 2, "perform": 2, "version": 2, "befor": 2, "attempt": 2, "target": 2, "bool": 2, "save": 2, "map": 2, "initi": 2, "field": 2, "name": 2, "migration_func": 2, "cl": 2, "to_vers": 2, "an": 2, "us": 2, "one": 2, "equival": 2, "altern": 2, "objbect": 2, "callabl": 2, "previous": 2, "had": 2, "number": 2, "here": 2, "whenev": 2, "valid": 2, "filter": 2, "attribut": 2, "cannot": 2, "error": 2, "instance_or_class": 2, "filenam": 2, "context": 2, "manag": 2, "modifi": 2, "contain": 2, "unset": 2, "instead": 2, "pre": 2, "skip": 2, "input": 2, "mess": 2, "whitelist": 2, "blacklist": 2, "describ": 2, "peform": 2, "were": 2, "str": 2, "pars": 2, "jsonstr": 2, "reset": 2, "default": 2, "librari": 2, "int": 2, "column": 2, "everyth": 2, "line": 2, "form": 2, "against": 2, "found": 2}, "objects": {"": [[2, 0, 0, "-", "versionedobj"]], "versionedobj": [[2, 0, 0, "-", "exceptions"], [2, 0, 0, "-", "object"], [2, 0, 0, "-", "serializer"]], "versionedobj.exceptions": [[2, 1, 1, "", "InputValidationError"], [2, 1, 1, "", "InvalidFilterError"], [2, 1, 1, "", "InvalidVersionAttributeError"], [2, 1, 1, "", "LoadObjectError"]], "versionedobj.object": [[2, 2, 1, "", "CustomValue"], [2, 2, 1, "", "MigrationResult"], [2, 2, 1, "", "VersionedObject"], [2, 4, 1, "", "add_migration"], [2, 4, 1, "", "migration"]], "versionedobj.object.CustomValue": [[2, 3, 1, "", "from_dict"], [2, 3, 1, "", "to_dict"]], "versionedobj.object.MigrationResult": [[2, 3, 1, "", "__init__"]], "versionedobj.object.VersionedObject": [[2, 3, 1, "", "__init__"]], "versionedobj.serializer": [[2, 2, 1, "", "FileLoader"], [2, 2, 1, "", "Serializer"]], "versionedobj.serializer.FileLoader": [[2, 3, 1, "", "__init__"]], "versionedobj.serializer.Serializer": [[2, 3, 1, "", "__init__"], [2, 3, 1, "", "from_dict"], [2, 3, 1, "", "from_file"], [2, 3, 1, "", "from_json"], [2, 3, 1, "", "reset_to_defaults"], [2, 3, 1, "", "to_dict"], [2, 3, 1, "", "to_file"], [2, 3, 1, "", "to_json"], [2, 3, 1, "", "validate_dict"]]}, "objtypes": {"0": "py:module", "1": "py:exception", "2": "py:class", "3": "py:method", "4": "py:function"}, "objnames": {"0": ["py", "module", "Python module"], "1": ["py", "exception", "Python exception"], "2": ["py", "class", "Python class"], "3": ["py", "method", "Python method"], "4": ["py", "function", "Python function"]}, "titleterms": {"versionedobj": [0, 1, 2], "content": [0, 2], "object": [0, 2], "serial": [0, 2], "version": 0, "framework": 0, "python": 0, "3x": 0, "instal": 0, "get": 0, "start": 0, "definit": 0, "creat": 0, "instanc": 0, "access": 0, "attribut": 0, "de": 0, "us": 0, "one": 0, "multipl": 0, "type": 0, "filter": 0, "deseri": 0, "output": 0, "whitelist": 0, "field": 0, "name": 0, "blacklist": 0, "listfield": 0, "store": 0, "sequenc": 0, "singl": 0, "context": 0, "manag": 0, "load": 0, "edit": 0, "save": 0, "data": 0, "migrat": 0, "make": 0, "number": 0, "exampl": 0, "scenario": 0, "part": 0, "1": 0, "you": 0, "have": 0, "beauti": 0, "2": 0, "updat": 0, "your": 0, "softwar": 0, "modifi": 0, "uh": 0, "oh": 0, "problem": 0, "solut": 0, "an": 0, "unvers": 0, "valid": 0, "input": 0, "without": 0, "reset": 0, "default": 0, "valu": 0, "test": 0, "equal": 0, "hash": 0, "whether": 0, "contain": 0, "specif": 0, "perform": 0, "stress": 0, "visual": 0, "contribut": 0, "indic": 0, "tabl": 0, "packag": 2, "submodul": 2, "modul": 2, "except": 2}, "envversion": {"sphinx.domains.c": 2, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 8, "sphinx.domains.index": 1, "sphinx.domains.javascript": 2, "sphinx.domains.math": 2, "sphinx.domains.python": 3, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.viewcode": 1, "sphinx": 57}, "alltitles": {"versionedobj": [[1, "versionedobj"], [0, "versionedobj"]], "versionedobj package": [[2, "versionedobj-package"]], "Submodules": [[2, "submodules"]], "versionedobj.object module": [[2, "module-versionedobj.object"]], "versionedobj.exceptions module": [[2, "module-versionedobj.exceptions"]], "versionedobj.serializer module": [[2, "module-versionedobj.serializer"]], "Module contents": [[2, "module-versionedobj"]], "Contents:": [[0, null]], "Object serialization & versioning framework for python 3x": [[0, "object-serialization-versioning-framework-for-python-3x"]], "Table of Contents": [[0, "table-of-contents"]], "Installing": [[0, "installing"]], "Getting started": [[0, "getting-started"]], "Object definition": [[0, "object-definition"]], "Creating object instances and accessing object attributes": [[0, "creating-object-instances-and-accessing-object-attributes"]], "Serializing and de-serializing": [[0, "serializing-and-de-serializing"]], "Using one Serializer instance with multiple object types": [[0, "using-one-serializer-instance-with-multiple-object-types"]], "Filtering serialization/deserialization output": [[0, "filtering-serialization-deserialization-output"]], "Whitelisting by field name": [[0, "whitelisting-by-field-name"]], "Blacklisting by field name": [[0, "blacklisting-by-field-name"]], "versionedobj.ListField: store a sequence of objects in a single field": [[0, "versionedobj-listfield-store-a-sequence-of-objects-in-a-single-field"]], "Context manager for loading & editing saved object data": [[0, "context-manager-for-loading-editing-saved-object-data"]], "Migrations: making use of the version number": [[0, "migrations-making-use-of-the-version-number"]], "Example scenario, part 1: you have created a beautiful versioned object": [[0, "example-scenario-part-1-you-have-created-a-beautiful-versioned-object"]], "Example scenario, part 2: you update your software, modifying the versioned object": [[0, "example-scenario-part-2-you-update-your-software-modifying-the-versioned-object"]], "Uh-oh, you have a problem\u2026": [[0, "uh-oh-you-have-a-problem"]], "Solution\u2013 migrations!": [[0, "solution-migrations"]], "Migrations: migrating an unversioned object": [[0, "migrations-migrating-an-unversioned-object"]], "Validating input data without deserializing": [[0, "validating-input-data-without-deserializing"]], "Resetting object instance to default values": [[0, "resetting-object-instance-to-default-values"]], "Testing object instance equality": [[0, "testing-object-instance-equality"]], "Object instance hashing": [[0, "object-instance-hashing"]], "Testing whether object instances contain specific values": [[0, "testing-whether-object-instances-contain-specific-values"]], "Performance/stress test visualization": [[0, "performance-stress-test-visualization"]], "Contributions": [[0, "contributions"]], "Indices and tables": [[0, "indices-and-tables"]]}, "indexentries": {}}) \ No newline at end of file
versionedobj
-Object serialization & versioning framework for python 3x
+Object serialization & versioning framework for python 3x
+
versionedobj is an object serialization framework that allows you to create
complex python objects that can be serialized/deserialized to and from strings,
or dicts, or JSON files.
versionedobj also provides a versioning mechanism, to track changes in object
structure across time, and to migrate between different object versions.
+
-Installing
+Installing
Install versionedobj using pip:
pip install versionedobj
-Getting started
+Getting started
-Object definition
+Object definition
Define objects by creating a new class that inherits from VersionedObject,
and set class attributes to define your object attributes:
from versionedobj import VersionedObjbect
@@ -137,7 +182,7 @@ Object definition
-Creating object instances and accessing object attributes
+Creating object instances and accessing object attributes
The values you set on the class attributes of a VersionedObject serve as the default
values for that object. When you create an instance of your VersionedObject class,
instance attributes will automatically be created to match the class attributes, and
@@ -183,7 +228,7 @@
Creating object instances and accessing object attributes
-Serializing and de-serializing
+Serializing and de-serializing
Create an instance of the versionedobj.Serializer class, and use the to_file
and from_file methods to serialize/deserialize data to/from a JSON file:
from versionedobj import VersionedObject, Serializer
@@ -231,7 +276,7 @@ Serializing and de-serializing
-Using one Serializer instance with multiple object types
+Using one Serializer instance with multiple object types
For convenience, you can pass an object instance when you create a versionedobj.Serializer,
and this object will be used for all future serialization/deserialization operations,
so that you don’t have to pass in the object instance every time (as shown in previous
@@ -265,9 +310,9 @@
Using one Serializer instance with multiple object types
-Filtering serialization/deserialization output
+Filtering serialization/deserialization output
-Whitelisting by field name
+Whitelisting by field name
When serializing, if you only want to output certain fields, you can use the ‘only’
parameter to specify which fields should be output (effectively a whitelist by field name):
serializer.to_file('user_config.json', only=['version', 'username', 'display_config.resolution'])
@@ -291,7 +336,7 @@ Whitelisting by field name
-Blacklisting by field name
+Blacklisting by field name
When serializing, if you don’t want to output certain fields, you can use the ‘ignore’
parameter to specify which fields should be excluded from output (effectively a blacklist
by field name):
@@ -318,7 +363,7 @@ Blacklisting by field name
-versionedobj.ListField: store a sequence of objects in a single field
+versionedobj.ListField: store a sequence of objects in a single field
versionedobj.ListField is a list class that behaves exactly like a regular python list,
except for the following 2 differences:
@@ -368,7 +413,7 @@ versionedobj.ListField: store a sequence of objects in a single field
-Context manager for loading & editing saved object data
+Context manager for loading & editing saved object data
If you want to load object data from a JSON file, make some changes to the data,
and save it back to the same JSON file, then you can use the FileLoader context
manager, which will load/create the file for you on entry, return a deserialized
@@ -399,13 +444,13 @@
Context manager for loading & editing saved object data
-Migrations: making use of the version number
+Migrations: making use of the version number
A VersionedObject object can have a version attribute, which can be any object,
although it is typically a string (e.g. "v1.2.3"). This version attribute can be
used to support migrations for older objects, in the event that you need to
change the format of your object.
-Example scenario, part 1: you have created a beautiful versioned object
+Example scenario, part 1: you have created a beautiful versioned object
Let’s take the same config file definition from the previous example:
from versionedobj import VersionedObject
@@ -428,7 +473,7 @@ Example scenario, part 1: you have created a beautiful versioned object
-Example scenario, part 2: you update your software, modifying the versioned object
+Example scenario, part 2: you update your software, modifying the versioned object
Now, imagine you are making a new release of your software, and some new features
require you to make the following changes to your versioned object:
@@ -454,7 +499,7 @@ Example scenario, part 2: you update your software, modifying the versioned
-Uh-oh, you have a problem…
+Uh-oh, you have a problem…
Right now, if you send this updated UserConfig class to your existing users, it will fail
to load their existing JSON files with version v1.0.0, since those files will contain
the DisplayConfig.resolution field that we deleted in v1.0.1, and
@@ -462,7 +507,7 @@
Uh-oh, you have a problem…DisplayConfig.volumes. This situation is what migrations are for.
-Solution– migrations!
+Solution– migrations!
The solution is to:
-Migrations: migrating an unversioned object
+Migrations: migrating an unversioned object
You may run into a situation where you release an unversioned object, but then
later you need to make changes, and migrate an unversioned object to a versioned object.
This can be handled simply by passing “None” to the “add_migration()” method, for the
@@ -525,7 +570,7 @@
Migrations: migrating an unversioned object
-Validating input data without deserializing
+Validating input data without deserializing
You may want to validate some serialized object data without actually deserializing
and loading the object values. You can use the Serializer.validate_dict method for this.
from versionedobj import VersionedObject, Serializer
@@ -547,7 +592,7 @@ Validating input data without deserializing
-Resetting object instance to default values
+Resetting object instance to default values
You can use the Serializer.reset_to_defaults method to set all instance attributes to
the default values defined in the matching class attributes.
from versionedobj import VersionedObject, Serializer
@@ -575,7 +620,7 @@ Resetting object instance to default values
-Testing object instance equality
+Testing object instance equality
You can test whether two VersionedObject instances are equal in both structure and
values, the same way in which you would check equality of any other two objects:
from versionedobj import VersionedObject
@@ -605,7 +650,7 @@ Testing object instance equality
-Object instance hashing
+Object instance hashing
Objects can be uniquely hashed based on their instance attribute values, using the builtin
hash() function. This means, for example, that you can use object instances as dict keys:
from versionedobj import VersionedObject
@@ -627,7 +672,7 @@ Object instance hashing
-Testing whether object instances contain specific values
+Testing whether object instances contain specific values
You can check whether an object instance contains a particular attribute value using the in
keyword:
from versionedobj import VersionedObject
@@ -652,7 +697,7 @@ Testing whether object instances contain specific values
-Performance/stress test visualization
+Performance/stress test visualization
The following image is generated by the tests/performance_tests/big_class_performance_test.py script,
which creates and serializes/deserializes multiple versioned objects of an incrementally increasing size,
and simultaneously having an increasing depth of contained nested objects.
@@ -667,7 +712,7 @@ Performance/stress test visualization
-Contributions
+Contributions
Contributions are welcome, please open a pull request at https://github.com/eriknyquist/versionedobj and ensure that:
Contributions
-Indices and tables
+Indices and tables
Installing
+Installing
Install versionedobj using pip:
pip install versionedobj
Getting started
+Getting started
Object definition
+Object definition
Define objects by creating a new class that inherits from VersionedObject,
and set class attributes to define your object attributes:
from versionedobj import VersionedObjbect
@@ -137,7 +182,7 @@ Object definition
-Creating object instances and accessing object attributes
+Creating object instances and accessing object attributes
The values you set on the class attributes of a VersionedObject serve as the default
values for that object. When you create an instance of your VersionedObject class,
instance attributes will automatically be created to match the class attributes, and
@@ -183,7 +228,7 @@
Creating object instances and accessing object attributes
-Serializing and de-serializing
+Serializing and de-serializing
Create an instance of the versionedobj.Serializer class, and use the to_file
and from_file methods to serialize/deserialize data to/from a JSON file:
from versionedobj import VersionedObject, Serializer
@@ -231,7 +276,7 @@ Serializing and de-serializing
-Using one Serializer instance with multiple object types
+Using one Serializer instance with multiple object types
For convenience, you can pass an object instance when you create a versionedobj.Serializer,
and this object will be used for all future serialization/deserialization operations,
so that you don’t have to pass in the object instance every time (as shown in previous
@@ -265,9 +310,9 @@
Using one Serializer instance with multiple object types
-Filtering serialization/deserialization output
+Filtering serialization/deserialization output
-Whitelisting by field name
+Whitelisting by field name
When serializing, if you only want to output certain fields, you can use the ‘only’
parameter to specify which fields should be output (effectively a whitelist by field name):
serializer.to_file('user_config.json', only=['version', 'username', 'display_config.resolution'])
@@ -291,7 +336,7 @@ Whitelisting by field name
-Blacklisting by field name
+Blacklisting by field name
When serializing, if you don’t want to output certain fields, you can use the ‘ignore’
parameter to specify which fields should be excluded from output (effectively a blacklist
by field name):
@@ -318,7 +363,7 @@ Blacklisting by field name
-versionedobj.ListField: store a sequence of objects in a single field
+versionedobj.ListField: store a sequence of objects in a single field
versionedobj.ListField is a list class that behaves exactly like a regular python list,
except for the following 2 differences:
@@ -368,7 +413,7 @@ versionedobj.ListField: store a sequence of objects in a single field
-Context manager for loading & editing saved object data
+Context manager for loading & editing saved object data
If you want to load object data from a JSON file, make some changes to the data,
and save it back to the same JSON file, then you can use the FileLoader context
manager, which will load/create the file for you on entry, return a deserialized
@@ -399,13 +444,13 @@
Context manager for loading & editing saved object data
-Migrations: making use of the version number
+Migrations: making use of the version number
A VersionedObject object can have a version attribute, which can be any object,
although it is typically a string (e.g. "v1.2.3"). This version attribute can be
used to support migrations for older objects, in the event that you need to
change the format of your object.
-Example scenario, part 1: you have created a beautiful versioned object
+Example scenario, part 1: you have created a beautiful versioned object
Let’s take the same config file definition from the previous example:
from versionedobj import VersionedObject
@@ -428,7 +473,7 @@ Example scenario, part 1: you have created a beautiful versioned object
-Example scenario, part 2: you update your software, modifying the versioned object
+Example scenario, part 2: you update your software, modifying the versioned object
Now, imagine you are making a new release of your software, and some new features
require you to make the following changes to your versioned object:
@@ -454,7 +499,7 @@ Example scenario, part 2: you update your software, modifying the versioned
-Uh-oh, you have a problem…
+Uh-oh, you have a problem…
Right now, if you send this updated UserConfig class to your existing users, it will fail
to load their existing JSON files with version v1.0.0, since those files will contain
the DisplayConfig.resolution field that we deleted in v1.0.1, and
@@ -462,7 +507,7 @@
Uh-oh, you have a problem…DisplayConfig.volumes. This situation is what migrations are for.
-Solution– migrations!
+Solution– migrations!
The solution is to:
-Migrations: migrating an unversioned object
+Migrations: migrating an unversioned object
You may run into a situation where you release an unversioned object, but then
later you need to make changes, and migrate an unversioned object to a versioned object.
This can be handled simply by passing “None” to the “add_migration()” method, for the
@@ -525,7 +570,7 @@
Migrations: migrating an unversioned object
-Validating input data without deserializing
+Validating input data without deserializing
You may want to validate some serialized object data without actually deserializing
and loading the object values. You can use the Serializer.validate_dict method for this.
from versionedobj import VersionedObject, Serializer
@@ -547,7 +592,7 @@ Validating input data without deserializing
-Resetting object instance to default values
+Resetting object instance to default values
You can use the Serializer.reset_to_defaults method to set all instance attributes to
the default values defined in the matching class attributes.
from versionedobj import VersionedObject, Serializer
@@ -575,7 +620,7 @@ Resetting object instance to default values
-Testing object instance equality
+Testing object instance equality
You can test whether two VersionedObject instances are equal in both structure and
values, the same way in which you would check equality of any other two objects:
from versionedobj import VersionedObject
@@ -605,7 +650,7 @@ Testing object instance equality
-Object instance hashing
+Object instance hashing
Objects can be uniquely hashed based on their instance attribute values, using the builtin
hash() function. This means, for example, that you can use object instances as dict keys:
from versionedobj import VersionedObject
@@ -627,7 +672,7 @@ Object instance hashing
-Testing whether object instances contain specific values
+Testing whether object instances contain specific values
You can check whether an object instance contains a particular attribute value using the in
keyword:
from versionedobj import VersionedObject
@@ -652,7 +697,7 @@ Testing whether object instances contain specific values
-Performance/stress test visualization
+Performance/stress test visualization
The following image is generated by the tests/performance_tests/big_class_performance_test.py script,
which creates and serializes/deserializes multiple versioned objects of an incrementally increasing size,
and simultaneously having an increasing depth of contained nested objects.
@@ -667,7 +712,7 @@ Performance/stress test visualization
-Contributions
+Contributions
Contributions are welcome, please open a pull request at https://github.com/eriknyquist/versionedobj and ensure that:
Contributions
-Indices and tables
+Indices and tables