cape.fileutils: Pure-Python file information utilities

This module provides several file utilities that mimic common BASH commands or programs, but written in pure Python to remove operating system dependencies.

class cape.fileutils.LatestRegex(fname, regmatch)

Output type containing latest file name and regex match instance

fname

Alias for field number 0

regmatch

Alias for field number 1

cape.fileutils.count_lines(fname: str) → int

Count lines in a file

Meant to mimic results of

$ wc -l $FNAME

but written in pure Python.

Call:
>>> n = count_lines(fname)
Inputs:
fname: str

Name of file to read

Outputs:
n: int

Number of lines in file

Versions:

  • 2024-07-15 @ddalle: v1.0

cape.fileutils.get_latest_file(filelist: list) → str

Get the latest modified file from a list of files

Call:
>>> fname = get_latest_file(filelist)
Inputs:
filelist: list[str]

List of file names

Outputs:
fname: str

Name of latest modified file in list

Version:

  • 2024-01-21 @ddalle: v1.0

cape.fileutils.get_latest_regex(pat: str, baseglob: str | None = None) → LatestRegex

Get the latest modified file matching a regular expression

Call:
>>> latest = get_latest_regex(pat, baseglob=None)
Inputs:
pat: str

Regular expression string

baseglob: {None} | str

Optional glob pattern to narrow candidates in current dir

Outputs:
latest: LatestRegex

Regex file-search instance

latest.fname: str

Name of latest modified file in list

latest.regmatch: re.Match

Regular expression groups, etc. for fname

Version:

  • 2024-03-24 @ddalle: v1.0

  • 2025-02-04 @ddalle: v1.1; add special output type

cape.fileutils.grep(pat: str, fname: str, nmax: int | None = None, encoding: str = 'utf-8') → list

Find lines of a file containing a regular expressoin

Call:
>>> lines = grep(pat, fname, nmax=None, encoding="utf-8")
Inputs:
pat: str

String of regular expression pattern

fname: str

Name of file to search

nmax: {None} | int

Optional maximum number of matches to find

encoding: {"utf-8"} | str

Encoding for file

Outputs:
lines: list[str]

List of lines containing a match of pat

Versions:

  • 2023-06-16 @ddalle: v1.0

  • 2024-07-30 @ddalle: v1.1; add nmax

cape.fileutils.head(fname: str, n=1, encoding='utf-8') → str

Get first n lines of a file

Call:
>>> txt = head(fname, n=1)
Inputs:
fname: str

Name of file to read

n: {1} | int

Number of lines to read from beginning of file

encoding: {"utf-8"} | str

Encoding for text file

Versions:

  • 2023-06-16 @ddalle: v1.0

cape.fileutils.readline_reverse(fb: IOBase) → bytes

Read line ending at current position

Call:
>>> txt = readline_reverse(fb)
Inputs:
fb: IOBase

File handle open for reading in binary mode

Outputs:
txt: bytes

Encoded text of last line

Versions:

  • 2024-07-26 @ddalle: v1.0

cape.fileutils.sort_by_mtime(filelist: list) → list

Sort list of files by modification time (ascending)

Call:
>>> tfiles = sort_by_mtime(filelist)
Inputs:
filelist: list[str]

List of file names

Outputs:
tfiles: list[str]

Files of filelist in order of ascending modification time

Version:

  • 2024-01-21 @ddalle: v1.0

cape.fileutils.tail(fname: str, n=1, encoding='utf-8')

Get last n lines of a file

Call:
>>> txt = tail(fname, n=1)
Inputs:
fname: str

Name of file to read

n: {1} | int

Number of lines to read from end of file

encoding: {"utf-8"} | str

Encoding for text file

Outputs:
txt: str

Text of last n lines of fname

Versions:

  • 2023-06-16 @ddalle: v1.0

cape.fileutils.touch(fname: str)

Replicate touch; creating new file or updating mod time

Call:
>>> touch(fname)
Inputs:
fname: str

Name of file to create/modify

Versions:

  • 2023-06-16 @ddalle: v1.0