hikari.internal.ux#

User-experience extensions and utilities.

Module Contents#

class hikari.internal.ux.HikariVersion(vstring)[source]#

Hikari strict version.

async hikari.internal.ux.check_for_updates(http_settings, proxy_settings)[source]#

Perform a check for newer versions of the library, logging any found.

hikari.internal.ux.init_logging(flavor, allow_color, force_color)[source]#

Initialize logging for the user.

Note

If any handlers already exist, some opinionated defaults will be configured (mostly do to with logging efficiency and warning logging), but existing handlers will not be overwritten. You can disable this by passing None as the flavor parameter.

Warning

This function is blocking!

Parameters:
flavortyping.Optional[None, str, int, typing.Dict[str, typing.Any], os.PathLike[str]]

The hint for configuring logging.

This can be None to not enable logging automatically.

If you pass a str or a int, it is interpreted as the global logging level to use, and should match one of "DEBUG", "INFO", "WARNING", "ERROR" or "CRITICAL". The configuration will be set up to use a colorlog coloured logger, and to use a sane logging format strategy. The output will be written to sys.stdout using this configuration.

If you pass a dict, it is treated as the mapping to pass to logging.config.dictConfig. If the dict defines any handlers, default handlers will not be setup if incremental is not specified.

If you pass a str to an existing file or a os.PathLike, it is interpreted as the file to load config from using logging.config.fileConfig.

Note that "TRACE_HIKARI" is a library-specific logging level which is expected to be more verbose than "DEBUG".

allow_colorbool

If False, no colour is allowed. If True, the output device must be supported for this to return True.

force_colorbool

If True, return True always, otherwise only return True if the device supports colour output and the allow_color flag is not False.

Examples

Simple logging setup:

init_logging("INFO")  # Registered logging level
# or
init_logging(20)  # Logging level as an int

File config:

# See https://docs.python.org/3/library/logging.config.html#configuration-file-format for more info
init_logging("path/to/file.ini")

Setting up logging through a dict config:

# See https://docs.python.org/3/library/logging.config.html#dictionary-schema-details for more info
init_logging(
    {
        "version": 1,
        "incremental": True,  # In incremental setups, the default stream handler will be setup
        "loggers": {
            "hikari.gateway": {"level": "DEBUG"},
            "hikari.ratelimits": {"level": "TRACE_HIKARI"},
        },
    }
)
hikari.internal.ux.print_banner(package, allow_color, force_color, extra_args=None)[source]#

Print a banner of choice to sys.stdout.

Inspired by Spring Boot, we display an ASCII logo on startup. This is styled to grab the user’s attention, and contains info such as the library version, the Python interpreter, the OS, and links to our Discord server and documentation. Users can override this by placing a banner.txt in some package and referencing it in this call.

Note

The banner.txt must be in the root folder of the package.

Warning

This function is blocking!

Parameters:
packagetyping.Optional[str]

The package to find the banner.txt in, or None if no banner should be shown.

allow_colorbool

If False, no colour is allowed. If True, the output device must be supported for this to return True.

force_colorbool

If True, return True always, otherwise only return True if the device supports colour output and the allow_color flag is not False.

extra_argstyping.Optional[typing.Dict[str, str]]

If provided, extra $-substitutions to use when printing the banner. Default substitutions can not be overwritten.

Raises:
ValueError

If extra_args contains a default $-substitution.

hikari.internal.ux.supports_color(allow_color, force_color)[source]#

Return True if the terminal device supports color output.

Parameters:
allow_colorbool

If False, no color is allowed. If True, the output device must be supported for this to return True.

force_colorbool

If True, return True always, otherwise only return True if the device supports color output and the allow_color flag is not False.

Returns:
bool

True if color is allowed on the output terminal, or False otherwise.

hikari.internal.ux.warn_if_not_optimized(suppress)[source]#

Log a warning if not running in optimization mode.