# jsonshiatsu 🤲
A *therapeutic* JSON parser for Python that gently massages malformed JSON back into shape. Like the Japanese healing art of shiatsu, this library applies just the right pressure points to transform broken JSON into something beautiful and usable.
Perfect for real-world scenarios where JSON may be improperly formatted, including LLM APIs, legacy systems, and user-generated content that can't be controlled. If you can control the model better use jsonformer. Regex is always an attack surface, be cautious when using this library.
## Features
jsonshiatsu can heal JSON-like strings that would normally cause standard JSON parsing to fail, including:
- **Unquoted object keys**: `{test: "value"}`
- **Single quotes**: `{'test': 'value'}`
- **Mixed quotes**: `{"test": 'value'}`
- **Trailing commas**: `{"test": "value",}`
- **Unquoted string values**: `{test: value}`
- **Embedded quotes with proper escaping**
- **Newlines in strings**
- **Markdown code blocks**: Extract JSON from ` ```json ... ``` ` blocks
- **Trailing explanatory text**: `{"result": "success"} This indicates completion`
- **JavaScript-style comments**: `{"key": "value" /* comment */}` and `// line comments`
- **Function call wrappers**: `return {"data": [1, 2, 3]};` or `parse_json(...)`
- **Multiple JSON objects**: Extract the first valid JSON from multiple objects
- **Non-standard boolean/null**: `True`/`False`, `yes`/`no`, `None`, `undefined`
- **Non-standard quotes**: Smart quotes (`""`), guillemets (`«»`), CJK quotes (`「」`), backticks
- **Incomplete structures**: Automatically close missing braces/brackets
## Installation
Not yet submitted to pip.
```bash
pip install jsonshiatsu
```
## Usage
### Drop-in Replacement for `json`
The easiest way to use jsonshiatsu is as a direct replacement for Python's `json` module:
```python
# Instead of: import json
import jsonshiatsu as json
# All standard json functionality works exactly the same
data = json.loads('{"name": "Alice", "age": 30}')
# But now malformed JSON also works!
data = json.loads('{ test: "this is a test"}') # Unquoted keys
data = json.loads("{'name': 'John', age: 30}") # Single quotes
data = json.loads('{"items": [1, 2, 3,]}') # Trailing commas
# File loading
with open('config.json') as f:
config = json.load(f)
# All json.loads parameters supported
from decimal import Decimal
data = json.loads('{"price": 123.45}', parse_float=Decimal)
```
### Options
```python
# Handle duplicate keys by creating arrays
result = jsonshiatsu.parse('{"key": "value1", "key": "value2"}', duplicate_keys=True)
print(result) # {'key': ['value1', 'value2']}
# Enable aggressive preprocessing for malformed JSON
result = jsonshiatsu.parse('return {"status": "ok"};', aggressive=True)
print(result) # {'status': 'ok'}
```
### `ParseLimits` Class
You can limit the lenght, depth and count of the data.
**Parameters:**
- `max_input_size` (int): Maximum input size in bytes (default: 10MB)
- `max_string_length` (int): Maximum string length (default: 1MB)
- `max_number_length` (int): Maximum number string length (default: 100)
- `max_nesting_depth` (int): Maximum nesting depth (default: 100)
- `max_object_keys` (int): Maximum keys per object (default: 10,000)
- `max_array_items` (int): Maximum items per array (default: 100,000)
- `max_total_items` (int): Maximum total parsed items (default: 1,000,000)
## Examples
### Real-world nightmares
```python
llm_response = """```json
{
// Generated response
"response": {
"message": "Hello! I'd say "welcome" to you.",
'confidence': 0.95,
"timestamp": Date("2025-08-16T10:30:00Z"),
"metadata": {
model: gpt-4,
tokens: 150,
"categories": ["greeting", "polite",],
settings: {
temperature: 0.7,
'max_tokens': 1000
}
}
},
"status": "success", // Operation completed
debug_info: {
"processing_time": 1.23e-2,
"memory_usage": "45MB",
errors: [],
}
}
```
### Limitations
- Some complex edge cases may not be handled perfectly
- Aggressive preprocessing mode should only be used with trusted inputs
- Performance can be much slower than regular json parsing. Use it only on malformed input.
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonshiatsu",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "json, parser, therapeutic, massage, malformed, resilient, shiatsu",
"author": "Jost Brandstetter",
"author_email": "brandstetterjost@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ce/c2/fb9f1260387f4543ba18a3457fb1af3d603376b82836067171950a06eaf2/jsonshiatsu-0.1.0.tar.gz",
"platform": null,
"description": "# jsonshiatsu \ud83e\udd32\n\nA *therapeutic* JSON parser for Python that gently massages malformed JSON back into shape. Like the Japanese healing art of shiatsu, this library applies just the right pressure points to transform broken JSON into something beautiful and usable.\n\nPerfect for real-world scenarios where JSON may be improperly formatted, including LLM APIs, legacy systems, and user-generated content that can't be controlled. If you can control the model better use jsonformer. Regex is always an attack surface, be cautious when using this library.\n\n## Features\n\njsonshiatsu can heal JSON-like strings that would normally cause standard JSON parsing to fail, including:\n\n- **Unquoted object keys**: `{test: \"value\"}`\n- **Single quotes**: `{'test': 'value'}`\n- **Mixed quotes**: `{\"test\": 'value'}`\n- **Trailing commas**: `{\"test\": \"value\",}`\n- **Unquoted string values**: `{test: value}`\n- **Embedded quotes with proper escaping**\n- **Newlines in strings**\n- **Markdown code blocks**: Extract JSON from ` ```json ... ``` ` blocks\n- **Trailing explanatory text**: `{\"result\": \"success\"} This indicates completion`\n- **JavaScript-style comments**: `{\"key\": \"value\" /* comment */}` and `// line comments`\n- **Function call wrappers**: `return {\"data\": [1, 2, 3]};` or `parse_json(...)`\n- **Multiple JSON objects**: Extract the first valid JSON from multiple objects\n- **Non-standard boolean/null**: `True`/`False`, `yes`/`no`, `None`, `undefined`\n- **Non-standard quotes**: Smart quotes (`\"\"`), guillemets (`\u00ab\u00bb`), CJK quotes (`\u300c\u300d`), backticks\n- **Incomplete structures**: Automatically close missing braces/brackets\n\n## Installation\n\nNot yet submitted to pip.\n\n```bash\npip install jsonshiatsu\n```\n\n## Usage\n\n### Drop-in Replacement for `json`\n\nThe easiest way to use jsonshiatsu is as a direct replacement for Python's `json` module:\n\n```python\n# Instead of: import json\nimport jsonshiatsu as json\n\n# All standard json functionality works exactly the same\ndata = json.loads('{\"name\": \"Alice\", \"age\": 30}')\n\n# But now malformed JSON also works!\ndata = json.loads('{ test: \"this is a test\"}') # Unquoted keys\ndata = json.loads(\"{'name': 'John', age: 30}\") # Single quotes \ndata = json.loads('{\"items\": [1, 2, 3,]}') # Trailing commas\n\n# File loading\nwith open('config.json') as f:\n config = json.load(f)\n\n# All json.loads parameters supported\nfrom decimal import Decimal\ndata = json.loads('{\"price\": 123.45}', parse_float=Decimal)\n```\n\n### Options\n\n```python\n# Handle duplicate keys by creating arrays\nresult = jsonshiatsu.parse('{\"key\": \"value1\", \"key\": \"value2\"}', duplicate_keys=True)\nprint(result) # {'key': ['value1', 'value2']}\n\n# Enable aggressive preprocessing for malformed JSON\nresult = jsonshiatsu.parse('return {\"status\": \"ok\"};', aggressive=True)\nprint(result) # {'status': 'ok'}\n```\n\n### `ParseLimits` Class\n\nYou can limit the lenght, depth and count of the data.\n\n**Parameters:**\n- `max_input_size` (int): Maximum input size in bytes (default: 10MB)\n- `max_string_length` (int): Maximum string length (default: 1MB)\n- `max_number_length` (int): Maximum number string length (default: 100)\n- `max_nesting_depth` (int): Maximum nesting depth (default: 100)\n- `max_object_keys` (int): Maximum keys per object (default: 10,000)\n- `max_array_items` (int): Maximum items per array (default: 100,000)\n- `max_total_items` (int): Maximum total parsed items (default: 1,000,000)\n\n## Examples\n\n### Real-world nightmares\n\n```python\n llm_response = \"\"\"```json\n {\n // Generated response\n \"response\": {\n \"message\": \"Hello! I'd say \"welcome\" to you.\",\n 'confidence': 0.95,\n \"timestamp\": Date(\"2025-08-16T10:30:00Z\"),\n \"metadata\": {\n model: gpt-4,\n tokens: 150,\n \"categories\": [\"greeting\", \"polite\",],\n settings: {\n temperature: 0.7,\n 'max_tokens': 1000\n }\n }\n },\n \"status\": \"success\", // Operation completed\n debug_info: {\n \"processing_time\": 1.23e-2,\n \"memory_usage\": \"45MB\",\n errors: [],\n }\n }\n\n```\n\n### Limitations\n\n- Some complex edge cases may not be handled perfectly\n- Aggressive preprocessing mode should only be used with trusted inputs\n- Performance can be much slower than regular json parsing. Use it only on malformed input.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A therapeutic JSON parser that gently massages malformed JSON into shape",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/JostBrand/jsonshiatsu",
"Homepage": "https://github.com/JostBrand/jsonshiatsu",
"Repository": "https://github.com/JostBrand/jsonshiatsu"
},
"split_keywords": [
"json",
" parser",
" therapeutic",
" massage",
" malformed",
" resilient",
" shiatsu"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "31eb838159d94ca4669726412bcd957506c8700b6a2ec3dae828549b75fd4ae7",
"md5": "28b553b1cc6d9e5145f7d6f110f63b59",
"sha256": "b88b3a4b88b66ac58adebf4b82b4e8f4f1ee10a66b1d9342eec02f08aafa70a5"
},
"downloads": -1,
"filename": "jsonshiatsu-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28b553b1cc6d9e5145f7d6f110f63b59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 53130,
"upload_time": "2025-08-18T09:19:27",
"upload_time_iso_8601": "2025-08-18T09:19:27.978541Z",
"url": "https://files.pythonhosted.org/packages/31/eb/838159d94ca4669726412bcd957506c8700b6a2ec3dae828549b75fd4ae7/jsonshiatsu-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cec2fb9f1260387f4543ba18a3457fb1af3d603376b82836067171950a06eaf2",
"md5": "4953ff6169c71e9153391461f91a2bcb",
"sha256": "6e9592a80c155c1101ebddc2559b58cfa048d18c5ccae9f19571174375e7baa1"
},
"downloads": -1,
"filename": "jsonshiatsu-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4953ff6169c71e9153391461f91a2bcb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 44831,
"upload_time": "2025-08-18T09:19:29",
"upload_time_iso_8601": "2025-08-18T09:19:29.486042Z",
"url": "https://files.pythonhosted.org/packages/ce/c2/fb9f1260387f4543ba18a3457fb1af3d603376b82836067171950a06eaf2/jsonshiatsu-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 09:19:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JostBrand",
"github_project": "jsonshiatsu",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsonshiatsu"
}
JSON
