mooch 2.0.0

Lightweight Python utility library designed to streamline common development tasks needed for every python project.

mooch

mooch is a lightweight Python utility library designed to streamline common development tasks needed for every python project — file handling, path operations, logging decorators, and more — all in one convenient minimum package.

Table of Contents

• Features
• Install
• Usage
• Contributing
• License

Features

Settings

Lightweight, TOML-backed configuration/settings utility that that exposes project settings as standard Python dictionaries — allowing you to work with settings in a familiar, Pythonic way.

• TOML-powered: Uses TOML under the hood for modern, human-friendly settings files.
• Dictionary-like interface: Access and manipulate settings with regular dictionary operations.
• Nested access: Supports nested keys with dotted key notation.
• Optional defaults: Provide default values for initializing the settings file or for when a key is missing in the settings file.
• Optional always_reload: Reload the setting file everytime a key is read. (Enabled by default)

Progress Bar

A lightweight, eye-friendly, and feature-rich terminal progress bar.

• Clean, minimal visual output
• Smooth gradient color transition (Red → Gold → Green)
• ETA and step tracking
• Fast render speed of ~200ns per iteration

Location

Uses the https://api.zippopotam.us API to retrieve location information from a zip code or a city and state. U.S. only for now.

• Input options:
  • zipcode (int)
  • city (str)
  • state (star)
• Retrieves:
  • ZIP Code
  • City
  • State
  • Latitude & Longitude

Validators

• Raise a RuntimeError if the current python version is not compatible with your project.
• Raise a RuntimeError if the current operating system is not compatible with your project.
• Raise a RuntimeError if system commands like git are not in system's PATH
• Raise a RuntimeError if a list of environmental variables are not set.

Logging Decorators

@log_entry_exit

• Logs the entry and exit of the function, including the arguments.
• Useful for debugging and tracing.

Function Decorators

@silent(fallback="fallback value")

• Suppresses exceptions raised within the decorated function.
• Returns fallback if an exception is caught.

@retry(3)

• Retries the decorated function if an exception is raised.
• Returns the last exception on final retry attempt. Optional fallback returned instead if desired.
• Set delay time between tries with delay argument.

@deprecated

• Emits a DeprecationWarning when the function is called.
• Accepts a custom reason string to explain the deprecation.
• Supports Python 3.9+ (@deprecated was added to Python 3.13)

@timeit

• Logs execution time of a function using the Python logging module.

@with_lock(threading.Lock or asyncio.Lock)

• Prevents concurrent execution using provided threading.Lock or asyncio.Lock
• Lock object is created if not provided, but doing this only prevents concurrent execution of same function.

Install

pip install mooch

or

uv add mooch

Dependencies

Python 3.9 or greater

Usage

Browse the examples folder for more examples.

Settings

from mooch import Settings

defaults = {}
defaults["settings.mood"] = "happy"
defaults["settings.volume"] = 50

settings = Settings("mooch", defaults)  # Change 'mooch' to your project's name

print("Current Settings:")
print(f"Mood: {settings['settings.mood']}")
print(f"Volume: {settings['settings.volume']}") # prints 50

settings["settings.volume"] = 75

print("Updated Settings:")
print(f"Mood: {settings['settings.mood']}")
print(f"Volume: {settings['settings.volume']}") # prints 75

Progress Bar

#pb = ColoredProgressBar(5)
pb = ProgressBar(total=5)

for _ in range(5):
    time.sleep(0.1)
    pb.update()

Terminal Output:

Logging Decorator

from mooch.decorators import log_entry_exit

@log_entry_exit
def random_function(arg1, arg2):
    print(arg1)
    print(arg2)

Log File Output:

DEBUG:__main__:Entering random_function() with args=('Hello', 'World'), kwargs={}
DEBUG:__main__:Exiting random_function()

Retry Decorator

from mooch.decorators import retry

@retry(3)
def get_age(name="random_person"):
    age = ...some other task...
    return age

Location

from mooch import Location
location = Location(zipcode=62704)

print(location.city)                # "Springfield"
print(location.state)               # "Illinois"
print(location.state_abbreviation)  # "IL"
print(location.latitude)            # "39.7725"
print(location.longitude)           # "-89.6889"

Validators

Raise an RuntimeError if the requirement isn't satisified.

from mooch.validators import command, operating_system, python_version

python_version.check("3.13")
operating_system.check("Windows")
command.check("python", "ls", "echo")

Development

Steps for setting up this project in VS Code.

1. Clone the Repository

git clone https://github.com/nickstuer/mooch

2. Install uv (skip if already installed)

curl -Ls https://astral.sh/uv/install.sh | sh

3. Install Project Dependencies

uv sync

4. Activate Virtual Environment

source .venv/bin/activate  # On Windows: source .venv/Scripts/activate

5. Install pre-commit hooks

pre-commit install

# Verify
pre-commit run --all-files

6. Setup Python Interpreter in VS Code

Press CMD + Shift + P   # On Windows: CTRL + Shift + P
Select `Python: Select Interpreter'
Choose `.\.venv\Scripts\python.exe`

7. Install mooch-settings as local editable

uv pip install -e ../mooch-settings 
uv pip install -e .

Contributing

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Bug Reports and Feature Requests

Please use the issue tracker to report any bugs or request new features.

Contributors

License

MIT © Nick Stuer