HandyLib

Table of contents

• Introduction
• Usage
• Configuration
• Modules
  • log
  • file
• License

Introduction

This is a collection of code snippets I find myself reusing frequently, so I decided to package them.

It's likely that other developers won't find them as useful as I do, but you can expect this package to be a dependency of most of my other projects. Feel free to use it in yours in whole or in part, either by listing this repository as a dependency or copying the parts you want directly -- all I ask is that you abide by the GPLv3 license and share the love!

Usage

Setup is simple, just run:

pip3 install -r requirements.txt

After that, copy the HandyLib directory into your project and import whatever you need.

You can import whole modules or individual functions, e.g.:

from HandyLib import log
from HandyLib.file import mkdir
from HandyLib import *

Note that importing HandyLib itself does nothing but load or generate the config. This is because I don't forsee anyone wanting to, for example, make a directory by calling HandyLib.file.mkdir("example"). If this deeply offends you, feel free to open an issue about it.

Configuration

After first use, there will be a file HandyLib/config.yml that will look something like this:

date_format: '%y-%m-%d'
datetime_format: '%y-%m-%d %H:%M:%S'
debug: false
force_print: [fail]
keep_log: true
log_format: {end: "\033[0m", fail: "\033[91m", header: "\033[95m", info: "\033[94m", success: "\033[92m", warn: "\033[93m"}
log_levels: [fail, warn]
verbose: true
show_caller: true
show_timestamp: true

You can edit this file directly to change settings. Here's what each one does:

• date_format and datetime_format are standard formatting strings for representing dates and datetimes
• log_format is a dictionary of styles to be applied to logs generated by the log module. ANSI codes are used by default but you can change them to be anything you want, for example HTML <div> tags with inline styles. The end tag is applied to the end of all log messages. You can add more log types by simply extending this dictionary.
• keep_log tells the log module whether to write logs out to a file in the /logs directory. The log files are named after the modules and/or classes that use the logging facility.
• log_levels is a list of log_format keys that should be written to log files. This does nothing if keep_log is false.
• verbose tells the log module whether to print logs to the console.
• force_print is a list of log_format keys that should always be written to the console. This is very useful for cron jobs, as you can set verbose to false but ensure that errors are written, e.g. to trigger an email.
• show_caller and show_timestamp allow for flexible formatting of logs printed to console.
• debug is a flag to determine whether errors should be fatal or silent.

The defaults are set by __init__.py and are used only if no config.yml file is found.

Modules

Functions are collected in modules based on type. There are only a few available at the moment, but I intend to extend this package indefinitely. Please forgive my preemptive attempt at organizing them.

log

Currently, this module only has one function (log). More functions are in the works.

All other modules will make use of this one. It is directly callable.

Example usage:

from HandyLib import log
log("This is a log message!", log_type="success", force=True, caller="MyScript")
log("This is a simpler log message!")

If caller is not defined, the function will attempt to determine what file and class it was called from.

If only a message is defined, the default log_type of info will be used.

I did some things I'm not proud of to make the module directly callable.

file

This module provides a few useful functions for working with files and folders:

• sha256 will hash a file and return the hexadecimal digest
• unique_filename takes a filename and path and returns a unique filename to prevent overwriting existing files
• get_file_extension accepts a filename and uses os.path.splitext() to return a basename and extension with the option to recurse
• mkdir will check if a directory exists and attempt to create it if it doesn't
• extract_file takes a filename and path of a compressed file or archive and extracts the contents with options to recurse and either preserve directory structure or not

License

Licensed under GNU GPLv3

See license.txt for full text