click.utils

module documentation

Undocumented

Constant F Undocumented
Class ​Keep​Open​File Undocumented
Class ​Lazy​File No summary
Class ​Pacify​Flush​Wrapper No summary
Function ​_detect​_program​_name No summary
Function ​_expand​_args Simulate Unix shell expansion with Python functions.
Function ​_posixify Undocumented
Function echo Print a message and newline to stdout or a file. This should be used instead of print because it provides better support for different data, files, and environments.
Function format​_filename No summary
Function get​_app​_dir Returns the config folder for the application. The default behavior is to return whatever is most appropriate for the operating system.
Function get​_binary​_stream Returns a system stream for byte processing.
Function get​_os​_args Returns the argument part of sys.argv, removing the first value which is the name of the script.
Function get​_text​_stream No summary
Function make​_default​_short​_help Returns a condensed version of help string.
Function make​_str Converts a value into a valid string.
Function open​_file This is similar to how the File works but for manual usage. Files are opened non lazy by default. This can open regular files as well as stdin/stdout if '-' is passed.
Function safecall Wraps a function so that it swallows exceptions.
F =

Undocumented

Value
t.TypeVar('F',
          bound=t.Callable[..., t.Any])
def _detect_program_name(path=None, _main=sys.modules['__main__']):

Determine the command used to run the program, for use in help text. If a file or entry point was executed, the file name is returned. If python -m was used to execute a module or package, python -m name is returned.

This doesn't try to be too precise, the goal is to give a concise name for help text. Files are only shown as their name without the path. python is only shown for modules, and the full path to sys.executable is not shown.

New in version 8.0: Based on command args detection in the Werkzeug reloader.
Parameters
path:t.Optional[str]The Python file being executed. Python puts this in sys.argv[0], which is used by default.
​_main:ModuleTypeThe __main__ module. This should only be passed during internal testing.
Returns
strUndocumented
Unknown Field: meta
private
def _expand_args(args, *, user=True, env=True, glob_recursive=True):

Simulate Unix shell expansion with Python functions.

See glob.glob, os.path.expanduser, and os.path.expandvars.

This intended for use on Windows, where the shell does not do any expansion. It may not exactly match what a Unix shell would do.

New in version 8.0.
Parameters
args:t.Iterable[str]List of command line arguments to expand.
user:boolExpand user home directory.
env:boolExpand environment variables.
glob​_recursive:bool** matches directories recursively.
Returns
t.List[str]Undocumented
Unknown Field: meta
private
def _posixify(name):

Undocumented

Parameters
name:strUndocumented
Returns
strUndocumented
def echo(message=None, file=None, nl=True, err=False, color=None):

Print a message and newline to stdout or a file. This should be used instead of print because it provides better support for different data, files, and environments.

Compared to print, this does the following:

  • Ensures that the output encoding is not misconfigured on Linux.
  • Supports Unicode in the Windows console.
  • Supports writing to binary outputs, and supports writing bytes to text outputs.
  • Supports colors and styles on Windows.
  • Removes ANSI color and style codes if the output does not look like an interactive terminal.
  • Always flushes the output.
Changed in version 6.0: Support Unicode output on the Windows console. Click does not modify sys.stdout, so sys.stdout.write() and print() will still not support Unicode.
Changed in version 4.0: Added the color parameter.
New in version 3.0: Added the err parameter.
Changed in version 2.0: Support colors on Windows if colorama is installed.
Parameters
message:t.Optional[t.Any]The string or bytes to output. Other objects are converted to strings.
file:t.Optional[t.IO]The file to write to. Defaults to stdout.
nl:boolPrint a newline after the message. Enabled by default.
err:boolWrite to stderr instead of stdout.
color:t.Optional[bool]Force showing or hiding colors and other styles. By default Click will remove color if the output does not look like an interactive terminal.
def format_filename(filename, shorten=False):
Formats a filename for user display. The main purpose of this function is to ensure that the filename can be displayed at all. This will decode the filename to unicode if necessary in a way that it will not fail. Optionally, it can shorten the filename to not include the full path to the filename.
Parameters
filename:t.Union[str, bytes, os.PathLike]formats a filename for UI display. This will also convert the filename into unicode without failing.
shorten:boolthis optionally shortens the filename to strip of the path that leads up to it.
Returns
strUndocumented
def get_app_dir(app_name, roaming=True, force_posix=False):

Returns the config folder for the application. The default behavior is to return whatever is most appropriate for the operating system.

To give you an idea, for an app called "Foo Bar", something like the following folders could be returned:

Mac OS X:
~/Library/Application Support/Foo Bar
Mac OS X (POSIX):
~/.foo-bar
Unix:
~/.config/foo-bar
Unix (POSIX):
~/.foo-bar
Windows (roaming):
C:\Users\<user>\AppData\Roaming\Foo Bar
Windows (not roaming):
C:\Users\<user>\AppData\Local\Foo Bar
New in version 2.0.
Parameters
app​_name:strthe application name. This should be properly capitalized and can contain whitespace.
roaming:boolcontrols if the folder should be roaming or not on Windows. Has no affect otherwise.
force​_posix:boolif this is set to True then on any POSIX system the folder will be stored in the home folder with a leading dot instead of the XDG config home or darwin's application support folder.
Returns
strUndocumented
def get_binary_stream(name):
Returns a system stream for byte processing.
Parameters
name:te.Literal['stdin', 'stdout', 'stderr']the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr'
Returns
t.BinaryIOUndocumented
def get_os_args():

Returns the argument part of sys.argv, removing the first value which is the name of the script.

Deprecated since version 8.0: Will be removed in Click 8.1. Access sys.argv[1:] directly instead.
Returns
t.Sequence[str]Undocumented
def get_text_stream(name, encoding=None, errors='strict'):
Returns a system stream for text processing. This usually returns a wrapped stream around a binary stream returned from get_binary_stream but it also can take shortcuts for already correctly configured streams.
Parameters
name:te.Literal['stdin', 'stdout', 'stderr']the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr'
encoding:t.Optional[str]overrides the detected default encoding.
errors:t.Optional[str]overrides the default error mode.
Returns
t.TextIOUndocumented
def make_default_short_help(help, max_length=45):
Returns a condensed version of help string.
Parameters
help:strUndocumented
max​_length:intUndocumented
Returns
strUndocumented
def make_str(value):
Converts a value into a valid string.
Parameters
value:t.AnyUndocumented
Returns
strUndocumented
def open_file(filename, mode='r', encoding=None, errors='strict', lazy=False, atomic=False):

This is similar to how the File works but for manual usage. Files are opened non lazy by default. This can open regular files as well as stdin/stdout if '-' is passed.

If stdin/stdout is returned the stream is wrapped so that the context manager will not close the stream accidentally. This makes it possible to always use the function like this without having to worry to accidentally close a standard stream:

with open_file(filename) as f:
    ...
New in version 3.0.
Parameters
filename:strthe name of the file to open (or '-' for stdin/stdout).
mode:strthe mode in which to open the file.
encoding:t.Optional[str]the encoding to use.
errors:t.Optional[str]the error handling for this file.
lazy:boolcan be flipped to true to open the file lazily.
atomic:boolin atomic mode writes go into a temporary file and it's moved on close.
Returns
t.IOUndocumented
def safecall(func):
Wraps a function so that it swallows exceptions.
Parameters
func:FUndocumented
Returns
FUndocumented