10 sec poll - please reply!

[Michael Herrmann]

Dear all, 

the emails are getting kind of long so to ask you briefly: What do you think of splitting `type` into two functions `press` and `enter`? Their use cases are:
        press(CTRL + 'a') 
        press(ENTER) 
        press(ALT + 'f', 's') 
        enter("Hello World!") 
        enter("test.txt", into="File name") 

Thanks, 
Michael

On Thursday, November 22, 2012 7:00:55 PM UTC+1, Michael Herrmann wrote:
> 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!