{"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":"python","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,"search_vec":"'3.1.0':53 'aim':27 'allow':19 'base':45 'comment':21 'common':30 'configur':15,55 'current':50 'design':9 'error':31 'extens':6 'file':16 'format':17 'friend':14 'hjson':1,2,42,57 'hjson-pi':41 'human':13,34,59 'human-friend':12 'human-read':58 'implement':40 'json':8,37,54 'made':32 'multilin':22 'option':25 'parser':56 'py':43 'python':39 'quot':26 'readabl':60 'reduc':29 'simplejson':47 'string':23 'syntax':5 'version':52 'write':36","created_at":"2026-04-09T05:07:32.898695+00:00","updated_at":"2026-04-16T15:34:40.416060+00:00","problems":[{"fix":"Install the hjson package using pip: `pip install hjson`","cause":"The 'hjson' library is not installed in your Python environment or is not accessible within the current environment.","error":"ModuleNotFoundError: No module named 'hjson'"},{"fix":"Ensure the Hjson input strictly adheres to the Hjson specification, correcting any syntax errors, misplaced characters, or malformed structures. For files intended to be empty, use an explicit empty object `{}`.","cause":"The input string or file provided to `hjson.loads()` or `hjson.load()` contains invalid Hjson syntax, such as a missing key/value, an unexpected character, or a file that is entirely empty or consists only of comments.","error":"hjson.scanner.HjsonDecodeError: Expecting value: line X column Y (char Z)"},{"fix":"Convert unsupported data types into JSON-compatible types (e.g., convert a set to a list) or provide a custom `default` function to `hjson.dumps()` to define how these specific types should be serialized.","cause":"The Python object you are attempting to serialize with `hjson.dumps()` or `hjson.dump()` contains data types (e.g., sets, custom classes, datetime objects) that Hjson (and JSON) does not natively support for serialization.","error":"TypeError: Object of type <ClassName> is not JSON serializable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.0","cli_name":"hjson","cli_version":"Hjson 3.1.0","type":"library","homepage":"https://hjson.org","github":"http://github.com/hjson/hjson-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/hjson/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}