DOCSEARCHbyAlgolia
Submit Docs

pyhocon Documentation

repository·master·Indexed 19 days ago

https://github.com/chimpler/pyhocon

A HOCON (Human-Optimized Config Object Notation) parser for Python. It supports hierarchical configuration with includes, substitutions, and merges. Features include a ConfigFactory for parsing files and dictionaries, type-specific getter methods, fallback configurations via with_fallback, and a CLI tool for converting HOCON to JSON, Properties, or YAML.

Tokens
1.6K
Snippets
6
Records
8
Agent score
18%

What's inside pyhocon

  1. How duration and period support works in pyhocon

    master

    Pyhocon implements HOCON duration/period support with the following deviations from the standard spec:

    • Nanoseconds: Supported by converting them to microseconds (divided by 1000 and rounded to an integer).
    • 'm' suffix: Only applies to minutes. In the standard spec, m can also mean months, but this is avoided here to prevent syntax conflicts.
    • Months and Years: These are only available if the dateutils package is installed (which uses relativedelta instead of timedelta).

  2. How HOCON includes work

    master

    HOCON supports including other files or URLs. When a relative path is used, the base directory is the directory of the file containing the include statement. If standard input is used, the current directory is the base. Included files are merged into the existing configuration; if keys overlap, the included values overwrite the existing ones.

    include "test.conf"
include "http://abc.com/test.conf"
include "https://abc.com/test.conf"
include "file://abc.com/test.conf"
include file("test.conf")
include required(file("test.conf"))
include url("http://abc.com/test.conf")
include url("https://abc.com/test.conf")
include url("file://abc.com/test.conf")
include package("package:assets/test.conf")

  4. Create a config from a dictionary with ConfigFactory.from_dict

    master

    You can create a HOCON configuration object directly from a Python dictionary using ConfigFactory.from_dict(d).

    from collections import OrderedDict
from pyhocon import ConfigFactory

d = OrderedDict()
d['banana'] = 3
d['apple'] = 4
d['pear'] = 1
d['orange'] = 2
config = ConfigFactory.from_dict(d)
assert config == d

  5. Use with_fallback to provide alternative configurations

    master

    The with_fallback method allows you to create a new configuration that falls back to another configuration if a key is not found. You can pass either another config object or a path to a file.

    Usage: config3 = config1.with_fallback(config2) or config3 = config1.with_fallback('samples/aws.conf')

  6. Parse HOCON files and access configuration values

    master

    Use ConfigFactory.parse_file to load a HOCON file. The resulting configuration object behaves like a nested dictionary. You can access values using:

    • Standard dictionary keys: conf['a']['b']
    • Path strings: conf['a.b']
    • The .get() method (supports default values).
    • Type-specific methods: .get_int(), .get_string(), .get_list(), .get_float(), .get_bool(), and .get_config() (returns a sub-config object).
    from pyhocon import ConfigFactory

conf = ConfigFactory.parse_file('samples/database.conf')
host = conf.get_string('databases.mysql.host')
same_host = conf.get('databases.mysql.host')
same_host = conf['databases.mysql.host']
same_host = conf['databases']['mysql.host']
port = conf['databases.mysql.port']
username = conf['databases']['mysql']['username']
password = conf.get_config('databases')['mysql.password']
password = conf.get('databases.mysql.password', 'default_password') # use default value if key not found

  7. Reference: HOCON Conversion CLI flags

    master

    The following flags are available for the pyhocon conversion tool:

    • -i, --input INPUT: Input file (defaults to stdin).
    • -o, --output OUTPUT: Output file (defaults to stdout).
    • -c, --compact: Use a compact representation for nested dictionaries of one element (e.g., a.b.c = 1).
    • -f FORMAT, --format FORMAT: Output format. Supported values: json, properties, yaml, or hocon.
    • -n INDENT, --indent INDENT: Indentation step (default is 2).
    • -v, --verbosity: Increase output verbosity.
      -i INPUT, --input INPUT    input file
  -o OUTPUT, --output OUTPUT output file
  -c, --compact              compact format
  -f FORMAT, --format FORMAT output format: json, properties, yaml or hocon
  -n INDENT, --indent INDENT indentation step (default is 2)
  -v, --verbosity            increase output verbosity

  8. Convert HOCON to JSON, Properties, or YAML

    master

    The pyhocon CLI tool allows you to convert HOCON files into other formats. If no input file is provided via -i, it reads from standard input. If no output file is provided via -o, it writes to standard output.

    usage: tool.py [-h] [-i INPUT] [-o OUTPUT] [-f FORMAT] [-n INDENT] [-v]

pyhocon tool

optional arguments:
  -h, --help                 show this help message and exit
  -i INPUT, --input INPUT    input file
  -o OUTPUT, --output OUTPUT output file
  -c, --compact              compact format
  -f FORMAT, --format FORMAT output format: json, properties, yaml or hocon
  -n INDENT, --indent INDENT indentation step (default is 2)
  -v, --verbosity            increase output verbosity