Use a better name for methods creating a new receiver

[leandro-lucarella-frequenz]

The Problem

Right now the LogicalMeter (and soon the BatteryPool and probably the EVChargerPool) name functions returning a receiver after the data that comes from the receiver.

Examples:

grid_power_receiver = logical_meter.grid_power()
power_bounds_receiver = battery_pool.power_bounds()

This can be a bit obscure for people that are new to programming with channels, senders and receivers in general and specifically new to the SDK.

People might think that the method (which sounds like a regular getter) might be idempotent so calling:

grid_power = await logical_meter.grid_power().receive()
# do something
grid_power = await logical_meter.grid_power().receive()

is OK, while in reality is creating multiple receivers, which adds overhead to the channel processing. Also if the channel has the option to always return the last value, it will receive a repeated value if there was nothing new between the first receive() and the second.

Suggested solutions

For me it is important to name functions after what they are really doing, so in this case the function should be called something that suggests it is creating a new receiver, because that's really what it is doing, and anything else is misleading.

Some options are:

1. p.new_WHAT_receiver()
2. p.WHAT.new_receiver()

p.new_WHAT_receiver()

Pros:

• Straightforward to implement.

Cons:

• A bit too long and clumsy.

p.WHAT.new_receiver()

Pros:

• Reads clean and nicely.

• Allows for adding extensions, new ways of retrieving the data, for example:

  current = await p.soc_capacity.current_value  # Queries the microgrid API (if it's even possible :D)
  last = p.soc_capacity.last_value  # If we have a channel getting this, we could peek into it
  resampled_receiver = p.soc_capacity.new_receiver()
  change_receiver = p.soc_capacity.new_changes_receiver()

• It is well structured, a pool or logical meter is providing access to some data, and each data can be retrieved in some particular way

Cons:

• Implementation is more complicated as it needs a wrapper.

[leandro-lucarella-frequenz]

FYI @frequenz-floss/python-sdk-team

I think I prefer the p.WHAT.new_receiver() approach, much of the implementation hassle can be abstracted out and reused and gives a nice and extensible interface, but I would be fine with p.new_WHAT_receiver().

I do really think it will be a mistake to keep the current approach if we want to make an SDK that is suitable for newcomers and not super experienced people.

[leandro-lucarella-frequenz]

Some supposed evidence that doing more than what the function name suggest is confusing :)

https://thenewstack.io/best-practices-for-naming-variables-what-the-research-shows/

[leandro-lucarella-frequenz]

Recently we had some people misunderstanding this interface for another reason. battery_pool.capacity() (and all these receiver-creating methods) is async, while the implementation doesn't require it at all.

So this is not even just creating a new receiver, it might be doing some async setup to actually create that receiver. Maybe it should even be called request_new_receiver().

This also makes me lean even more towards the p.WHAT.request_new_receiver() approach. This also allow us to have a common interface that can be enforced (the WHAT wrapper can implement this interface), because now it is only convention to make calls to battery_pool async even if it's not really needed. It could even allow us to provide a sync p.WHAT.new_receiver() for some metrics if that's supported and leave only the p.WHAT.request_new_receiver() for stuff that really needs it.

[mathias-baumann-frequenz]

I don't understand the adding extensions example. You seem to be using both of your suggestions in it?

[leandro-lucarella-frequenz]

No, if you mean p.soc_capacity.new_changes_receiver() here changes is not a metric, new_changes_receiver() would be a new receiver that only gets messages when soc_capacity changes, not on every resampling period.

It was trying to show how the same metric (soc_capacity) could be able to provide different types of receivers depending on how you need to get the metric.

[mathias-baumann-frequenz]

I like the p.WHAT.new_receiver() option.

[leandro-lucarella-frequenz]

We agreed to proceed with this:

• Use a better name for methods creating a new receiver #314