Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/face/utils.py: 41%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import os
4import re
5import sys
6import getpass
7import keyword
8import textwrap
9import typing
11from boltons.strutils import pluralize, strip_ansi
12from boltons.iterutils import split, unique
13from boltons.typeutils import make_sentinel
15import face
17raw_input = input
19ERROR = make_sentinel('ERROR') # used for parse_as=ERROR
21# keep it just to subset of valid ASCII python identifiers for now
22VALID_FLAG_RE = re.compile(r"^[A-z][-_A-z0-9]*\Z")
24FRIENDLY_TYPE_NAMES = {int: 'integer',
25 float: 'decimal'}
28def process_command_name(name):
29 """Validate and canonicalize a Command's name, generally on
30 construction or at subcommand addition. Like
31 ``flag_to_identifier()``, only letters, numbers, '-', and/or
32 '_'. Must begin with a letter, and no trailing underscores or
33 dashes.
35 Python keywords are allowed, as subcommands are never used as
36 attributes or variables in injection.
38 """
40 if not name or not isinstance(name, str):
41 raise ValueError(f'expected non-zero length string for subcommand name, not: {name!r}')
43 if name.endswith('-') or name.endswith('_'):
44 raise ValueError('expected subcommand name without trailing dashes'
45 ' or underscores, not: %r' % name)
47 name_match = VALID_FLAG_RE.match(name)
48 if not name_match:
49 raise ValueError('valid subcommand name must begin with a letter, and'
50 ' consist only of letters, digits, underscores, and'
51 ' dashes, not: %r' % name)
53 subcmd_name = normalize_flag_name(name)
55 return subcmd_name
58def normalize_flag_name(flag):
59 ret = flag.lstrip('-')
60 if (len(flag) - len(ret)) > 1:
61 # only single-character flags are considered case-sensitive (like an initial)
62 ret = ret.lower()
63 ret = ret.replace('-', '_')
64 return ret
67def flag_to_identifier(flag):
68 """Validate and canonicalize a flag name to a valid Python identifier
69 (variable name).
71 Valid input strings include only letters, numbers, '-', and/or
72 '_'. Only single/double leading dash allowed (-/--). No trailing
73 dashes or underscores. Must not be a Python keyword.
75 Input case doesn't matter, output case will always be lower.
76 """
77 orig_flag = flag
78 if not flag or not isinstance(flag, str):
79 raise ValueError(f'expected non-zero length string for flag, not: {flag!r}')
81 if flag.endswith('-') or flag.endswith('_'):
82 raise ValueError('expected flag without trailing dashes'
83 ' or underscores, not: %r' % orig_flag)
85 if flag[:2] == '--':
86 flag = flag[2:]
88 flag_match = VALID_FLAG_RE.match(flag)
89 if not flag_match:
90 raise ValueError('valid flag names must begin with a letter, optionally'
91 ' prefixed by two dashes, and consist only of letters,'
92 ' digits, underscores, and dashes, not: %r' % orig_flag)
94 flag_name = normalize_flag_name(flag)
96 if keyword.iskeyword(flag_name):
97 raise ValueError(f'valid flag names must not be Python keywords: {orig_flag!r}')
99 return flag_name
102def identifier_to_flag(identifier):
103 """
104 Turn an identifier back into its flag format (e.g., "Flag" -> --flag).
105 """
106 if identifier.startswith('-'):
107 raise ValueError(f'expected identifier, not flag name: {identifier!r}')
108 ret = identifier.lower().replace('_', '-')
109 return '--' + ret
112def format_flag_label(flag):
113 "The default flag label formatter, used in help and error formatting"
114 if flag.display.label is not None:
115 return flag.display.label
116 parts = [identifier_to_flag(flag.name)]
117 if flag.char:
118 parts.append('-' + flag.char)
119 ret = ' / '.join(parts)
120 if flag.display.value_name:
121 ret += ' ' + flag.display.value_name
122 return ret
125def format_posargs_label(posargspec):
126 "The default positional argument label formatter, used in help formatting"
127 if posargspec.display.label:
128 return posargspec.display.label
129 if not posargspec.accepts_args:
130 return ''
131 return get_cardinalized_args_label(posargspec.display.name, posargspec.min_count, posargspec.max_count)
134def get_cardinalized_args_label(name, min_count, max_count):
135 '''
136 Examples for parameter values: (min_count, max_count): output for name=arg:
138 1, 1: arg
139 0, 1: [arg]
140 0, None: [args ...]
141 1, 3: args ...
142 '''
143 if min_count == max_count:
144 return ' '.join([name] * min_count)
145 if min_count == 1:
146 return name + ' ' + get_cardinalized_args_label(name,
147 min_count=0,
148 max_count=max_count - 1 if max_count is not None else None)
150 tmpl = '[%s]' if min_count == 0 else '%s'
151 if max_count == 1:
152 return tmpl % name
153 return tmpl % (pluralize(name) + ' ...')
156def format_flag_post_doc(flag):
157 "The default positional argument label formatter, used in help formatting"
158 if flag.display.post_doc is not None:
159 return flag.display.post_doc
160 if flag.missing is face.ERROR:
161 return '(required)'
162 if flag.missing is None or repr(flag.missing) == object.__repr__(flag.missing):
163 # avoid displaying unhelpful defaults
164 return ''
165 return f'(defaults to {flag.missing!r})'
168def get_type_desc(parse_as):
169 "Kind of a hacky way to improve message readability around argument types"
170 if not callable(parse_as):
171 raise TypeError(f'expected parse_as to be callable, not {parse_as!r}')
172 try:
173 return 'as', FRIENDLY_TYPE_NAMES[parse_as]
174 except KeyError:
175 pass
176 try:
177 # return the type name if it looks like a type
178 return 'as', parse_as.__name__
179 except AttributeError:
180 pass
181 try:
182 # return the func name if it looks like a function
183 return 'with', parse_as.func_name
184 except AttributeError:
185 pass
186 # if all else fails
187 return 'with', repr(parse_as)
190def unwrap_text(text):
191 """Turn wrapped text into flowing paragraphs, ready for rewrapping by
192 the console, browser, or textwrap.
193 """
194 all_grafs = []
195 cur_graf = []
196 for line in text.splitlines():
197 line = line.strip()
198 if line:
199 cur_graf.append(line)
200 else:
201 all_grafs.append(' '.join(cur_graf))
202 cur_graf = []
203 if cur_graf:
204 all_grafs.append(' '.join(cur_graf))
205 return '\n\n'.join(all_grafs)
208def get_rdep_map(dep_map):
209 """
210 expects and returns a dict of {item: set([deps])}
212 item can be a string or any other hashable object.
213 """
214 # TODO: the way this is used, this function doesn't receive
215 # information about what functions take what args. this ends up
216 # just being args depending on args, with no mediating middleware
217 # names. this can make circular dependencies harder to debug.
218 ret = {}
219 for key in dep_map:
220 to_proc, rdeps, cur_chain = [key], set(), []
221 while to_proc:
222 cur = to_proc.pop()
223 cur_chain.append(cur)
225 cur_rdeps = dep_map.get(cur, [])
227 if key in cur_rdeps:
228 raise ValueError('dependency cycle: %r recursively depends'
229 ' on itself. full dep chain: %r' % (cur, cur_chain))
231 to_proc.extend([c for c in cur_rdeps if c not in to_proc])
232 rdeps.update(cur_rdeps)
234 ret[key] = rdeps
235 return ret
238def get_minimal_executable(executable=None, path=None, environ=None):
239 """Get the shortest form of a path to an executable,
240 based on the state of the process environment.
242 Args:
243 executable (str): Name or path of an executable
244 path (list): List of directories on the "PATH", or a string using
245 the platform path separator (os.pathsep). Defaults to ``environ['PATH']``.
246 environ (dict): Mapping of environment variables, will be used
247 to retrieve *path* if it is None. Ignored if *path* is
248 set. Defaults to ``os.environ``.
250 Used by face's default help renderer for a more readable usage string.
251 """
252 executable = sys.executable if executable is None else executable
253 environ = os.environ if environ is None else environ
254 path = environ.get('PATH', '') if path is None else path
255 if isinstance(path, str):
256 path = path.split(os.pathsep)
258 executable_basename = os.path.basename(executable)
259 for p in path:
260 try:
261 if os.path.relpath(executable, p) == executable_basename:
262 return executable_basename
263 except ValueError:
264 # On Windows, relpath raises ValueError when paths are on
265 # different drives (e.g., D:\exe vs C:\path). Skip these.
266 continue
267 # TODO: support "../python" as a return?
268 return executable
271# prompt and echo owe a decent amount of design to click (and
272# pocket_protector)
273def isatty(stream):
274 "Returns True if *stream* is a tty"
275 try:
276 return stream.isatty()
277 except Exception:
278 return False
281def should_strip_ansi(stream):
282 "Returns True when ANSI color codes should be stripped from output to *stream*."
283 return not isatty(stream)
286def echo(msg: str | bytes | object, *,
287 err: bool = False,
288 file: typing.TextIO | None = None,
289 nl: bool = True,
290 end: str | None = None,
291 color: bool | None = None,
292 indent: str | int = '') -> None:
293 """A better-behaved :func:`print()` function for command-line applications.
295 Writes text or bytes to a file or stream and flushes. Seamlessly
296 handles stripping ANSI color codes when the output file is not a
297 TTY.
299 >>> echo('test')
300 test
302 Args:
303 msg: A text or byte string to echo.
304 err: Set the default output file to ``sys.stderr``
305 file: Stream or other file-like object to output
306 to. Defaults to ``sys.stdout``, or ``sys.stderr`` if *err* is
307 True.
308 nl: If ``True``, sets *end* to ``'\\n'``, the newline character.
309 end: Explicitly set the line-ending character. Setting this overrides *nl*.
310 color: Set to ``True``/``False`` to always/never echo ANSI color
311 codes. Defaults to inspecting whether *file* is a TTY.
312 indent: String prefix or number of spaces to indent the output.
313 """
314 msg = msg or ''
315 if not isinstance(msg, (str, bytes)):
316 msg = str(msg)
318 _file = file or (sys.stderr if err else sys.stdout)
319 enable_color = color
320 space: str = ' '
321 if isinstance(indent, int):
322 indent = space * indent
324 if enable_color is None:
325 enable_color = not should_strip_ansi(_file)
327 if end is None:
328 if nl:
329 end = '\n' if isinstance(msg, str) else b'\n'
330 if end:
331 msg += end
332 if indent:
333 msg = textwrap.indent(msg, prefix=indent)
335 if msg:
336 if not enable_color:
337 msg = strip_ansi(msg)
338 _file.write(msg)
340 _file.flush()
342 return
345def echo_err(*a, **kw):
346 """
347 A convenience function which works exactly like :func:`echo`, but
348 always defaults the output *file* to ``sys.stderr``.
349 """
350 kw['err'] = True
351 return echo(*a, **kw)
354# variant-style shortcut to help minimize kwarg noise and imports
355echo.err = echo_err
358def _get_text(inp):
359 if not isinstance(inp, str):
360 return inp.decode('utf8')
361 return inp
364def prompt(label, confirm=None, confirm_label=None, hide_input=False, err=False):
365 """A better-behaved :func:`input()` function for command-line applications.
367 Ask a user for input, confirming if necessary, returns a text
368 string. Handles Ctrl-C and EOF more gracefully than Python's built-ins.
370 Args:
372 label (str): The prompt to display to the user.
373 confirm (bool): Pass ``True`` to ask the user to retype the input to confirm it.
374 Defaults to False, unless *confirm_label* is passed.
375 confirm_label (str): Override the confirmation prompt. Defaults
376 to "Retype *label*" if *confirm* is ``True``.
377 hide_input (bool): If ``True``, disables echoing the user's
378 input as they type. Useful for passwords and other secret
379 entry. See :func:`prompt_secret` for a more convenient
380 interface. Defaults to ``False``.
381 err (bool): If ``True``, prompts are printed on
382 ``sys.stderr``. Defaults to ``False``.
384 :func:`prompt` is primarily intended for simple plaintext
385 entry. See :func:`prompt_secret` for handling passwords and other
386 secret user input.
388 Raises :exc:`UsageError` if *confirm* is enabled and inputs do not match.
390 """
391 do_confirm = confirm or confirm_label
392 if do_confirm and not confirm_label:
393 confirm_label = f'Retype {label.lower()}'
395 def prompt_func(label):
396 func = getpass.getpass if hide_input else raw_input
397 try:
398 # Write the prompt separately so that we get nice
399 # coloring through colorama on Windows (someday)
400 echo(label, nl=False, err=err)
401 ret = func('')
402 except (KeyboardInterrupt, EOFError):
403 # getpass doesn't print a newline if the user aborts input with ^C.
404 # Allegedly this behavior is inherited from getpass(3).
405 # A doc bug has been filed at https://bugs.python.org/issue24711
406 if hide_input:
407 echo(None, err=err)
408 raise
410 return ret
412 ret = prompt_func(label)
413 ret = _get_text(ret)
414 if do_confirm:
415 ret2 = prompt_func(confirm_label)
416 ret2 = _get_text(ret2)
417 if ret != ret2:
418 raise face.UsageError('Sorry, inputs did not match.')
420 return ret
423def prompt_secret(label, **kw):
424 """A convenience function around :func:`prompt`, which is
425 preconfigured for secret user input, like passwords.
427 All arguments are the same, except *hide_input* is always
428 ``True``, and *err* defaults to ``True``, for consistency with
429 :func:`getpass.getpass`.
431 """
432 kw['hide_input'] = True
433 kw.setdefault('err', True) # getpass usually puts prompts on stderr
434 return prompt(label, **kw)
437# variant-style shortcut to help minimize kwarg noise and imports
438prompt.secret = prompt_secret