«

Since the event being generated is commonly called a "keystroke", and since
my dictionary defines the noun "stroke" as being: "the act of striking", a
good verb to choose for the action itself would seem to be "strike":

strike('a')

On Tue, 20 Nov 2012 04:18:38 -0800 (PST)
Michael Herrmann <> wrote:

> Hi,
>
> I'm developing a GUI Automation library (http://www.getautoma.com)
> and am having difficulty picking a name for the function that
> simulates key strokes. I currently have it as 'type' but that clashes
> with the built-in function. Example uses of 'type':
>
> type(ENTER)
>
> type("Hello World!")
>
> type(CTRL + 'a')
>
> What, in your view, would be the most intuitive alternative name?

keybot()
or
kbbot()

To counter your question. 10 sec. poll for the name for the law that
states that people will discuss/argue the most over those things
having little or no significance.

>
> Here are my thoughts so far: I could call it 'press' but then our GUI
> automation tool also allows you to click things and then "press"
> might be mistaken for "pressing a button". A less ambiguous
> alternative is "type_keys" but that is rather long and doesn't read
> as well, for instance in type_keys(ENTER).
>
> Thank you very much!


--

On Wed, Nov 21, 2012 at 4:25 PM, rh <> wrote:
> To counter your question. 10 sec. poll for the name for the law that
> states that people will discuss/argue the most over those things
> having little or no significance.

You mean bikeshedding? Parkinson's Law of something-or-other... not
the Law of Inverse Relevance, though the two do discuss the same sorts
of things.

And yet, trivial though it may seem, function naming in a permanent
API is pretty important. Threads like this can be the difference
between coherent and useful APIs and veritable piles of excrement.

ChrisA

On Wed, 21 Nov 2012 17:35:27 +1100, Chris Angelico wrote:

> And yet, trivial though it may seem, function naming in a permanent API
> is pretty important. Threads like this can be the difference between
> coherent and useful APIs and veritable piles of excrement.


"There are only two hard problems in Computer Science: cache invalidation
and naming things." -- Phil Karlton



--
Steven

Am Dienstag, 20. November 2012 13:18:38 UTC+1 schrieb Michael Herrmann:
> Hi,
>
>
>
> I'm developing a GUI Automation library (http://www.getautoma.com) and amhaving difficulty picking a name for the function that simulates key strokes. I currently have it as 'type' but that clashes with the built-in function. Example uses of 'type':
>
>
>
> type(ENTER)
>
>
>
> type("Hello World!")
>
>
>
> type(CTRL + 'a')
>
>
>
> What, in your view, would be the most intuitive alternative name?
>
>
>
> Here are my thoughts so far: I could call it 'press' but then our GUI automation tool also allows you to click things and then "press" might be mistaken for "pressing a button". A less ambiguous alternative is "type_keys" but that is rather long and doesn't read as well, for instance in type_keys(ENTER).
>
>
>
> Thank you very much!

I would expect 'type' or 'press'. 'type' is maybe not the best solution because of overloading. I like 'press'.

Good luck, Mr. Michael

On 21/11/12 02:17:26, Steven D'Aprano wrote:
> On Tue, 20 Nov 2012 18:00:59 -0600, Tim Chase wrote:
>
>> On 11/20/12 06:18, Michael Herrmann wrote:
>>> am having difficulty picking a name for the function that simulates key
>>> strokes. I currently have it as 'type' but that clashes with the
>>> built-in function.
>>
>> Just to add one more to the pot, Vim uses "feedkeys()" for a similar
>> purpose.
>
> What does it feed to the keys?

Spam, spam, spam, eggs, and spam.

-- HansM

Dear all,

thanks so much for your replies. Based on your inputs, we have started to experiment with changes to our API. I hope to be able to present the resultsto you tomorrow.

Thanks again,
Michael

On Tuesday, November 20, 2012 1:18:38 PM UTC+1, Michael Herrmann wrote:
> Hi,
>
>
>
> I'm developing a GUI Automation library (http://www.getautoma.com) and amhaving difficulty picking a name for the function that simulates key strokes. I currently have it as 'type' but that clashes with the built-in function. Example uses of 'type':
>
>
>
> type(ENTER)
>
>
>
> type("Hello World!")
>
>
>
> type(CTRL + 'a')
>
>
>
> What, in your view, would be the most intuitive alternative name?
>
>
>
> Here are my thoughts so far: I could call it 'press' but then our GUI automation tool also allows you to click things and then "press" might be mistaken for "pressing a button". A less ambiguous alternative is "type_keys" but that is rather long and doesn't read as well, for instance in type_keys(ENTER).
>
>
>
> Thank you very much!

On 21/11/2012 07:01, Steven D'Aprano wrote:
> On Wed, 21 Nov 2012 17:35:27 +1100, Chris Angelico wrote:
>
>> And yet, trivial though it may seem, function naming in a permanent API
>> is pretty important. Threads like this can be the difference between
>> coherent and useful APIs and veritable piles of excrement.
>
>
> "There are only two hard problems in Computer Science: cache invalidation
> and naming things." -- Phil Karlton
>

"counting" is missing from that list of two hard problems.

~Andrew

Dear all,

thank you for your replies. After experimenting with your suggestions, we have arrived at a solution that we believe fits well with our existing API. However, before we implement this solution, we would like to ask you one last time to sign off on our proposal or raise any serious problems you see with it.

We took the fact that naming our one function 'type' was so difficult to name as an indicator that it may be trying to do too many things: On the one hand, it allows you to enter plain text as in `type("Hello World!")`; on the other hand, it lets you press single keys, possibly in combination with control keys as for instance in `type(CTRL + 'a')`. We believe it won't normally be necessary to combine the two. For instance, while you could see what
type(CTRL + 'a' + "Hello World!")
does, we think you would be more likely to use the two separate calls
type(CTRL + 'a')
type("Hello World!")

One of the main goals of our automation product is that using it should feel like giving instructions to a human being looking over their shoulder at a screen. For this reason, it's very useful for us if the function names inour API are short, if possible without underscores, and close to the vocabulary you would use in an everyday conversation. We hope that by offering an API with this property, we can not only make it easier to use for experienced programmers such as yourself, but also be approachable for people froma less technical background.

In our gut feeling, the words apart from `type` that would most normally beused in an everyday conversation to express the three examples I have given in my first mail are:
press(CTRL + 'a')
enter("Hello World")
press(ENTER)

We really quite like the word `type`, and a few people here seem to favour it too. In particular, Steven: We're glad you accidentally clicked on our mail. Thank you for your inputs and the great quote by Phil Karlton. We think you were right in everything you said. However, some people seem to be *really* put off when you override a built-in function. Even though of courseyou can avoid the overriding by saying
from automa.api import type *as* ...,
(as Tim pointed out) we'd like to avoid irritating those people. For this reason, we would rather not use `type`.

Many people here voted for send_keys(...). We agree with Dave and Neil that`type` may have too many uses already. As Chris and MRAB pointed out, 'send_keys' is used in many other automation tools. This makes it intuitive forpeople with knowledge of such tools. However, as I said above (and should have probably said earlier), we are also trying to reach users from a less technical background. Since these people would not normally use 'send_keys'in an everyday conversion, we are afraid that it would not be an intuitivename for them. A similar argument applies to some extent to our 'type_keys', to our 'generate_keystrokes', Ramit's 'simulate_keypress', 'simulate_key(s)_down', 'send_kb_press', 'fake_typing' and 'send_char(s)' and Tim's 'feedkeys'. We thank you for your suggestions. Hopefully you can also agree with our choice!

Some suggestions were very nice, short and pretty unambiguous, such as Dennis' `emit` and particularly Alan's `strike`. However, they're unfortunatelyalso rather rarely used and we'd be afraid that it'd be hard to remember them. Thank you though!

A final point that Evan made and that also we find very important is to have verbs in our function names.

Our proposed solution is to split what we previously called `type` into twofunctions, 'press' and 'enter' (proposed by xDog Walker). 'press' could beused to press single keys or combinations of them, at once:
press(CTRL + 'a')
press(ENTER)
To open a menu via the keyboard, you could also supply several key combinations to be pressed, in sequence:
press(ALT + 'f', 's')
'enter' on the other hand would be used to enter longer strings of plain text:
enter("Hello World!")
With a functionality we already have, you could supply an optional 'into' parameter that selects a text field into which the text is entered:
enter("test.txt", into="File name")
'enter' currently does involve generating same system events that are firedwhen pressing (and releasing) sequences of keys. However, we did not want to include this technical detail in the function name - it keeps the name shorter, makes it more intuitive for users from a less technical background and also leaves us to change this implementation detail in the future.

These names aren't perfect. As Emile rightly pointed out, several tools distinguish between 'press' and 'release' and a user might wonder how to release a key that was pressed using 'press'. That's an ambiguity that is certainly there, however we hope that once the user has at least seen
press(ENTER)
it is clear what is meant. Distinguishing between pressing and releasing could we think easily be done with, say
hold_down(SHIFT)
...
release(SHIFT)
Another ambiguity of 'press' that I pointed out in my original mail is thatit could also be understood as "pressing a button". The current idea is toraise a ValueError if the user supplies a string that is longer than one character:
>>> press("OK")
ValueError: 'press' generates keystrokes and can only press single lettersat a time. Did you maybe mean click("OK") or press('O', 'K')?

What do you think of this solution? I hope anybody read this far. I probably shouldn't have written that much but wanted to do justice to your inputs.

Thanks!

Michael

On Tuesday, November 20, 2012 1:18:38 PM UTC+1, Michael Herrmann wrote:
> Hi,
>
>
>
> I'm developing a GUI Automation library (http://www.getautoma.com) and amhaving difficulty picking a name for the function that simulates key strokes. I currently have it as 'type' but that clashes with the built-in function. Example uses of 'type':
>
>
>
> type(ENTER)
>
>
>
> type("Hello World!")
>
>
>
> type(CTRL + 'a')
>
>
>
> What, in your view, would be the most intuitive alternative name?
>
>
>
> Here are my thoughts so far: I could call it 'press' but then our GUI automation tool also allows you to click things and then "press" might be mistaken for "pressing a button". A less ambiguous alternative is "type_keys" but that is rather long and doesn't read as well, for instance in type_keys(ENTER).
>
>
>
> Thank you very much!

On Fri, Nov 23, 2012 at 5:00 AM, Michael Herrmann
<> wrote:
> In our gut feeling, the words apart from `type` that would most normally be used in an everyday conversation to express the three examples I have given in my first mail are:
> press(CTRL + 'a')
> enter("Hello World")
> press(ENTER)

Looks fairly good, except for one possible problem: The verb "enter"
often means "type this, and then press the Enter key". (For instance,
"open up a terminal/shell and enter this command".) Is that likely to
be a point of confusion?

It's plenty plausible either way. I like the multiple-keystrokes version:
> press(ALT + 'f', 's')
and the split API does make good sense.

ChrisA