-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
94 lines (56 loc) · 3.41 KB
/
README
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
scription
light-weight library to enhance command-line scripts; includes conversion of
parameters to specified data types, parameter checking, basic input/output with
users, support for suid [1], sending email, executing sub-programs, and having
sub-commands within a script
decorators
- Script: sets global variables and/or parameters for Commands; when used as
decorator, the decorated function will be called by Main/Run before any
specified Command
- Command: marks function as a subcommand for the script (e.g. add, delete,
list, etc.); if no subcommand is specified on the command-line, scription
will look for a Command with the same name as the script
- Alias: registers other names for Commands (e.g. delete / remove / kill)
functions
- Main: if the importing module's __name__ is __main__, call Run() (this
allows for importing the script as a module)
- Run: unconditionally attempts to run the Script function (if any) and the
Command found on the command-line
Main() or Run() should be the last thing in the script
classes
- Spec: can be used when defining the command-line parameters (can also just
use tuples)
helper functions/classes
- abort: quits immediately by raising SystemExit
- Execute: class for executing other programs; uses subprocess.Popen by
default, but if `pty=True` is specified then `pty.fork` will be used
(handy for programs that only accept input from a pty)
- get_response: function for displaying text and getting feedback
- help: quits immediately, but adds a reference to --help in the quit message
- log_exception: logs an exception with logging.logger
- mail: rudimentary mail sender
- OrmFile: lightweight orm -- supports str, int, float, date, time,
datetime, bool, and path (which defaults to str); custom data types can
also be specified
- print: wrapper around print that adds a 'verbose_level' keyword (default: 1);
default script verbosity is 0 (so print does nothing), but can be increased
using -v, -vv, --verbose, or --verbose=2 (in Python 2 the script must use
'from __future__ import print_function' to use scription's print)
- user_ids: context manager useful for suid scripts -- all actions taken
within the context are run as the user/group specified
- Exit: an enumeration of useful exit codes (scription uses Exit.ScriptionError
(63) if unable to parse the command line and run the script)
features
- extra parameters defined by Script are global, and can be accessed from any
function or Command
- 'module' is a namespace inserted into the script
- 'script_command' is the Command selected from the command line (useful when
one needs to call the subcommand directly from a main() function)
- 'script_command_name' is the name of the script_command
- 'script_verbosity' is the level of verboseness selected (defaults to 0)
- 'script_name' is the name of the script
- builtin options are: --help, --verbose (-v or -vv), --version, --all-versions
--version attempts to display the version of the main package in use
--all-versions attempts to display the versions of any imported packages
- command-line is decoded to unicode under Python 2 (Python 3 does this for us)
[1] I use the suid-python program, available at http://selliott.org/python/suid-python.c