Which method name would you choose?

[Gribouillis]

I currently have this syntax

preamble, content = mediator.read()

Here, mediator is an instance of a Mediator class, which you can view as a smart pointer referencing a resource stored somewhere. The read() method accesses the resource and gets two things: a 'preamble' (instance of a Preamble class) and a 'content' which is a unicode string.

Problem: the method name read() doesn't seem very good to me because one usually expects that a read() method returns a string, but here it returns a tuple with two elements.

English is not my mother tongue, so what better word would you choose to name this method? The idea is to dereference the 'smart pointer' to get the pointed data.

[XavierPlatinum]

mediator.get_pointer_data()?

[jefsummers]

May be a bit wordy but mediator.get_preamble_and_content() leaves nothing to the imagination.

[PyDan]

Use type hints

mediator.read_data() -> tuple[preamble, content]:
mediator.import_data() -> tuple[preamble, content]:

this way you can change / append later

[Gribouillis]

Thank you all for your input. I think get_preamble_and_content() is too specific. It gives the impression that a mediator is a container which it is not, I want to keep it clear that it is some kind of pointer. get_pointer_data() and read_data() are a little verbose, the 'data' could be avoided. I think I'll use the following

resource = mediator.get()
# resource has members
resource.preamble
resource.text

The .get() makes it clear that we are dereferencing something. A known example is

response = requests.get(url)

We can see a url as a pointer to a resource on the internet, and it suffices to indicate that we dereference this pointer. A benefit of returning a single object is that this object's content can change later more easily.

There is an example of a smart pointer in the standard library: weak references

>>> from weakref import ref
>>> class A: pass
... 
>>> a = A()
>>> r = ref(a)
>>> r
<weakref at 0x7fedeedb1350; to 'A' at 0x7fedeed7f490>
>>> r()
<__main__.A object at 0x7fedeed7f490>

Here the __call__() is used to dereference the pointer, but I think it is cryptic for the reader of the program. get() is better than call.

Another example is that of tkinter variables, which are just pointers dereferenced by the get() method.

string = stringvar.get()

Thanks again, if you have more ideas about this, please add them to this thread.

[PyDan]

(Disclaimer, my primary language is C++, so …)

To me, get with no arguments means return an instance, I would read it as.

mediator.get()

returns a mediator.
Exactly as you mention “just pointers dereferenced by the get() method”

But now, I read

resource = mediator.get()

and I get confused, wait is resource a mediator or a tuple containing preamble and content?

If resource is a mediator with properties, preamble and content, then .get is perfect

[Gribouillis]

To me, get with no arguments means return an instance, I would read it as.

You're probably biased by your C++ culture, although cin.get() does not return an input stream in C++.

The problem is that we don't have a star operator to dereference pointers in Python. It is not possible to write

resource = *mediator

So the .get() method appears to be a simple way to mean 'dereference that pointer', unless you see a better alternative?

I would never interprete mediator.get() as 'get a Mediator'. Also in the Python culture, the example of the tkinter variables enlights the meaning of this 'get()'.

[buran]

IMHO, read is perfectly fine, especially in computer/programming context. Expecting read to return string is too narrow definition.
See e.g. https://www.google.com/search?&q=read+meaning See e.g. 3 or 6

...
inspect and record the figure indicated on (a measuring instrument).
"I've come to read the gas meter"

...

(of a computer) copy, transfer, or interpret (data).
"it attempts to read the disk without regard to its format"

enter or extract (data) in an electronic storage device.
"the commonest way of reading a file into the system"
(of a device) obtain data from (light or other input).
"the microchip gives a unique code when read by the scanner"
...

Disclaimer: I am not native English speaker