pytimedinput
============
Description
-----------
A tiny, simplistic little alternative to the standard Python input()-function allowing you to specify an optional timeout for the function.
pytimedinput should work on both Windows and Linux, though no exceedingly extensive testing has been done and there might be bugs.
Install
-------
.. code:: bash
$ pip3 install pytimedinput
Usage
-----
timedInput()
............
*timedInput()* works similar to Python's default *input()* - function, asking user for a string of text, but *timedInput()* allows you to define an amount of time the user has to enter any text or how many consecutive seconds to wait for input, if the user goes idle.
.. code:: python
def timedInput(prompt="", timeout=5, resetOnInput=True, maxLength=0, allowCharacters="", endCharacters="\x1b\n\r")
The function *timedInput()* from *pytimedinput* accepts the following parameters:
- **prompt**, *str*: a string to show the user as a prompt when waiting for input.
*Defaults to an empty string.*
- **timeout**, *int*: how many seconds to wait before timing out.
*Defaults to 5 seconds, use -1 to disable.*
- **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.
*Defaults to True.*
- **maxLength**, *int*: the maximum length of the string user is allowed to enter.
*Defaults to 0, ie. unlimited.*
- **allowCharacters**, *str*: Which characters the user is allowed to enter.
*Defaults to "", ie. any character.*
- **endCharacters**, *str*: On which characters to stop accepting input.
*Defaults to "\\x1b\\n\\r", ie. ESC, newline and carriage-return. Cannot be empty.*
The function returns a tuple of:
- *str*: a string containing whatever the user typed, regardless of whether the function timed out or not.
- *bool*: whether the function timed out or not.
**Example:**
.. code:: python
from pytimedinput import timedInput
userText, timedOut = timedInput("Please, do enter something: ")
if(timedOut):
print("Timed out when waiting for input.")
print(f"User-input so far: '{userText}'")
else:
print(f"User-input: '{userText}'")
timedKey()
..........
*timedKey()* waits for the user to press one of a set of predefined keys, with a timeout, while ignoring any keys not on the list.
.. code:: python
def timedKey(prompt="", timeout=5, resetOnInput=True, allowCharacters="")
The function *timedKey()* from *pytimedinput* accepts the following parameters:
- **prompt**, *str*: a string to show the user as a prompt when waiting for input.
*Defaults to an empty string.*
- **timeout**, *int*: how many seconds to wait before timing out.
*Defaults to 5 seconds, use -1 to disable.*
- **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.
*Defaults to True.*
- **allowCharacters**, *str*: Which characters the user is allowed to enter.
*Defaults to "", ie. any character.*
The function returns a tuple of:
- *str*: a string containing the key the user pressed or an empty string.
- *bool*: whether the function timed out or not.
**Example:**
.. code:: python
from pytimedinput import timedKey
userText, timedOut = timedKey("Please, press 'y' to accept or 'n' to decline: ", allowCharacters="yn")
if(timedOut):
print("Timed out when waiting for input. Pester the user later.")
else:
if(userText == "y"):
print("User consented to selling their first-born child!")
else:
print("User unfortunately declined to sell their first-born child!")
**Tip: use timedKey() for the infamous "Press any key to continue."-prompt!**
.. code:: python
from pytimedinput import timedKey
timedKey("Press any key to continue.", timeout=-1)
timedInteger() and timedFloat()
...............................
*timedInteger()* and *timedFloat* work like *timedInput()*, except they only allow the user to enter numbers, and comma or period in case of *timedFloat*. Can be used to enter a negative number.
.. code:: python
def timedInteger(prompt="", timeout=5, resetOnInput=True, allowNegative=True)
The function *timedInteger()* and *timedFloat()* from *pytimedinput* accept the following parameters:
- **prompt**, *str*: a string to show the user as a prompt when waiting for input.
*Defaults to an empty string.*
- **timeout**, *int*: how many seconds to wait before timing out.
*Defaults to 5 seconds, use -1 to disable.*
- **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.
*Defaults to True.*
- **allowNegative**, *bool*: Whether to allow the user to enter a negative value or not.
The function returns a tuple of:
- *int/float* or *None*: an integer or float, depending on which function was called or None, if no number was entered.
- *bool*: whether the function timed out or not.
**Example:**
.. code:: python
from pytimedinput import *
userNumber, timedOut = timedFloat("Enter a floating-point value: ")
if(not timedOut):
if(userNumber == None):
print("We wanted a number, but got none.")
else:
print(f"We should do some fancy maths with {userNumber}!")
Exceptions
----------
All the functions require an interactive shell to function and will raise a Runtimerror-exception otherwise, which will need to be caught in any script that will be used both interactively and non-interactively.
License
-------
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/werecatf/pytimedinput/",
"name": "pytimedinput",
"maintainer": "WereCatf",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "werecatf@runbox.com",
"keywords": "Text-input,Shell,Interactive,Keyboard,Input",
"author": "WereCatf",
"author_email": "werecatf@runbox.com",
"download_url": "https://files.pythonhosted.org/packages/1f/22/4a13155366e99d78809bb05a92ee7644e5ca9e2d973ccb29cc304ce66c62/pytimedinput-2.0.1.tar.gz",
"platform": "",
"description": "pytimedinput\n============\n\nDescription\n-----------\n\nA tiny, simplistic little alternative to the standard Python input()-function allowing you to specify an optional timeout for the function.\n\npytimedinput should work on both Windows and Linux, though no exceedingly extensive testing has been done and there might be bugs.\n\nInstall\n-------\n\n.. code:: bash\n\n $ pip3 install pytimedinput\n\nUsage\n-----\n\ntimedInput()\n............\n\n*timedInput()* works similar to Python's default *input()* - function, asking user for a string of text, but *timedInput()* allows you to define an amount of time the user has to enter any text or how many consecutive seconds to wait for input, if the user goes idle.\n\n.. code:: python\n\n def timedInput(prompt=\"\", timeout=5, resetOnInput=True, maxLength=0, allowCharacters=\"\", endCharacters=\"\\x1b\\n\\r\")\n\nThe function *timedInput()* from *pytimedinput* accepts the following parameters:\n\n - **prompt**, *str*: a string to show the user as a prompt when waiting for input.\n *Defaults to an empty string.*\n - **timeout**, *int*: how many seconds to wait before timing out.\n *Defaults to 5 seconds, use -1 to disable.*\n - **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.\n *Defaults to True.*\n - **maxLength**, *int*: the maximum length of the string user is allowed to enter.\n *Defaults to 0, ie. unlimited.*\n - **allowCharacters**, *str*: Which characters the user is allowed to enter.\n *Defaults to \"\", ie. any character.*\n - **endCharacters**, *str*: On which characters to stop accepting input.\n *Defaults to \"\\\\x1b\\\\n\\\\r\", ie. ESC, newline and carriage-return. Cannot be empty.*\n\nThe function returns a tuple of:\n\n - *str*: a string containing whatever the user typed, regardless of whether the function timed out or not.\n - *bool*: whether the function timed out or not.\n\n**Example:**\n\n.. code:: python\n\n from pytimedinput import timedInput\n userText, timedOut = timedInput(\"Please, do enter something: \")\n if(timedOut):\n print(\"Timed out when waiting for input.\")\n print(f\"User-input so far: '{userText}'\")\n else:\n print(f\"User-input: '{userText}'\")\n\ntimedKey()\n..........\n*timedKey()* waits for the user to press one of a set of predefined keys, with a timeout, while ignoring any keys not on the list.\n\n.. code:: python\n\n def timedKey(prompt=\"\", timeout=5, resetOnInput=True, allowCharacters=\"\")\n\nThe function *timedKey()* from *pytimedinput* accepts the following parameters:\n\n - **prompt**, *str*: a string to show the user as a prompt when waiting for input.\n *Defaults to an empty string.*\n - **timeout**, *int*: how many seconds to wait before timing out.\n *Defaults to 5 seconds, use -1 to disable.*\n - **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.\n *Defaults to True.*\n - **allowCharacters**, *str*: Which characters the user is allowed to enter.\n *Defaults to \"\", ie. any character.*\n\nThe function returns a tuple of:\n\n - *str*: a string containing the key the user pressed or an empty string.\n - *bool*: whether the function timed out or not.\n\n**Example:**\n\n.. code:: python\n\n from pytimedinput import timedKey\n userText, timedOut = timedKey(\"Please, press 'y' to accept or 'n' to decline: \", allowCharacters=\"yn\")\n if(timedOut):\n print(\"Timed out when waiting for input. Pester the user later.\")\n else:\n if(userText == \"y\"):\n print(\"User consented to selling their first-born child!\")\n else:\n print(\"User unfortunately declined to sell their first-born child!\")\n\n**Tip: use timedKey() for the infamous \"Press any key to continue.\"-prompt!**\n\n.. code:: python\n\n from pytimedinput import timedKey\n timedKey(\"Press any key to continue.\", timeout=-1)\n\ntimedInteger() and timedFloat()\n...............................\n*timedInteger()* and *timedFloat* work like *timedInput()*, except they only allow the user to enter numbers, and comma or period in case of *timedFloat*. Can be used to enter a negative number.\n\n.. code:: python\n\n def timedInteger(prompt=\"\", timeout=5, resetOnInput=True, allowNegative=True)\n\nThe function *timedInteger()* and *timedFloat()* from *pytimedinput* accept the following parameters:\n\n - **prompt**, *str*: a string to show the user as a prompt when waiting for input.\n *Defaults to an empty string.*\n - **timeout**, *int*: how many seconds to wait before timing out.\n *Defaults to 5 seconds, use -1 to disable.*\n - **resetOnInput**, *bool*: Reset the timeout-timer any time user presses a key.\n *Defaults to True.*\n - **allowNegative**, *bool*: Whether to allow the user to enter a negative value or not.\n\nThe function returns a tuple of:\n\n - *int/float* or *None*: an integer or float, depending on which function was called or None, if no number was entered.\n - *bool*: whether the function timed out or not.\n\n**Example:**\n\n.. code:: python\n\n from pytimedinput import *\n userNumber, timedOut = timedFloat(\"Enter a floating-point value: \")\n if(not timedOut):\n if(userNumber == None):\n print(\"We wanted a number, but got none.\")\n else:\n print(f\"We should do some fancy maths with {userNumber}!\")\n\n\nExceptions\n----------\n\nAll the functions require an interactive shell to function and will raise a Runtimerror-exception otherwise, which will need to be caught in any script that will be used both interactively and non-interactively.\n\nLicense\n-------\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Query a user for input with a timeout.",
"version": "2.0.1",
"split_keywords": [
"text-input",
"shell",
"interactive",
"keyboard",
"input"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "012ad296b80c86d39e39208fbeebf2b2",
"sha256": "dcef8f5ce713f59cace8dc45e4dfc0e5c7369d44d533d4fbb772fa84ca36a110"
},
"downloads": -1,
"filename": "pytimedinput-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "012ad296b80c86d39e39208fbeebf2b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 6069,
"upload_time": "2021-10-25T10:02:39",
"upload_time_iso_8601": "2021-10-25T10:02:39.208617Z",
"url": "https://files.pythonhosted.org/packages/e3/12/2f7379e94fd521d7b965ab18ca494e82e71fe26ea8744684421ddc9b9423/pytimedinput-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e892f7830b6acbb2d26ff6e28a96f9c4",
"sha256": "f680c9a51a5677ffd0d15334628eb2e9e15ddad4a2d9222e00bf6c0d77768f41"
},
"downloads": -1,
"filename": "pytimedinput-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e892f7830b6acbb2d26ff6e28a96f9c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 5740,
"upload_time": "2021-10-25T10:02:42",
"upload_time_iso_8601": "2021-10-25T10:02:42.066695Z",
"url": "https://files.pythonhosted.org/packages/1f/22/4a13155366e99d78809bb05a92ee7644e5ca9e2d973ccb29cc304ce66c62/pytimedinput-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-10-25 10:02:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "werecatf",
"github_project": "pytimedinput",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pytimedinput"
}
JSON
