| Name | tomlkit-extras JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Python package that extends the functionality of tomlkit, allowing for advanced manipulation, validation, and introspection of TOML files, including handling comments and nested structures |
| upload_time | 2024-12-17 06:12:17 |
| maintainer | None |
| docs_url | None |
| author | galactixx |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tomlkit-extras
**tomlkit-extras** is a Python package that extends the functionality of [tomlkit](https://github.com/sdispater/tomlkit), allowing for advanced manipulation, validation, and introspection of TOML files. This package provides enhanced capabilities for handling comments, nested structures, and other nuanced elements within TOML files.
## 📦 **Installation**
To install tomlkit-extras, run the following command:
```bash
pip install tomlkit-extras
```
## 🚀 **Features**
- **Comment Handling**: Introspect, modify, or retain comments within TOML files.
- **Nested Structure Support**: Access, edit, and validate deeply nested tables and arrays.
- **Validation Tools**: Validate and ensure the integrity of TOML file structures.
- **Enhanced Introspection**: Retrieve metadata and structure details from TOML documents.
- **Comprehensive Field Retrieval**: Extract and modify TOML fields and their properties.
## 📚 **Usage**
### **Using `TOMLDocumentDescriptor`**
The `TOMLDocumentDescriptor` class provides powerful tools for parsing and extracting elements from a TOML document. It can be used to retrieve statistics, extract specific fields, tables, or array-of-tables, and analyze document stylings.
Below are examples showcasing some of the methods available in the `TOMLDocumentDescriptor` class.
#### **Example Usage**
```python
from tomlkit_extras import TOMLDocumentDescriptor, load_toml_file
# Sample TOML content
raw_toml = """
# This is a top-level comment explaining the TOML file
# It provides context about the file's purpose
[table1]
key1 = "value1"
key2 = "value2"
[[array_of_tables]]
name = "first"
[[array_of_tables]]
name = "second"
"""
# Load the TOML into a TOMLDocument
toml_doc = load_toml_file(raw_toml)
# Initialize the descriptor
descriptor = TOMLDocumentDescriptor(toml_doc)
```
```python
# Access the number of tables appearing in the TOML document
num_tables = descriptor.number_of_tables
```
**Return Type:** `int`
| **Description** |
|-----------------|
| The total number of tables in the TOML document. |
```python
# Access the number of array-of-tables appearing in the TOML document
num_aots = descriptor.number_of_aots
```
**Return Type:** `int`
| **Description** |
|-----------------|
| The total number of array of tables in the TOML document. |
```python
# Retrieve a specific field
field = descriptor.get_field(hierarchy='table1.key1')
```
**Return Type:** `FieldDescriptor`
| **Attribute** | **Type** | **Description** |
|-------------------|-----------------------|-----------------|
| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the field. |
| **name** | `str` | The name of the field. |
| **item_type** | `FieldItem` | A `FieldItem` instance corresponding to a string literal, either 'field' or 'array'. |
| **parent_type** | `ParentItem` \| `None`| A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |
| **line_no** | `int` | An integer line number marking the beginning of the structure. |
| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |
| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |
| **comment** | `CommentDescriptor` \| `None` | A `CommentDescriptor` instance corresponding to the comment associated with the structure. Can be None if there is no comment. |
| **value** | `Any` | The value of the field. |
| **value_type** | `Type[Any]` | The type of the field value. |
| **stylings** | `StylingDescriptors` | An object with all stylings associated with the field. |
| **from_aot** | `bool` | A boolean indicating whether the field is nested within an array of tables. |
```python
# Retrieve a specific table
table = descriptor.get_table(hierarchy='table1')
```
**Return Type:** `TableDescriptor`
| **Attribute** | **Type** | **Description** |
|-----------------|------------------|-----------------|
| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the table. |
| **name** | `str` | The name of the table. |
| **item_type** | `TableItem` | A `TableItem` instance corresponding to a string literal, either 'table' or 'inline-table'. |
| **parent_type** | `ParentItem` \| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |
| **line_no** | `int` | An integer line number marking the beginning of the table. |
| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |
| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |
| **comment** | `CommentDescriptor` \| `None` | A `CommentDescriptor` instance corresponding to the comment associated with the structure. Can be None if there is no comment. |
| **fields** | `Dict[str, FieldDescriptor]` | A dictionary of key-value pairs, each being a field contained in the table. |
| **num_fields** | `int` | The number of fields contained in the table. |
| **stylings** | `StylingDescriptors` | An object with all stylings appearing within the table. |
| **from_aot** | `bool` | A boolean indicating whether the table is nested within an array of tables. |
```python
# Retrieve a specific AoT
aots = descriptor.get_aot(hierarchy='array_of_tables')
```
**Return Type:** `List[AoTDescriptor]`
| **Attribute** | **Type** | **Description** |
|--------------|-------------------|-----------------|
| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the array. |
| **name** | `str` | The name of the array of tables. |
| **item_type** | `AoTItem` | An `AoTItem` instance, the literal 'array-of-tables'. |
| **parent_type** | `ParentItem` \| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |
| **line_no** | `int` | An integer line number marking the beginning of the array of tables. |
| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |
| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |
| **tables** | `List[TableDescriptor]` | A list of `TableDescriptor` instances where each one represents a table within the array of tables. |
| **from_aot** | `bool` | A boolean indicating whether the array is nested within an array of tables. |
```python
# Get all comments from the top-level
stylings = descriptor.get_top_level_stylings(styling='comment')
```
**Return Type:** `List[StyleDescriptor]`
| **Attribute** | **Type** | **Description** |
|----------------|------------------|-----------------|
| **hierarchy** | `Hierarchy` \| `None` | A `Hierarchy` instance representing the full hierarchy of the styling, or None if it is a top-level styling. |
| **item_type** | `StyleItem` | A `StyleItem` instance corresponding to a string literal, either 'whitespace' or 'comment'. |
| **parent_type** | `ParentItem` \| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |
| **line_no** | `int` | An integer line number marking the beginning of the styling. |
| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |
| **style** | `str` | The string representation of the styling. |
| **from_aot** | `bool` | A boolean indicating whether the styling is nested within an array of tables. |
#### **`TOMLDocumentDescriptor` Properties**
- **`number_of_tables`**: Returns the number of tables in the TOML document.
- **`number_of_inline_tables`**: Returns the number of inline tables in the TOML document.
- **`number_of_aots`**: Returns the number of array-of-tables in the TOML document.
- **`number_of_arrays`**: Returns the number of arrays in the TOML document.
- **`number_of_comments`**: Returns the number of comments in the TOML document.
- **`number_of_fields`**: Returns the number of non-array fields in the TOML document.
#### **`TOMLDocumentDescriptor` Methods**
- **`get_field_from_aot(hierarchy)`**: Retrieves all fields from an array-of-tables at a given hierarchy.
- **`get_table_from_aot(hierarchy)`**: Retrieves all tables from an array-of-tables at a given hierarchy.
- **`get_aot(hierarchy)`**: Retrieves all array-of-tables at a given hierarchy.
- **`get_field(hierarchy)`**: Retrieves a field descriptor corresponding to a specific hierarchy.
- **`get_table(hierarchy)`**: Retrieves a table descriptor corresponding to a specific hierarchy.
- **`get_top_level_stylings(styling=None)`**: Retrieves top-level stylings such as comments or whitespace.
- **`get_stylings(styling, hierarchy=None)`**: Retrieves specific stylings, either whitespace or comments, at a specific hierarchy.
### **Using Provided Functions**
### **Comments**
#### **`get_comments` Function**
```python
from tomlkit_extras import get_comments
# Example usage
comments = get_comments(toml_doc, hierarchy=None)
```
**Return Type:** `List[ContainerComment]` \| `None`
Where `ContainerComment` is a **tuple** with the following objects:
| **Index** | **Type** | **Description** |
|---------------------|-------------------|-----------------|
| **0** | `int` | The line number where the comment is located. |
| **1** | `str` | The content of the comment. |
#### **`get_array_field_comment` Function**
```python
from tomlkit_extras import get_array_field_comment
# Example usage
comment = get_array_field_comment(array, array_item)
```
**Return Type:** `str` \| `None`
| **Type** | **Description** |
|-------------------|-----------------|
| `str` \| `None` | The comment associated with the array item. Can be None if the array item does not exist. |
### **Deletion**
#### **`delete_from_toml_source` Function**
```python
from tomlkit_extras import delete_from_toml_source
# Example usage
delete_from_toml_source('table1.key1', toml_doc)
```
**Return Type:** `None`
This will delete the key `key1` from the table `[table1]` within the provided TOML document. The deletion will cascade backwards to remove any empty structures left behind as a result of this deletion.
### **Insertion**
```python
from tomlkit_extras import load_toml_file
# Sample TOML content
raw_toml = """
[table1]
# This comment separates the first field
key1 = "value1"
# This comment separates the second field
key2 = "value2"
"""
# Load the TOML into a TOMLDocument
toml_doc = load_toml_file(raw_toml)
```
#### **`general_insert` Function**
```python
from tomlkit_extras import general_insert
# Example usage
general_insert(toml_doc, 'some_value', 'table1', 'some_key')
```
**Return Type:** `None`
This will insert a new key-value pair `some_key = "some_value"` into the `[table1]` table, at the bottom after all other fields and comments.
#### **`attribute_insert` Function**
```python
from tomlkit_extras import attribute_insert
# Example usage
attribute_insert(toml_doc, 'some_value', 2, 'table1', 'some_key')
```
**Return Type:** `None`
This will insert a new key-value pair `some_key = "some_value"` at position 2 within the `[table1]` table. This position is relative to other fields appearing within `[table1]`. Thus, the new field would appear between `key1` and `key2`.
#### **`container_insert` Function**
```python
from tomlkit_extras import container_insert
# Example usage
container_insert(toml_doc, 'some_value', 2, 'table1', 'some_key')
```
**Return Type:** `None`
This will insert a new key-value pair `some_key = "some_value"` at position 2 within the `[table1]` table. This position is relative to other fields and stylings (comments and whitespaces) appearing within `[table1]`. Thus, the new field would appear between the comment `# This comment separates the first field` and `key1`.
### **Out-of-Order**
#### **`fix_out_of_order_table` Function**
```python
from tomlkit_extras import fix_out_of_order_table
# Example usage
fixed_table = fix_out_of_order_table(out_of_order_table)
```
**Return Type:** `items.Table`
| **Type** | **Description** |
|-------------------|-----------------|
| `items.Table` | The re-ordered TOML table. |
#### **`fix_out_of_order_tables` Function**
```python
from tomlkit_extras import fix_out_of_order_tables
# Example usage
fix_out_of_order_tables(toml_doc)
```
**Return Type:** `None`
This will re-order all out-of-order tables in the provided TOML document. The changes are applied in-place.
### **Retrieval**
#### **`get_positions` Function**
```python
from tomlkit_extras import get_positions
# Example usage
attribute_pos, container_pos = get_positions('table1.key1', toml_doc)
```
**Return Type:** `Tuple[int, int]`
| **Index** | **Type** | **Description** |
|---------------------|-------------------|-----------------|
| **0** | `int` | The position of the item among key-value pairs in the container. |
| **1** | `int` | The position of the item among all container elements (including comments and whitespace). |
#### **`get_attribute_from_toml_source` Function**
```python
from tomlkit_extras import get_attribute_from_toml_source
# Example usage
attribute = get_attribute_from_toml_source('table1.key1', toml_doc)
```
**Return Type:** `Retrieval`
| **Type** | **Description** |
|-------------------|-----------------|
| `Retrieval` | The retrieved TOML item, which could be an Item, a Proxy, or a list of Items. |
#### **`is_toml_instance` Function**
```python
from tomlkit_extras import is_toml_instance
# Example usage
is_instance = is_toml_instance(str, 'table1.key1', toml_doc)
```
**Return Type:** `bool`
| **Type** | **Description** |
|-------------------|-----------------|
| `bool` | Indicates if the TOML item at the specified hierarchy is of the given type. |
### **Update**
#### **`update_toml_source` Function**
```python
from tomlkit_extras import update_toml_source
# Example usage
update_toml_source(toml_doc, {"key1": "some_value"}, 'table1')
```
**Return Type:** `None`
This will update the `key1` within `[table1]` to have the value `some_value`. The update will be done in place.
## 🔮 **Future Features**
- **TOML Modification**: Provide an extension to the `TOMLDocumentDescriptor` class for modification of structures while maintaining the fast lookup that is already provided.
- **Advanced Comment Handling**: Ability to modify and move comments programmatically.
## 🤝 **License**
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
## 📞 **Contact**
If you have any questions or need support, feel free to reach out by opening an issue on the [GitHub repository](#).
Raw data
{
"_id": null,
"home_page": null,
"name": "tomlkit-extras",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "galactixx",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/00/e0/f2e47582070d6ce4e924963c122123ba311bcbeaee59700b3cd566d7155a/tomlkit_extras-0.1.0.tar.gz",
"platform": null,
"description": "# tomlkit-extras\n\n\n**tomlkit-extras** is a Python package that extends the functionality of [tomlkit](https://github.com/sdispater/tomlkit), allowing for advanced manipulation, validation, and introspection of TOML files. This package provides enhanced capabilities for handling comments, nested structures, and other nuanced elements within TOML files.\n\n## \ud83d\udce6 **Installation**\n\nTo install tomlkit-extras, run the following command:\n\n```bash\npip install tomlkit-extras\n```\n\n## \ud83d\ude80 **Features**\n\n- **Comment Handling**: Introspect, modify, or retain comments within TOML files.\n- **Nested Structure Support**: Access, edit, and validate deeply nested tables and arrays.\n- **Validation Tools**: Validate and ensure the integrity of TOML file structures.\n- **Enhanced Introspection**: Retrieve metadata and structure details from TOML documents.\n- **Comprehensive Field Retrieval**: Extract and modify TOML fields and their properties.\n\n## \ud83d\udcda **Usage**\n\n### **Using `TOMLDocumentDescriptor`**\n\nThe `TOMLDocumentDescriptor` class provides powerful tools for parsing and extracting elements from a TOML document. It can be used to retrieve statistics, extract specific fields, tables, or array-of-tables, and analyze document stylings.\n\nBelow are examples showcasing some of the methods available in the `TOMLDocumentDescriptor` class.\n\n#### **Example Usage**\n\n```python\nfrom tomlkit_extras import TOMLDocumentDescriptor, load_toml_file\n\n# Sample TOML content\nraw_toml = \"\"\" \n# This is a top-level comment explaining the TOML file\n# It provides context about the file's purpose\n\n[table1] \nkey1 = \"value1\" \nkey2 = \"value2\" \n\n[[array_of_tables]] \nname = \"first\" \n\n[[array_of_tables]] \nname = \"second\" \n\"\"\"\n\n# Load the TOML into a TOMLDocument\ntoml_doc = load_toml_file(raw_toml)\n\n# Initialize the descriptor\ndescriptor = TOMLDocumentDescriptor(toml_doc)\n```\n\n```python\n# Access the number of tables appearing in the TOML document\nnum_tables = descriptor.number_of_tables\n```\n\n**Return Type:** `int`\n\n| **Description** |\n|-----------------|\n| The total number of tables in the TOML document. |\n\n```python\n# Access the number of array-of-tables appearing in the TOML document\nnum_aots = descriptor.number_of_aots\n```\n\n**Return Type:** `int`\n\n| **Description** |\n|-----------------|\n| The total number of array of tables in the TOML document. |\n\n```python\n# Retrieve a specific field\nfield = descriptor.get_field(hierarchy='table1.key1')\n```\n\n**Return Type:** `FieldDescriptor`\n\n| **Attribute** | **Type** | **Description** |\n|-------------------|-----------------------|-----------------|\n| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the field. |\n| **name** | `str` | The name of the field. |\n| **item_type** | `FieldItem` | A `FieldItem` instance corresponding to a string literal, either 'field' or 'array'. |\n| **parent_type** | `ParentItem` \\| `None`| A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |\n| **line_no** | `int` | An integer line number marking the beginning of the structure. |\n| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |\n| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |\n| **comment** | `CommentDescriptor` \\| `None` | A `CommentDescriptor` instance corresponding to the comment associated with the structure. Can be None if there is no comment. |\n| **value** | `Any` | The value of the field. |\n| **value_type** | `Type[Any]` | The type of the field value. |\n| **stylings** | `StylingDescriptors` | An object with all stylings associated with the field. |\n| **from_aot** | `bool` | A boolean indicating whether the field is nested within an array of tables. |\n\n```python\n# Retrieve a specific table\ntable = descriptor.get_table(hierarchy='table1')\n```\n\n**Return Type:** `TableDescriptor`\n\n| **Attribute** | **Type** | **Description** |\n|-----------------|------------------|-----------------|\n| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the table. |\n| **name** | `str` | The name of the table. |\n| **item_type** | `TableItem` | A `TableItem` instance corresponding to a string literal, either 'table' or 'inline-table'. |\n| **parent_type** | `ParentItem` \\| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |\n| **line_no** | `int` | An integer line number marking the beginning of the table. |\n| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |\n| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |\n| **comment** | `CommentDescriptor` \\| `None` | A `CommentDescriptor` instance corresponding to the comment associated with the structure. Can be None if there is no comment. |\n| **fields** | `Dict[str, FieldDescriptor]` | A dictionary of key-value pairs, each being a field contained in the table. |\n| **num_fields** | `int` | The number of fields contained in the table. |\n| **stylings** | `StylingDescriptors` | An object with all stylings appearing within the table. |\n| **from_aot** | `bool` | A boolean indicating whether the table is nested within an array of tables. |\n\n```python\n# Retrieve a specific AoT\naots = descriptor.get_aot(hierarchy='array_of_tables')\n```\n\n**Return Type:** `List[AoTDescriptor]`\n\n| **Attribute** | **Type** | **Description** |\n|--------------|-------------------|-----------------|\n| **hierarchy** | `Hierarchy` | A `Hierarchy` instance representing the full hierarchy of the array. |\n| **name** | `str` | The name of the array of tables. |\n| **item_type** | `AoTItem` | An `AoTItem` instance, the literal 'array-of-tables'. |\n| **parent_type** | `ParentItem` \\| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |\n| **line_no** | `int` | An integer line number marking the beginning of the array of tables. |\n| **attribute_position** | `int` | An integer position of the structure amongst all other key-value pairs (fields, tables) within the parent. |\n| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |\n| **tables** | `List[TableDescriptor]` | A list of `TableDescriptor` instances where each one represents a table within the array of tables. |\n| **from_aot** | `bool` | A boolean indicating whether the array is nested within an array of tables. |\n\n```python\n# Get all comments from the top-level\nstylings = descriptor.get_top_level_stylings(styling='comment')\n```\n\n**Return Type:** `List[StyleDescriptor]`\n\n| **Attribute** | **Type** | **Description** |\n|----------------|------------------|-----------------|\n| **hierarchy** | `Hierarchy` \\| `None` | A `Hierarchy` instance representing the full hierarchy of the styling, or None if it is a top-level styling. |\n| **item_type** | `StyleItem` | A `StyleItem` instance corresponding to a string literal, either 'whitespace' or 'comment'. |\n| **parent_type** | `ParentItem` \\| `None` | A `ParentItem` instance corresponding to a string literal representing the type of the parent of the structure. Can be None if there is no parent. |\n| **line_no** | `int` | An integer line number marking the beginning of the styling. |\n| **container_position** | `int` | An integer position of the structure amongst all types, including stylings (whitespace, comments), within the parent. |\n| **style** | `str` | The string representation of the styling. |\n| **from_aot** | `bool` | A boolean indicating whether the styling is nested within an array of tables. |\n\n#### **`TOMLDocumentDescriptor` Properties**\n\n- **`number_of_tables`**: Returns the number of tables in the TOML document.\n- **`number_of_inline_tables`**: Returns the number of inline tables in the TOML document.\n- **`number_of_aots`**: Returns the number of array-of-tables in the TOML document.\n- **`number_of_arrays`**: Returns the number of arrays in the TOML document.\n- **`number_of_comments`**: Returns the number of comments in the TOML document.\n- **`number_of_fields`**: Returns the number of non-array fields in the TOML document.\n\n#### **`TOMLDocumentDescriptor` Methods**\n\n- **`get_field_from_aot(hierarchy)`**: Retrieves all fields from an array-of-tables at a given hierarchy.\n- **`get_table_from_aot(hierarchy)`**: Retrieves all tables from an array-of-tables at a given hierarchy.\n- **`get_aot(hierarchy)`**: Retrieves all array-of-tables at a given hierarchy.\n- **`get_field(hierarchy)`**: Retrieves a field descriptor corresponding to a specific hierarchy.\n- **`get_table(hierarchy)`**: Retrieves a table descriptor corresponding to a specific hierarchy.\n- **`get_top_level_stylings(styling=None)`**: Retrieves top-level stylings such as comments or whitespace.\n- **`get_stylings(styling, hierarchy=None)`**: Retrieves specific stylings, either whitespace or comments, at a specific hierarchy.\n\n\n### **Using Provided Functions**\n\n### **Comments**\n\n#### **`get_comments` Function**\n\n```python\nfrom tomlkit_extras import get_comments\n\n# Example usage\ncomments = get_comments(toml_doc, hierarchy=None)\n```\n\n**Return Type:** `List[ContainerComment]` \\| `None`\n\nWhere `ContainerComment` is a **tuple** with the following objects:\n\n| **Index** | **Type** | **Description** |\n|---------------------|-------------------|-----------------|\n| **0** | `int` | The line number where the comment is located. |\n| **1** | `str` | The content of the comment. |\n\n#### **`get_array_field_comment` Function**\n\n```python\nfrom tomlkit_extras import get_array_field_comment\n\n# Example usage\ncomment = get_array_field_comment(array, array_item)\n```\n\n**Return Type:** `str` \\| `None`\n\n| **Type** | **Description** |\n|-------------------|-----------------|\n| `str` \\| `None` | The comment associated with the array item. Can be None if the array item does not exist. |\n\n### **Deletion**\n\n#### **`delete_from_toml_source` Function**\n\n```python\nfrom tomlkit_extras import delete_from_toml_source\n\n# Example usage\ndelete_from_toml_source('table1.key1', toml_doc)\n```\n\n**Return Type:** `None`\n\nThis will delete the key `key1` from the table `[table1]` within the provided TOML document. The deletion will cascade backwards to remove any empty structures left behind as a result of this deletion.\n\n### **Insertion**\n\n```python\nfrom tomlkit_extras import load_toml_file\n\n# Sample TOML content\nraw_toml = \"\"\" \n[table1] \n# This comment separates the first field\nkey1 = \"value1\" \n\n# This comment separates the second field\nkey2 = \"value2\" \n\"\"\"\n\n# Load the TOML into a TOMLDocument\ntoml_doc = load_toml_file(raw_toml)\n```\n\n#### **`general_insert` Function**\n\n```python\nfrom tomlkit_extras import general_insert\n\n# Example usage\ngeneral_insert(toml_doc, 'some_value', 'table1', 'some_key')\n```\n\n**Return Type:** `None`\n\nThis will insert a new key-value pair `some_key = \"some_value\"` into the `[table1]` table, at the bottom after all other fields and comments.\n\n#### **`attribute_insert` Function**\n\n```python\nfrom tomlkit_extras import attribute_insert\n\n# Example usage\nattribute_insert(toml_doc, 'some_value', 2, 'table1', 'some_key')\n```\n\n**Return Type:** `None`\n\nThis will insert a new key-value pair `some_key = \"some_value\"` at position 2 within the `[table1]` table. This position is relative to other fields appearing within `[table1]`. Thus, the new field would appear between `key1` and `key2`.\n\n#### **`container_insert` Function**\n\n```python\nfrom tomlkit_extras import container_insert\n\n# Example usage\ncontainer_insert(toml_doc, 'some_value', 2, 'table1', 'some_key')\n```\n\n**Return Type:** `None`\n\nThis will insert a new key-value pair `some_key = \"some_value\"` at position 2 within the `[table1]` table. This position is relative to other fields and stylings (comments and whitespaces) appearing within `[table1]`. Thus, the new field would appear between the comment `# This comment separates the first field` and `key1`.\n\n### **Out-of-Order**\n\n#### **`fix_out_of_order_table` Function**\n\n```python\nfrom tomlkit_extras import fix_out_of_order_table\n\n# Example usage\nfixed_table = fix_out_of_order_table(out_of_order_table)\n```\n\n**Return Type:** `items.Table`\n\n| **Type** | **Description** |\n|-------------------|-----------------|\n| `items.Table` | The re-ordered TOML table. |\n\n#### **`fix_out_of_order_tables` Function**\n\n```python\nfrom tomlkit_extras import fix_out_of_order_tables\n\n# Example usage\nfix_out_of_order_tables(toml_doc)\n```\n\n**Return Type:** `None`\n\nThis will re-order all out-of-order tables in the provided TOML document. The changes are applied in-place.\n\n### **Retrieval**\n\n#### **`get_positions` Function**\n\n```python\nfrom tomlkit_extras import get_positions\n\n# Example usage\nattribute_pos, container_pos = get_positions('table1.key1', toml_doc)\n```\n\n**Return Type:** `Tuple[int, int]`\n\n| **Index** | **Type** | **Description** |\n|---------------------|-------------------|-----------------|\n| **0** | `int` | The position of the item among key-value pairs in the container. |\n| **1** | `int` | The position of the item among all container elements (including comments and whitespace). |\n\n#### **`get_attribute_from_toml_source` Function**\n\n```python\nfrom tomlkit_extras import get_attribute_from_toml_source\n\n# Example usage\nattribute = get_attribute_from_toml_source('table1.key1', toml_doc)\n```\n\n**Return Type:** `Retrieval`\n\n| **Type** | **Description** |\n|-------------------|-----------------|\n| `Retrieval` | The retrieved TOML item, which could be an Item, a Proxy, or a list of Items. |\n\n#### **`is_toml_instance` Function**\n\n```python\nfrom tomlkit_extras import is_toml_instance\n\n# Example usage\nis_instance = is_toml_instance(str, 'table1.key1', toml_doc)\n```\n\n**Return Type:** `bool`\n\n| **Type** | **Description** |\n|-------------------|-----------------|\n| `bool` | Indicates if the TOML item at the specified hierarchy is of the given type. |\n\n### **Update**\n\n#### **`update_toml_source` Function**\n\n```python\nfrom tomlkit_extras import update_toml_source\n\n# Example usage\nupdate_toml_source(toml_doc, {\"key1\": \"some_value\"}, 'table1')\n```\n\n**Return Type:** `None`\n\nThis will update the `key1` within `[table1]` to have the value `some_value`. The update will be done in place.\n\n## \ud83d\udd2e **Future Features**\n\n- **TOML Modification**: Provide an extension to the `TOMLDocumentDescriptor` class for modification of structures while maintaining the fast lookup that is already provided.\n- **Advanced Comment Handling**: Ability to modify and move comments programmatically.\n\n## \ud83e\udd1d **License**\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## \ud83d\udcde **Contact**\n\nIf you have any questions or need support, feel free to reach out by opening an issue on the [GitHub repository](#).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package that extends the functionality of tomlkit, allowing for advanced manipulation, validation, and introspection of TOML files, including handling comments and nested structures",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31b738994aeec9aebd695a355fc0b660f718a38e48bf93ac5c2a63b64fc758fb",
"md5": "f05ffbc5f78ebd0632113787c50c7200",
"sha256": "893c151d783939ea8fdf3311e73c2a8d30b4f79ac8f10a2cbe5ab9a813dd7ce7"
},
"downloads": -1,
"filename": "tomlkit_extras-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f05ffbc5f78ebd0632113787c50c7200",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 50037,
"upload_time": "2024-12-17T06:12:14",
"upload_time_iso_8601": "2024-12-17T06:12:14.888913Z",
"url": "https://files.pythonhosted.org/packages/31/b7/38994aeec9aebd695a355fc0b660f718a38e48bf93ac5c2a63b64fc758fb/tomlkit_extras-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00e0f2e47582070d6ce4e924963c122123ba311bcbeaee59700b3cd566d7155a",
"md5": "15457209769f97fc06c4016bcd0f23cc",
"sha256": "0bf06476ca16cfc22791aa6f0ff5463f792c699e0aa4f7457fddd4480afcc04c"
},
"downloads": -1,
"filename": "tomlkit_extras-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "15457209769f97fc06c4016bcd0f23cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 42667,
"upload_time": "2024-12-17T06:12:17",
"upload_time_iso_8601": "2024-12-17T06:12:17.299453Z",
"url": "https://files.pythonhosted.org/packages/00/e0/f2e47582070d6ce4e924963c122123ba311bcbeaee59700b3cd566d7155a/tomlkit_extras-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 06:12:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tomlkit-extras"
}
