API reference

Introduction

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

Variables

GLOBAL_CONF

Global configuration variable.
This variable contains following attributes.

Attributes:
debug: bool
    debug mode is enabled or not.
conf_dir: pathlib.Path
    configuration directory.
    default: "$XDG_CONFIG_HOME/aftviewer" or "~/.config/aftviewer"
opts: dict
    behavior options. This values are overridden by conf_dir/setting.json.
types: dict
    supported file types and its extensions.
    This dictionary is overridden by "additional_types" in opts.
logname: str
    log name used in logger.

Types

Args

wrapper of argument parser. The following attributes are examples
that are used in some of default file types.
The actual arguments depends on the file type.
Type 'aftviewer help -t <file type>' to see the selectable arguments.

Attributes:
file: str
    opened file.
type: str
    file type.
image_viewer: str
    Image viewer which specify the method to open an image file.
    If image viewer is specified at both command line and setting file
    (setting.json), command value has priority.
encoding: str
    The name of the encoding used to open the file.
verbose: bool
    Show the details if --verbose|-v is set.
key: list of keys
    Specify the keys/pathes to show the information.
interactive: bool
    Open the file with interactive mode if --interactive|-i is set.
cui: bool
    Open the file with interactive-cui mode if --interactive_cui|-c is set.
output: str
    Specify the output file.

Note that verbose, key, interactive, and interactive_cui options
are exclusive.

ReturnMessage

class for returned message.

Attributes:
message: str
    returned message.
error: bool
    True if this message is an error.

Functions

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.

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
-------
str, int, or None
    foreground color id. If the name is incorrect, return None.
str, int, or None
    foreground color id. If the name is incorrect, 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: str, int, or 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: str, int, or 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

print_error

print error message.

Parameters
----------
msg: string
    error message.

Returns
-------
None

print_warning

print warning message.

Parameters
----------
msg: string
    warning message.

Returns
-------
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

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.
purepath: PurePath, PurePosixPath, or PureWindowsPath
    Specify the class to treat the path-like object.
    This is because in some case, the separator shoud be '/' not '\'
    even if the OS is Windows.

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.

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
-------
True, False, or None
    Return True if the file opened successfully and
    False if opening file failed.
    If a module to open the image is not found, return None.

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 file opened successfully and
    False if opening file failed.
    If a module to open the image is not found, return None.

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 `aftviewer` command.
description: str
    the description of the file type.
add_args: Callable or None
    A function to add optional arguments.
    This function takes one variable which type is ArgumentParser.

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

add_args_imageviewer

add optional argument --image_viewer.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_encoding

add optional argument --encoding.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_output

add optional argument --output.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_verbose

add optional argument --verbose.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_key

add optional argument --key.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_interactive

add optional argument --interactive.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_cui

add optional argument --interactive_cui.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.

Returns
-------
None

add_args_specification

add optional arguments that are used to specify items.

Parameters
----------
parser: ArgumentParser
    ArgumentParser which optional arguments will be added.
verbose: bool
    add optional argument --verbose
key: bool
    add optional argument --key
interactive: bool
    add optional argument --interactive
cui: bool
    add optional argument --interactive_cui

Returns
-------
None

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.
purepath: PurePath, PurePosixPath, or PureWindowsPath
    Specify the class to treat the path-like object.
    This is because in some case, the separator shoud be '/' not '\'
    even if the OS is Windows.

Returns
-------
None