Python Click Master Class

if you're starting out learning python as with any programming language console applications or terminal applications are going to be one of the main points of emphasis for you on one end of the spectrum you have the full graphical user interface applications of the type that you're very familiar with if you use a windows or a mac os pc closely related to gui applications or web applications which are growing more and more popular and depending on your age you might be more or less familiar with applications on the other end of the spectrum terminal user interface applications or tui applications as well as command line interface applications or cli applications and what tui or cli applications might lack in visual appeal they usually make up for it in terms of utility python has several packages and modules that facilitate the creation of console applications like tui and cli applications and one of these is click and that's what we'll be looking at today let's go ahead and get started i'm going to go ahead and start up my editor visual studio code visual studio code is free for download it's available for multiple platforms i'm going to start up screencast mode i'll go ahead and start up a new project folder as well let's call this one click since we're learning click [Music] and go ahead and start a new file main dot pi just to get things started off let's do a hello world i have the python extension installed so i'm going to use the main snippet just defining a main function and print hello world and that should work i'm going to open up the menu again we're going to run this python file in the terminal we should see hello world which we do how do we adapt this to click well it's pretty simple i'm going to go ahead and put an import statement at the beginning save right away we notice a problem uh import click has an error because i didn't install click before i install click i'm going to actually start up a new virtual environment so this is the recommended way of managing dependencies if you're starting a new python project where you're going to be installing packages and modules and such we don't want to clutter up our main python installation we want to manage that by putting all that stuff in a virtual environment so i actually consolidate all my virtual environments uh in a particular directory um here in the vm directory by the way i'm using powershell so if some of this syntax confuses you don't worry these steps will work exactly the same way if you like using bash or any other shell of your choice all right so i'm going to go ahead and start up a new virtual environment right here i'm going to call it click so what a virtual environment does is it installs a kind of secondary python installation on your computer um and you load it by using a command a lot like this we're going to do click scripts activate activate.ps1 because i'm using powershell so what that did it changed the prompt of my integra integrated terminal at the bottom there and basically if we run get command python now we can see if we run python in the integrated terminal right now it's actually going to run the python that's been installed in this directory all right now we're going to go ahead and install click click is installed we have one more step to go we've got to tell visual studio code to use this virtual environment instead of the main system python the default installation of python we can do that in one of two ways one way is we can click this down here where it shows you which interpreter you're using the python 3.8.5 and we can go into the file system and specify the virtual environment that we just created the python.xe will be in this folder in the scripts folder right next to the activate script once we do that we see that the import click statement no longer has the error the squiggly underline and we are good to go so how do we in how do we fully implement a hello world in click very simple we're going to attach a decorator to the main function and once again we're going to run it there we go let's continue to develop our example by parameterizing the world in hello world what i'd like to do is uh be able to pass in a name from the command line when i invoke this script i like to be able to pass in a name like jasper and have it say hello jasper rather than hello world how do we do that well this is one one area where click shines i'm going to add a second decorator here click.argument and i'm just going to specify the name of the variable that's going to contain the argument that we're going to pass in so we'll just put name so we specify it as a string up here and you know that's going to become the identifier of the actual variable that's passed into the into the function itself so we'll put name here and now we're going to uh change this to a formatted string and uh surround this with uh curly braces and put name in there um so now any any argument that we pass in from the command line in invocation of the script should be reproduced by uh should be should be placed within this formatted string and there we go we can add some additional functionality to our project here by um adding yet another decorator as you can tell click is big on decorators um we're going to specify an option and we're going to go ahead and you know specify a number option similar to the click argument this string is going to specify the name of the actual uh the identifier of the actual variable so we'll put in number in here in this case for option we actually need to specify a data type so type will be int all right and what we'll do with this number is that we'll put this into a loop that will repeat this message n number of times or number number of times all right so the invocation would be like this uh python main dot pi jasper dash dash number and we'll put three as we can see we can now specify an option from the command line and enhance our functionality with that option now one of the interesting things about click is that allows you to incorporate progressive help messages if we put ourselves in the shoes of an end user maybe they're not familiar with this script they could pass in the dash dash help parameter out of the box click tries to provide some sort of assistance on what you can do with the script all right so we have the dash dash number right here with the data type required and it also uh gives you some additional usage tips uh as far as what type of argument it's looking for so we can pass in options as well as an argument it did all this dynamically from the way that we actually constructed the script using these decorators so if we want to provide a more helpful uh message actually we can incorporate just a simple docstring so the first string that we specify within a function is known as a doc string and is typically done as a block as a block style dock string so if we put in help message over here save if we run the command again with dash dash help we can see the help message is actually provided so this is how we can incorporate progressive help at various levels if we have a very complex command line utility that we're designing we can incorporate this type of these type of help messages very easily we can actually do that with the options themselves not just the not just the functions but in line with for example this click.option we can attach a help message for example help message here if we run it again we can see that this string that we provided here shows up as a help message from this parameter this is how we can improve the end user's experience using our application all right we've developed this hello world example far enough let's go ahead and start a new file weather.pi and i'm going to go ahead and hide some of the extra stuff in the ui just so we can concentrate on the script a little bit more i'm going to compose something very similar to the hello world so another interesting thing is how do we implement enumeration functionality meaning how are we able to specify that the input from the user can only be of can only be certain values so we've we've managed to process an int input as well as a string but what if we only had specific values that we wanted to accept from a user well we can do that as i'm about to show you let's go ahead and implement an option this time the type is going to be click.choice okay click.choice will accept a list and we can specify uh all the all the available choices uh within these parentheses as members of the list we'll specify members including sunny rainy and snowy so we'll be describing weather the main function we need to take in those values and then we'll print a formatted string i love it when it when the weather is weather like that all right once we do that we'll open the integrated terminal again and we'll run weather.pi with sunny weather i think i forgot colon here i always forget that and we have double quotes here that's no good very sloppy but we finally got there i love it when the weather is sunny now what happens if we try to put something else in here like uh cloudy well we get an error because click is going to enforce that the input from the user can only be of certain types um if we ask for help at this level well we didn't incorporate a help message in the option but over here we can see that there are only specific values accepted for the weather option a final topic i'd like to cover before we end the video is command groups so with click we can also implement the functionality that you might have seen you might have seen on other command line utilities like git or net shell where various options and sub commands are available only to certain command groups so for example if we were to run uh git init and you know if you're not familiar with git it's the kind of standard version control software that's used across the software development industry i don't this isn't actually a git repo so i can double check that by running git status we can see it's not a git repository if i wanted to start one i could do one with git init i don't want to do with that at the moment but if it was a git repository i could then add files to the repository by using git add in various options and sub commands are available to each of these command groups and this is a way to organize functionality for complex command line utility suites we can actually implement this type of thing within click by using uh groups sometimes it can be kind of challenging to think of interesting toy scenarios for the purpose of learning for some of these more advanced topics but uh one i think i found something so what we're gonna do we're gonna have a kind of a restaurant script all right so we're gonna start very similarly to you know the scripts that we had before so this is pretty much how we started all of our other scripts okay but if we're going to implement groups if we're going to implement groups with click we need to have a discussion of what this entry point is and why it's why it's uh why it's important so this loop is basically how python separates functionality for modules which are imported versus scripts which are run uh you know on command interactively typically okay so what this does is if uh this module if this file is loaded as a main script meaning that the user end user wants to run this as a script then run the logic that's in the main uh in the main function that's been defined in the main function so basically this is called the entry point okay this is a kind of this is a concept in uh software development development more generally but in python it's kind of been calcified into this structure um so in if we're going to define command groups then we're actually going to change this main one and we're going to change the decorator up here so first thing we're going to do we're going to define this decorator as group and then we're going to change the name of the main function to cli we're gonna change that in both places so now the the entry point so let's pretend we're implementing a command line menu system for a restaurant okay um so restaurants typically serve the same dishes no matter the time of day lunch or dinner so we're going to implement a kind of toy implementation to see how we can organize commands into groups and how we can share the same command with more than one group so actually before we get to the commands we're going to do a subgroup we'll call this lunch we'll have another sub group both of these are using the klee object as a decorator we'll call this dinner and now what we'll do is we'll define a command to serve a burger now once we do this we're going to have to attach this command to both of these groups so basically this burger function will show up in both the dinner and lunch groups the way we do that we're going to call lunch dot add command we're going to pass it the burger function we're going to duplicate this line and do the same thing for dinner so now let's see what we come up with when we run this python restaurant.pie up we forgot a colon up here try it again click presents us with two command groups dinner and lunch if we repeat this with dinner we can see that we have the burger sub command available under the dinner group and we just ordered a burger for dinner now let's try lunch as we can see the same function shows up as a sub command for the lunch group and we had a burger for lunch as well now there is actually a second way to associate commands to command groups but i haven't figured out a way to get it to reuse the same function so let me show you what i mean so instead of click.command we're actually going to directly associate this with for example let's do lunch.com so you see i'm going to comment both of these lines out all right so before we were associating uh this burger function with the lunch command group down here with this method with the add underscore command method we were passing it that function but now we're going to directly associate it by decorating it with the group so now if we run it it should work but we won't be able to do we well let's see what let's see what happens all right so we're going to run this script again and we just to double check we decorate it with the lunch command so it should be available under lunch and there's a burger and let's order a burger and we can enjoy a burger now if we do dinner well first of all both lunch and dinner do appear but if we do dinner there's really nothing available now we can implement a second copy of the burger function if we save and then run this again now burger shows up and we can order a burger but one thing we cannot do is we cannot double up these decorators on the same function so if i take this and double decorate one of these and comment the other burger function out and attempt to run this we're going to get an error okay so unfortunately if you want to reuse the same the same function in more than one command group you're going to have to use this method which is well let's erase this uncomment it will change this decorator back to click and open up the terminal again and now we're able to order burgers for lunch or for dinner and for lunch so that's all i got for you today i appreciate the time out of your day that you provided to uh i appreciate the time that you've uh allotted to watching this video and i hope to see you soon thank you

Channel: Jasper Zanjani

Views: 6,995

Keywords:

Id: DO-QWK-o0jU

Length: 19min 24sec (1164 seconds)

Published: Sun Aug 30 2020