Getting started#

Installation#

Prefer pip?

pyufunc can be installed via pip from PyPI.

pip install pyufunc
In-depth instructions?

Installing a specific version? Installing from source? Check the advanced installation page.

Learn more

Intro to pyufunc#

pyufunc is a Python package that collects small helper functions for common programming tasks. These helpers cover areas such as string cleanup, list processing, date and time conversion, path and file handling, testing helpers, image utilities, and selected wrappers around third-party packages.

Most functions are available directly from the top-level package:

import pyufunc as pf

cleaned_text = pf.str_strip("  Hello     Python   ")
print(cleaned_text)

You can think of pyufunc as a toolbox. You still choose the tool that fits your task, but pyufunc gives you one place to look for common helpers.

Tutorials#

These tutorials are written for entry-level Python users. Each example can be copied into a Python file and run from the terminal.

If you are new to Python packages, start with this pattern:

  1. Install the package with pip.

  2. Import the package in Python.

  3. Call one function.

  4. Save the return value in a variable or print it.

Tutorial 1: install, import, and check the version#

Install pyufunc from PyPI:

pip install pyufunc

Create a file named my_first_pyufunc.py and add:

import pyufunc as pf

print(pf.__version__)

Run the file:

python my_first_pyufunc.py

If Python prints a version number, pyufunc is installed and ready to use.

Tutorial 2: find a function before using it#

pyufunc contains functions in different categories. You can inspect those categories from Python.

import pyufunc as pf

categories = pf.show_util_func_by_category(verbose=False)

print(categories.keys())
print(categories["util_data_processing"][:5])

You can also search by a word in the function name:

import pyufunc as pf

time_functions = pf.find_util_func_by_keyword("time", verbose=False)
print(time_functions)

Use this when you know the task, such as working with time, files, paths, or lists, but do not know the exact function name yet.

Tutorial 3: clean text and convert simple values#

This example starts with messy text and a number stored as a string.

import pyufunc as pf

message = "  Hello     Python   "
clean_message = pf.str_strip(message)

user_input = "42.9"
user_number = pf.str_digit_to_int(user_input)

print(clean_message)
print(user_number)
print(pf.is_float("3.14"))

Expected output:

Hello Python
42
True

This is useful when reading values from forms, text files, spreadsheets, or command-line input.

Tutorial 4: convert text into a date and time#

Dates often begin as text, especially when they come from a CSV file or user input. fmt_str_to_dt converts a text value into a Python datetime object.

import pyufunc as pf

meeting_time = pf.fmt_str_to_dt("2026-05-28 09:30:00")

print(meeting_time.year)
print(meeting_time.month)
print(meeting_time.day)
print(meeting_time.hour)

Expected output:

2026
5
28
9

After conversion, you can use normal Python date and time attributes such as year, month, day, and hour.

Tutorial 5: work with files safely#

This example creates a small text file, checks whether it exists, and asks pyufunc for a safe filename to use if another file with the same name already exists.

from pathlib import Path

import pyufunc as pf

note = Path("tutorial_note.txt")
note.write_text("hello", encoding="utf-8")

print(pf.check_filename(note))

safe_name = pf.generate_unique_filename(note)
print(safe_name.endswith("tutorial_note(1).txt"))

note.unlink()

Expected output:

True
True

The last line, note.unlink(), deletes the small tutorial file after the example runs.

Tutorial 6: split and flatten lists#

Lists are one of the most common Python data structures. pyufunc includes helpers for list cleanup and grouping.

import pyufunc as pf

nested_numbers = [[1, 2], [3, 4], [5]]
flat_numbers = pf.list_flatten_nested(nested_numbers)

groups = list(pf.list_split_by_fixed_length(flat_numbers, fixed_length=2))

print(flat_numbers)
print(groups)

Expected output:

[1, 2, 3, 4, 5]
[[1, 2], [3, 4], [5]]

Tutorial 7: understand optional dependencies#

pyufunc does not automatically install missing optional packages. This avoids unexpected package installation in CI, offline, or security-sensitive environments.

Some helper functions wrap third-party packages. If the package is not installed, install it yourself before using that helper.

import pyufunc as pf

humanize = pf.import_package("humanize")

if humanize is None:
    print("Install the optional package with: pip install humanize")
else:
    print(pf.human_file_size(1536))

This pattern is useful when sharing code with other users because it gives a clear message when an optional package is missing.

Next steps#

  • Use API reference when you want the full list of public functions.

  • Use util_pkgs when you want helpers that wrap selected third-party utility packages.

  • Use the GitHub issue tracker to report unclear documentation or request a tutorial for a specific task.