| Name | listofdicts JSON |
| Version |
1.1.4
JSON |
| download |
| home_page | None |
| Summary | A strongly typed list of dictionaries data type with validation and serialization support. |
| upload_time | 2025-07-20 17:12:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
list
dict
list of dict
listofdict
listofdicts
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# listofdicts
`listofdicts` is a Python container class that extends `List[Dict[str, Any]]` to provide:
- Optional **schema enforcement** with runtime type validation
- **Safe mutation** with immutability support
- **Deep JSON serialization/deserialization**
- **Custom metadata storage**
- Utilities for **sorting**, **copying**, and **prompt formatting** (LLM support)
This class is ideal for applications that require structured tabular-like data management in Python without external dependencies.
---
## 🚀 Features
- 🔒 **Immutability**: Optional protection against in-place changes
- ✅ **Schema validation**:
- `schema_constrain_to_existing`: restrict keys to the schema
- `schema_add_missing`: auto-insert missing schema keys as `None`
- 🔁 **Full list-like behavior**: slicing, appending, extending, sorting, copying, updating
- 🧠 **Metadata support**: Store additional metadata alongside your list of dicts
- 🔄 **JSON I/O**: Easily serialize/deserialize from JSON
- 🤖 **LLM prompt builder**: `as_llm_prompt` constructor with built-in prompt roles and tone presets
---
## 📦 Installation
[](https://pypi.org/project/listofdicts/)
[](LICENSE)
## 🔧 Usage
```python
from listofdicts import listofdicts
data = [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
]
lod = listofdicts( data,
schema = {"name": str, "age": int},
schema_constrain_to_existing = True,
schema_add_missing = True)
lod.append({"name": "Carol", "age": 22})
lod += {"name":"Danny", "age":26}
try:
lod += {"name":"Errorboy", "fingers":11}
except TypeError as te:
print(f"schema set to constrain keys to existing, so this fails due to fingers.\n{te}")
# you can add arbitrary metadata to the object:
lod.metadata = {"data_source":"some.test.location",
"load_errors":1,
"errors":[te]}
# iterate or enumerate core data (without metadata)
for person in lod:
print(f" The person named {person['name']} is {person['age'] or 'unknown'} years old.")
# when seralizing to JSON, you can optionally keep the metadata.
# with metadata, you'll get {"data": [{core data}], "metadata": {optional metadata} }
# with no metadata, you'll only get [{core data}]
print(lod.to_json(indent=2, preserve_metadata=True))
```
## 📘 API Reference
### 🔧 Methods
| Method | Description |
|--------|-------------|
| `append` | Append a dictionary to the end of this listofdicts object. This will fail if the object has been made immutable, or if the schema was defined and enforced, and the new dictionary keys do not match the schema. |
| `as_immutable` | Returns an immutable deepcopy of this listofdicts instance. |
| `as_llm_prompt` | Creates a listofdicts instance, customized for LLM prompts. |
| `as_mutable` | Returns a mutable deepcopy of this listofdicts instance. |
| `clear` | Clear the listofdicts object (in place). This will fail if this object has been made immutable. |
| `copy` | Performs a deep copy of the listofdicts instance, with optional schema and immutability overrides. |
| `extend` | Extend THIS listofdicts object (in place) with dictionaries from another listofdicts object (returning None). This will fail if this object has been made immutable, or if the schema was defined and enforced, and the new dictionary keys do not match the schema. |
| `from_json` | Creates a listofdicts instance from a JSON string. |
| `pop` | Remove and return an element from the listofdicts object, at the given index (default last). This will fail if this object has been made immutable. |
| `popitem` | Remove and return an element from the listofdicts object. This will fail if this object has been made immutable. |
| `remove` | Remove an element from the listofdicts object (in place), by value (aka dictionary). This will fail if this object has been made immutable. |
| `sort` | Sort the order of dictionaries within the list by a given dictionary key, with the requirement that the key must be present in all dictionaries in the list. This does not affect the data, only its order within the list, and therefore can be called on immutable listofdicts objects. |
| `to_json` | Returns a JSON string representation of the listofdicts instance. If `preserve_metadata` is True, all metadata and other settings will be nested under a "metadata" key, and the core iterator data will be nested under a "data" key. If False, only the core data is returned. |
| `unique_key_values` | Returns a list of all unique values across all dicts in the listofdicts, for a given key. |
| `unique_keys` | Returns a list of all unique keys found in all dicts. |
| `update_item` | Updates the dictionary object of the list at the given index. Args: `index (int)` – index to update; `updates (Dict[str, Any])` – dictionary with updates. |
| `validate_all` | Validate all elements in the listofdicts object. Fails if the schema is enforced and any keys do not match the schema. Useful before applying a new schema. |
| `validate_item` | Validate a single dictionary element in the listofdicts object. Fails if the schema is enforced and keys do not match the schema. Useful for validating an item before insertion. |
---
### 🏷️ Properties
| Property | Description |
|----------|-------------|
| `metadata` | Metadata is a dictionary of arbitrary key-value pairs to be stored with the listofdicts instance. This is intended to store information about the listofdicts instance that is not part of the core data. This is not exposed during object iteration or enumeration, but can be optionally serialized to JSON. |
| `schema` | Schema is a dictionary of key-type pairs that specifies the {KeyName: Type} of each key in the listofdicts, for example: {"key1": str, "key2": int, "key3": float}. This is used for runtime type enforcement and schema validation, using the two flag options: <br> - schema_constrain_to_existing: all data keys must exist in the schema. <br> - schema_add_missing: any data keys missing compared to the schema will be added with a value of None. |
| `schema_add_missing` | If set to True with a defined schema, any keys in the schema that are not present in the dictionary data will be added with a value of None. This is useful when adding new listofdicts elements, to ensure that all keys in the schema are present in the dictionary data. Note, this does NOT CONSTRAIN data keys to only keys defined in the schema, it only adds missing keys. To constrain data to only keys defined in the schema, set schema_constrain_to_existing to True. |
| `schema_constrain_to_existing` | If set to True with a defined schema, all keys in the dictionary data must also be present in the schema. This constrains data added to the listofdicts to only keys defined in the schema (if defined). Note, this does NOT REQUIRE all keys in the schema to be present in the dictionary data, it only enforces the constraint. To add missing keys when adding new listofdict elements, set schema_add_missing to True. |
## 🧪 Python Compatibility
Tested with Python 3.10+
## 📄 License
MIT License
## 👤 Author
Built by Stephen Hilton — Contributions welcome!
## Directory Structure
```
listofdicts/
├── src/
│ ├── __init__.py
│ └── listofdicts.py
├── tests/
│ └── test_listofdicts.py
├── README.md
├── pyproject.toml
├── setup.cfg
└── LICENSE
```
Raw data
{
"_id": null,
"home_page": null,
"name": "listofdicts",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "list, dict, list of dict, listofdict, listofdicts",
"author": null,
"author_email": "Stephen Hilton <stephen@familyhilton.com>",
"download_url": "https://files.pythonhosted.org/packages/fb/b8/d07674d62fbc16c8d2034e4467a9a10e9549b7aebaf5223875f92e971bad/listofdicts-1.1.4.tar.gz",
"platform": null,
"description": "# listofdicts\n\n`listofdicts` is a Python container class that extends `List[Dict[str, Any]]` to provide:\n\n- Optional **schema enforcement** with runtime type validation\n- **Safe mutation** with immutability support\n- **Deep JSON serialization/deserialization**\n- **Custom metadata storage**\n- Utilities for **sorting**, **copying**, and **prompt formatting** (LLM support)\n\nThis class is ideal for applications that require structured tabular-like data management in Python without external dependencies.\n\n---\n\n## \ud83d\ude80 Features\n\n- \ud83d\udd12 **Immutability**: Optional protection against in-place changes\n- \u2705 **Schema validation**:\n - `schema_constrain_to_existing`: restrict keys to the schema\n - `schema_add_missing`: auto-insert missing schema keys as `None`\n- \ud83d\udd01 **Full list-like behavior**: slicing, appending, extending, sorting, copying, updating\n- \ud83e\udde0 **Metadata support**: Store additional metadata alongside your list of dicts\n- \ud83d\udd04 **JSON I/O**: Easily serialize/deserialize from JSON\n- \ud83e\udd16 **LLM prompt builder**: `as_llm_prompt` constructor with built-in prompt roles and tone presets\n\n---\n\n## \ud83d\udce6 Installation\n\n[](https://pypi.org/project/listofdicts/)\n[](LICENSE)\n\n \n\n\n## \ud83d\udd27 Usage\n\n```python\nfrom listofdicts import listofdicts\n\ndata = [\n {\"name\": \"Alice\", \"age\": 30},\n {\"name\": \"Bob\", \"age\": 25}\n]\n \nlod = listofdicts( data, \n schema = {\"name\": str, \"age\": int}, \n schema_constrain_to_existing = True, \n schema_add_missing = True)\n\nlod.append({\"name\": \"Carol\", \"age\": 22})\nlod += {\"name\":\"Danny\", \"age\":26}\n\ntry:\n lod += {\"name\":\"Errorboy\", \"fingers\":11}\nexcept TypeError as te:\n print(f\"schema set to constrain keys to existing, so this fails due to fingers.\\n{te}\") \n\n# you can add arbitrary metadata to the object:\nlod.metadata = {\"data_source\":\"some.test.location\",\n \"load_errors\":1,\n \"errors\":[te]}\n\n# iterate or enumerate core data (without metadata)\nfor person in lod:\n print(f\" The person named {person['name']} is {person['age'] or 'unknown'} years old.\")\n\n# when seralizing to JSON, you can optionally keep the metadata.\n# with metadata, you'll get {\"data\": [{core data}], \"metadata\": {optional metadata} }\n# with no metadata, you'll only get [{core data}]\nprint(lod.to_json(indent=2, preserve_metadata=True))\n```\n\n\n## \ud83d\udcd8 API Reference\n\n### \ud83d\udd27 Methods\n\n| Method | Description |\n|--------|-------------|\n| `append` | Append a dictionary to the end of this listofdicts object. This will fail if the object has been made immutable, or if the schema was defined and enforced, and the new dictionary keys do not match the schema. |\n| `as_immutable` | Returns an immutable deepcopy of this listofdicts instance. |\n| `as_llm_prompt` | Creates a listofdicts instance, customized for LLM prompts. |\n| `as_mutable` | Returns a mutable deepcopy of this listofdicts instance. |\n| `clear` | Clear the listofdicts object (in place). This will fail if this object has been made immutable. |\n| `copy` | Performs a deep copy of the listofdicts instance, with optional schema and immutability overrides. |\n| `extend` | Extend THIS listofdicts object (in place) with dictionaries from another listofdicts object (returning None). This will fail if this object has been made immutable, or if the schema was defined and enforced, and the new dictionary keys do not match the schema. |\n| `from_json` | Creates a listofdicts instance from a JSON string. |\n| `pop` | Remove and return an element from the listofdicts object, at the given index (default last). This will fail if this object has been made immutable. |\n| `popitem` | Remove and return an element from the listofdicts object. This will fail if this object has been made immutable. |\n| `remove` | Remove an element from the listofdicts object (in place), by value (aka dictionary). This will fail if this object has been made immutable. |\n| `sort` | Sort the order of dictionaries within the list by a given dictionary key, with the requirement that the key must be present in all dictionaries in the list. This does not affect the data, only its order within the list, and therefore can be called on immutable listofdicts objects. |\n| `to_json` | Returns a JSON string representation of the listofdicts instance. If `preserve_metadata` is True, all metadata and other settings will be nested under a \"metadata\" key, and the core iterator data will be nested under a \"data\" key. If False, only the core data is returned. |\n| `unique_key_values` | Returns a list of all unique values across all dicts in the listofdicts, for a given key. |\n| `unique_keys` | Returns a list of all unique keys found in all dicts. |\n| `update_item` | Updates the dictionary object of the list at the given index. Args: `index (int)` \u2013 index to update; `updates (Dict[str, Any])` \u2013 dictionary with updates. |\n| `validate_all` | Validate all elements in the listofdicts object. Fails if the schema is enforced and any keys do not match the schema. Useful before applying a new schema. |\n| `validate_item` | Validate a single dictionary element in the listofdicts object. Fails if the schema is enforced and keys do not match the schema. Useful for validating an item before insertion. |\n\n---\n\n### \ud83c\udff7\ufe0f Properties\n\n| Property | Description |\n|----------|-------------|\n| `metadata` | Metadata is a dictionary of arbitrary key-value pairs to be stored with the listofdicts instance. This is intended to store information about the listofdicts instance that is not part of the core data. This is not exposed during object iteration or enumeration, but can be optionally serialized to JSON. |\n| `schema` | Schema is a dictionary of key-type pairs that specifies the {KeyName: Type} of each key in the listofdicts, for example: {\"key1\": str, \"key2\": int, \"key3\": float}. This is used for runtime type enforcement and schema validation, using the two flag options: <br> - schema_constrain_to_existing: all data keys must exist in the schema. <br> - schema_add_missing: any data keys missing compared to the schema will be added with a value of None. |\n| `schema_add_missing` | If set to True with a defined schema, any keys in the schema that are not present in the dictionary data will be added with a value of None. This is useful when adding new listofdicts elements, to ensure that all keys in the schema are present in the dictionary data. Note, this does NOT CONSTRAIN data keys to only keys defined in the schema, it only adds missing keys. To constrain data to only keys defined in the schema, set schema_constrain_to_existing to True. |\n| `schema_constrain_to_existing` | If set to True with a defined schema, all keys in the dictionary data must also be present in the schema. This constrains data added to the listofdicts to only keys defined in the schema (if defined). Note, this does NOT REQUIRE all keys in the schema to be present in the dictionary data, it only enforces the constraint. To add missing keys when adding new listofdict elements, set schema_add_missing to True. |\n\n\n\n## \ud83e\uddea Python Compatibility\nTested with Python 3.10+\n\n\n## \ud83d\udcc4 License\nMIT License\n\n\n## \ud83d\udc64 Author\nBuilt by Stephen Hilton \u2014 Contributions welcome!\n\n\n## Directory Structure\n```\nlistofdicts/\n \u251c\u2500\u2500 src/\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2514\u2500\u2500 listofdicts.py\n \u251c\u2500\u2500 tests/\n \u2502 \u2514\u2500\u2500 test_listofdicts.py\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 pyproject.toml\n \u251c\u2500\u2500 setup.cfg\n \u2514\u2500\u2500 LICENSE\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A strongly typed list of dictionaries data type with validation and serialization support.",
"version": "1.1.4",
"project_urls": null,
"split_keywords": [
"list",
" dict",
" list of dict",
" listofdict",
" listofdicts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6a0e4988b7a654b2081de476fd248b24c344f146e43d6f15168291c2ffbef97a",
"md5": "be7b79213e9c25cb7fe02b3834ffd8af",
"sha256": "b8e61d1bef18ad89fdf92b4bd4fe3c64c96539ed5602d91304fa62e3b148ffa5"
},
"downloads": -1,
"filename": "listofdicts-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be7b79213e9c25cb7fe02b3834ffd8af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11074,
"upload_time": "2025-07-20T17:12:02",
"upload_time_iso_8601": "2025-07-20T17:12:02.947560Z",
"url": "https://files.pythonhosted.org/packages/6a/0e/4988b7a654b2081de476fd248b24c344f146e43d6f15168291c2ffbef97a/listofdicts-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fbb8d07674d62fbc16c8d2034e4467a9a10e9549b7aebaf5223875f92e971bad",
"md5": "6944c0e49839b450a98279792f285d75",
"sha256": "0de801d0e9741a11485371f80993dc040eec32ab1e30a1087fa58e53ac59087f"
},
"downloads": -1,
"filename": "listofdicts-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "6944c0e49839b450a98279792f285d75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13464,
"upload_time": "2025-07-20T17:12:03",
"upload_time_iso_8601": "2025-07-20T17:12:03.993477Z",
"url": "https://files.pythonhosted.org/packages/fb/b8/d07674d62fbc16c8d2034e4467a9a10e9549b7aebaf5223875f92e971bad/listofdicts-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 17:12:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "listofdicts"
}
