happi cfg documentation?

[untzag]

Why do I need a configuration file to use the happi CLI? I don't need one for the Python interface, as far as I can tell.

Are the contents of this file documented anywhere?

[klauer]

Most likely your config file is either set by way of HAPPI_CFG or you may have put it in ~/.config as we had talked about in #189 (comment).

The happi CLI will try to load from the default locations if HAPPI_CFG and --path are not specified. The Python Client interface will do the same when you call happi.client.Client.from_config().

As to documentation - I think the answer is not yet. The contents are backend-dependent, as instantiating a JSON "database" client requires a path to a file, whereas the mongo backend requires server information.

Digging into the source

happi/happi/client.py

Lines 664 to 691 in 5c7b3a2

	cfg_parser = configparser.ConfigParser()
	cfg_file = cfg_parser.read(cfg)
	logger.debug("Loading configuration file at %r", cfg_file)
	db_kwargs = cfg_parser['DEFAULT']
	# If a backend is specified use it, otherwise default
	if 'backend' in db_kwargs:
	db_str = db_kwargs.pop('backend')
	try:
	backend = BACKENDS[db_str]
	except KeyError:
	raise RuntimeError(
	f'Happi backend {db_str!r} unavailable'
	) from None
	else:
	backend = DEFAULT_BACKEND
	logger.debug("Using Happi backend %r with kwargs", backend, db_kwargs)
	# Create our database with provided kwargs
	try:
	database = backend(**db_kwargs)
	return cls(database=database)
	except Exception as ex:
	raise RuntimeError(
	f'Unable to instantiate the client. Please verify that '
	f'your HAPPI_CFG points to the correct file and has '
	f'the required configuration settings. In {cfg!r}, found '
	f'settings: {dict(db_kwargs)}.'
	) from ex

Indicates: DEFAULT is the required "ini"-like section, and this is where the keywords to the backend initialization are derived from.

JSON backend:

happi/happi/backends/json_db.py

Line 49 in 5c7b3a2

def __init__(self, path, initialize=False):

So here, path is the required setting.

Mongo:

happi/happi/backends/mongo_db.py

Lines 40 to 42 in 5c7b3a2

	def __init__(self, host=None, user=None,
	pw=None, db=None, collection=None,
	timeout=None):

For this one, despite being optional in the initializer, the format string above pretty clearly shows you'll need to have user, pw, host, and db.

[untzag]

Thanks for your patient response @klauer. I now see exactly how the config file works. I'll write some notes to myself about it 😄

[klauer]

No problem at all. I'll flip that around and say thanks for prodding us to make happi better.

This is still a valid issue - so I'll reopen it as a reminder that we need to actually document this.

[tangkong]

With the addition of #287 , there's some notes to be added about the multi-backend backend, particularly when it comes to backend priority and config file section ordering.