Quick reference guide

This is a cheatsheet for common tasks in Plumbum.

CLI

Optional arguments

Utility

Usage

Flag

True or False descriptor

SwitchAttr

A value as a descriptor

CountOf

Counting version of Flag

@switch

A function that runs when passed

@autoswitch

A switch that gets its name from the function decorated

@validator

A positional argument validator on main (or use Py3 attributes)

Validators

Anything that produces a ValueError or TypeError, is applied to argument. Some special ones included:

Validator

Usage

Range

A number in some range

Set

A choice in a set

ExistingFile

A file (converts to Path)

ExistingDirectory

A directory

NonexistentPath

Not a file or directory

Common options

Option

Used in

Usage

First argument

Non-auto

The name, or list of names, includes dash(es)

Second argument

All

The validator

docstring

switch, Application

The help message

help=

All

The help message

list=True

switch

Allow multiple times (passed as list)

requires=

All

A list of optional arguments to require

excludes=

All

A list of optional arguments to exclude

group=

All

The name of a group

default=

All

The default if not given

envname=

SwitchAttr

The name of an environment variable to check

mandatory=True

Switches

Require this argument to be passed

Special member variables

Utility

Usage

PROGNAME=

Custom program name and/or color

VERSION=

Custom version

DESCRIPTION=

Custom description (or use docstring)

DESCRIPTION_MORE=

Custom description with whitespace

ALLOW_ABREV=True

Allow argparse style abbreviations

COLOR_USAGE=

Custom color for usage statement

COLOR_GROUPS=

Colors of groups (dictionary)

Paths

Idiom

Description

local.cwd

Common way to make paths

/ Construct

Composition of parts

// Construct

Grep for files

Sorting

Alphabetical

Iteration

By parts

To str

Canonical full path

Subtraction

Relative path

in

Check for file in folder

Property

Description

Compare to Pathlib

.name

The file name

.basename

DEPRECATED

.stem

Name without extension

.dirname

Directory name

.root

The file tree root

.drive

Drive letter (Windows)

.suffix

The suffix

.suffixes

A list of suffixes

.uid

User ID

.gid

Group ID

.parts

Tuple of split

.parents

The ancestors of the path

.parent

The ancestor of the path

Method

Description

Compare to Pathlib

.up(count = 1)

Go up count directories

.walk(filter=*, dir_filter=*)

Traverse directories

.as_uri(scheme=None)

Universal Resource ID

.join(part, ...)

Put together paths (/)

.joinpath

.list()

Files in directory

✗ (shortcut)

.iterdir()

Fast iterator over dir

.is_dir()

If path is dir

.isdir()

DEPRECATED

.is_file()

If is file

.isfile()

DEPRECATED

.is_symlink()

If is symlink

.islink()

DEPRECATED

.exists()

If file exists

.stat()

Return OS stats

.with_name(name)

Replace filename

.with_suffix(suffix, depth=1)

Replace suffix

✓ (no depth)

.preferred_suffix(suffix)

Replace suffix if no suffix

.glob(pattern)

Search for pattern

.split()

Split into directories

.parts

.relative_to(source)

Relative path (-)

.resolve(strict=False)

Does nothing

.access(mode = 0)

Check access permissions

Method (changes files)

Description

Compare to Pathlib

.link(dst)

Make a hard link

.symlink(dst)

Make a symlink

.symlink_to

.unlink()

Unlink a file (delete)

.delete()

Delete file

.unlink

.move(dst)

Move file

.rename(newname)

Change the file name

.copy(dst, override=False)

Copy a file

.mkdir()

Make a directory

✓ (+ more args)

.open(mode="r")

Open a file for reading

✓ (+ more args)

.read(encoding=None)

Read a file to text

.read_text

.write(data, encoding=None)

Write to a file

.write_text

.touch()

Touch a file

✓ (+ more args)

.chown(owner=None, group=None, recursive=None)

Change owner

.chmod(mode)

Change permissions

Colors

You pick colors from fg or bg, also can reset

Main colors: black red green yellow blue magenta cyan white

Default styles: warn title fatal highlight info success

Attrs: bold dim underline italics reverse strikeout hidden