Skip to content

Commit f51dc32

Browse files
eriknyquisteriknyquist
committed
Update README
1 parent 0ca46d1 commit f51dc32

File tree

1 file changed

+75
-94
lines changed

1 file changed

+75
-94
lines changed

‎README.rst

Lines changed: 75 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,26 @@ Install ``versionedobj`` using pip:
2020

2121
pip install versionedobj
2222

23-
Example-- VersionedObject as a configuration file
24-
-------------------------------------------------
23+
Getting started
24+
---------------
25+
26+
Object definition
27+
*****************
28+
29+
Define objects by creating a new class that inherits from ``VersionedObject``,
30+
and set class attributes to define your object attribubtes:
31+
32+
.. code:: python
33+
34+
from versionedobj import VersionedObjbect
35+
36+
class UserConfig(VersionedObject):
37+
version = "v1.0.0"
38+
username = "john smith"
39+
friend_list = ["user1", "user2", "user3"]
40+
41+
You can also nest VersionedObjects by simply assigning another ``VersionedObject``
42+
class or instance object to a class attribute:
2543

2644
.. code:: python
2745
@@ -39,132 +57,95 @@ Example-- VersionedObject as a configuration file
3957
friend_list = ["user1", "user2", "user3"]
4058
display_config = DisplayConfig() # VersionedObjects can be nested
4159
42-
# Create an instance of your object (instance attributes will match class attributes,
43-
# and the initial values will be whatever values you set on the class attributes)
44-
cfg = UserConfig()
60+
# Nested VersionedObjects can be a class object, or an instance of the
61+
# class, either way will behave the same
4562
46-
# Change some values on the object instance
47-
cfg.display_config.volume = 1.0
48-
cfg.username = "jane doe"
63+
# display_config = DisplayConfig
4964
50-
# Save object instance to JSON file
51-
cfg.to_file('user_config.json', indent=4)
65+
Creating object instances and accessing object attributes
66+
*********************************************************
5267

53-
# Load object instance from JSON file
54-
cfg.from_file('user_config.json')
68+
The values you set on the class attributes of a ``VersionedObject`` serve as the default
69+
values for that object. When you create an instance of your ``VersionedObject`` class,
70+
instance attributes will automatically be created to match the class attributes, and
71+
the values of the class attributes will be copied over to the instance attributes:
5572

73+
.. code:: python
5674
57-
You can also save/load object data as a JSON string:
75+
obj = UserConfig()
5876
59-
.. code:: python
77+
print(obj.friend_list)
78+
# Output looks like this: ["user1", "user2", "user3"]
6079
61-
>>> obj_as_json = cfg.to_json(indent=4) # Serialize to JSON string
62-
>>> obj_as_json # Print JSON string
63-
64-
{
65-
"version": "v1.0.0",
66-
"username": "jane doe",
67-
"friend_list": [
68-
"user1",
69-
"user2",
70-
"user3"
71-
],
72-
"display_config": {
73-
"display_mode": "windowed",
74-
"resolution": "1920x1080",
75-
"volume": 1.0
76-
}
77-
}
78-
79-
>>> cfg.from_json(obj_as_json) # Load from JSON string
80+
print(obj.display_config.display_mode)
81+
# Output looks like this: "windowed"
8082
81-
Or, as a dict:
83+
As well as regular dot notation, you can also treat an object instance like a dict,
84+
and access individual attribubtes using their full dot name as the key:
8285

8386
.. code:: python
8487
85-
>>> obj_as_dict = cfg.to_dict() # Serialize to dict
86-
>>> obj_as_dict # Print dict
88+
print(obj['friend_list'])
89+
# Output looks like this: ["user1", "user2", "user3"]
8790
88-
{'version': '1.0.0', 'username': 'jane doe', 'friend_list': ['user1', 'user2', 'user3'], 'display_config': {'display_mode': 'windowed', 'resolution': '1920x1080', 'volume': 1.0}}
91+
print(obj['display_config.display_mode'])
92+
# Output looks like this: "windowed"
8993
90-
>>> cfg.from_dict(obj_as_dict) # Load from dict
94+
# Change the value of an instance attribute
95+
obj['display_config.display_mode'] = "fullscreen"
9196
92-
Accessing versioned object instance attributes
93-
----------------------------------------------
97+
print(obj['display_config.display_mode'])
98+
# Output looks like this: "fullscreen"
9499
95-
When you create an instance of your VersionedObject class, the instance attributes
96-
will be automatically populated to match the class attributes you have created:
100+
You can also use the ``object_attributes()`` method to iterate over all object attribute
101+
names and values:
97102

98103
.. code:: python
99104
100-
from versionedobj import VersionedObject
101-
102-
class AccountInfo(VersionedObject):
103-
user_name = "john"
104-
user_id = 11223344
105-
106-
class Session(VersionedObject):
107-
ip_addr = "255.255.255.255"
108-
port = 22
109-
account_info = AccountInfo()
110-
111-
session = Session()
112-
113-
print(session.ip_addr)
114-
# "255.255.255.255"
115-
116-
print(session.account_info.user_name)
117-
# "john"
105+
for attr_name, attr_value in obj.object_attributes():
106+
print(f"{attr_name}: {attr_value}")
118107
119-
session.account_info.user_name = "jane"
108+
# Output looks like this:
109+
#
110+
# version: v1.0.0
111+
# username: john smith
112+
# friend_list: ["user1", "user2", "user3"]
113+
# display_config.display_mode: windowed
114+
# display_config.resolution: 1920x1080
115+
# display_config.volume: 0.66
120116
121-
print(session.account_info.user_name)
122-
# "jane"
117+
Serializing and de-serializing
118+
******************************
123119

124-
Alternatively, you can treat a VersionedObject instance as a dict, and access
125-
attributes by passing their full name as the key:
120+
Use the ``to_file`` and ``from_file`` methods to serialize/deserialize data to/from a JSON file:
126121

127122
.. code:: python
128123
129-
print(session['account_info.user_name'])
130-
# "jane"
131-
132-
session['account_info.user_name'] = "jack"
133-
134-
print(session['account_info.user_name'])
135-
# "jack"
124+
# Save object instance to JSON file
125+
obj.to_file('user_config.json', indent=4)
136126
137-
Iterating over versioned object instance attributes
138-
---------------------------------------------------
127+
# Load object instance from JSON file
128+
obj.from_file('user_config.json')
139129
140-
If you want to enumerate all attribute names & values on a versioned object instance,
141-
you can use the ``object_attributes()`` method, which returns a generator for all instance
142-
attributes:
130+
You can also save/load object data as a JSON string:
143131

144132
.. code:: python
145133
146-
from versionedobj import VersionedObject
134+
# Save object instance to JSON string
135+
obj_as_json = obj.to_json(indent=4)
147136
148-
class AccountInfo(VersionedObject):
149-
user_name = "john"
150-
user_id = 11223344
137+
# Load object instance from JSON string
138+
obj.from_json(obj_as_json)
151139
152-
class Session(VersionedObject):
153-
ip_addr = "255.255.255.255"
154-
port = 22
155-
account_info = AccountInfo()
140+
Or, as a dict:
156141

157-
session = Session()
142+
.. code:: python
158143
159-
for attr_name, attr_value in session.object_attributes():
160-
print(f"{attr_name}: {attr_value}")
144+
# Save object instance to dict
145+
obj_as_dict = obj.to_dict()
161146
162-
# Output looks like this:
163-
#
164-
# ip_addr: 255.255.255.255
165-
# port: 22
166-
# account_info.user_name: john
167-
# account_info.user_id: 11223344
147+
# Load object instance from dict
148+
obj.from_dict(obj_as_dict)
168149
169150
Filtering serialization/deserialization output
170151
----------------------------------------------

0 commit comments

Comments
 (0)