1.. _guide-quickref: 2 3Quick reference guide 4--------------------- 5 6This is a cheatsheet for common tasks in Plumbum. 7 8CLI 9=== 10 11Optional arguments 12****************** 13 14================ ========================= 15Utility Usage 16================ ========================= 17``Flag`` True or False descriptor 18``SwitchAttr`` A value as a descriptor 19``CountOf`` Counting version of ``Flag`` 20``@switch`` A function that runs when passed 21``@autoswitch`` A switch that gets its name from the function decorated 22``@validator`` A positional argument validator on main (or use Py3 attributes) 23================ ========================= 24 25 26Validators 27********** 28 29Anything that produces a ``ValueError`` or ``TypeError``, is applied to argument. Some special ones included: 30 31======================= ========================= 32Validator Usage 33======================= ========================= 34``Range`` A number in some range 35``Set`` A choice in a set 36``ExistingFile`` A file (converts to Path) 37``ExistingDirectory`` A directory 38``NonexistentPath`` Not a file or directory 39======================= ========================= 40 41Common options 42************** 43 44================== ============================ ================== 45Option Used in Usage 46================== ============================ ================== 47First argument Non-auto The name, or list of names, includes dash(es) 48Second argument All The validator 49docstring ``switch``, ``Application`` The help message 50``help=`` All The help message 51``list=True`` ``switch`` Allow multiple times (passed as list) 52``requires=`` All A list of optional arguments to require 53``excludes=`` All A list of optional arguments to exclude 54``group=`` All The name of a group 55``default=`` All The default if not given 56``envname=`` ``SwitchAttr`` The name of an environment variable to check 57``mandatory=True`` Switches Require this argument to be passed 58================== ============================ ================== 59 60 61Special member variables 62************************ 63 64====================== ===================================== 65Utility Usage 66====================== ===================================== 67``PROGNAME=`` Custom program name and/or color 68``VERSION=`` Custom version 69``DESCRIPTION=`` Custom description (or use docstring) 70``DESCRIPTION_MORE=`` Custom description with whitespace 71``ALLOW_ABREV=True`` Allow argparse style abbreviations 72``COLOR_USAGE=`` Custom color for usage statement 73``COLOR_USAGE_TITLE=`` Custom color for usage statement's title 74``COLOR_GROUPS=`` Colors of groups (dictionary) 75``COLOR_GROUP_TITLES=`` Colors of group titles (dictionary) 76====================== ===================================== 77 78Paths 79===== 80 81================= ============================= 82Idiom Description 83================= ============================= 84``local.cwd`` Common way to make paths 85``/`` Construct Composition of parts 86``//`` Construct Grep for files 87Sorting Alphabetical 88Iteration By parts 89To str Canonical full path 90Subtraction Relative path 91``in`` Check for file in folder 92================= ============================= 93 94.. 95 The main difference is the loss of relative files 96 97=================================================== =========================== ================== 98Property Description Compare to Pathlib 99=================================================== =========================== ================== 100``.name`` The file name ✓ 101``.basename`` DEPRECATED 102``.stem`` Name without extension ✓ 103``.dirname`` Directory name ✗ 104``.root`` The file tree root ✓ 105``.drive`` Drive letter (Windows) ✓ 106``.suffix`` The suffix ✓ 107``.suffixes`` A list of suffixes ✓ 108``.uid`` User ID ✗ 109``.gid`` Group ID ✗ 110``.parts`` Tuple of ``split`` ✓ 111``.parents`` The ancestors of the path ✓ 112``.parent`` The ancestor of the path ✓ 113=================================================== =========================== ================== 114 115.. 116 Missing: 117 .anchor 118 119 120 121=================================================== =========================== ================== 122Method Description Compare to Pathlib 123=================================================== =========================== ================== 124``.up(count = 1)`` Go up count directories ✗ 125``.walk(filter=*, dir_filter=*)`` Traverse directories ✗ 126``.as_uri(scheme=None)`` Universal Resource ID ✓ 127``.join(part, ...)`` Put together paths (``/``) ``.joinpath`` 128``.list()`` Files in directory ✗ (shortcut) 129``.iterdir()`` Fast iterator over dir ✓ 130``.is_dir()`` If path is dir ✓ 131``.isdir()`` DEPRECATED 132``.is_file()`` If is file ✓ 133``.isfile()`` DEPRECATED 134``.is_symlink()`` If is symlink ✓ 135``.islink()`` DEPRECATED 136``.exists()`` If file exists ✓ 137``.stat()`` Return OS stats ✓ 138``.with_name(name)`` Replace filename ✓ 139``.with_suffix(suffix, depth=1)`` Replace suffix ✓ (no depth) 140``.preferred_suffix(suffix)`` Replace suffix if no suffix ✗ 141``.glob(pattern)`` Search for pattern ✓ 142``.split()`` Split into directories ``.parts`` 143``.relative_to(source)`` Relative path (``-``) ✓ 144``.resolve(strict=False)`` Does nothing ✓ 145``.access(mode = 0)`` Check access permissions ✗ 146=================================================== =========================== ================== 147 148.. 149 Missing: 150 .match(pattern) 151 .is_reserved() 152 .is_absolute() 153 .as_posix() 154 .is_symlink() 155 .is_fifo() 156 .is_block_device() 157 .is_char_device() 158 .lchmod(mode) 159 .lstat() 160 161=================================================== =========================== ================== 162Method (changes files) Description Compare to Pathlib 163=================================================== =========================== ================== 164``.link(dst)`` Make a hard link ✗ 165``.symlink(dst)`` Make a symlink ``.symlink_to`` 166``.unlink()`` Unlink a file (delete) ✓ 167``.delete()`` Delete file ``.unlink`` 168``.move(dst)`` Move file ✗ 169``.rename(newname)`` Change the file name ✓ 170``.copy(dst, override=False)`` Copy a file ✗ 171``.mkdir()`` Make a directory ✓ (+ more args) 172``.open(mode="r")`` Open a file for reading ✓ (+ more args) 173``.read(encoding=None)`` Read a file to text ``.read_text`` 174``.write(data, encoding=None)`` Write to a file ``.write_text`` 175``.touch()`` Touch a file ✓ (+ more args) 176``.chown(owner=None, group=None, recursive=None)`` Change owner ✗ 177``.chmod(mode)`` Change permissions ✓ 178=================================================== =========================== ================== 179 180.. 181 Missing: 182 .group() 183 .owner() 184 .read_bytes() 185 .write_bytes() 186 .replace(target) 187 .rglob(pattern) 188 .rmdir() 189 .samefile() 190 191Colors 192====== 193 194 195You pick colors from ``fg`` or ``bg``, also can ``reset`` 196 197Main colors: ``black`` ``red`` ``green`` ``yellow`` ``blue`` ``magenta`` ``cyan`` ``white`` 198 199Default styles: ``warn`` ``title`` ``fatal`` ``highlight`` ``info`` ``success`` 200 201Attrs: ``bold`` ``dim`` ``underline`` ``italics`` ``reverse`` ``strikeout`` ``hidden`` 202