{"id":10300,"library":"tomledit","title":"tomledit","description":"tomledit is a Python library designed for parsing and editing TOML files while meticulously preserving comments, whitespace, and the original order of elements. It is especially useful for managing configuration files where maintaining human-readable formatting is critical. The current version is 1.1.0, and it is actively maintained with releases made as needed.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/dimbleby/tomledit","tags":["TOML","configuration","parser","editor","format-preserving"],"install":[{"cmd":"pip install tomledit","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"TomlDocument","correct":"from tomledit import TomlDocument"},{"symbol":"TomlEditError","correct":"from tomledit import TomlEditError"}],"quickstart":{"code":"from tomledit import TomlDocument\n\ntoml_content = \"\"\"\n# Main config\n[server]\nhost = \"localhost\" # Server IP\nport = 8080\n\n[database]\ntype = \"PostgreSQL\"\nuser = \"admin\"\n\"\"\"\n\n# Parse the TOML content\ndoc = TomlDocument.parse(toml_content)\n\nprint(\"--- Original Document ---\")\nprint(doc)\n\n# Modify values, preserving comments and format\ndoc[\"server\"][\"host\"] = \"127.0.0.1\"\ndoc[\"database\"][\"user\"] = \"dbuser\"\n\n# Add a new key to an existing table\ndoc[\"database\"][\"password\"] = \"securepassword\"\n\nprint(\"\\n--- Modified Document ---\")\nprint(doc)","lang":"python","description":"This quickstart demonstrates how to parse a TOML string, modify existing values, add new key-value pairs, and print the resulting document, all while preserving the original comments and formatting."},"warnings":[{"fix":"For highly specific formatting, it's often better to start with a template TOML file and load it, then make edits. If creating from a dict, accept the default formatting or manually adjust the output string if truly necessary.","message":"tomledit prioritizes format preservation for *existing* documents. When creating a new document entirely from a dictionary using `TomlDocument.from_dict()`, the resulting TOML string's formatting (e.g., indentation, spacing, table order) will use default styles and is not highly configurable to match specific aesthetic preferences.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For maximum format preservation, prefer direct item assignment (`doc['key'] = new_value`) for modifications. Avoid bulk dictionary operations on sub-structures if fine-grained control over original formatting and comments is critical.","message":"While `TomlDocument` mimics dictionary behavior, not all dictionary operations are fully format-preserving. Methods like `pop()`, `clear()`, or direct list manipulation (for arrays of tables) can lead to loss of associated comments or specific whitespace for the affected sections.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that the input TOML string or file is syntactically correct according to the TOML 1.0.0 specification before parsing with `TomlDocument.parse()` or `TomlDocument.load()`. Handle `TomlEditError` for expected invalid inputs.","message":"tomledit parses TOML 1.0.0. While robust, feeding it significantly malformed TOML will raise a `TomlEditError`. It's an editor designed to work with valid TOML, not a parser designed to recover from arbitrary syntax errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install tomledit`","cause":"The 'tomledit' package has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'tomledit'"},{"fix":"Review the TOML input at the specified line and column for syntax errors. `tomledit` requires valid TOML for parsing, even if its goal is to preserve formatting during edits.","cause":"The input TOML string provided to `TomlDocument.parse()` or the file loaded by `TomlDocument.load()` contains syntax errors and is not valid TOML.","error":"TomlEditError: Unexpected token '...' at line X, column Y"},{"fix":"Ensure all modifications are done directly on the `TomlDocument` object using item assignment (`doc['key'] = new_value`) to preserve associated comments. Avoid `pop()` for modifications where comments must be retained. If saving to a file, use `doc.dump(file_object)`.","cause":"This typically occurs if you use non-format-preserving dictionary methods (like `pop()`) on a `TomlDocument` object, which removes the entire node including its comments. It can also happen if you print the document to a string and then re-parse that string, as some default string representations may not perfectly capture all formatting.","error":"My comments are gone after modifying a TOML value!"}]}