A practical utility library for transforming data, handling user input,
and parsing text in Python. Built for interactive development workflows
where you need to quickly process messy real-world data without
wrestling with configuration or format conversion.
This library works immediately without setup ceremonies, accepts
inconsistent input gracefully, and fails helpfully when things go wrong.
Functions are designed around common patterns in data science, CLI
tools, DevOps automation, and exploratory programming.
**Who benefits from this library:** - Data scientists working with
inconsistent input formats - CLI tool builders who need robust text
processing - DevOps engineers automating data transformation tasks -
Anyone prototyping data processing pipelines interactively - Developers
tired of writing the same input handling code repeatedly
This library prioritizes **data integrity** and **cognitive load
reduction**. Key design principles: - **Format Agnosticism**: Functions
accept multiple input formats rather than enforcing strict types -
**Conservative Type Conversion**: Preserves data semantics (like leading
zeros) rather than aggressive normalization - **Graceful Degradation**:
Multiple fallback strategies before giving up - **Self-Documenting**:
Function names describe behavior clearly, reducing documentation
dependency - **REPL-Optimized**: Designed for interactive development
with immediate feedback - **Stateless**: No global configuration or
hidden state; same inputs always produce same outputs
Tested for Python 3.5 - 3.13.
Install
-------
::
pip install input-helper
Dependencies
~~~~~~~~~~~~
Core functionality requires only Python standard library. Optional
features: - **xmljson**: For XML parsing
(``pip install input-helper[xmljson]``) - **IPython**: For enhanced REPL
sessions (``pip install input-helper[ipython]``)
QuickStart
----------
.. code:: python
import input_helper as ih
# Transform messy string data into clean Python objects
data = ih.string_to_converted_list('dog, 01, 2, 3.10, none, true')
# Returns: ['dog', '01', 2, 3.1, None, True]
# Note: leading zeros preserved (often semantic), types inferred safely
# Parse complex nested structures with dot notation
nested_data = {
'order': {'details': {'price': 99.99, 'items': ['phone', 'case']}},
'user': {'name': 'John', 'verified': True}
}
price = ih.get_value_at_key(nested_data, 'order.details.price') # 99.99
items = ih.get_value_at_key(nested_data, 'order.details.items') # ['phone', 'case']
# Extract structured data from natural text
mm = ih.matcher.MasterMatcher(debug=True)
result = mm('@john check out #python https://python.org for more info')
# Returns rich dictionary with mentions, tags, URLs, and metadata
# Interactive selection menus with flexible input
options = ['option1', 'option2', 'option3', 'option4', 'option5']
selected = ih.make_selections(options)
# Displays numbered menu, handles ranges (1-3), multiple selections (1 3 5)
# Selection menus with structured data
servers = [
{'name': 'web01', 'status': 'running', 'cpu': 45},
{'name': 'db01', 'status': 'stopped', 'cpu': 0},
{'name': 'cache01', 'status': 'running', 'cpu': 78}
]
selected_servers = ih.make_selections(servers, item_format='{name} ({status}) - CPU: {cpu}%')
# Displays: "web01 (running) - CPU: 45%" etc.
# Flexible argument handling
args = ih.get_list_from_arg_strings('a,b,c', ['d', 'e'], 'f,g')
# Returns: ['a', 'b', 'c', 'd', 'e', 'f', 'g']
**What you gain:** Immediate productivity with real-world data. No setup
overhead, no silent failures, no format wrestling. Functions adapt to
your data instead of forcing you to adapt to the library.
API Overview
------------
Core Data Transformation
~~~~~~~~~~~~~~~~~~~~~~~~
Type Conversion
^^^^^^^^^^^^^^^
- **``from_string(val, keep_num_as_string=False)``** - Smart
string-to-type conversion with leading zero preservation
- ``val``: String or any value to convert
- ``keep_num_as_string``: If True, preserve numeric strings as
strings
- Returns: Converted value (bool, None, int, float, or original
string)
- Internal calls: None (pure implementation)
- **``string_to_list(s)``** - Split strings on common delimiters
(comma, semicolon, pipe)
- ``s``: String to split or existing list (passed through)
- Returns: List of trimmed strings
- Internal calls: None (pure implementation)
- **``string_to_set(s)``** - Convert string to set, handling delimiters
and duplicates
- ``s``: String to split or existing list/set
- Returns: Set of unique strings
- Internal calls: None (pure implementation)
- **``string_to_converted_list(s, keep_num_as_string=False)``** -
Combines splitting and type conversion
- ``s``: Delimited string
- ``keep_num_as_string``: Preserve numeric strings as strings
- Returns: List with appropriate Python types
- Internal calls: ``from_string()``, ``string_to_list()``
Flexible Input Processing
^^^^^^^^^^^^^^^^^^^^^^^^^
- **``get_list_from_arg_strings(*args)``** - Universal argument
flattening
- ``*args``: Any combination of strings, lists, nested structures
- Returns: Flattened list of strings (handles recursive nesting)
- Internal calls: ``string_to_list()``,
``get_list_from_arg_strings()`` (recursive)
- **``decode(obj, encoding='utf-8')``** - Safe string decoding with
fallback
- ``obj``: Object to decode (bytes or other)
- ``encoding``: Target encoding
- Returns: Decoded string or original object if not bytes
- Internal calls: None (pure implementation)
Data Structure Manipulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dictionary Operations
^^^^^^^^^^^^^^^^^^^^^
- **``get_value_at_key(some_dict, key, condition=None)``** - Extract
values with dot notation
- ``some_dict``: Source dictionary
- ``key``: Simple key or nested path like ‘user.profile.name’
- ``condition``: Optional filter function for list values
- Returns: Value at key path, filtered if condition provided
- Internal calls: None (pure implementation)
- **``filter_keys(some_dict, *keys, **conditions)``** - Extract and
filter nested data
- ``some_dict``: Source dictionary
- ``*keys``: Key paths to extract
- ``**conditions``: Field-specific filter functions
- Returns: New dictionary with filtered data
- Internal calls: ``get_list_from_arg_strings()``,
``get_value_at_key()``
- **``flatten_and_ignore_keys(some_dict, *keys)``** - Flatten nested
dict, optionally ignoring patterns
- ``some_dict``: Nested dictionary to flatten
- ``*keys``: Key patterns to ignore (supports wildcards)
- Returns: Flat dictionary with dot-notation keys
- Internal calls: ``get_list_from_arg_strings()``
- **``unflatten_keys(flat_dict)``** - Reconstruct nested structure from
flat dictionary
- ``flat_dict``: Dictionary with dot-notation keys
- Returns: Nested dictionary structure
- Internal calls: None (pure implementation)
- **``ignore_keys(some_dict, *keys)``** - Remove specified keys from
dictionary
- ``some_dict``: Source dictionary
- ``*keys``: Keys or key patterns to remove
- Returns: New dictionary without specified keys
- Internal calls: ``get_list_from_arg_strings()``
Advanced Dictionary Operations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``rename_keys(some_dict, **mapping)``** - Rename dictionary keys
- ``some_dict``: Source dictionary
- ``**mapping``: old_key=new_key pairs
- Returns: Dictionary with renamed keys
- Internal calls: None (pure implementation)
- **``cast_keys(some_dict, **casting)``** - Apply type conversion to
specific keys
- ``some_dict``: Source dictionary
- ``**casting``: key=conversion_function pairs
- Returns: Dictionary with type-converted values
- Internal calls: None (pure implementation)
- **``sort_by_keys(some_dicts, *keys, reverse=False)``** - Sort list of
dicts by key values
- ``some_dicts``: List of dictionaries
- ``*keys``: Keys to sort by (priority order)
- ``reverse``: Sort direction
- Returns: Sorted list of dictionaries
- Internal calls: ``get_list_from_arg_strings()``
- **``find_items(some_dicts, terms)``** - Query list of dicts with
flexible operators
- ``some_dicts``: List of dictionaries to search
- ``terms``: Query string like ‘status:active, price:>100’
- Returns: Generator of matching dictionaries
- Internal calls: ``string_to_set()``,
``get_list_from_arg_strings()``, ``get_value_at_key()``,
``from_string()``, ``_less_than()``, ``_less_than_or_equal()``,
``_greater_than()``, ``_greater_than_or_equal()``,
``_sloppy_equal()``, ``_sloppy_not_equal()``
Text Processing and Parsing
~~~~~~~~~~~~~~~~~~~~~~~~~~~
String Utilities
^^^^^^^^^^^^^^^^
- **``splitlines(s)``** - Split text on line breaks, preserve empty
lines
- ``s``: String to split
- Returns: List of lines
- Internal calls: None (pure implementation)
- **``splitlines_and_strip(s)``** - Split and trim whitespace from each
line
- ``s``: String to split
- Returns: List of trimmed lines
- Internal calls: None (pure implementation)
- **``make_var_name(s)``** - Convert string to valid Python variable
name
- ``s``: String to convert
- Returns: Valid Python identifier
- Internal calls: None (pure implementation)
- **``get_keys_in_string(s)``** - Extract {placeholder} keys from
format strings
- ``s``: Format string with {key} placeholders
- Returns: List of key names
- Internal calls: Uses module-level ``cm`` (CurlyMatcher instance)
Data Format Conversion
^^^^^^^^^^^^^^^^^^^^^^
- **``string_to_obj(s, convention='BadgerFish', **kwargs)``** - Parse
JSON or XML strings
- ``s``: JSON or XML string (auto-detected)
- ``convention``: XML parsing convention
- Returns: Python dict/list
- Internal calls: ``_clean_obj_string_for_parsing()``,
``get_obj_from_xml()``, ``get_obj_from_json()``
- **``get_obj_from_json(json_text, cleaned=False)``** - Parse JSON with
error recovery
- ``json_text``: JSON string
- ``cleaned``: Skip string cleaning
- Returns: Python object
- Internal calls: ``_clean_obj_string_for_parsing()``,
``yield_objs_from_json()``
- **``get_obj_from_xml(xml_text, convention='BadgerFish', warn=True, cleaned=False, **kwargs)``**
- Parse XML to dict
- ``xml_text``: XML string
- ``convention``: XML-to-dict conversion style
- ``warn``: Show warnings for missing dependencies
- Returns: Python dictionary
- Internal calls: ``_clean_obj_string_for_parsing()``
- **``yield_objs_from_json(json_text, pos=0, decoder=JSONDecoder(), cleaned=False)``**
- Stream JSON objects
- ``json_text``: JSON string (potentially multi-object)
- ``pos``: Starting position
- ``decoder``: Custom JSON decoder
- Returns: Generator of Python objects
- Internal calls: ``_clean_obj_string_for_parsing()``
Time and Version Handling
^^^^^^^^^^^^^^^^^^^^^^^^^
- **``timestamp_to_seconds(timestamp)``** - Parse time strings to
seconds
- ``timestamp``: String like ‘1h30m45s’ or ‘01:30:45’
- Returns: Total seconds as number
- Internal calls: None (pure implementation)
- **``seconds_to_timestamps(seconds)``** - Convert seconds to multiple
time formats
- ``seconds``: Number of seconds
- Returns: Dict with ‘colon’, ‘hms’, and ‘pretty’ formats
- Internal calls: None (pure implementation)
- **``string_to_version_tuple(s)``** - Parse version strings
- ``s``: Version string like ‘1.2.3’
- Returns: Tuple (major_int, minor_int, patch_string)
- Internal calls: None (pure implementation)
User Interaction
~~~~~~~~~~~~~~~~
Input Collection
^^^^^^^^^^^^^^^^
- **``user_input(prompt_string='input', ch='> ')``** - Basic user input
with prompt
- ``prompt_string``: Prompt text
- ``ch``: Prompt suffix
- Returns: User input string (empty on Ctrl+C)
- Internal calls: None (pure implementation)
- **``user_input_fancy(prompt_string='input', ch='> ')``** - Input with
automatic text parsing
- ``prompt_string``: Prompt text
- ``ch``: Prompt suffix
- Returns: Dictionary with optional keys: ``allcaps_phrase_list``,
``backtick_list``, ``capitalized_phrase_list``,
``curly_group_list``, ``doublequoted_list``, ``mention_list``,
``paren_group_list``, ``singlequoted_list``, ``tag_list``,
``url_list``, ``line_comment``, ``non_comment``, ``non_url_text``,
``text``
- Internal calls: ``user_input()``, uses module-level ``sm``
(SpecialTextMultiMatcher instance)
- **``user_input_unbuffered(prompt_string='input', ch='> ', raise_interrupt=False)``**
- Single character input
- ``prompt_string``: Prompt text
- ``ch``: Prompt suffix
- ``raise_interrupt``: Raise KeyboardInterrupt on Ctrl+C
- Returns: Single character or empty string
- Internal calls: ``getchar()``
Interactive Selection
^^^^^^^^^^^^^^^^^^^^^
- **``make_selections(items, prompt='', wrap=True, item_format='', unbuffered=False, one=False, raise_interrupt=False, raise_exception_chars=[])``**
- Generate selection menus
- ``items``: List of items to choose from
- ``prompt``: Menu prompt text
- ``wrap``: Wrap long lines
- ``item_format``: Format string for dict/tuple items
- ``unbuffered``: Single-key selection mode
- ``one``: Return single item instead of list
- ``raise_interrupt``: If True and unbuffered is True, raise
KeyboardInterrupt when Ctrl+C is pressed
- ``raise_exception_chars``: List of characters that will raise a
generic exception if typed while unbuffered is True
- Returns: List of selected items (or single item if ``one=True``)
- Internal calls: ``get_string_maker()``,
``user_input_unbuffered()``, ``user_input()``,
``get_selection_range_indices()``, uses module-level ``CH2NUM``,
``NUM2CH``
- **``get_selection_range_indices(start, stop)``** - Generate index
ranges for selections
- ``start``: Start index (numeric or alphanumeric)
- ``stop``: End index (inclusive)
- Returns: List of indices between start and stop
- Internal calls: Uses module-level ``CH2NUM``
Pattern Matching (input_helper.matcher)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matcher Classes
^^^^^^^^^^^^^^^
- **``MasterMatcher(debug=False)``** - Comprehensive text analysis
- ``debug``: Include execution metadata in results
- Extracts: URLs, mentions (@user), hashtags (#tag), quotes, dates,
file paths
- Returns: Rich dictionary with all found patterns
- **``SpecialTextMultiMatcher(debug=False)``** - Common text pattern
extraction
- Subset of MasterMatcher focused on social media patterns
- Extracts: mentions, tags, URLs, quotes, parenthetical text
Individual Matchers (Composable)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``AllCapsPhraseMatcher``** - Extract ALL CAPS PHRASES
- **``BacktickMatcher``** - Extract ``backtick quoted`` text
- **``CapitalizedPhraseMatcher``** - Extract Capitalized Phrases
- **``CommentMatcher``** - Separate comments from code/text
- **``CurlyMatcher``** - Extract {placeholder} patterns
- **``DatetimeMatcher``** - Extract date/time patterns
- **``DollarCommandMatcher``** - Extract $(command) patterns
- **``DoubleQuoteMatcher``** - Extract “double quoted” text
- **``FehSaveFileMatcher``** - Parse feh image viewer save patterns
- **``LeadingSpacesMatcher``** - Count leading whitespace
- **``MentionMatcher``** - Extract @mentions
- **``NonUrlTextMatcher``** - Extract non-URL text portions
- **``ParenMatcher``** - Extract parenthetical content
- **``PsOutputMatcher``** - Parse process list output
- **``ScrotFileMatcher``** - Parse screenshot filename patterns
- **``ScrotFileMatcher2``** - Parse alternative screenshot filename
patterns
- **``SingleQuoteMatcher``** - Extract ‘single quoted’ text (avoiding
apostrophes)
- **``TagMatcher``** - Extract #hashtags
- **``UrlDetailsMatcher``** - Extract URLs with detailed parsing
(domain, path, parameters)
- **``UrlMatcher``** - Extract URLs from text
- **``ZshHistoryLineMatcher``** - Parse zsh history file entries
Utility Functions
~~~~~~~~~~~~~~~~~
List Operations
^^^^^^^^^^^^^^^
- **``chunk_list(some_list, n)``** - Split list into chunks of size n
- ``some_list``: List to chunk
- ``n``: Chunk size
- Returns: Generator of list chunks
- Internal calls: None (pure implementation)
- **``unique_counted_items(items)``** - Count unique items with
ordering
- ``items``: Iterable of items
- Returns: List of (count, item) tuples, sorted by count
- Internal calls: None (pure implementation)
Advanced Utilities
^^^^^^^^^^^^^^^^^^
- **``get_string_maker(item_format='', missing_key_default='')``** -
Create safe formatting functions
- ``item_format``: Format string with {key} placeholders
- ``missing_key_default``: Default for missing keys
- Returns: Function that safely formats data
- Internal calls: ``get_keys_in_string()``
- **``parse_command(input_line)``** - Parse command strings with
flexible delimiters
- ``input_line``: Command string like ‘cmd arg1 arg2’ or ‘cmd item –
item – item –’
- Returns: Dict with ‘cmd’ and ‘args’ keys
- Internal calls: None (pure implementation)
- **``start_ipython(warn=True, colors=True, vi=True, confirm_exit=False, **things)``**
- Launch IPython session
- ``warn``: Show warnings if IPython unavailable
- ``colors``: Enable syntax highlighting
- ``vi``: Use vi editing mode
- ``confirm_exit``: Prompt before exit
- ``**things``: Objects to pre-load in namespace
- Internal calls: None (external dependencies only)
- **``get_all_urls(*urls_or_filenames)``** - Extract URLs from files or
strings
- ``*urls_or_filenames``: Mix of URLs and files containing URLs
- Returns: List of discovered URLs
- Internal calls: Uses module-level ``um`` (UrlMatcher instance)
MasterMatcher Example
---------------------
.. code:: python
In [1]: import input_helper as ih
In [2]: from pprint import pprint
In [3]: mm = ih.matcher.MasterMatcher(debug=True)
In [4]: pprint(mm('@handle1 and @handle2 here are the #docs you requested https://github.com/kenjyco/input-helper/blob/master/README.md'))
{'_key_matcher_dict': {'mention_list': 'MentionMatcher',
'non_url_text': 'NonUrlTextMatcher',
'tag_list': 'TagMatcher',
'text': 'IdentityMatcher',
'url_details_list': 'UrlDetailsMatcher',
'url_list': 'UrlMatcher'},
'mention_list': ['handle1', 'handle2'],
'non_url_text': '@handle1 and @handle2 here are the #docs you requested',
'tag_list': ['docs'],
'text': '@handle1 and @handle2 here are the #docs you requested '
'https://github.com/kenjyco/input-helper/blob/master/README.md',
'url_details_list': [{'domain': 'github.com',
'filename_prefix': 'github.com--kenjyco--input-helper--blob--master--README.md',
'full_url': 'https://github.com/kenjyco/input-helper/blob/master/README.md',
'path': {'full_path': '/kenjyco/input-helper/blob/master/README.md',
'uri': '/kenjyco/input-helper/blob/master/README.md'},
'protocol': 'https'}],
'url_list': ['https://github.com/kenjyco/input-helper/blob/master/README.md']}
In [5]: ih.user_input_fancy()
input> go to https://github.com/kenjyco for a good time #learning stuff
Out[5]:
{'line_orig': 'go to https://github.com/kenjyco for a good time #learning stuff',
'non_url_text': 'go to for a good time #learning stuff',
'tag_list': ['learning'],
'url_list': ['https://github.com/kenjyco']}
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/input-helper",
"name": "input-helper",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "input, user input, regex, matching, json, selection, menus, filtering, conversions, transformations, comparisons, cli, command-line, helper, kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/input-helper/tarball/v0.1.54",
"platform": null,
"description": "A practical utility library for transforming data, handling user input,\nand parsing text in Python. Built for interactive development workflows\nwhere you need to quickly process messy real-world data without\nwrestling with configuration or format conversion.\n\nThis library works immediately without setup ceremonies, accepts\ninconsistent input gracefully, and fails helpfully when things go wrong.\nFunctions are designed around common patterns in data science, CLI\ntools, DevOps automation, and exploratory programming.\n\n**Who benefits from this library:** - Data scientists working with\ninconsistent input formats - CLI tool builders who need robust text\nprocessing - DevOps engineers automating data transformation tasks -\nAnyone prototyping data processing pipelines interactively - Developers\ntired of writing the same input handling code repeatedly\n\nThis library prioritizes **data integrity** and **cognitive load\nreduction**. Key design principles: - **Format Agnosticism**: Functions\naccept multiple input formats rather than enforcing strict types -\n**Conservative Type Conversion**: Preserves data semantics (like leading\nzeros) rather than aggressive normalization - **Graceful Degradation**:\nMultiple fallback strategies before giving up - **Self-Documenting**:\nFunction names describe behavior clearly, reducing documentation\ndependency - **REPL-Optimized**: Designed for interactive development\nwith immediate feedback - **Stateless**: No global configuration or\nhidden state; same inputs always produce same outputs\n\nTested for Python 3.5 - 3.13.\n\nInstall\n-------\n\n::\n\n pip install input-helper\n\nDependencies\n~~~~~~~~~~~~\n\nCore functionality requires only Python standard library. Optional\nfeatures: - **xmljson**: For XML parsing\n(``pip install input-helper[xmljson]``) - **IPython**: For enhanced REPL\nsessions (``pip install input-helper[ipython]``)\n\nQuickStart\n----------\n\n.. code:: python\n\n import input_helper as ih\n\n # Transform messy string data into clean Python objects\n data = ih.string_to_converted_list('dog, 01, 2, 3.10, none, true')\n # Returns: ['dog', '01', 2, 3.1, None, True]\n # Note: leading zeros preserved (often semantic), types inferred safely\n\n # Parse complex nested structures with dot notation\n nested_data = {\n 'order': {'details': {'price': 99.99, 'items': ['phone', 'case']}},\n 'user': {'name': 'John', 'verified': True}\n }\n price = ih.get_value_at_key(nested_data, 'order.details.price') # 99.99\n items = ih.get_value_at_key(nested_data, 'order.details.items') # ['phone', 'case']\n\n # Extract structured data from natural text\n mm = ih.matcher.MasterMatcher(debug=True)\n result = mm('@john check out #python https://python.org for more info')\n # Returns rich dictionary with mentions, tags, URLs, and metadata\n\n # Interactive selection menus with flexible input\n options = ['option1', 'option2', 'option3', 'option4', 'option5']\n selected = ih.make_selections(options)\n # Displays numbered menu, handles ranges (1-3), multiple selections (1 3 5)\n\n # Selection menus with structured data\n servers = [\n {'name': 'web01', 'status': 'running', 'cpu': 45},\n {'name': 'db01', 'status': 'stopped', 'cpu': 0},\n {'name': 'cache01', 'status': 'running', 'cpu': 78}\n ]\n selected_servers = ih.make_selections(servers, item_format='{name} ({status}) - CPU: {cpu}%')\n # Displays: \"web01 (running) - CPU: 45%\" etc.\n\n # Flexible argument handling\n args = ih.get_list_from_arg_strings('a,b,c', ['d', 'e'], 'f,g')\n # Returns: ['a', 'b', 'c', 'd', 'e', 'f', 'g']\n\n**What you gain:** Immediate productivity with real-world data. No setup\noverhead, no silent failures, no format wrestling. Functions adapt to\nyour data instead of forcing you to adapt to the library.\n\nAPI Overview\n------------\n\nCore Data Transformation\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nType Conversion\n^^^^^^^^^^^^^^^\n\n- **``from_string(val, keep_num_as_string=False)``** - Smart\n string-to-type conversion with leading zero preservation\n\n - ``val``: String or any value to convert\n - ``keep_num_as_string``: If True, preserve numeric strings as\n strings\n - Returns: Converted value (bool, None, int, float, or original\n string)\n - Internal calls: None (pure implementation)\n\n- **``string_to_list(s)``** - Split strings on common delimiters\n (comma, semicolon, pipe)\n\n - ``s``: String to split or existing list (passed through)\n - Returns: List of trimmed strings\n - Internal calls: None (pure implementation)\n\n- **``string_to_set(s)``** - Convert string to set, handling delimiters\n and duplicates\n\n - ``s``: String to split or existing list/set\n - Returns: Set of unique strings\n - Internal calls: None (pure implementation)\n\n- **``string_to_converted_list(s, keep_num_as_string=False)``** -\n Combines splitting and type conversion\n\n - ``s``: Delimited string\n - ``keep_num_as_string``: Preserve numeric strings as strings\n - Returns: List with appropriate Python types\n - Internal calls: ``from_string()``, ``string_to_list()``\n\nFlexible Input Processing\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``get_list_from_arg_strings(*args)``** - Universal argument\n flattening\n\n - ``*args``: Any combination of strings, lists, nested structures\n - Returns: Flattened list of strings (handles recursive nesting)\n - Internal calls: ``string_to_list()``,\n ``get_list_from_arg_strings()`` (recursive)\n\n- **``decode(obj, encoding='utf-8')``** - Safe string decoding with\n fallback\n\n - ``obj``: Object to decode (bytes or other)\n - ``encoding``: Target encoding\n - Returns: Decoded string or original object if not bytes\n - Internal calls: None (pure implementation)\n\nData Structure Manipulation\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDictionary Operations\n^^^^^^^^^^^^^^^^^^^^^\n\n- **``get_value_at_key(some_dict, key, condition=None)``** - Extract\n values with dot notation\n\n - ``some_dict``: Source dictionary\n - ``key``: Simple key or nested path like \u2018user.profile.name\u2019\n - ``condition``: Optional filter function for list values\n - Returns: Value at key path, filtered if condition provided\n - Internal calls: None (pure implementation)\n\n- **``filter_keys(some_dict, *keys, **conditions)``** - Extract and\n filter nested data\n\n - ``some_dict``: Source dictionary\n - ``*keys``: Key paths to extract\n - ``**conditions``: Field-specific filter functions\n - Returns: New dictionary with filtered data\n - Internal calls: ``get_list_from_arg_strings()``,\n ``get_value_at_key()``\n\n- **``flatten_and_ignore_keys(some_dict, *keys)``** - Flatten nested\n dict, optionally ignoring patterns\n\n - ``some_dict``: Nested dictionary to flatten\n - ``*keys``: Key patterns to ignore (supports wildcards)\n - Returns: Flat dictionary with dot-notation keys\n - Internal calls: ``get_list_from_arg_strings()``\n\n- **``unflatten_keys(flat_dict)``** - Reconstruct nested structure from\n flat dictionary\n\n - ``flat_dict``: Dictionary with dot-notation keys\n - Returns: Nested dictionary structure\n - Internal calls: None (pure implementation)\n\n- **``ignore_keys(some_dict, *keys)``** - Remove specified keys from\n dictionary\n\n - ``some_dict``: Source dictionary\n - ``*keys``: Keys or key patterns to remove\n - Returns: New dictionary without specified keys\n - Internal calls: ``get_list_from_arg_strings()``\n\nAdvanced Dictionary Operations\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``rename_keys(some_dict, **mapping)``** - Rename dictionary keys\n\n - ``some_dict``: Source dictionary\n - ``**mapping``: old_key=new_key pairs\n - Returns: Dictionary with renamed keys\n - Internal calls: None (pure implementation)\n\n- **``cast_keys(some_dict, **casting)``** - Apply type conversion to\n specific keys\n\n - ``some_dict``: Source dictionary\n - ``**casting``: key=conversion_function pairs\n - Returns: Dictionary with type-converted values\n - Internal calls: None (pure implementation)\n\n- **``sort_by_keys(some_dicts, *keys, reverse=False)``** - Sort list of\n dicts by key values\n\n - ``some_dicts``: List of dictionaries\n - ``*keys``: Keys to sort by (priority order)\n - ``reverse``: Sort direction\n - Returns: Sorted list of dictionaries\n - Internal calls: ``get_list_from_arg_strings()``\n\n- **``find_items(some_dicts, terms)``** - Query list of dicts with\n flexible operators\n\n - ``some_dicts``: List of dictionaries to search\n - ``terms``: Query string like \u2018status:active, price:>100\u2019\n - Returns: Generator of matching dictionaries\n - Internal calls: ``string_to_set()``,\n ``get_list_from_arg_strings()``, ``get_value_at_key()``,\n ``from_string()``, ``_less_than()``, ``_less_than_or_equal()``,\n ``_greater_than()``, ``_greater_than_or_equal()``,\n ``_sloppy_equal()``, ``_sloppy_not_equal()``\n\nText Processing and Parsing\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nString Utilities\n^^^^^^^^^^^^^^^^\n\n- **``splitlines(s)``** - Split text on line breaks, preserve empty\n lines\n\n - ``s``: String to split\n - Returns: List of lines\n - Internal calls: None (pure implementation)\n\n- **``splitlines_and_strip(s)``** - Split and trim whitespace from each\n line\n\n - ``s``: String to split\n - Returns: List of trimmed lines\n - Internal calls: None (pure implementation)\n\n- **``make_var_name(s)``** - Convert string to valid Python variable\n name\n\n - ``s``: String to convert\n - Returns: Valid Python identifier\n - Internal calls: None (pure implementation)\n\n- **``get_keys_in_string(s)``** - Extract {placeholder} keys from\n format strings\n\n - ``s``: Format string with {key} placeholders\n - Returns: List of key names\n - Internal calls: Uses module-level ``cm`` (CurlyMatcher instance)\n\nData Format Conversion\n^^^^^^^^^^^^^^^^^^^^^^\n\n- **``string_to_obj(s, convention='BadgerFish', **kwargs)``** - Parse\n JSON or XML strings\n\n - ``s``: JSON or XML string (auto-detected)\n - ``convention``: XML parsing convention\n - Returns: Python dict/list\n - Internal calls: ``_clean_obj_string_for_parsing()``,\n ``get_obj_from_xml()``, ``get_obj_from_json()``\n\n- **``get_obj_from_json(json_text, cleaned=False)``** - Parse JSON with\n error recovery\n\n - ``json_text``: JSON string\n - ``cleaned``: Skip string cleaning\n - Returns: Python object\n - Internal calls: ``_clean_obj_string_for_parsing()``,\n ``yield_objs_from_json()``\n\n- **``get_obj_from_xml(xml_text, convention='BadgerFish', warn=True, cleaned=False, **kwargs)``**\n - Parse XML to dict\n\n - ``xml_text``: XML string\n - ``convention``: XML-to-dict conversion style\n - ``warn``: Show warnings for missing dependencies\n - Returns: Python dictionary\n - Internal calls: ``_clean_obj_string_for_parsing()``\n\n- **``yield_objs_from_json(json_text, pos=0, decoder=JSONDecoder(), cleaned=False)``**\n - Stream JSON objects\n\n - ``json_text``: JSON string (potentially multi-object)\n - ``pos``: Starting position\n - ``decoder``: Custom JSON decoder\n - Returns: Generator of Python objects\n - Internal calls: ``_clean_obj_string_for_parsing()``\n\nTime and Version Handling\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``timestamp_to_seconds(timestamp)``** - Parse time strings to\n seconds\n\n - ``timestamp``: String like \u20181h30m45s\u2019 or \u201801:30:45\u2019\n - Returns: Total seconds as number\n - Internal calls: None (pure implementation)\n\n- **``seconds_to_timestamps(seconds)``** - Convert seconds to multiple\n time formats\n\n - ``seconds``: Number of seconds\n - Returns: Dict with \u2018colon\u2019, \u2018hms\u2019, and \u2018pretty\u2019 formats\n - Internal calls: None (pure implementation)\n\n- **``string_to_version_tuple(s)``** - Parse version strings\n\n - ``s``: Version string like \u20181.2.3\u2019\n - Returns: Tuple (major_int, minor_int, patch_string)\n - Internal calls: None (pure implementation)\n\nUser Interaction\n~~~~~~~~~~~~~~~~\n\nInput Collection\n^^^^^^^^^^^^^^^^\n\n- **``user_input(prompt_string='input', ch='> ')``** - Basic user input\n with prompt\n\n - ``prompt_string``: Prompt text\n - ``ch``: Prompt suffix\n - Returns: User input string (empty on Ctrl+C)\n - Internal calls: None (pure implementation)\n\n- **``user_input_fancy(prompt_string='input', ch='> ')``** - Input with\n automatic text parsing\n\n - ``prompt_string``: Prompt text\n - ``ch``: Prompt suffix\n - Returns: Dictionary with optional keys: ``allcaps_phrase_list``,\n ``backtick_list``, ``capitalized_phrase_list``,\n ``curly_group_list``, ``doublequoted_list``, ``mention_list``,\n ``paren_group_list``, ``singlequoted_list``, ``tag_list``,\n ``url_list``, ``line_comment``, ``non_comment``, ``non_url_text``,\n ``text``\n - Internal calls: ``user_input()``, uses module-level ``sm``\n (SpecialTextMultiMatcher instance)\n\n- **``user_input_unbuffered(prompt_string='input', ch='> ', raise_interrupt=False)``**\n - Single character input\n\n - ``prompt_string``: Prompt text\n - ``ch``: Prompt suffix\n - ``raise_interrupt``: Raise KeyboardInterrupt on Ctrl+C\n - Returns: Single character or empty string\n - Internal calls: ``getchar()``\n\nInteractive Selection\n^^^^^^^^^^^^^^^^^^^^^\n\n- **``make_selections(items, prompt='', wrap=True, item_format='', unbuffered=False, one=False, raise_interrupt=False, raise_exception_chars=[])``**\n - Generate selection menus\n\n - ``items``: List of items to choose from\n - ``prompt``: Menu prompt text\n - ``wrap``: Wrap long lines\n - ``item_format``: Format string for dict/tuple items\n - ``unbuffered``: Single-key selection mode\n - ``one``: Return single item instead of list\n - ``raise_interrupt``: If True and unbuffered is True, raise\n KeyboardInterrupt when Ctrl+C is pressed\n - ``raise_exception_chars``: List of characters that will raise a\n generic exception if typed while unbuffered is True\n - Returns: List of selected items (or single item if ``one=True``)\n - Internal calls: ``get_string_maker()``,\n ``user_input_unbuffered()``, ``user_input()``,\n ``get_selection_range_indices()``, uses module-level ``CH2NUM``,\n ``NUM2CH``\n\n- **``get_selection_range_indices(start, stop)``** - Generate index\n ranges for selections\n\n - ``start``: Start index (numeric or alphanumeric)\n - ``stop``: End index (inclusive)\n - Returns: List of indices between start and stop\n - Internal calls: Uses module-level ``CH2NUM``\n\nPattern Matching (input_helper.matcher)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nMatcher Classes\n^^^^^^^^^^^^^^^\n\n- **``MasterMatcher(debug=False)``** - Comprehensive text analysis\n\n - ``debug``: Include execution metadata in results\n - Extracts: URLs, mentions (@user), hashtags (#tag), quotes, dates,\n file paths\n - Returns: Rich dictionary with all found patterns\n\n- **``SpecialTextMultiMatcher(debug=False)``** - Common text pattern\n extraction\n\n - Subset of MasterMatcher focused on social media patterns\n - Extracts: mentions, tags, URLs, quotes, parenthetical text\n\nIndividual Matchers (Composable)\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``AllCapsPhraseMatcher``** - Extract ALL CAPS PHRASES\n- **``BacktickMatcher``** - Extract ``backtick quoted`` text\n- **``CapitalizedPhraseMatcher``** - Extract Capitalized Phrases\n- **``CommentMatcher``** - Separate comments from code/text\n- **``CurlyMatcher``** - Extract {placeholder} patterns\n- **``DatetimeMatcher``** - Extract date/time patterns\n- **``DollarCommandMatcher``** - Extract $(command) patterns\n- **``DoubleQuoteMatcher``** - Extract \u201cdouble quoted\u201d text\n- **``FehSaveFileMatcher``** - Parse feh image viewer save patterns\n- **``LeadingSpacesMatcher``** - Count leading whitespace\n- **``MentionMatcher``** - Extract @mentions\n- **``NonUrlTextMatcher``** - Extract non-URL text portions\n- **``ParenMatcher``** - Extract parenthetical content\n- **``PsOutputMatcher``** - Parse process list output\n- **``ScrotFileMatcher``** - Parse screenshot filename patterns\n- **``ScrotFileMatcher2``** - Parse alternative screenshot filename\n patterns\n- **``SingleQuoteMatcher``** - Extract \u2018single quoted\u2019 text (avoiding\n apostrophes)\n- **``TagMatcher``** - Extract #hashtags\n- **``UrlDetailsMatcher``** - Extract URLs with detailed parsing\n (domain, path, parameters)\n- **``UrlMatcher``** - Extract URLs from text\n- **``ZshHistoryLineMatcher``** - Parse zsh history file entries\n\nUtility Functions\n~~~~~~~~~~~~~~~~~\n\nList Operations\n^^^^^^^^^^^^^^^\n\n- **``chunk_list(some_list, n)``** - Split list into chunks of size n\n\n - ``some_list``: List to chunk\n - ``n``: Chunk size\n - Returns: Generator of list chunks\n - Internal calls: None (pure implementation)\n\n- **``unique_counted_items(items)``** - Count unique items with\n ordering\n\n - ``items``: Iterable of items\n - Returns: List of (count, item) tuples, sorted by count\n - Internal calls: None (pure implementation)\n\nAdvanced Utilities\n^^^^^^^^^^^^^^^^^^\n\n- **``get_string_maker(item_format='', missing_key_default='')``** -\n Create safe formatting functions\n\n - ``item_format``: Format string with {key} placeholders\n - ``missing_key_default``: Default for missing keys\n - Returns: Function that safely formats data\n - Internal calls: ``get_keys_in_string()``\n\n- **``parse_command(input_line)``** - Parse command strings with\n flexible delimiters\n\n - ``input_line``: Command string like \u2018cmd arg1 arg2\u2019 or \u2018cmd item \u2013\n item \u2013 item \u2013\u2019\n - Returns: Dict with \u2018cmd\u2019 and \u2018args\u2019 keys\n - Internal calls: None (pure implementation)\n\n- **``start_ipython(warn=True, colors=True, vi=True, confirm_exit=False, **things)``**\n - Launch IPython session\n\n - ``warn``: Show warnings if IPython unavailable\n - ``colors``: Enable syntax highlighting\n - ``vi``: Use vi editing mode\n - ``confirm_exit``: Prompt before exit\n - ``**things``: Objects to pre-load in namespace\n - Internal calls: None (external dependencies only)\n\n- **``get_all_urls(*urls_or_filenames)``** - Extract URLs from files or\n strings\n\n - ``*urls_or_filenames``: Mix of URLs and files containing URLs\n - Returns: List of discovered URLs\n - Internal calls: Uses module-level ``um`` (UrlMatcher instance)\n\nMasterMatcher Example\n---------------------\n\n.. code:: python\n\n In [1]: import input_helper as ih\n\n In [2]: from pprint import pprint\n\n In [3]: mm = ih.matcher.MasterMatcher(debug=True)\n\n In [4]: pprint(mm('@handle1 and @handle2 here are the #docs you requested https://github.com/kenjyco/input-helper/blob/master/README.md'))\n {'_key_matcher_dict': {'mention_list': 'MentionMatcher',\n 'non_url_text': 'NonUrlTextMatcher',\n 'tag_list': 'TagMatcher',\n 'text': 'IdentityMatcher',\n 'url_details_list': 'UrlDetailsMatcher',\n 'url_list': 'UrlMatcher'},\n 'mention_list': ['handle1', 'handle2'],\n 'non_url_text': '@handle1 and @handle2 here are the #docs you requested',\n 'tag_list': ['docs'],\n 'text': '@handle1 and @handle2 here are the #docs you requested '\n 'https://github.com/kenjyco/input-helper/blob/master/README.md',\n 'url_details_list': [{'domain': 'github.com',\n 'filename_prefix': 'github.com--kenjyco--input-helper--blob--master--README.md',\n 'full_url': 'https://github.com/kenjyco/input-helper/blob/master/README.md',\n 'path': {'full_path': '/kenjyco/input-helper/blob/master/README.md',\n 'uri': '/kenjyco/input-helper/blob/master/README.md'},\n 'protocol': 'https'}],\n 'url_list': ['https://github.com/kenjyco/input-helper/blob/master/README.md']}\n\n In [5]: ih.user_input_fancy()\n input> go to https://github.com/kenjyco for a good time #learning stuff\n Out[5]:\n {'line_orig': 'go to https://github.com/kenjyco for a good time #learning stuff',\n 'non_url_text': 'go to for a good time #learning stuff',\n 'tag_list': ['learning'],\n 'url_list': ['https://github.com/kenjyco']}\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Helpers for parsing user input, generating menus, transforming data, making comparisons, flexible argument acceptance (string to list/set), regex matching, and more",
"version": "0.1.54",
"project_urls": {
"Download": "https://github.com/kenjyco/input-helper/tarball/v0.1.54",
"Homepage": "https://github.com/kenjyco/input-helper"
},
"split_keywords": [
"input",
" user input",
" regex",
" matching",
" json",
" selection",
" menus",
" filtering",
" conversions",
" transformations",
" comparisons",
" cli",
" command-line",
" helper",
" kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e98a4fa393ac5239d027f934e616eeeb3d3fba22c3cd0184c3bf08b596833f24",
"md5": "7b8c107828229607441ebbe1305c4ce2",
"sha256": "7e359948bbe896668dcddd0fc3ff6318926a4c98b5fa566c04e5b230ce85e1f0"
},
"downloads": -1,
"filename": "input_helper-0.1.54-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b8c107828229607441ebbe1305c4ce2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30030,
"upload_time": "2025-07-23T17:55:01",
"upload_time_iso_8601": "2025-07-23T17:55:01.957214Z",
"url": "https://files.pythonhosted.org/packages/e9/8a/4fa393ac5239d027f934e616eeeb3d3fba22c3cd0184c3bf08b596833f24/input_helper-0.1.54-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 17:55:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "input-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "input-helper"
}
JSON
