nclutils

Collection of convenience functions used in Python packages and scripts. These are written and maintained for my own personal use. Comprehensive tests are included but I make no guarantees about the quality or correctness of the code.

Features

• Filesystem Utilities: Common filesystem operations
• Logging: A wrapper around the Loguru logger with configurable log levels and custom styles.
• Network: Helper functions for working with network connections.
• Pretty Printing: Rich text formatting for console output with customizable styles
• Pytest Fixtures: Convenience functions and fixtures for testing.
• Questions: Short-cut functions for asking questions and getting user input using the questionary library.
• Shell Commands: Safe execution of shell commands with proper error handling
• Strings: Convenience functions for working with strings.
• Text Processing: Convenience functions for working with text files.
• Other miscellaneous utilities.

Requirements

• Python 3.10 or higher
• Dependencies are managed with uv

Dependencies

nclutils has a few dependencies that are included in the project.

• questionary - For asking questions
• rich - For pretty printing
• sh - For running shell commands
• Loguru - For logging

Installation

# With uv
uv add nclutils

# With pip
pip install nclutils

Included Modules

Filesystem Utilities

• backup_path(path: Path, raise_on_missing: bool = False, with_progress: bool = False, transient: bool = True) -> Path | None

  Create a backup of a file or directory. Silently returns None if the source path does not exist by default.

• clean_directory(directory: Path) -> None

  Recursively cleans up the contents of a directory, deleting all files and subdirectories without deleting the directory itself.

• copy_directory(src: Path, dst: Path, with_progress: bool = False, transient: bool = True, keep_backup: bool = True) -> Path

  Copy a directory with an optional progress bar for each file. If the destination directory already exists, it will be backed up with a timestamped suffix.

• copy_file(src: Path, dst: Path, with_progress: bool = False, transient: bool = True, keep_backup: bool = True) -> Path

  Copy a file with a progress bar. If the destination file already exists, it will be backed up with a timestamped suffix.

  Raises FileNotFoundError if the source file does not exist or is not a file.

• directory_tree(directory: Path, show_hidden: bool = False) -> Tree

  Build a rich.tree representation of a directory's contents.

• find_files(path: Path, globs: list[str] | None = None, ignore_dotfiles: bool = False) -> list[Path]

  Search for files within a directory optionally matching specific glob patterns.

• find_subdirectories(directory: Path, depth: int = 1, filter_regex: str = "", ignore_dotfiles: bool = False, leaf_dirs_only: bool = False) -> list[Path]

  Find and filter subdirectories with granular control:

  from pathlib import Path
  from nclutils import find_subdirectories
  
  root_directory = Path(".")
  
  # Find subdirectories with specific criteria
  subdirs = find_subdirectories(
      root_directory,
      depth=2, # How deep to search
      filter_regex=r"^a", # Only dirs starting with 'a'
      leaf_dirs_only=True, # Furthest down directories only
      ignore_dotfiles=True # Skip hidden directories
  )

• find_user_home_dir(username: str | None = None) -> Path | None

  Find the home directory for a requested user or the current user if no user is requested. When running under sudo, the home directory for the sudo user is returned.

Logging

• logger

  A wrapper around the Loguru logger with configurable log levels and custom styles. See the logging docs for more information.

Network

• network_available(address: str = "8.8.4.4", port: int = 53, timeout: int = 5) -> bool

  Check if a network connection is available.

Pretty Printing

The pretty printing module provides styled console output with configurable log levels and custom styles. See the pretty_print docs for more information.

• console

  A rich console object for styled console output.

• err_console

  A rich console object for styled console output to stderr.

• PrettyPrinter(Class)

  Styled console output with configurable levels and custom styles.

• print_debug(envar_prefix: str = None, custom: list[dict] = None, packages: list[str] = None, all_packages: bool = False) -> None

  Print debug information about the current environment.

Pytest Fixtures

The nclutils.pytest_fixtures module contains convenience functions and fixtures that are useful for testing. See the pytest_fixtures docs for more information.

• clean_stdout Clean the stdout of the console output by creating a wrapper around capsys to capture console stdout output.
• clean_stderr Clean the stderr of the console output by creating a wrapper around capsys to capture console stderr output.
• clean_stderrout Clean the stdout and stderr of the console output by creating a wrapper around capsys to capture both stdout and stderr output.
• debug Prints debug information to the console. Useful for writing and debugging tests.
• pytest_assertrepr_compare Patches the default pytest behavior of hiding whitespace differences in assertion failure messages. Replaces spaces and tabs with [space] and [tab] markers.

Questions

Convenience functions for working with the questionary library.

See the questions docs for more information.

• choose_one_from_list(choices: list[T] | list[tuple[str, T]] | list[dict[str, T]], message: str) -> T | None

  Presents a list of options to the user and returns a single selected option.

• choose_multiple_from_list(choices: list[T] | list[tuple[str, T]] | list[dict[str, T]], message: str) -> list[T] | None

  Presents a list of options to the user and returns a list of selected options.

Shell Commands

Convenience functions built on top of the sh module. See the shell_commands docs for more information.

• run_command(cmd: str, args: list[str] = [], quiet: bool = False, pushd: str | Path | None = None, okay_codes: list[int] | None = None, exclude_regex: str | None = None, sudo: bool = False, fg: bool = False) -> str

  Execute shell commands with proper error handling and output control.

• which(cmd: str) -> str | None

  Check if a command exists in the PATH. Returns the absolute path to the command if found, otherwise None.

Strings

• camel_case(text: str) -> str

  Convert a string to camel case. (hello world -> helloWorld)

• deburr(text: str) -> str

  Deburr a string. (crème brûlée -> creme brulee)

• kebab_case(text: str) -> str

  Convert a string to kebab case. (hello world -> hello-world)

• int_to_emoji(num: int, markdown: bool = False, images: bool = False) -> str

  Transform integers between 0-10 into their corresponding emoji codes or image representations. For numbers outside this range, return the number as a string with optional markdown formatting.

• list_words(text: str, pattern: str = "", strip_apostrophes: bool = False) -> list[str]

  Extract words from text by splitting on word boundaries and handling contractions. Optionally use a custom regex pattern for more control over word splitting. Handles apostrophes, underscores, and mixed case text intelligently.

  from nclutils import list_words
  
  print(list_words("Jim's horse is fast"))
  # ["Jim's", 'horse', 'is', 'fast']
  
  print(list_words("Jim's horse is fast", strip_apostrophes=True))
  # ['Jims', 'horse', 'is', 'fast']
  
  print(list_words("fred, barney, & pebbles", "[^, ]+"))
  # ['fred', 'barney', '&', 'pebbles']

• random_string(length: int) -> str

  Generate a random string of ASCII letters with the specified length.

• pad(text: str, length: int, chars: str = " ") -> str

  Pad a string with a character.

• pad_end(text: str, length: int, chars: str = " ") -> str

  Pad a string on the right side.

• pad_start(text: str, length: int, chars: str = " ") -> str

  Pad a string on the left side.

• pascal_case(text: str) -> str

  Convert a string to pascal case. (Hello World -> HelloWorld)

• separator_case(text: str, separator: str = "-") -> str

  Convert a string to separator case. (hello world -> hello-world)

• snake_case(text: str) -> str

  Convert a string to snake case. (hello world -> hello_world)

• strip_ansi(text: str) -> str

  Strip ANSI escape sequences from a string. (\x1b[31mHello, World!\x1b[0m -> Hello, World!)

• split_camel_case(string_list: list[str], match_case_list: tuple[str, ...] = ()) -> list[str]

  Split camel case strings into into separate words returning a list of words. Optionally, provide a list of strings that should not be split.

Text Processing

• replace_in_file(path: str | Path, replacements: dict[str, str], *, use_regex: bool = False) -> bool

  Replace text in a file with a dictionary of replacements.

  from nclutils import replace_in_file
  
  replacements = {"old": "new"}
  replace_in_file(path="test.txt", replacements=replacements)
  
  # Or use regex
  replacements = {"^old": "new"}
  replace_in_file(path="test.txt", replacements=replacements, use_regex=True)

• ensure_lines_in_file(path: str | Path, lines: list[str], *, at_top: bool = False) -> bool

  Ensure lines are in a file. If the lines are not present, they will be added to the file.

Utils

• check_python_version(major: int, minor: int) -> bool

  Check if the current Python version meets minimum requirements.

• format_iso_timestamp(datetime_obj: datetime, microseconds: bool = True) -> str

  Formats a given datetime object as an ISO 8601 timestamp, ensuring UTC formatting with a trailing Z.

• iso_timestamp(microseconds: bool = False) -> str

  Returns an ISO 8601 timestamp in UTC for the current time. (2024-03-15T12:34:56Z)

• new_timestamp_uid(bits: int = 32) -> str

  Generate a unique ID with a UTC timestamp prefix. (0240315T123456-kgk5mzn)

• new_uid(bits: int = 64) -> str

  Generate a unique ID with the specified number of bits. (kgk5mzn)

• unique_id(prefix: str = "") -> str

  Generate consecutive unique IDs with an optional prefix.

  from nclutils import unique_id
  
  print(unique_id())
  # 1
  print(unique_id("id_"))
  # id_2
  print(unique_id())
  # 3

Contributing

See CONTRIBUTING.md for more information.