Random Command Line and Docstrings

00:00 In the previous lesson, I showed you some changes to the typing system. In this lesson, I’ll explain the new command-line interface to the random module and how docstrings have changed.

00:10 Several of the modules in the standard library can be invoked directly on the command line using the -m argument. My favorite is json.tool, which does JSON pretty printing.

00:21 This release has added direct invocation of the random module. This can be handy if you desperately need a random value on the command line or if you want some randomness in a shell script. Off to the terminal once more to see this in practice.

00:37 As I mentioned, you get at this feature by using the -m argument to Python, passing it the name of the random module. After that, any arguments you pass determine what kind of random generation happens. Without any flags, the default behavior is to randomly choose one of the arguments passed in.

01:01 This has chosen the word “two” from one, two, three, and “four five.” Note how I’ve used quotes around “four five.” That’s not a Python thing, but a shell thing.

01:12 Normally, spaces indicate a new argument, but if you surround it in quotes, the string gets treated as a single argument. So if I just run it enough times, I get “four five” as my random answer.

01:30 If instead of a list of strings you pass in an integer, the module generates a random number between one and that integer. This is essentially a command-line front to the randint() function in the module.

01:44 Giving it a float

01:49 generates a floating-point number. The release candidate I’m using actually has a bug in it where the float is between one and the number, like as in randint(), but it’s supposed to be changed to zero as when you’re doing floats that’s typically what’s expected.

02:04 You can also be explicit about which kind of behavior you want by using additional command-line flags.

02:15 The --choice flag chooses one of the values passed in.

02:22 The --integer flag causes integer behavior,

02:29 and the --float flag does a float. Using explicit flags is helpful if you want to be clear about what you’re doing or say you want to be lazy and just type two to get a random float less than two.

02:42 If your code is indented, which of course it is, it looks funny for the docstring that goes with it to not be indented, but indenting the docstring means the output is indented.

02:53 Well, not anymore. Python 3.13 automatically removes the spaces in your docstrings that line them up with your code. Note that this is a breaking change if you happen to test something in your docstrings, this is different. Let’s head to the REPL to see the new feature. In the upper window, I have cat.py and lines two through eight have the docstring for the Tiger class.

03:19 Now in the lower window, I’ve got a two-line program that imports Tiger and prints out its docstring. Let me run this in 3.12.

03:34 Note how the docstring is indented to match the code above. Well, with the new release,

03:43 it has been shifted left. Let’s do this again with a messier case.

03:52 Note how the first line of the docstring for Wolf is flush with the triple quotes. And also note how lines five through nine are indented to match the quotes. I’ve got a print_dog_doc() that does the same as print_cat_doc(), essentially printing out the docstring for this class.

04:08 Let me call that on the command line. In Python 3.12,

04:15 line three is flushed left, while lines five through nine are indented once. Now, instead in Python 3.13,

04:27 it all gets flushed left. The algorithm that looks for indentations to trim ignores the first line. So if you are flush with the triple quotes like in line three, it still sees the indentations in lines five through nine and compensates for them.

04:44 The copy module has a new replace() function. That’s what’s next.