readme

README.md

@@ -12,8 +12,19 @@ Please see [this](docs/usage.md) Python notebook for features and usage instruct
 ## Upgrading guide
 
 How to upgrade to yacman v1.0.0.
+Yacman v1 provides 2 feature upgrades:
 
-There are some transition objects in the 0.9.3 to help with transition.
+1. Constructors take the form of `yacman.YAMLConfigManager.from_x(...)` functions, to make it clearer how to 
+create a new `ym` object.
+2. It separates locks into read locks and write locks, to allow mutliple simultaneous readers.
+
+The v0.9.3 transition release would has versions, really: 
+- attmap-based version (YacAttMap)
+- non-attmap-but-mostly-compatible (YAMLConfigManager)
+- new future object (FutureYAMLConfigManager...), which is not-backwards-compatible.
+
+In v1.0.0, FutureYAMLConfigManager will be renamed to YAMLConfigManager and the old stuff will be removed.
+Here's how to transition your code:
 
 ### Use the FutureYAMLConfigManager in 0.9.3
 
@@ -44,7 +55,6 @@ Change
 ```
 with ym as locked_ym:
 	locked_ym.write()
-
 ```	
 
 to
@@ -55,10 +65,71 @@ with write_lock(ym) as locked_ym:
 	locked_ym.write()
 ```
 
+
+
+More examples:
+
+```
+
+from yacman import FutureYAMLConfigManager as YAMLConfigManager
+
+
+data = {"my_list": [1,2,3], "my_int": 8, "my_str": "hello world!", "my_dict": {"nested_val": 15}}
+
+ym = YAMLConfigManager(data)
+
+ym["my_list"]
+ym["my_int"]
+ym["my_dict"]
+
+# Use in a context manager to write to the file
+
+ym["new_var"] = 15
+
+with write(ym) as locked_ym:
+    locked_ym.rebase()
+	locked_ym.write()
+
+with read(ym) as locked_ym:
+	locked_ym.rebase()
+
+```
+
+
+
+
 3. Update any constructors to use the `from_{x}` functions
 
 You can no longer just create a `YAMLConfigManager` object directly; now you need to use the constructor helpers.
 
+Examples:
+
+```
+from yacman import FutureYAMLConfigManager as YAMLConfigManager
+
+data = {"my_list": [1,2,3], "my_int": 8, "my_str": "hello world!", "my_dict": {"nested_val": 15}}
+file_path = "tests/data/full.yaml"
+yaml_data = "myvar: myval"
+
+yacman.YAMLConfigManager.from_yaml_file(file_path)
+yacman.YAMLConfigManager.from_yaml_data(yaml_data)
+yacman.YAMLConfigManager.from_obj(data)
+
+```
+
+In the past, you could load from a file and overwrite some attributes with a dict of variables, all from the constructor.
+Now it would is more explicit:
+
+```
+ym = yacman.YacMan.from_yaml_file(file_path)
+ym.update_from_obj(data)
+```
+
+To exppand environment variables in values, use `.exp`.
+
+```
+ym.exp["text_expand_home_dir"]
+```
 
 ## From v0.9.3 (using future) to v1.X.X:
 
@@ -67,3 +138,41 @@ Switch back to:
 ```
 from yacman import YAMLConfigManager
 ```
+
+
+
+
+
+## Demos
+
+Some interactive demos
+
+```
+from yacman import FutureYAMLConfigManager as YAMLConfigManager
+ym = yacman.YAMLConfigManager(entries=["a", "b", "c"])
+ym.to_dict()
+ym
+
+print(ym.to_yaml())
+
+ym = YAMLConfigManager(entries={"top": {"bottom": ["a", "b"], "bottom2": "a"}, "b": "c"})
+ym
+print(ym.to_yaml())
+
+ym = YAMLConfigManager(filepath="tests/data/conf_schema.yaml")
+print(ym.to_yaml())
+ym
+
+ym = YAMLConfigManager(filepath="tests/data/empty.yaml")
+print(ym.to_yaml())
+
+ym = YAMLConfigManager(filepath="tests/data/list.yaml")
+print(ym.to_yaml())
+
+ym = YAMLConfigManager(YAMLConfigManager(filepath="tests/data/full.yaml").exp)
+print(ym.to_yaml())
+
+ym = YAMLConfigManager(filepath="tests/data/full.yaml")
+print(ym.to_yaml(expand=True))
+
+```