Skip to content

API reference

Takuro Fujino edited this page Aug 27, 2023 · 16 revisions

Introduction

This page explain the API references to extend the PyViewer. Also see Extension page.

Details

debug_print

print a message if PyViewer works in debug mode.

Parameters
----------
msg: str
    a message printed if in debug mode.

Returns
-------
None

args_chk

return True if a given attribute is set in args.
NOTE: This function supports only default attributes.

Parameters
----------
args: Args
    The arguments given by the command line.
attr: str
    The attribute to check that is set from the command line.

Returns
-------
bool
    Return True if the attribute is set correctly.

get_config

get the current configuration value.

Parameters
----------
key1: str
    Main key name. Selected one from "config", "colors" and type names.
key2: str
    configuration key name.

Returns
-------
Any
    Return specified configuration value. If it is not set, return None.

cprint

print message in color.

Parameters
----------
str1: str
    The message to be printed in color.
str2: str
    The message to be printed after str1 without color.
fg: Union[str, int, None]
    The key of the foreground color. Possible values are
        'k': black, 'r': red, 'g': green, 'y': yellow,
        'b': blue, 'c': cyan, 'm': magenta, 'w': white,
        0-255: The color id corresponding to the 256 terminal colors.
bg: Union[str, int, None]
    The key of the background color. Possible values are the same as fg.
**kwargs:
    Keyword arguments passed to the print function.

Returns
-------
None

print_key

print the key name with emphasis.

Parameters
----------
key_name: str
    the key name.

Returns
-------
None

get_col

get the color id of a given name.

Parameters
----------
name: str
    A name of the option. This name should be included in
    "color_config" in configuration options.

Returns
-------
Union[str, int, None]
    foreground color id. If the name is incorrect, return None.
Union[str, int, None]
    foreground color id. If the name is incorrect, return None.

set_numpy_format

set NumPy format following the given configuration option.

Parameters
----------
numpy: module
    NumPy module. (This file is designed not to call anything other than
    standard modules, so the NumPy module is used as an argument.)

Returns
-------
None

show_opts

show the current configuration options.

Parameters
----------
None

Returns
-------
None

interactive_view

provide the interactive UI to show the contents.

Parameters
----------
fname: str
    An opened file name.
get_contents: Callable[[PurePath], Tuple[List[str], List[str]]]
    A function to get lists of directories and files.
    The argument is the path to an item.
    The first return value is a list of directory names,
    and the second return value is a list of file names.
    In this context, a directory means something that includes
    files and directories, and a file means something that includes data.
show_func: Callable[[str, **kwargs], ReturnMessage]
    A function to show the contents.
    The first argument is the path to a file.
    Other arguments are treated as keyword arguments.
    Please see the wiki for possible keywords.
    The return value is the ReturnMessage. It is treated as
    an error message if ReturnMessage.error is True. Otherwise, it is
    treated as a standard message.

Returns
-------
None

run_system_cmd

open the file using the system command.

Parameters
----------
fname: str
    a file name to be opened.

Returns
-------
bool
    Return True if the command succeeded, otherwise False.

get_image_viewer

get the image viewer following the arguments from the command line and
configuration options.

Parameters
----------
args: Args
    The arguments given by the command line.

Returns
-------
Optional[str]
    the name of image viewer.

is_image

judge whether the file of a given path is an image file.

Parameters
----------
path: str or PathLike
    a path to a file judging whether it is an image file or not.

Returns
-------
bool
    return True if the file is judged as an image file.

show_image_file

show an image file with the image viewer.

Parameters
----------
img_file: str
    image file.
args: Args
    The arguments given by the command line.

Returns
-------
bool
    Return True if the file opened successfully, otherwise False.

show_image_ndarray

show a given ndArray as an image with the image viewer.

Parameters
----------
data: numpy.ndarray
    Data to be shown as an image. the shape of the data should be
    (h, w, 3) or (h, w, 4).
name: str
    The name of the image.
args: Args
    The arguments given by the command line.

Returns
-------
bool
    Return True if the image is shown successfully, otherwise False.

help_template

offer a template for help messages.

Parameters
----------
filetype: str
    The file type of help message. This file type is required to be
    supported by the `pyviewer` command.
description: str
    the description of the file type.
sup_iv: bool
    set True if this file type supports --image_viewer option.
sup_encoding: bool
    set True if this file type supports --encoding option.
sup_password: bool
    set True if this file type supports --ask_password option.
sup_v: bool
    set True if this file type supports --verbose option.
sup_k: bool
    set True if this file type supports --key option.
sup_i: bool
    set True if this file type supports --interactive option.
sup_c: bool
    set True if this file type supports --interactive_cui option.
add_args: Optional[str]
    The name of the file adding optional arguments.
    Please see the wiki for more details.

Returns
-------
str
    the help message.

interactive_cui

provide the CUI (TUI) to show the contents.

Parameters
----------
fname: str
    An opened file name.
get_contents: Callable[[PurePath], Tuple[List[str], List[str]]]
    A function to get lists of directories and files.
    The argument is the path to an item.
    The first return value is a list of directory names,
    and the second return value is a list of file names.
    In this context, a directory means something that includes
    files and directories, and a file means something that includes data.
show_func: Callable[[str, **kwargs], ReturnMessage]
    A function to show the contents.
    The first argument is the path to a file.
    Other arguments are treated as keyword arguments.
    Please see the wiki for possible keywords.
    The return value is the ReturnMessage. It is treated as
    an error message if ReturnMessage.error is True. Otherwise, it is
    treated as a standard message.

Returns
-------
None
Clone this wiki locally