# diffx-python
Python wrapper for the `diffx` CLI tool - semantic diff for structured data.
## Installation
```bash
pip install diffx-python
```
This will automatically download the appropriate `diffx` binary for your system from GitHub Releases.
## Usage
### Modern API (Recommended)
```python
import diffx
# Compare two JSON files
result = diffx.diff('file1.json', 'file2.json')
print(result)
# Get structured output as JSON
json_result = diffx.diff(
'config1.yaml',
'config2.yaml',
diffx.DiffOptions(format='yaml', output='json')
)
for diff_item in json_result:
if diff_item.added:
print(f"Added: {diff_item.added}")
elif diff_item.modified:
print(f"Modified: {diff_item.modified}")
# Compare directory trees
dir_result = diffx.diff(
'dir1/',
'dir2/',
diffx.DiffOptions(recursive=True, path='config')
)
# Compare strings directly
json1 = '{"name": "Alice", "age": 30}'
json2 = '{"name": "Alice", "age": 31}'
string_result = diffx.diff_string(
json1, json2, 'json',
diffx.DiffOptions(output='json')
)
```
### Legacy API (Backward Compatibility)
```python
from diffx import run_diffx
# Compare two JSON files (legacy)
result = run_diffx(["file1.json", "file2.json"])
if result.returncode == 0:
print("No differences found.")
else:
print("Differences found:")
print(result.stdout)
```
## Features
- **Multiple formats**: JSON, YAML, TOML, XML, INI, CSV
- **Smart diffing**: Understands structure, not just text
- **Flexible output**: CLI, JSON, YAML, unified diff formats
- **Advanced options**:
- Regex-based key filtering
- Floating-point tolerance
- Array element identification
- Path-based filtering
- **Cross-platform**: Automatically downloads the right binary
## Development
To install in development mode with uv:
```bash
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
```
## Manual Binary Installation
If automatic download fails:
```bash
diffx-download-binary
```
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "diffx-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "automation, ci-cd, comparison, configuration, csv, data-analysis, devops, diff, ini, json, semantic, structured-data, toml, xml, yaml",
"author": null,
"author_email": "kako-jun <kako.jun.42@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/83/10/beb033faa8e715099d9753ae6681a9f422ef2250f1d76c0589423834ec3e/diffx_python-0.3.2.tar.gz",
"platform": null,
"description": "# diffx-python\n\nPython wrapper for the `diffx` CLI tool - semantic diff for structured data.\n\n## Installation\n\n```bash\npip install diffx-python\n```\n\nThis will automatically download the appropriate `diffx` binary for your system from GitHub Releases.\n\n## Usage\n\n### Modern API (Recommended)\n\n```python\nimport diffx\n\n# Compare two JSON files\nresult = diffx.diff('file1.json', 'file2.json')\nprint(result)\n\n# Get structured output as JSON\njson_result = diffx.diff(\n 'config1.yaml', \n 'config2.yaml',\n diffx.DiffOptions(format='yaml', output='json')\n)\n\nfor diff_item in json_result:\n if diff_item.added:\n print(f\"Added: {diff_item.added}\")\n elif diff_item.modified:\n print(f\"Modified: {diff_item.modified}\")\n\n# Compare directory trees\ndir_result = diffx.diff(\n 'dir1/', \n 'dir2/',\n diffx.DiffOptions(recursive=True, path='config')\n)\n\n# Compare strings directly\njson1 = '{\"name\": \"Alice\", \"age\": 30}'\njson2 = '{\"name\": \"Alice\", \"age\": 31}'\nstring_result = diffx.diff_string(\n json1, json2, 'json',\n diffx.DiffOptions(output='json')\n)\n```\n\n### Legacy API (Backward Compatibility)\n\n```python\nfrom diffx import run_diffx\n\n# Compare two JSON files (legacy)\nresult = run_diffx([\"file1.json\", \"file2.json\"])\n\nif result.returncode == 0:\n print(\"No differences found.\")\nelse:\n print(\"Differences found:\")\n print(result.stdout)\n```\n\n## Features\n\n- **Multiple formats**: JSON, YAML, TOML, XML, INI, CSV\n- **Smart diffing**: Understands structure, not just text\n- **Flexible output**: CLI, JSON, YAML, unified diff formats\n- **Advanced options**: \n - Regex-based key filtering\n - Floating-point tolerance\n - Array element identification\n - Path-based filtering\n- **Cross-platform**: Automatically downloads the right binary\n\n## Development\n\nTo install in development mode with uv:\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install -e .[dev]\n```\n\n## Manual Binary Installation\n\nIf automatic download fails:\n\n```bash\ndiffx-download-binary\n```\n\n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for diffx - semantic diffing of JSON, YAML, TOML, XML, INI, and CSV files. Focuses on structural meaning rather than formatting.",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://github.com/kako-jun/diffx/tree/main/docs",
"Homepage": "https://github.com/kako-jun/diffx",
"Issues": "https://github.com/kako-jun/diffx/issues",
"Repository": "https://github.com/kako-jun/diffx"
},
"split_keywords": [
"automation",
" ci-cd",
" comparison",
" configuration",
" csv",
" data-analysis",
" devops",
" diff",
" ini",
" json",
" semantic",
" structured-data",
" toml",
" xml",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4cd8349986ab211236f9c211f3b78f745d58b9c41477ec4547fe1cfdc1c308ed",
"md5": "9c77c16ed0ac55507467ba1bb663b042",
"sha256": "9591000d5e63311af0345bcbbb9ef499a6c189df494f2eb4280e11a952d54ca4"
},
"downloads": -1,
"filename": "diffx_python-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c77c16ed0ac55507467ba1bb663b042",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7738,
"upload_time": "2025-07-09T13:33:05",
"upload_time_iso_8601": "2025-07-09T13:33:05.888145Z",
"url": "https://files.pythonhosted.org/packages/4c/d8/349986ab211236f9c211f3b78f745d58b9c41477ec4547fe1cfdc1c308ed/diffx_python-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8310beb033faa8e715099d9753ae6681a9f422ef2250f1d76c0589423834ec3e",
"md5": "bf82dda3335e80a6384cca768abb1f60",
"sha256": "816ca626a8fb844df85719247a021c85da9e3347499c9746e23f5eb49a599378"
},
"downloads": -1,
"filename": "diffx_python-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "bf82dda3335e80a6384cca768abb1f60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6492,
"upload_time": "2025-07-09T13:33:07",
"upload_time_iso_8601": "2025-07-09T13:33:07.021760Z",
"url": "https://files.pythonhosted.org/packages/83/10/beb033faa8e715099d9753ae6681a9f422ef2250f1d76c0589423834ec3e/diffx_python-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 13:33:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kako-jun",
"github_project": "diffx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "diffx-python"
}
JSON
