pyosplus 1.1.0

useful Python package based on os/os.path

pyosplus

This Python package provides several useful functions based on os/os.path:

• count_in_dir

• ext_files

• find_files_dirs

• inc_name

• write_dir_tree

These functions are really primitive but they happen to be used quite often by some people.

Please feel free to report any bugs.

Requirements

Python 3.10 or higher.

Installation

pip install pyosplus

(see https://pypi.org/project/pyosplus/)

Functions

count_in_dir

count_in_dir(
    directory: str,
    scan_subdirs: bool,
    ignored_exts: list[str] | str = [],
    ) -> tuple[int, int, dict]

Arguments

• directory: str
  Directory to scan.

• scan_subdirs: bool
  To scan subdirectories (True) or not (False).

• ignored_exts: list[str] | str = []
  Extension(s) of files to be ignored. Each extension should start with . (dot). Extension checks are always case-insensitive (e.g., ".jpg" is the same as ".JPG").

Returns

• tuple[int, int, dict]
  Number of directories, number of files, and dictionary with numbers of files with each found extension. Files with extensions ignored_exts are not counted.

Minimal Example

from pyosplus import count_in_dir
directory = "/path/to/dir"
scan_subdirs = True
num_dirs, num_files, ext_count = count_in_dir(directory, scan_subdirs)

---

ext_files

ext_files(
    directory: str,
    extensions: str | list[str],
    scan_subdirs: bool,
    ) -> list[str]

Arguments

• directory: str
  Directory to scan.

• extensions: str | list[str]
  Extension(s) of files to search. Each extension should start with . (dot). Extension checks are always case-insensitive (e.g., ".jpg" is the same as ".JPG").

• scan_subdirs: bool
  To scan subdirectories (True) or not (False).

Returns

• list[str]
  Sorted list of paths to files with extensions.

Minimal Example

from pyosplus import ext_files
directory = "/path/to/dir"
extensions = [".jpg", ".jpeg"]
paths = ext_files(directory, extensions)

---

find_files_dirs

find_files_dirs(
    what: str | list[str],
    where: str | list[str],
    where_not: str | list[str] = [],
    name_mode: str = "part",
    type_mode: str = "both",
    ignore_case: bool = True,
    ) -> Generator[str, None, None]

Arguments

• what: str | list[str]
  String(s) to search in names of files/directories.

• where: str | list[str]
  Path(s) to the directories where to search.

• where_not: str | list[str] = []
  Path(s) to the directories to exclude from search. They should be subdirectories of where.

• name_mode: str = "part"
"full" — what is the full name(s) of files/directories,
  "part" — what is the name part(s) of files/directories,
  "end" — what is the name end(s) of files/directories.

• type_mode: str = "both"
"both" — search among files and directories,
  "files" — search among files only,
  "dirs" — search among directories only.

• ignore_case: bool = True
  Ignore the case or not:
  True — "ABC" is equal to "abc",
  False — "ABC" is not equal to "abc".
  It works for what only. Paths in where and where_not should have the same case as in the system.

Returns

• Generator[str, None, None]
  Generator of paths to the found files/directories.

Minimal Example

from pyosplus import find_files_dirs
what = "thesis"
where = "/path/to/dir"
for path in find_files_dirs(what, where):
    print(path)

---

inc_name

inc_name(
    path: str,
    width: int = 2,
    sep_1: str = ".",
    sep_2: str = "",
    start: int = 2,
    use_ext: bool = True,
    ) -> str

Arguments

• path: str
  Path to file/directory to be incremented.

• width: int = 2
  Argument of zfill() to fill the counter with leading zeros.

• sep_1: str = "."
  Separator before the counter.

• sep_2: str = ""
  Separator after the counter.

• start: int = 2
  The counter first value.

• use_ext: bool = True
  If True, the counter will be put before the file extension.
  If False, the counter will be put at the end of string.
  The latter is for the directories with dot(s) in the names.

Returns

• str
  Incremented path if path already exists or path itself if it does not exist.

Minimal Example

from pyosplus import inc_name
path = "/path/to/file.txt"
inc = inc_name(path)

It returns:

• "/path/to/file.txt"
  if this file does not exist;

• "/path/to/file.02.txt"
  if "/path/to/file.txt" exists and "/path/to/file.02.txt" does not exist;

• etc.

---

write_dir_tree

write_dir_tree(
    directories: str | list[str],
    html_file: str,
    print_exts: bool = True,
    num_spaces: int = 4,
    shrunk_dirs: str | list[str] = [],
    shrunk_depth: int = -1,
    shrunk_text: str = " <...>",
    ignored_exts: str | list[str] = [],
    ignored_paths: str | list[str] = [],
    print_root: bool = True,
    print_hr: bool = True,
    )

Arguments

• directories: str | list[str]
  Directory/directories to scan.

• html_file: str
  Path to a new HTML file for output. If it exists, it will be overwritten.

• print_exts: bool = True
  Print file extensions (True) or not (False).

• num_spaces: int = 4
  Number of spaces for indentation.

• shrunk_dirs: str | list[str] = []
  Path(s) to the specific directories to be shrunk (i.e., collapsed) in HTML.

• shrunk_depth: int = -1
  The depth (i.e., hierarchy level) from which all the directories should be shrunk (collapsed) in HTML. The depth of directories equals 0. shrunk_depth = -1 means that no directories should be shrunk except those in shrunk_dirs (if any).

• shrunk_text: str = " <...>"
  The text to be put next to a shrunk directory name.

• ignored_exts: str | list[str] = []
  Extensions of files to be ignored in HTML. Such files will not be visible in HTML at all. Each extension should start with . (dot). Extension checks are always case-insensitive (e.g., ".jpg" is the same as ".JPG").

• ignored_paths: str | list[str] = []
  Paths to the directories/files to be ignored. Unlike the shrunk directories, ignored_paths will not be visible in HTML at all.

• print_root: bool = True
  Print a root directory (True) or not (False).

• print_hr: bool = True
  Print a horizontal line (True) or not (False).

Returns

• None. Writes a directory tree structure to html_file.

Minimal Example

from pyosplus import write_dir_tree
directories = ["/path/to/dir_1", "/path/to/dir_2"]
html_file = "tree.html"
write_dir_tree(directories, html_file)

---

write_html_dir_tree

Note: this function is deprecated and will be removed soon. Use write_dir_tree instead.

write_html_dir_tree(
    directory: str,
    html_file: str,
    num_spaces: int = 4,
    shrunk_dirs: str | list[str] = [],
    shrunk_depth: int = -1,
    shrunk_text: str = " <...>",
    ignored_dirs: str | list[str] = [],
    print_exts: bool = True,
    ignored_exts: str | list[str] = [],
    before: str = None,
    after: str = "",
    )

Arguments

• directory: str
  Directory to scan.

• html_file: str
  Path to a new HTML file for output.

• num_spaces: int = 4
  Number of spaces for indentation.

• shrunk_dirs: str | list[str] = []
  Path(s) to the specific directories to be shrunk (i.e., collapsed) in HTML.

• shrunk_depth: int = -1
  The depth (i.e., hierarchy level) from which all directories to be shrunk (collapsed) in HTML. The depth of directory equals 0. shrunk_depth = -1 means that no directories are shrunk except those in shrunk_dirs (if any).

• shrunk_text: str = " <...>"
  The text to be put next to a shrunk directory name.

• ignored_dirs: str | list[str] = []
  Paths to the directories to be ignored. Unlike the shrunk directories, ignored_dirs are not visible in HTML at all.

• print_exts: bool = True
  Print file extensions (True) or not (False).

• ignored_exts: str | list[str] = []
  Extensions of files to be ignored in HTML. Such files are not visible in HTML at all.

• before: str = None
  The text before tree structure, None means directory.

• after: str = ""
  The text after tree structure, None means directory.

Returns

• None; writes a directory tree structure to html_file.

Minimal Example

from pyosplus import write_html_dir_tree
directory = "/path/to/dir"
html_file = "tree.html"
write_html_dir_tree(directory, html_file)

Changelog

• Version 1.1.0 (2023-11-07):

  • function write_dir_tree added,
  • function write_html_dir_tree deprecated,
  • the default values of scan_subdirs in functions count_in_dir and ext_files removed.

• Version 1.0.0 (2023-11-05): initial release

---

pyosplus

• Version 1.1.0 (2023-11-07)

Copyright (c) 2023 Evgenii Shirokov

MIT License