{"id":1866,"library":"pyhocon","title":"PyHOCON","description":"PyHOCON is a Python parser for the HOCON (Human Optimized Config Object Notation) configuration format. It allows for reading, parsing, and manipulating HOCON configuration files and strings, including support for substitutions, includes, and various data types. The library is actively maintained with irregular but consistent minor releases, currently at version 0.3.63.","status":"active","version":"0.3.63","language":"en","source_language":"en","source_url":"https://github.com/chimpler/pyhocon/","tags":["HOCON","config","parser","configuration","config-management"],"install":[{"cmd":"pip install pyhocon","lang":"bash","label":"Install PyHOCON"}],"dependencies":[],"imports":[{"note":"Main entry point for parsing HOCON strings and files.","symbol":"ConfigFactory","correct":"from pyhocon import ConfigFactory"},{"note":"Used for converting ConfigTree objects back to HOCON or other formats.","symbol":"HOCONConverter","correct":"from pyhocon import HOCONConverter"},{"note":"Represents the parsed HOCON configuration as a tree-like dictionary.","symbol":"ConfigTree","correct":"from pyhocon import ConfigTree"}],"quickstart":{"code":"import os\nfrom pyhocon import ConfigFactory, HOCONConverter\n\n# Example HOCON string\nhocon_string = \"\"\"\napp {\n    name = \"MyApplication\"\n    version = \"1.0.0\"\n    features = [\n        { id = 1, enabled = true },\n        { id = 2, enabled = false }\n    ]\n    environment = ${?ENV_NAME} # Optional environment variable substitution\n}\n\"\"\"\n\n# Parse from a string\nconfig_from_string = ConfigFactory.parse_string(hocon_string)\nprint(f\"Config from string: {config_from_string.get('app.name')}\")\n\n# Set an environment variable for substitution demonstration\nos.environ['ENV_NAME'] = 'production'\nconfig_from_string = ConfigFactory.parse_string(hocon_string)\nprint(f\"Config environment: {config_from_string.get('app.environment')}\")\nos.environ.pop('ENV_NAME') # Clean up\n\n# Create a dummy config file for parsing\nfile_content = \"\"\"\ndatabase {\n    host = \"localhost\"\n    port = 5432\n    user = \"admin\"\n}\n\"\"\"\nwith open(\"config.conf\", \"w\") as f:\n    f.write(file_content)\n\n# Parse from a file\nconfig_from_file = ConfigFactory.parse_file(\"config.conf\")\nprint(f\"Config from file: {config_from_file.get('database.host')}\")\n\n# Convert a ConfigTree back to HOCON string\nhocon_output = HOCONConverter.to_hocon(config_from_string)\nprint(\"\\nConverted HOCON output:\\n\", hocon_output)\n\n# Clean up dummy file\nos.remove(\"config.conf\")","lang":"python","description":"This quickstart demonstrates how to parse HOCON configuration from both a string and a file using `ConfigFactory`. It also shows how to use environment variable substitutions and how to convert a parsed configuration back into a HOCON string using `HOCONConverter`."},"warnings":[{"fix":"Ensure your `pyparsing` dependency is compatible with `>=2,<4`. If conflicts arise, consider upgrading or downgrading `pyparsing` to fit `pyhocon`'s requirements, or using a virtual environment to manage dependencies.","message":"The `pyparsing` dependency version constraint was updated from `~=2.0` to `>=2,<4` in version `0.3.60`. If your project has a specific older `pyparsing` version pinned or relies on `pyparsing` 3.x series, this change might cause dependency conflicts or unexpected behavior.","severity":"gotcha","affected_versions":">=0.3.60"},{"fix":"If encountering unexpected substitution behavior, upgrade to the latest version of `pyhocon`. Thoroughly test your configurations, particularly those with complex substitutions or environment variable reliance, after upgrading.","message":"Substitution resolution logic, especially for complex or nested substitutions, has received multiple fixes and enhancements across minor versions (e.g., 0.3.54, 0.3.58, 0.3.61). Behavior involving environment variables, cross-config resolutions, and override order might differ subtly between versions.","severity":"gotcha","affected_versions":"<0.3.61"},{"fix":"Review any HOCON configurations using relative `include` directives after upgrading. Ensure that `pyhocon` can still locate the included files correctly. You might need to adjust relative paths or ensure the working directory is set appropriately for file resolution.","message":"In version `0.3.57`, the logic for resolving package-relative paths was rewritten, and the internal `asset` library was removed. This change might subtly alter how `pyhocon` resolves relative file paths within HOCON `include` directives, especially if you had configurations that relied on specific interpretations of relative paths prior to this version.","severity":"gotcha","affected_versions":"<0.3.57"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}