# pypaya-json
Enhanced JSON processing with includes, comments, path resolution, and more.
## Features
- **File Inclusions**: Include other JSON files using `"include"` declarations
- **Comment Support**: Add comments to JSON files using custom comment characters
- **Path Resolution**: Automatically resolve relative paths to absolute paths using `@path:` annotations
- **Flexible Configuration**: Use as class methods for one-time operations or instances for reusable configurations
- **Nested Key Access**: Navigate and extract data from nested JSON structures
- **Conditional Processing**: Enable/disable sections using custom enable keys
- **Value Replacement**: Replace entire sections with data from external files
## Installation
```bash
pip install pypaya-json
```
## Quick start
### One-time usage (class method)
```python
from pypaya_json import PypayaJSON
# Basic loading
data = PypayaJSON.load("config.json")
# With comments support and path resolution
data = PypayaJSON.load("config.json", comment_string="#")
# With custom enable key and path annotations disabled
data = PypayaJSON.load("config.json", enable_key="active", resolve_path_annotations=False)
# With custom path annotation prefix
data = PypayaJSON.load("config.json", path_annotation_prefix="$resolve:")
```
### Reusable configuration (instance)
```python
from pypaya_json import PypayaJSON
# Create a reusable loader
loader = PypayaJSON(enable_key="active", comment_string="//")
# Load multiple files with same settings
config = loader.load_file("config.json")
settings = loader.load_file("settings.json")
```
## Examples
### Path resolution
**config.json**:
```json
{
"training": {
"@path:data_dir": "../../data/training",
"@path:checkpoint": "../models/best.ckpt"
},
"output": {
"@path:save_dir": "./outputs"
}
}
```
**Result**:
```python
data = PypayaJSON.load("config.json")
# {
# "training": {
# "data_dir": "/absolute/path/to/data/training",
# "checkpoint": "/absolute/path/to/models/best.ckpt"
# },
# "output": {
# "save_dir": "/absolute/path/to/project/outputs"
# }
# }
```
### Basic file inclusion
**main.json**:
```json
{
"app_name": "MyApp",
"include": {
"filename": "database.json"
},
"features": ["auth", "api"]
}
```
**database.json**:
```json
{
"host": "localhost",
"port": 5432,
"name": "myapp_db"
}
```
**Result**:
```python
data = PypayaJSON.load("main.json")
# {
# "app_name": "MyApp",
# "host": "localhost",
# "port": 5432,
# "name": "myapp_db",
# "features": ["auth", "api"]
# }
```
### Comments support
**config.json**:
```json
{
"server": {
"host": "0.0.0.0", // Bind to all interfaces
"port": 8080 // Default port
},
// "debug": true, // Commented out
"workers": 4
}
```
```python
data = PypayaJSON.load("config.json", comment_string="//")
# Comments are automatically stripped
```
### Combined path resolution and includes
**main.json**:
```json
{
"@path:base_dir": "../data",
"include": {
"filename": "models.json"
}
}
```
**models.json**:
```json
{
"@path:checkpoint_dir": "./checkpoints",
"model_name": "best_model.ckpt"
}
```
**Result**: All paths resolved relative to their respective config file locations
### Nested key access
**data.json**:
```json
{
"database": {
"connections": {
"primary": "postgresql://...",
"replica": "postgresql://..."
}
}
}
```
**main.json**:
```json
{
"include": {
"filename": "data.json",
"keys_path": "database/connections/primary"
}
}
```
**Result**: `"postgresql://..."`
### Conditional inclusion
```json
{
"base_config": "value",
"include": {
"filename": "optional.json",
"enabled": false
}
}
```
```python
# With custom enable key
loader = PypayaJSON(enable_key="active")
data = loader.load_file("config.json")
```
### Value replacement
```json
{
"database": {
"replace_value": {
"filename": "secrets.json",
"key": "database_url"
}
}
}
```
### Custom path annotation prefix
```json
{
"$resolve:data_dir": "../../data",
"$resolve:model_path": "../models/best.ckpt"
}
```
```python
data = PypayaJSON.load("config.json", path_annotation_prefix="$resolve:")
```
## API Reference
### PypayaJSON class
#### Class methods
- `PypayaJSON.load(path, enable_key="enabled", comment_string=None, resolve_path_annotations=True, path_annotation_prefix="@path:")` - Load JSON file with one-time configuration
#### Instance methods
- `PypayaJSON(enable_key="enabled", comment_string=None, resolve_path_annotations=True, path_annotation_prefix="@path:")` - Create reusable loader instance
- `loader.load_file(path)` - Load JSON file using instance configuration
#### Parameters
- `path` (str): Path to the JSON file
- `enable_key` (str): Key used for conditional inclusion (default: "enabled")
- `comment_string` (str, optional): String that denotes comments (default: None)
- `resolve_path_annotations` (bool): Whether to resolve path annotations (default: True)
- `path_annotation_prefix` (str): Prefix for path annotation keys (default: "@path:")
## Advanced usage
### Multiple inclusions
```json
{
"include": [
{"filename": "config1.json"},
{"filename": "config2.json", "keys": ["specific_key"]},
{"filename": "config3.json", "enabled": false}
]
}
```
### Specific key selection
```json
{
"include": {
"filename": "large_config.json",
"keys": ["database", "cache", "logging"]
}
}
```
### Deep nested access
```json
{
"include": {
"filename": "nested.json",
"keys_path": ["level1", "level2", "target_key"]
}
}
```
### Complex configuration with all features
```json
{
// Application settings
"app": {
"@path:base_dir": "../../app",
"name": "MyApp"
},
// Include database config
"include": {
"filename": "database.json",
"keys": ["production"]
},
// Model configuration with paths
"model": {
"@path:checkpoint_dir": "./checkpoints",
"@path:data_dir": "../data",
"config": {
"replace_value": {
"filename": "model_params.json",
"key": "transformer"
}
}
},
// Optional development settings
"dev_tools": {
"enabled": false,
"@path:debug_dir": "./debug"
}
}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pypaya-json",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "json, include, config, loader, comments, enhanced",
"author": "PypayaTech",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9d/01/3eb0359aa5a6c46204a1d70b8f11a5a61276468402d74eb38b4909366869/pypaya_json-0.3.0.tar.gz",
"platform": null,
"description": "# pypaya-json\n\nEnhanced JSON processing with includes, comments, path resolution, and more.\n\n## Features\n\n- **File Inclusions**: Include other JSON files using `\"include\"` declarations\n- **Comment Support**: Add comments to JSON files using custom comment characters\n- **Path Resolution**: Automatically resolve relative paths to absolute paths using `@path:` annotations\n- **Flexible Configuration**: Use as class methods for one-time operations or instances for reusable configurations\n- **Nested Key Access**: Navigate and extract data from nested JSON structures\n- **Conditional Processing**: Enable/disable sections using custom enable keys\n- **Value Replacement**: Replace entire sections with data from external files\n\n## Installation\n\n```bash\npip install pypaya-json\n```\n\n## Quick start\n\n### One-time usage (class method)\n\n```python\nfrom pypaya_json import PypayaJSON\n\n# Basic loading\ndata = PypayaJSON.load(\"config.json\")\n\n# With comments support and path resolution\ndata = PypayaJSON.load(\"config.json\", comment_string=\"#\")\n\n# With custom enable key and path annotations disabled\ndata = PypayaJSON.load(\"config.json\", enable_key=\"active\", resolve_path_annotations=False)\n\n# With custom path annotation prefix\ndata = PypayaJSON.load(\"config.json\", path_annotation_prefix=\"$resolve:\")\n```\n\n### Reusable configuration (instance)\n\n```python\nfrom pypaya_json import PypayaJSON\n\n# Create a reusable loader\nloader = PypayaJSON(enable_key=\"active\", comment_string=\"//\")\n\n# Load multiple files with same settings\nconfig = loader.load_file(\"config.json\")\nsettings = loader.load_file(\"settings.json\")\n```\n\n## Examples\n\n### Path resolution\n\n**config.json**:\n```json\n{\n \"training\": {\n \"@path:data_dir\": \"../../data/training\",\n \"@path:checkpoint\": \"../models/best.ckpt\"\n },\n \"output\": {\n \"@path:save_dir\": \"./outputs\"\n }\n}\n```\n\n**Result**:\n```python\ndata = PypayaJSON.load(\"config.json\")\n# {\n# \"training\": {\n# \"data_dir\": \"/absolute/path/to/data/training\",\n# \"checkpoint\": \"/absolute/path/to/models/best.ckpt\"\n# },\n# \"output\": {\n# \"save_dir\": \"/absolute/path/to/project/outputs\"\n# }\n# }\n```\n\n### Basic file inclusion\n\n**main.json**:\n```json\n{\n \"app_name\": \"MyApp\",\n \"include\": {\n \"filename\": \"database.json\"\n },\n \"features\": [\"auth\", \"api\"]\n}\n```\n\n**database.json**:\n```json\n{\n \"host\": \"localhost\",\n \"port\": 5432,\n \"name\": \"myapp_db\"\n}\n```\n\n**Result**:\n```python\ndata = PypayaJSON.load(\"main.json\")\n# {\n# \"app_name\": \"MyApp\",\n# \"host\": \"localhost\",\n# \"port\": 5432,\n# \"name\": \"myapp_db\",\n# \"features\": [\"auth\", \"api\"]\n# }\n```\n\n### Comments support\n\n**config.json**:\n```json\n{\n \"server\": {\n \"host\": \"0.0.0.0\", // Bind to all interfaces\n \"port\": 8080 // Default port\n },\n // \"debug\": true, // Commented out\n \"workers\": 4\n}\n```\n\n```python\ndata = PypayaJSON.load(\"config.json\", comment_string=\"//\")\n# Comments are automatically stripped\n```\n\n### Combined path resolution and includes\n\n**main.json**:\n```json\n{\n \"@path:base_dir\": \"../data\",\n \"include\": {\n \"filename\": \"models.json\"\n }\n}\n```\n\n**models.json**:\n```json\n{\n \"@path:checkpoint_dir\": \"./checkpoints\",\n \"model_name\": \"best_model.ckpt\"\n}\n```\n\n**Result**: All paths resolved relative to their respective config file locations\n\n### Nested key access\n\n**data.json**:\n```json\n{\n \"database\": {\n \"connections\": {\n \"primary\": \"postgresql://...\",\n \"replica\": \"postgresql://...\"\n }\n }\n}\n```\n\n**main.json**:\n```json\n{\n \"include\": {\n \"filename\": \"data.json\",\n \"keys_path\": \"database/connections/primary\"\n }\n}\n```\n\n**Result**: `\"postgresql://...\"`\n\n### Conditional inclusion\n\n```json\n{\n \"base_config\": \"value\",\n \"include\": {\n \"filename\": \"optional.json\",\n \"enabled\": false\n }\n}\n```\n\n```python\n# With custom enable key\nloader = PypayaJSON(enable_key=\"active\")\ndata = loader.load_file(\"config.json\")\n```\n\n### Value replacement\n\n```json\n{\n \"database\": {\n \"replace_value\": {\n \"filename\": \"secrets.json\",\n \"key\": \"database_url\"\n }\n }\n}\n```\n\n### Custom path annotation prefix\n\n```json\n{\n \"$resolve:data_dir\": \"../../data\",\n \"$resolve:model_path\": \"../models/best.ckpt\"\n}\n```\n\n```python\ndata = PypayaJSON.load(\"config.json\", path_annotation_prefix=\"$resolve:\")\n```\n\n## API Reference\n\n### PypayaJSON class\n\n#### Class methods\n\n- `PypayaJSON.load(path, enable_key=\"enabled\", comment_string=None, resolve_path_annotations=True, path_annotation_prefix=\"@path:\")` - Load JSON file with one-time configuration\n\n#### Instance methods\n\n- `PypayaJSON(enable_key=\"enabled\", comment_string=None, resolve_path_annotations=True, path_annotation_prefix=\"@path:\")` - Create reusable loader instance\n- `loader.load_file(path)` - Load JSON file using instance configuration\n\n#### Parameters\n\n- `path` (str): Path to the JSON file\n- `enable_key` (str): Key used for conditional inclusion (default: \"enabled\")\n- `comment_string` (str, optional): String that denotes comments (default: None)\n- `resolve_path_annotations` (bool): Whether to resolve path annotations (default: True)\n- `path_annotation_prefix` (str): Prefix for path annotation keys (default: \"@path:\")\n\n## Advanced usage\n\n### Multiple inclusions\n\n```json\n{\n \"include\": [\n {\"filename\": \"config1.json\"},\n {\"filename\": \"config2.json\", \"keys\": [\"specific_key\"]},\n {\"filename\": \"config3.json\", \"enabled\": false}\n ]\n}\n```\n\n### Specific key selection\n\n```json\n{\n \"include\": {\n \"filename\": \"large_config.json\",\n \"keys\": [\"database\", \"cache\", \"logging\"]\n }\n}\n```\n\n### Deep nested access\n\n```json\n{\n \"include\": {\n \"filename\": \"nested.json\",\n \"keys_path\": [\"level1\", \"level2\", \"target_key\"]\n }\n}\n```\n\n### Complex configuration with all features\n\n```json\n{\n // Application settings\n \"app\": {\n \"@path:base_dir\": \"../../app\",\n \"name\": \"MyApp\"\n },\n \n // Include database config\n \"include\": {\n \"filename\": \"database.json\",\n \"keys\": [\"production\"]\n },\n \n // Model configuration with paths\n \"model\": {\n \"@path:checkpoint_dir\": \"./checkpoints\",\n \"@path:data_dir\": \"../data\",\n \"config\": {\n \"replace_value\": {\n \"filename\": \"model_params.json\",\n \"key\": \"transformer\"\n }\n }\n },\n \n // Optional development settings\n \"dev_tools\": {\n \"enabled\": false,\n \"@path:debug_dir\": \"./debug\"\n }\n}\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enhanced JSON processing with includes, comments, and more",
"version": "0.3.0",
"project_urls": {
"Repository": "https://github.com/PypayaTech/pypaya-json"
},
"split_keywords": [
"json",
" include",
" config",
" loader",
" comments",
" enhanced"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3ba5eadda888c84f3c06ce1644af990eccf6382380b89a9b721994f6c6ce52db",
"md5": "6b38d235a971fa2c4a420a66e6d89039",
"sha256": "535036c69c3504af7727a4b8241ca5469a1c6aa1315aed9ac02b6d9606292403"
},
"downloads": -1,
"filename": "pypaya_json-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6b38d235a971fa2c4a420a66e6d89039",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 6899,
"upload_time": "2025-07-12T15:26:56",
"upload_time_iso_8601": "2025-07-12T15:26:56.437507Z",
"url": "https://files.pythonhosted.org/packages/3b/a5/eadda888c84f3c06ce1644af990eccf6382380b89a9b721994f6c6ce52db/pypaya_json-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d013eb0359aa5a6c46204a1d70b8f11a5a61276468402d74eb38b4909366869",
"md5": "5458626efbf28de556c8b4df2031ab1a",
"sha256": "1fd1facac81d6d8c7d9441215e148a7283663f04478bf4463ccd5e75f9a3fa99"
},
"downloads": -1,
"filename": "pypaya_json-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "5458626efbf28de556c8b4df2031ab1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 6680,
"upload_time": "2025-07-12T15:26:57",
"upload_time_iso_8601": "2025-07-12T15:26:57.406658Z",
"url": "https://files.pythonhosted.org/packages/9d/01/3eb0359aa5a6c46204a1d70b8f11a5a61276468402d74eb38b4909366869/pypaya_json-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 15:26:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PypayaTech",
"github_project": "pypaya-json",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pypaya-json"
}
JSON
