Metadata-Version: 2.1
Name: pnu-libpnu
Version: 1.3.0
Summary: Common utility functions for the PNU project
Home-page: https://github.com/HubTou/libpnu/
Author: Hubert Tournier
Author-email: hubert.tournier@gmail.com
License: BSD 3-Clause License
Project-URL: Bug Tracker, https://github.com/HubTou/libpnu/issues
Keywords: pnu-project
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: BSD :: FreeBSD
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.3
Description-Content-Type: text/markdown
License-File: License

# Installation
This library will be installed as a dependency by other PNU utilities.

# LibPNU(3)

## NAME
libpnu — Common utility functions for the PNU project

## SYNOPSIS
import **libpnu**

*libpnu*.**initialize_debugging**(String *program_name*)

*libpnu*.**handle_interrupt_signals**(Function *handler_function*)

*libpnu*.**interrupt_handler_function**(Int *signal_number*, FrameObject *current_stack_frame*)

String *libpnu*.**get_home_directory**()

String *libpnu*.**get_caching_directory**(String *name*)

List *libpnu*.**locate_directory**(String *directory*)

List *libpnu*.**load_strings_from_file**(String *filename*)

## DESCRIPTION
The **initialize_debugging()** function sets up the Python logging module with a syslog style kind of console log using *program_name* as the program name.
By default, the logging level is set at WARNING or more, but can be lowered by calling **logging.disable()**,
for example with the *logging.NOTSET* parameter to get DEBUG or more logging level.

The **handle_interrupt_signals()** function calls the specified *handler_function* to process the SIGINT and SIGPIPE signals,
usually to avoid an ugly trace dump to the console in case of interrupt (Control-C pressed or broken pipe).
If all you want is printing an "Interrupted" English message and exit your program,
then you can use the **interrupt_handler_function()** as the *handler_function*.

The **get_home_directory()** function returns the location of the user's home directory in a string
depending on the operating system used (Unix, Windows).

The **get_caching_directory()** function returns the location of a user writable directory for caching files in a string
depending on the operating system used (Unix, Windows).
The provided *name* will be the last directory part of this location.

The **locate_directory()** function searches the specified *directory* in a variety of possible other directories,
depending on the operating system used (Unix, Windows) and the fact that a package can be user or system installed.
It is intended to be used when the directory can't be directly found, and returns a list of paths where the directory searched has been found.

For example, if the argument is "/usr/local/etc/man.d", we'll search for "usr/local/etc/man.d", "local/etc/man.d", "etc/man.d" (more likely) and "man.d"
in a list of user's local Python package directories
("$HOME/.local" on Unix, "$APPDATA/python", "$HOMEPATH/appdata/roaming/python", "$USERPROFILE/appdata/roaming/python" on Windows)
and system wide Python package base directories (given by *sys.base_prefix*: "/usr/local" on Unix, "C:/Program Files/Python3x" on Windows).

The **load_strings_from_file()** function returns a list of strings from the given *filename*,
filtering out comments and empty lines (with '#' being the comment character),
and joining continued lines (those ending with a '\\' character).

## ENVIRONMENT
The following environment variables can be used to identify the user identity and home directory,
or find a caching directory.

On Unix: *HOME*, *LNAME*, *LOGNAME*, *TMP*, *TMPDIR*, *USER* and *USERNAME*.

On Windows: *APPDATA*, *HOME*, *HOMEPATH*, *LOCALAPPDATA*, *TMP* and *USERPROFILE*.

## STANDARDS
The **libpnu** library is not a standard UNIX one.

It tries to follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for [Python](https://www.python.org/) code.

## PORTABILITY
Tested OK under Windows.

Packaged for FreeBSD as *pyXX-pnu-libpnu*.

## HISTORY
This library was made for the [PNU project](https://github.com/HubTou/PNU).

## LICENSE
It is available under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause).

## AUTHORS
[Hubert Tournier](https://github.com/HubTou)

