{"id":1840,"library":"hjson","title":"Hjson","description":"Hjson is a syntax extension to JSON, designed as a human-friendly configuration file format. It allows for comments, multiline strings, and optional quotes, aiming to reduce common errors made by humans when writing JSON. The Python implementation, `hjson-py`, is based on `simplejson` and is currently at version 3.1.0.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"http://github.com/hjson/hjson-py","tags":["json","configuration","parser","hjson","human-readable"],"install":[{"cmd":"pip install hjson","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"The Python implementation of Hjson is based on simplejson.","package":"simplejson","optional":false}],"imports":[{"symbol":"hjson","correct":"import hjson"},{"note":"Used for parsing Hjson strings into Python objects.","symbol":"loads","correct":"hjson.loads(hjson_string)"},{"note":"Used for converting Python objects into Hjson formatted strings.","symbol":"dumps","correct":"hjson.dumps(python_object)"},{"note":"Used for converting Python objects into strict JSON formatted strings (potentially less performant than `simplejson`'s equivalent).","symbol":"dumpsJSON","correct":"hjson.dumpsJSON(python_object)"}],"quickstart":{"code":"import hjson\nimport collections\n\n# Decoding Hjson\nhjson_text = '''\n{\n  foo: a # This is a comment\n  bar: 1\n  # Multiline string example\n  description: '''\n    This is a\n    multiline string.\n  '''\n}\n'''\n\n# Parse Hjson string\ndata = hjson.loads(hjson_text)\nprint(f\"Decoded Hjson: {data}\")\nassert data == collections.OrderedDict([\n    ('foo', 'a'),\n    ('bar', 1),\n    ('description', 'This is a\\nmultiline string.\\n')\n])\n\n# Encoding Python object hierarchies to Hjson\npython_obj = {'foo': 'text', 'bar': [1, 2], 'nested': {'key': 'value'}}\nhjson_output = hjson.dumps(python_obj, indent=2)\nprint(f\"\\nEncoded Hjson:\\n{hjson_output}\")\n\n# Encoding to strict JSON (note: may be less performant than simplejson)\njson_output = hjson.dumpsJSON(python_obj, indent=2)\nprint(f\"\\nEncoded JSON:\\n{json_output}\")","lang":"python","description":"Demonstrates how to parse Hjson strings into Python objects using `hjson.loads()` and how to serialize Python objects into Hjson or strict JSON strings using `hjson.dumps()` and `hjson.dumpsJSON()` respectively."},"warnings":[{"fix":"For explicit string content, especially with whitespace, comments, or escapes, always use single or double quotes. Place comments on separate lines before or after the string value.","message":"Quoteless strings in Hjson automatically end at the newline. Preceding and trailing whitespace is ignored, and escapes are not supported. Additionally, a quoteless string cannot start with a comment sequence (`#`, `//`, `/*`), as these characters would become part of the string or be misinterpreted.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of Hjson's type inference rules. If strict type control is necessary, explicitly quote string values that could be misinterpreted as other data types.","message":"Hjson's relaxed syntax can introduce ambiguity, particularly with quoteless strings that resemble booleans or numbers. For example, `true` is parsed as a boolean, but `True` (with a capital 'T') is parsed as a string, because it's not a recognized boolean literal in Hjson.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure opening and closing braces for the root object are on separate lines from their content for robust parsing. Example: `{ \\n  key: value \\n }` instead of `{ key: value }`.","message":"When parsing Hjson, if the root object's opening brace `{` is on the same line as its first key-value pair without a preceding newline, the Python parser might error or misinterpret the structure. While not explicitly in official docs as a bug, it's a reported parsing quirk.","severity":"gotcha","affected_versions":"Potentially all versions, observed in specific parsing scenarios."},{"fix":"Use a string value for the `indent` parameter, e.g., `indent='  '` for two spaces, or `indent='\\t'` for tabs.","message":"For `hjson.dumps()`, the `indent` parameter in versions prior to 2.1.0 accepted an integer, which was then converted to a string of spaces. While still supported for backwards compatibility, it is now recommended to pass a string (e.g., `'  '`) for indentation.","severity":"deprecated","affected_versions":"< 2.1.0 (integer indent), >= 2.1.0 (string indent preferred)"},{"fix":"For maximum portability and compatibility across different Hjson parsers and tools, it is recommended to explicitly include the root braces in your Hjson files.","message":"Hjson allows omitting curly braces `{}` for the root object, similar to YAML, making configuration files simpler. However, this feature might not be universally supported by all third-party Hjson implementations.","severity":"gotcha","affected_versions":"All versions (support for omitted root braces)"},{"fix":"For optimal performance when serializing to strict JSON, especially large data structures, consider using the `json` module from Python's standard library or `simplejson` directly instead of `hjson.dumpsJSON()`.","message":"The `hjson.dumpsJSON()` function, which converts Python objects to strict JSON, is noted in the documentation to be 'probably not as performant as the `simplejson` version'. If performance is critical for JSON output, consider using `json.dumps` from the standard `json` module or `simplejson.dumps` directly.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}