1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
.. _guide-quickref:
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_USAGE_TITLE=`` Custom color for usage statement's title
``COLOR_GROUPS=`` Colors of groups (dictionary)
``COLOR_GROUP_TITLES=`` Colors of group titles (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
================= =============================
..
The main difference is the loss of relative files
=================================================== =========================== ==================
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 ✓
=================================================== =========================== ==================
..
Missing:
.anchor
=================================================== =========================== ==================
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 ✗
=================================================== =========================== ==================
..
Missing:
.match(pattern)
.is_reserved()
.is_absolute()
.as_posix()
.is_symlink()
.is_fifo()
.is_block_device()
.is_char_device()
.lchmod(mode)
.lstat()
=================================================== =========================== ==================
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 ✓
=================================================== =========================== ==================
..
Missing:
.group()
.owner()
.read_bytes()
.write_bytes()
.replace(target)
.rglob(pattern)
.rmdir()
.samefile()
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``
|
