From 2da09250134b65f6665ceb9f2e0dfca5b86b343e Mon Sep 17 00:00:00 2001
From: kristiker <kristik06@outlook.com>
Date: Fri, 21 Apr 2023 16:37:28 +0200
Subject: [PATCH] Noted write method in readme

---
 README.md                |  3 +++
 keyvalues3/__init__.py   | 19 ++++++++++++-------
 keyvalues3/keyvalues3.py |  4 ++--
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 62ff2f8..d4ce202 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,9 @@ Encoding(name='text', version=UUID('e21c7f3c-8a33-41c5-9977-a76d3a32aa0d'))
 
 >>> bt_config.format
 Format(name='generic', version=UUID('7412167c-06e9-4698-aff2-e63eb59037e7'))
+
+# To write it back
+>>> kv3.write(bt_config, "tests/documents/bt_config.kv3", use_original_encoding=True)
 ```
 
 ## Install
diff --git a/keyvalues3/__init__.py b/keyvalues3/__init__.py
index 1167cf4..363e53f 100644
--- a/keyvalues3/__init__.py
+++ b/keyvalues3/__init__.py
@@ -83,9 +83,11 @@ def write(kv3: KV3File | ValueType, path_or_stream: str | os.PathLike | typing.I
 
     Args:
         kv3: The KV3File or KV3 value to write.
-        path: The path to write to.
+        path_or_stream: The file path to write to. Or a text/binary stream.
         encoding: The encoding to use.
-        format: If kv3 passed is not a file, this is the format to build it with.
+
+        format: If a raw kv3 value is passed, this is the format to build it with. Default is 'generic'.
+        use_original_encoding: If a kv3 file is passed, use its original encoding.
     """
 
     if not isinstance(kv3, KV3File):
@@ -115,12 +117,15 @@ def write(kv3: KV3File | ValueType, path_or_stream: str | os.PathLike | typing.I
             fp.write(text_result)
         else:
             fp.write(text_result.encode("utf-8"))
-    elif encoding == ENCODING_BINARY_UNCOMPRESSED:
-       binarywriter.BinaryV1UncompressedWriter(kv3).write(fp)
-    elif encoding == ENCODING_BINARY_BLOCK_LZ4:
-        binarywriter.BinaryLZ4(kv3).write(fp)
     else:
-        raise NotImplementedError(f"Encoding type {encoding} not implemented.")
+        if isinstance(fp, io.TextIOBase):
+            raise TypeError("Cannot write binary KV3 to a text stream. If this is a file, please open it in binary mode ('wb').")
+        if encoding == ENCODING_BINARY_UNCOMPRESSED:
+            binarywriter.BinaryV1UncompressedWriter(kv3).write(fp)
+        elif encoding == ENCODING_BINARY_BLOCK_LZ4:
+            binarywriter.BinaryLZ4(kv3).write(fp)
+        else:
+            raise NotImplementedError(f"Encoding type {encoding} not implemented.")
     
     if is_file:
         fp.close()
diff --git a/keyvalues3/keyvalues3.py b/keyvalues3/keyvalues3.py
index a18505e..34265e5 100644
--- a/keyvalues3/keyvalues3.py
+++ b/keyvalues3/keyvalues3.py
@@ -71,9 +71,9 @@ def check_valid(value: ValueType):
                 if nested_value is value:
                     raise ValueError("dict contains itself")
                 if not isinstance(key, str):
-                    raise ValueError("dict key is not a string")
+                    raise ValueError(f"dict key is not a string type, but {type(key)}")
                 if not key.isidentifier():
-                    raise ValueError("dict key is not a valid identifier") # I think
+                    raise ValueError(f"dict key '{key}' is not accepted (not a valid identifier)") # TODO: spaces and . are allowed
                 check_valid(nested_value)
         case array.array() | bytes() | bytearray():
             pass