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 in our
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 from a less
technical background.
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)
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 course you 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 for
people 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 intuitive name 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 unfortunately also
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 two
functions, 'press' and 'enter' (proposed by xDog Walker). 'press' could be used
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 fired
when 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 that it
could also be understood as "pressing a button". The current idea is to raise 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
letters at 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 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?
>
>
>
> 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!
--
http://mail.python.org/mailman/listinfo/python-list
