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