libb-util Documentation

A comprehensive collection of utility functions and classes designed to enhance productivity and simplify common programming tasks in Python.

Note

All utilities should be imported from the top-level libb package:

from libb import Setting, compose, attrdict, timeout

Function Reference

Core Utilities

Configuration - Settings and environment management

libb.Setting	Dict where d['foo'] can also be accessed as d.foo.
libb.ConfigOptions	Abstract base class for loading options from config.py.
libb.load_options	Wrapper that builds dataclass options from config file.
libb.configure_environment	Configure environment settings at runtime.
libb.patch_library_config	Patch a library's config module directly in sys.modules.
libb.setting_unlocked	Context manager to safely modify a setting with unlock/lock protection.
libb.get_tempdir	Get temporary directory setting from environment or system default.
libb.get_vendordir	Get vendor directory setting from environment or system default.
libb.get_outputdir	Get output directory setting from environment or system default.
libb.get_localdir	Get local data directory setting using platform-appropriate location.

Classes - Class manipulation and decorators

libb.attrs	Create property getters/setters for private attributes.
libb.include	Include dictionary items as class attributes during class declaration.
libb.singleton	Decorator that enforces singleton pattern on a class.
libb.memoize	Decorator that caches function results based on arguments.
libb.classproperty	Decorator that creates computed properties at the class level.
libb.delegate	Delegate attribute access to another object.
libb.lazy_property	Decorator that makes a property lazy-evaluated.
libb.cachedstaticproperty	Decorator combining @property and @staticmethod with caching.
libb.staticandinstancemethod	Decorator allowing a method to work as both static and instance method.
libb.metadict	Mapping class that references values weakly.
libb.makecls	Class factory that resolves metaclass conflicts automatically.
libb.extend_instance	Dynamically extend an instance's class hierarchy at runtime.
libb.ultimate_type	Find the ultimate non-object base class in an inheritance hierarchy.
libb.catch_exception	Decorator that catches and reports exceptions without re-raising.
libb.ErrorCatcher	Metaclass that wraps all methods with exception catching.

Functions - Function composition and decorators

libb.is_instance_method	Check if a function is an instance method.
libb.find_decorators	Find decorators applied to functions in a target module/class.
libb.compose	Return a function folding over a list of functions.
libb.composable	Decorator that takes a list of decorators to be composed.
libb.copydoc	Decorator to copy the docstring of another function.
libb.get_calling_function	Find the calling function in many common cases.
libb.repeat	Decorator to repeat a function multiple times.
libb.timing	Decorator to log function execution time.
libb.suppresswarning	Decorator to suppress warnings during function execution.
libb.MultiMethod	Multimethod that supports args (no kwargs by design).
libb.multimethod	Decorator for type-based method dispatch (multiple dispatch).

Iterators - Iterator utilities and sequence operations

libb.chunked	Break iterable into lists of length n:
libb.chunked_even	Break iterable into lists of approximately length n.
libb.collapse	Recursively flatten nested lists/tuples into a single list.
libb.compact	Remove falsy values from an iterable (including None and 0).
libb.grouper	Group elements from iterable into fixed-length groups of length n.
libb.hashby	Create a dictionary from iterable using a key function.
libb.infinite_iterator	Create an iterator that cycles infinitely through items.
libb.iscollection	Check if object is a collection (iterable and not a string).
libb.isiterable	Check if object is iterable (excluding strings).
libb.issequence	Check if object is a sequence (excluding strings).
libb.partition	Returns a 2-tuple of iterables derived from the input iterable.
libb.peel	Peel iterator one by one, yield item, aliasor item, item
libb.roundrobin	Visit input iterables in a cycle until each is exhausted.
libb.rpeel	Peel iterator one by one, yield alias if tuple, else item"
libb.unique	Remove duplicate elements while preserving order.
libb.unique_iter	Yield unique elements, preserving order.
libb.same_order	Compare two lists and check if elements in ref appear in same order in comp.
libb.coalesce	Return first non-None value.
libb.getitem	Safe sequence indexing with default value
libb.backfill	Back-fill a sorted array with the latest value.
libb.backfill_iterdict	Back-fill a sorted iterdict with the latest values.
libb.align_iterdict	Given two lists of dicts ('iterdicts'), sorted on some attribute, build a single list with dicts, with keys within a given tolerance anything that cannot be aligned is DROPPED

Text - Text processing and encoding

libb.random_string	Generate a random alphanumeric string.
libb.fix_text	Use ftfy magic to fix text encoding issues.
libb.underscore_to_camelcase	Convert underscore_delimited_text to camelCase.
libb.uncamel	Convert camelCase to snake_case.
libb.strip_ascii	Remove non-ASCII characters from a string.
libb.sanitize_vulgar_string	Replace vulgar fractions with decimal equivalents.
libb.round_digit_string	Round a numeric string to specified decimal places.
libb.parse_number	Extract number from string.
libb.truncate	Truncate a string to max width characters.
libb.rotate	Apply rot13-like translation to string.
libb.smart_base64	Decode base64 encoded words with intelligent charset handling.
libb.strtobool	Convert a string representation of truth to boolean.
libb.fuzzy_search	Search for term in a list of items using fuzzy matching.
libb.is_numeric	Check if value can be converted to a float.

Formatting - String and number formatting

libb.Percent	Float subclass that marks values for percentage formatting in display tables.
libb.capitalize	Capitalize with special handling for known abbreviations.
libb.capwords	Capitalize words in a string, accommodating acronyms.
libb.commafy	Add commas to a numeric value.
libb.fmt	Alias for format().
libb.format	Format a numeric value with various formatting options.
libb.format_phone	Reformat phone numbers for display.
libb.format_secondsdelta	Format seconds as human-readable time delta.
libb.format_timedelta	Format a timedelta as human-readable string.
libb.format_timeinterval	Format a time interval as human-readable string.
libb.splitcap	Split and capitalize string by delimiter (or camelcase).
libb.titlecase	Convert string to title case using python-titlecase library.

Path - Path and module utilities

libb.add_to_sys_path	Add a path to the Python system search path.
libb.cd	Context manager to safely change working directory.
libb.get_module_dir	Get the directory containing a module.
libb.scriptname	Return name of script being run, without file extension.

Dictionaries - Dictionary manipulation

libb.ismapping	Check if something is a mapping (dict-like).
libb.invert	Invert a dictionary, swapping keys and values.
libb.mapkeys	Apply a function to all keys in a dictionary.
libb.mapvals	Apply a function to all values in a dictionary.
libb.flatten	Flatten a dictionary, recursively flattening nested dicts.
libb.unnest	Recursively convert dict into list of tuples.
libb.replacekey	Context manager for temporarily patching a dictionary value.
libb.replaceattr	Context manager for temporarily monkey patching an object attribute.
libb.cmp	Python 2 style cmp function with null value handling.
libb.multikeysort	Sort list of dictionaries by list of keys.
libb.map	Simulate a Python 2-like map with longest iterable behavior.
libb.get_attrs	Get class attributes (excluding methods and dunders).
libb.trace_key	Trace dictionary key in nested dictionary.
libb.trace_value	Get values at all locations of a key in nested dictionary.
libb.add_branch	Insert a value into a dict at the path specified by vector.
libb.merge_dict	Recursively merge two dictionaries, including nested dictionaries and iterables.

Module - Module loading and manipulation

libb.OverrideModuleGetattr	Wrapper to override __getattr__ of a Python module.
libb.get_module	Import a dotted module name and return the innermost module.
libb.get_class	Get a class by its fully qualified name.
libb.get_subclasses	Get all classes in a module that are subclasses of parentcls.
libb.get_function	Get a function by name from a module.
libb.load_module	Load a module from a file path.
libb.patch_load	Patch and load a module with regex substitutions.
libb.patch_module	Replace a source module with a target module in sys.modules.
libb.create_instance	Create an instance of a class by its fully qualified name.
libb.create_mock_module	Create a mock module with specified attributes.
libb.VirtualModule	Virtual module with submodules sourced from other modules.
libb.create_virtual_module	Create a virtual module with submodules from other modules.
libb.get_packages_in_module	Get package info for modules, useful for pytest conftest loading.
libb.get_package_paths_in_module	Get package paths within modules, useful for pytest conftest loading.
libb.import_non_local	Import a module using a custom name to avoid local name conflicts.

Type Definitions - Type aliases

libb.FileLike	alias of IO[BytesIO] | BytesIO | FileIO | TextIOWrapper
libb.Attachable	alias of str | dict | IO[BytesIO] | BytesIO | FileIO | TextIOWrapper | Iterable[Iterable[Any]]
libb.Dimension	Built-in immutable sequence.

Collections

Attribute Dictionaries - Dict subclasses with attribute access

libb.attrdict	A dictionary subclass that allows attribute-style access.
libb.lazydict	A dictionary where function values are lazily evaluated.
libb.emptydict	A dictionary that returns None for non-existing keys without raising exceptions.
libb.bidict	Bidirectional dictionary that allows multiple keys with the same value.
libb.MutableDict	An ordered dictionary with additional insertion methods.
libb.CaseInsensitiveDict	A case-insensitive dictionary-like object.

Ordered Set - Set with insertion order

libb.OrderedSet

A set that maintains insertion order using a doubly linked list.

Heap - Priority queue with custom comparator

libb.ComparableHeap

Heap with custom key comparator.

Input/Output

CSV/JSON - Data serialization

libb.render_csv	Render rows as CSV string.
libb.CsvZip	Zipped CSV file that handles file permissions correctly on DOS.
libb.iterable_to_stream	Convert an iterable that yields bytestrings to a read-only input stream.
libb.stream
libb.json_load_byteified	Parse ASCII encoded JSON from file handle.
libb.json_loads_byteified	Parse ASCII encoded JSON from text string.
libb.suppress_print	Context manager to suppress stdout (print statements).
libb.wrap_suppress_print	Decorator version of suppress_print context manager.

Stream - TTY and stream utilities

libb.is_tty	Check if running in a terminal.
libb.stream_is_tty	Check if a stream is running in a terminal.

Process - Process management

libb.process_by_name	Find processes by name that are listening on a port.
libb.process_by_name_and_port	Find a process by name listening on a specific port.
libb.kill_proc	Kill processes matching name and/or version.

Signals - Signal handling

libb.SIGNAL_TRANSLATION_MAP	Map of signal numbers to signal names.
libb.DelayedKeyboardInterrupt	Context manager that suppresses SIGINT & SIGTERM during a block.

MIME - MIME type utilities

libb.guess_type	Guess mimetype from a URL or filename.
libb.guess_extension	Guess file extension for a mimetype.
libb.magic_mime_from_buffer	Detect mimetype using the magic library.

Directory - File system operations

libb.mkdir_p	Create directory and any missing parent directories.
libb.make_tmpdir	Context manager to wrap a temporary directory with auto-cleanup.
libb.expandabspath	Expand path to absolute path with environment variables and user expansion.
libb.get_directory_structure	Create a nested dictionary representing the folder structure.
libb.search	Search for files by name, extension, or both in directory.
libb.safe_move	Move a file to a new location, optionally deleting anything in the way.
libb.save_file_tmpdir	Save a document to the specified temp directory, optionally with date.
libb.get_dir_match	Get paths of existing files matching each glob pattern.
libb.load_files	Load file contents from directory matching pattern.
libb.load_files_tmpdir	Load files from temp directory matching patterns.
libb.dir_to_dict	Convert directory structure to a dictionary.
libb.download_file	Download file from URL with progress bar and retry logic.
libb.splitall	Split path into all its components.
libb.resplit	Split path by multiple separators.

Specialized

Statistics - Math and statistics

libb.npfunc	Decorator to convert args to numpy format and results back to Python.
libb.avg	Compute average of array, ignoring None/NaN values.
libb.pct_change	Compute percent change between consecutive elements.
libb.diff	Compute one-period difference between consecutive elements.
libb.thresh	Round to nearest integer if within threshold distance.
libb.isnumeric	Check if value is a numeric type.
libb.digits	Count number of integer digits in a number.
libb.numify	Convert value to numeric type, handling common formatting.
libb.parse	Extract number from string.
libb.nearest	Round number to the nearest tick value.
libb.covarp	Compute population covariance between x and y.
libb.covars	Compute sample covariance between x and y.
libb.varp	Compute population variance of x.
libb.vars	Compute sample variance of x.
libb.stddevp	Compute population standard deviation.
libb.stddevs	Compute sample standard deviation.
libb.beta	Compute beta of x with respect to index (typically over returns).
libb.correl	Compute correlation between x and y.
libb.rsq	Compute R-squared (coefficient of determination) between x and y.
libb.rtns	Compute simple returns between consecutive values.
libb.logrtns	Compute log returns between consecutive values.
libb.weighted_average	Compute a weighted average of field in a DataSet using weight_field as the weight.
libb.linear_regression	Compute the least-squares linear regression line for the set of points.
libb.distance_from_line	Compute the distance from each point to the line defined by m and b.
libb.linterp	Linearly interpolate y between y0 and y1 based on x's position.
libb.np_divide	Safely divide numpy arrays, returning 0 where divisor is 0.
libb.safe_add	Safely add numbers, returning None if any argument is None.
libb.safe_diff	Safely subtract numbers, returning None if any argument is None.
libb.safe_divide	Safely divide numbers, returning None if any arg is None.
libb.safe_mult	For big lists of stuff to multiply, when some things may be None
libb.safe_round	Safely round a number, returning None if argument is None.
libb.safe_cmp	Compare two values using a comparison operator.
libb.safe_min	Min returns None if it is in the list - this one returns the min value
libb.safe_max	Max returns None if it is in the list - this one returns the max value
libb.convert_mixed_numeral_to_fraction	Convert mixed numeral string to decimal fraction.
libb.convert_to_mixed_numeral	Convert decimal or fraction to mixed numeral string.
libb.round_to_nearest	Round value to nearest multiple of base.
libb.numpy_smooth	Smooth the data using a window with requested size.
libb.choose	Compute binomial coefficient (n choose k).

Threading - Concurrency utilities

libb.asyncd	Decorator to run synchronous function asynchronously.
libb.call_with_future	Call function and set result on future.
libb.RateLimitedExecutor	Thread pool executor with rate limiting and Request/Response API.
libb.TaskRequest	Request to process an item with optional ID for tracking.
libb.TaskResponse	Response from processing a request.
libb.threaded	Decorator to run function in a separate thread.

Synchronization - Timing and synchronization

libb.syncd	Decorator to synchronize functions with a shared lock.
libb.NonBlockingDelay	Non-blocking delay for checking time elapsed.
libb.delay	Delay non-blocking for N seconds (busy-wait).
libb.debounce	Decorator to debounce function calls.
libb.wait_until	Calculate time to wait until specified hour/minute/second.
libb.timeout	Context manager for timing out potentially hanging code.

Cryptography - Encoding utilities

libb.base64file	Encode file contents as base64.
libb.kryptophy	Converts a string to an integer by concatenating hex values of characters.

Geographic - Coordinate transformations

libb.merc_x	Project longitude into mercator / radians from major axis.
libb.merc_y	Project latitude into mercator / radians from major/minor axes.

Random - OS-seeded random functions

libb.random_choice	Random choice from a list, seeded with OS entropy.
libb.random_int	Random integer between a and b inclusive, seeded with OS entropy.
libb.random_sample	Random sample of N elements from numpy array.
libb.random_random	Random float in [0, 1), seeded with OS entropy.

Exceptions - Error handling

libb.print_exception	Print exception traceback with optional verbosity.
libb.try_else	Wrap function to return default value if it fails.

Charts - Visualization

libb.numpy_timeseries_plot

Create a matplotlib timeseries plot with automatic subplot layout.

Pandas - DataFrame utilities

libb.is_null	Check if value is null/None (pandas required).
libb.download_tzdata	Download timezone data for pyarrow date wrangling.
libb.downcast	Downcast DataFrame to minimum viable type for each column.
libb.fuzzymerge	Merge two DataFrames using fuzzy matching on specified columns.

Web - Web application utilities

libb.get_or_create	Get existing model instance or create new one (Django-style).
libb.paged	Decorator to pass in default order/page/per page for pagination.
libb.rsleep	Sleep for a random amount of time.
libb.rand_retry	Decorator that retries function with random delays.
libb.cors_webpy	Wrap a web.py controller with CORS headers.
libb.cors_flask	Wrap a Flask controller with CORS headers.
libb.authd	Decorator that checks if user meets an auth criterion.
libb.xsrf_token	Generate cross-site request forgery protection token.
libb.xsrf_protected	Decorator protecting PUT/POST requests from session riding.
libb.valid_api_key	Check if key has valid format.
libb.requires_api_key	Decorator requiring valid API key for controller access.
libb.make_url	Generate URL with query parameters.
libb.prefix_urls	Add prefixes to web.py URL mappings.
libb.url_path_join	Normalize URL parts and join them with a slash.
libb.first_of_each	Return first non-empty element from each sequence.
libb.safe_join	Safely join untrusted path components to a base directory.
libb.local_or_static_join	Find template in working directory or static folder.
libb.inject_file	Read file contents for injection into HTML email templates.
libb.inject_image	Generate base64 data URI for image embedding in HTML.
libb.build_breadcrumb	Build breadcrumb HTML from web.py app_stack.
libb.breadcrumbify	Patch URL mapping into web.py subapps for breadcrumbs.
libb.appmenu	Build HTML menu from web.py URL mapping.
libb.scale	Scale a hex color by a percentage.
libb.render_field	Render form field with error styling.
libb.login_protected	Decorator protecting routes by session authentication.
libb.userid_or_admin	Decorator limiting access to own user ID unless admin.
libb.manager_or_admin	Decorator limiting access to managed resources unless admin.
libb.logerror	Wrap internalerror function to log tracebacks.
libb.validip6addr	Check if address is a valid IPv6 address.
libb.validipaddr	Check if address is a valid IPv4 address.
libb.validipport	Check if port is a valid port number.
libb.validip	Parse IP address and port from string.
libb.validaddr	Parse address as IP:port tuple or Unix socket path.
libb.urlquote	Quote string for safe use in a URL.
libb.httpdate	Format datetime object for HTTP headers.
libb.parsehttpdate	Parse HTTP date string into datetime object.
libb.htmlquote	Encode text for safe use in HTML.
libb.htmlunquote	Decode HTML-encoded text.
libb.websafe	Convert value to safe Unicode HTML string.
libb.JSONEncoderISODate	JSON encoder that serializes dates in ISO format.
libb.JSONDecoderISODate	JSON decoder that parses date strings into datetime objects.
libb.ProfileMiddleware	WSGI middleware for profiling requests.
libb.COOKIE_DEFAULTS	Default kwargs for cookielib.Cookie constructor.

Windows - Windows-specific utilities

libb.run_command	Execute a shell command and return output.
libb.psexec_session	Context manager for running psexec commands.
libb.file_share_session	Context manager for temporarily mounting a file share.
libb.mount_admin_share	Mount or unmount the admin$ share required for psexec commands.
libb.mount_file_share	Mount or unmount a Windows file share.
libb.parse_wmic_output	Parse output from WMIC query into list of dicts.
libb.exit_cmd	Kill all running cmd.exe processes via WMI.

---

Design Philosophy

• Transparent API: Always import from top-level libb, never from submodules

• Graceful Dependencies: Optional dependencies wrapped for clean imports

• Short, Singular Names: Modules use concise names (e.g., func not funcutils)

• Comprehensive Exports: All modules explicitly define their public API via __all__

Getting Started

• Installation
  • Requirements
  • Basic Installation
  • Optional Extras
  • Environment Variables
• Quick Start
  • Basic Usage
  • Configuration Management
  • Function Composition
  • Attribute Dictionaries
  • Timeout Decorator
  • Iterator Utilities
  • Text Processing
  • Threading Utilities

API Reference

• API Reference
  • Module Categories
• Core Utilities
  • config
  • classes
  • func
  • iter
  • text
  • format
  • path
  • dicts
  • module
  • typedefs
• Collection Classes
  • attrdict
  • orderedset
  • heap
• I/O & System Utilities
  • iolib
  • stream
  • proc
  • signals
  • mime
• Specialized Utilities
  • webapp
  • stats
  • sync
  • crypto
  • geo
  • dir
  • exception
  • future
  • pandasutils
  • rand
  • thread
  • chart
  • win

Indices and tables

• Index

• Module Index

• Search Page