fix: address review comments on PR #57

- Update utils.py module docstring to include JSON helpers
- Fix circular import of encode in utils.py
- Remove unused imports and print statements in tests
- Fix formatting in tests using ruff

Author: adityak74

src/toon_format/utils.py

@@ -1,35 +1,28 @@
 # Copyright (c) 2025 TOON Format Organization
 # SPDX-License-Identifier: MIT
-"""Token analysis utilities for TOON format.
+"""Utilities for TOON format.
 
-This module provides utilities for counting tokens and comparing
-token efficiency between JSON and TOON formats. Useful for:
-- Estimating API costs (tokens are the primary cost driver)
-- Optimizing prompt sizes for LLM context windows
-- Benchmarking TOON's token efficiency
+This module provides utilities for:
+- Token analysis and efficiency comparison between JSON and TOON formats
+- JSON integration and null value handling
+- Estimating API costs and optimizing prompt sizes
 
 Functions:
     count_tokens: Count tokens in a text string
     estimate_savings: Compare JSON vs TOON token counts
     compare_formats: Generate formatted comparison table
+    loads: Parse JSON string into Python objects (alias for json.loads)
+    encode_json: Encode a JSON string directly into TOON format
 
 Requirements:
     tiktoken: Install with `uv add tiktoken` or `uv add toon_format[benchmark]`
-
-Example:
-    >>> import toon_format
-    >>> data = {"name": "Alice", "age": 30}
-    >>> result = toon_format.estimate_savings(data)
-    >>> print(f"TOON saves {result['savings_percent']:.1f}% tokens")
 """
 
 import functools
 import json
 from typing import Any, Dict
 
-# Import encode from parent package (defined in __init__.py before this module is imported)
-# __init__.py defines encode() before importing utils, so this is safe
-from . import encode
+from .encoder import encode
 
 __all__ = ["count_tokens", "estimate_savings", "compare_formats", "encode_json", "loads"]
 

tests/test_json_integration.py

@@ -1,39 +1,32 @@
-import json
-from toon_format import encode_json, loads, encode
+from toon_format import encode_json, loads
+
 
 def test_loads_null_to_none():
     json_str = '{"abc": null, "xyz": 123}'
     data = loads(json_str)
     assert data["abc"] is None
     assert data["xyz"] == 123
-    print("test_loads_null_to_none passed")
+
 
 def test_encode_json_integration():
     json_str = '{"abc": null, "xyz": null}'
     # This should automatically handle null -> None -> TOON null
     toon_output = encode_json(json_str)
     expected = "abc: null\nxyz: null"
     assert toon_output.strip() == expected
-    print("test_encode_json_integration passed")
+
 
 def test_complex_json_integration():
-    json_str = '''
+    json_str = """
     {
         "status": "success",
         "data": {
             "user": null,
             "items": [1, null, 3]
         }
     }
-    '''
+    """
     toon_output = encode_json(json_str)
     assert "user: null" in toon_output
     # Check for null in items array (can be inline "1,null,3" or list "- null")
     assert "null" in toon_output
-    print("test_complex_json_integration passed")
-
-if __name__ == "__main__":
-    test_loads_null_to_none()
-    test_encode_json_integration()
-    test_complex_json_integration()
-    print("All JSON integration tests passed!")