nclutils

A grab-bag of small convenience helpers I reach for again and again across my Python scripts and packages: filesystem operations, shell execution, string transformations, console output, interactive prompts, and a few odds and ends.

Comprehensive tests are included, but this package is written and maintained for my own use. No guarantees are made about API stability or correctness for your use case.

Quick example

from pathlib import Path
from nclutils import pp
from nclutils.fs import copy_file, find_files
from nclutils.strings import snake_case

pp.info("collecting Python sources")

with pp.step("copying files") as s:
    for src in find_files(Path("src"), globs=["*.py"]):
        dst = Path("backup") / src.name
        copy_file(src, dst)
        s.sub(f"copied {src.name}")

pp.success(f"normalized name: {snake_case('Hello World')}")

Installation

Requires Python 3.11 or newer.

# With uv
uv add nclutils

# With pip
pip install nclutils

The package brings in two runtime dependencies: questionary and rich.

Importing

Each module is imported from its submodule. The pretty-printing helpers are namespaced under pp:

from nclutils import pp

pp.info("hello")
pp.success("done")

Other modules follow the same pattern:

from nclutils.ask import choose_one_from_list
from nclutils.fs import copy_file, find_files
from nclutils.net import network_available
from nclutils.sh import run_command, run_interactive, which, CompletedCommand, ShellCommandError
from nclutils.strings import camel_case, deburr
from nclutils.text import replace_in_file
from nclutils.utils import iso_timestamp, unique_id

Individual pp symbols can also be imported directly when that reads better at the call site:

from nclutils.pp import info, success

Modules

The larger modules have their own documentation pages. Smaller modules are listed inline below. Function signatures live with the source; consult docstrings (help(func) or your editor's hover) for authoritative argument details.

nclutils.net

• network_available(address="8.8.4.4", port=53, timeout=5). Return True if a TCP connection to the given host and port succeeds within timeout seconds.

nclutils.text

• replace_in_file(path, replacements, *, use_regex=False). Apply a dict of replacements to a file in place. Returns True if the file changed.
• ensure_lines_in_file(path, lines, *, at_top=False). Add lines to a file if they aren't already present. Returns True if the file changed.

from nclutils.text import ensure_lines_in_file, replace_in_file

replace_in_file("config.toml", {"old": "new"})

# Regex mode (each key is a pattern; matches use re.MULTILINE)
replace_in_file("config.toml", {r"^old": "new"}, use_regex=True)

ensure_lines_in_file(".gitignore", [".env", "*.pyc"])

For coding agents

A bundled reference skill lives in skill/. It's a quick-reference card aimed at AI coding agents working in projects that depend on nclutils: correct import paths, a task-to-module lookup, top gotchas (the pp vs stdlib logging split, sh.run_command error handling, places to reach for nclutils instead of hand-rolling shutil/subprocess/uuid equivalents), with per-module deep dives in skill/references/.

If you use an AI coding agent (Claude Code, Cursor, etc.) in a project that imports nclutils, point it at the skill before it starts editing. For example:

Before writing any code that touches nclutils, read https://raw.githubusercontent.com/natelandau/nclutils/main/skill/SKILL.md. Follow the import patterns and gotchas described there. If a task involves the pp, sh, fs, git, strings, or smaller modules in detail, also read the matching file under https://raw.githubusercontent.com/natelandau/nclutils/main/skill/references/.

Pinning to a tag (e.g. /v3.1.0/skill/SKILL.md) keeps the guidance aligned with whichever version of nclutils the project depends on.

Diagnostic logging

Internal modules (nclutils.fs, nclutils.text) emit diagnostic messages through the stdlib logging module under their own logger names. By default these are silent. Attach a handler in your application to see them:

import logging

logging.basicConfig(level=logging.WARNING)
# or, narrower:
logging.getLogger("nclutils").setLevel(logging.DEBUG)

This is separate from nclutils.pp, which writes to the console (and optionally a logfile) using its own machinery.

Contributing

See CONTRIBUTING.md for development setup, task runner commands, and the commit workflow.

License

MIT. See LICENSE.