PyInputPlus
===========
A Python 2 and 3 module to provide input()- and raw_input()-like functions with additional validation features, including:
* Re-prompting the user if they enter invalid input.
* Validating for numeric, boolean, date, time, or yes/no responses.
* Timeouts or retry limits for user responses.
* Specifying regexes for whitelists or blacklists of responses.
* Specifying ranges for numeric inputs.
* Presenting menus with bulleted, lettered, or numbered options.
* Allowing case-sensitive or case-insensitive responses.
Installation
------------
pip install pyinputplus
Example Usage
-------------
>>> import pyinputplus as pyip
>>> result = pyip.inputStr()
Blank values are not allowed.
Hello
>>> result
'Hello'
>>> result = pyip.inputNum()
forty two
'forty two' is not a number.
42
>>> result
42
>>> result = pyip.inputNum(min=4, max=6)
3
Input must be at minimum 4.
7
Input must be at maximum 6.
4
>>> result
4
>>> result = pyip.inputNum(greaterThan=4, lessThan=6)
4
Input must be greater than 4.
4.1
>>> result
4.1
>>> result = pyip.inputStr('Favorite animal> ', blacklistRegexes=['moose'])
Favorite animal> moose
This response is invalid.
Favorite animal> cat
>>> result
'cat'
>>> result = inputMenu(['dog', 'cat', 'moose'])
Please select one of the following:
* dog
* cat
* moose
DoG
>>> result
'dog'
>>> result = inputMenu(['dog', 'cat', 'moose'], lettered=True, numbered=False)
Please select one of the following:
A. dog
B. cat
C. moose
b
>>> result
'cat'
Common Input Function Parameters
--------------------------------
All input functions have the following parameters:
* `prompt` (str): The text to display before each prompt for user input. Identical to the prompt argument for Python's `raw_input()` and `input()` functions. Default
* `default` (str, None): A default value to use should the user time out or exceed the number of tries to enter valid input.
* `blank` (bool): If `True`, blank strings will be allowed as valid user input.
* `timeout` (int, float): The number of seconds since the first prompt for input after which a TimeoutException is raised the next time the user enters input.
* `limit` (int): The number of tries the user has to enter valid input before the default value is returned.
* `strip` (bool, str, None): If `True`, whitespace is stripped from `value`. If a str, the characters in it are stripped from value. If `None`, nothing is stripped. Defaults to `True`.
* `whitelistRegexes` (Sequence, None): A sequence of regex str that will explicitly pass validation, even if they aren't numbers. Defaults to `None`.
* `blacklistRegexes` (Sequence, None): A sequence of regex str or (regex_str, response_str) tuples that, if matched, will explicitly fail validation. Defaults to `None`.
* `applyFunc` (Callable, None): An optional function that is passed the user's input, and returns the new value to use as the input.
* `validationFunc` (Callable): A function that is passed the user's input value, which raises an exception if the input isn't valid. (The return value of this function is ignored.)
* `postValidateApplyFunc` (Callable): An optional function that is passed the user's input after it has passed validation, and returns a transformed version for the input function to return.
Other input functions may have additional parameters.
Input Functions
---------------
* `inputStr()` - Accepts a string. Use this if you basically want Python's `input()` or `raw_input()`, but with PyInputPlus features such as whitelist/blacklist, timeouts, limits, etc.
* `inputNum()` - Accepts a numeric number. Additionally has `min` and `max` parameters for inclusive bounds and `greaterThan` and `lessThan` parameters for exclusive bounds. Returns an int or float, not a str.
* `inputInt()` - Accepts an integer number. Also has `min`/`max`/`greaterThan`/`lessThan` parameters. Returns an int, not a str.
* `inputFloat()` - Accepts a floating-point number. Also has `min`/`max`/`greaterThan`/`lessThan` parameters. Returns a float, not a str.
* `inputBool()` - Accepts a case-insensitive form of `'True'`, `'T'`, `'False'`, or `'F'` and returns a bool value.
* `inputChoice()` - Accepts one of the strings in the list of strings passed for its `choices` parameter.
* `inputMenu()` - Similar to `inputChoice()`, but will also present the choices in a menu with 1, 2, 3... or A, B, C... options if `numbered` or `lettered` are set to `True`.
* `inputDate()` - Accepts a date typed in one of the `strftime` formats passed to the `formats` parameter. (This has several common formats by default.) Returns a `datetime.date` object.
* `inputDatetime()` - Same as `inputDate()`, except it handles dates and times. (This has several common formats by default.) Returns a `datetime.datetime` object.
* `inputTime()` - Same as `inputDate()`, except it handles times. (This has several common formats by default.) Returns a `datetime.time` object.
* `inputYesNo()` - Accepts a case-insensitive form of `'Yes'`, `'Y'`, `'No'`, or `'N'` and returns `'yes'` or `'no'`.
Raw data
{
"_id": null,
"home_page": "https://github.com/asweigart/pyinputplus",
"name": "PyInputPlus",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "input validation text gui message box",
"author": "Al Sweigart",
"author_email": "al@inventwithpython.com",
"download_url": "https://files.pythonhosted.org/packages/6a/d4/afb45ed88323ef6d3c4cbf48e9c1bac38059a168b8392a56f3b8f9d1d39c/PyInputPlus-0.2.12.tar.gz",
"platform": "",
"description": "PyInputPlus\n===========\n\nA Python 2 and 3 module to provide input()- and raw_input()-like functions with additional validation features, including:\n\n* Re-prompting the user if they enter invalid input.\n* Validating for numeric, boolean, date, time, or yes/no responses.\n* Timeouts or retry limits for user responses.\n* Specifying regexes for whitelists or blacklists of responses.\n* Specifying ranges for numeric inputs.\n* Presenting menus with bulleted, lettered, or numbered options.\n* Allowing case-sensitive or case-insensitive responses.\n\nInstallation\n------------\n\n pip install pyinputplus\n\nExample Usage\n-------------\n\n >>> import pyinputplus as pyip\n >>> result = pyip.inputStr()\n\n Blank values are not allowed.\n Hello\n >>> result\n 'Hello'\n\n >>> result = pyip.inputNum()\n forty two\n 'forty two' is not a number.\n 42\n >>> result\n 42\n\n >>> result = pyip.inputNum(min=4, max=6)\n 3\n Input must be at minimum 4.\n 7\n Input must be at maximum 6.\n 4\n >>> result\n 4\n\n >>> result = pyip.inputNum(greaterThan=4, lessThan=6)\n 4\n Input must be greater than 4.\n 4.1\n >>> result\n 4.1\n\n >>> result = pyip.inputStr('Favorite animal> ', blacklistRegexes=['moose'])\n Favorite animal> moose\n This response is invalid.\n Favorite animal> cat\n >>> result\n 'cat'\n\n >>> result = inputMenu(['dog', 'cat', 'moose'])\n Please select one of the following:\n * dog\n * cat\n * moose\n DoG\n >>> result\n 'dog'\n\n >>> result = inputMenu(['dog', 'cat', 'moose'], lettered=True, numbered=False)\n Please select one of the following:\n A. dog\n B. cat\n C. moose\n b\n >>> result\n 'cat'\n\nCommon Input Function Parameters\n--------------------------------\n\nAll input functions have the following parameters:\n\n* `prompt` (str): The text to display before each prompt for user input. Identical to the prompt argument for Python's `raw_input()` and `input()` functions. Default\n* `default` (str, None): A default value to use should the user time out or exceed the number of tries to enter valid input.\n* `blank` (bool): If `True`, blank strings will be allowed as valid user input.\n* `timeout` (int, float): The number of seconds since the first prompt for input after which a TimeoutException is raised the next time the user enters input.\n* `limit` (int): The number of tries the user has to enter valid input before the default value is returned.\n* `strip` (bool, str, None): If `True`, whitespace is stripped from `value`. If a str, the characters in it are stripped from value. If `None`, nothing is stripped. Defaults to `True`.\n* `whitelistRegexes` (Sequence, None): A sequence of regex str that will explicitly pass validation, even if they aren't numbers. Defaults to `None`.\n* `blacklistRegexes` (Sequence, None): A sequence of regex str or (regex_str, response_str) tuples that, if matched, will explicitly fail validation. Defaults to `None`.\n* `applyFunc` (Callable, None): An optional function that is passed the user's input, and returns the new value to use as the input.\n* `validationFunc` (Callable): A function that is passed the user's input value, which raises an exception if the input isn't valid. (The return value of this function is ignored.)\n* `postValidateApplyFunc` (Callable): An optional function that is passed the user's input after it has passed validation, and returns a transformed version for the input function to return.\n\nOther input functions may have additional parameters.\n\nInput Functions\n---------------\n\n* `inputStr()` - Accepts a string. Use this if you basically want Python's `input()` or `raw_input()`, but with PyInputPlus features such as whitelist/blacklist, timeouts, limits, etc.\n* `inputNum()` - Accepts a numeric number. Additionally has `min` and `max` parameters for inclusive bounds and `greaterThan` and `lessThan` parameters for exclusive bounds. Returns an int or float, not a str.\n* `inputInt()` - Accepts an integer number. Also has `min`/`max`/`greaterThan`/`lessThan` parameters. Returns an int, not a str.\n* `inputFloat()` - Accepts a floating-point number. Also has `min`/`max`/`greaterThan`/`lessThan` parameters. Returns a float, not a str.\n* `inputBool()` - Accepts a case-insensitive form of `'True'`, `'T'`, `'False'`, or `'F'` and returns a bool value.\n* `inputChoice()` - Accepts one of the strings in the list of strings passed for its `choices` parameter.\n* `inputMenu()` - Similar to `inputChoice()`, but will also present the choices in a menu with 1, 2, 3... or A, B, C... options if `numbered` or `lettered` are set to `True`.\n* `inputDate()` - Accepts a date typed in one of the `strftime` formats passed to the `formats` parameter. (This has several common formats by default.) Returns a `datetime.date` object.\n* `inputDatetime()` - Same as `inputDate()`, except it handles dates and times. (This has several common formats by default.) Returns a `datetime.datetime` object.\n* `inputTime()` - Same as `inputDate()`, except it handles times. (This has several common formats by default.) Returns a `datetime.time` object.\n* `inputYesNo()` - Accepts a case-insensitive form of `'Yes'`, `'Y'`, `'No'`, or `'N'` and returns `'yes'` or `'no'`.",
"bugtrack_url": null,
"license": "BSD",
"summary": "Provides more featureful versions of input() and raw_input().",
"version": "0.2.12",
"split_keywords": [
"input",
"validation",
"text",
"gui",
"message",
"box"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ad4afb45ed88323ef6d3c4cbf48e9c1bac38059a168b8392a56f3b8f9d1d39c",
"md5": "73d419bb080b37fa88e9f2a50f9b54aa",
"sha256": "3a86b03dc6d003fec7dc627ad175cacaaf6e14a6a3b13b34c8fe6f5d01506231"
},
"downloads": -1,
"filename": "PyInputPlus-0.2.12.tar.gz",
"has_sig": false,
"md5_digest": "73d419bb080b37fa88e9f2a50f9b54aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20872,
"upload_time": "2020-10-11T01:31:20",
"upload_time_iso_8601": "2020-10-11T01:31:20.243801Z",
"url": "https://files.pythonhosted.org/packages/6a/d4/afb45ed88323ef6d3c4cbf48e9c1bac38059a168b8392a56f3b8f9d1d39c/PyInputPlus-0.2.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-10-11 01:31:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "asweigart",
"github_project": "pyinputplus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyinputplus"
}
JSON
