Surprisingly, with_fallback() mutates parameter

[twm]

It's not in the docs proper, but with_fallback() is described in the readme:

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

I read this to mean that config3 is a new object, independent of config1 or config2—a copy.

That's not what happens, though. Actually, config3 is config2!

For example:

In [1]: from pyhocon import ConfigTree

In [2]: a = ConfigTree()

In [3]: a.put('foo.bar', ['a'])

In [4]: b = ConfigTree()

In [5]: b.put('foo.bar', ['b'])

In [6]: a
Out[6]: ConfigTree([('foo', ConfigTree([('bar', ['a'])]))])

In [7]: b
Out[7]: ConfigTree([('foo', ConfigTree([('bar', ['b'])]))])

In [8]: c = a.with_fallback(b)

In [9]: a
Out[9]: ConfigTree([('foo', ConfigTree([('bar', ['a'])]))])

In [10]: b
Out[10]: ConfigTree([('foo', ConfigTree([('bar', ['a'])]))])

In [11]: c
Out[11]: ConfigTree([('foo', ConfigTree([('bar', ['a'])]))])

In [12]: c is a
Out[12]: False

In [13]: c is b
Out[13]: True

I would expect a method on a to either return a copy of a, or mutate a (and return None). Mutating and returning b is quite surprising and at the least should be called out explicitly in the docs! Returning a new ConfigTree instance would be best, though.