Building Command Line Applications with Click

hello welcome to this instruction to building commands and applications with Kiki I'm going to show you how to build a simple hello world application and to show you the basic subject so let's get started the first thing we need to do is create a folder where we can do all working working so I'm just going to call this hello click and in this hello click folder I'm going to create the first ones so this are basically just apply virtual and p.m. on my virtual Emma fakirs in the VM folder so lesson it's in here and I kind of lead it by using a dot space and then V and can activate well so at this point my piping is another life as we expect so the first thing we need to do when we were thick well the click application is to create a proper piping package and we can do this by basically creating a setup the PI module which will install our application so let's do this so we pour some setup tools set up function and then we're going to keep our I don't forget your name so just going to fill this whole world and we get the version so this is basically the minimum requirements to install something and they're also going to define the pipe model to install so in this case we want to use like modules instead of alcohol piping package so we're just going to have a hello duck hi pal and that's going to be our our main module we want to install we also can instruct setup tools to install other things for us as dependencies so in this case we want the click is available and we're going to set up the entry points and the entry points is going to be basically an instruction for setup tools to to associate some additional metadata with our piping package some of this metadata can be used by the libraries some of the metadata is used by setup tools internally and this console scripts metadata is basically being used by setup tools to automatically create command and executables for us so we're going to do this here we are going to create one plan executable called hello and it's going to climb through the hello module and the CLI function so this is all we need to do to install a pet village if we would install it at this point it's going to tell us that the pipe module doesn't exist the header module doesn't exist so let's create this just going to create a function see right here and say hello world so if we run this now so if you keep install this it will install our application into our version the - - editable flag is useful because it will instruct it to use the current working directory we're instead of copying over all of them of the patent source code this means that as we do modifications on our code we don't need to reinstall it this I'm just going to use the current folder so it's going to download it from the internet and then it's going to install our hello world script at this point that is going to be hello executable and this basically is installed into our virtual end and it's going to import this module and execute the CLI function so let's replace the CLI function with a click it CLI function so all we have to do is import click and we mark this as clicked command so we don't do anything else at this point if we run it again it is exactly the same the difference however is that now it also responds to the search help it gives it an automatic help page this case it tells us the application called hello there are options available but the only option we have implemented such as help which is the default so let's add more options for instance we can have an option called string and this is going to be passed here and we can set the default here and so we set equal this world and then we do print hello string and if you run it again it says hello world but with the help page you'll see that it's not a swing available so you can do a string no town and it tells us how town now before we go any further I want to point out that obviously this print function here is functions of statement so this is obviously quite new to point X I'm using and the print I would say the print statement and the print function both of them have some problems with dealing with bytes in Unicode so click provides a function called echo which works much better with bytes in unicode and it will automatically print properly in however misconfigured your terminal is so you can use click aleppo which was pretty much the same thing as you can see it does the same thing but it automatic Andals flight engineer good for us and also it has the same behavior in Python 2 and Titan sorry so I would strongly recommend using click the deco instead of the print function whenever you buy to create a click of a vision so as you can see there is a help page available but this help page doesn't tell us much so let's fix this first the first thing we can use for adding help strings is the boxspring or not function just going to pull this this script reads well then if we run how help again you can see or help text appears here obviously there is no help text for this yet so let's do this on help text here goes with this help parameter you can say this is less then if you do help again we can see this place here what you can also see is that the parameter type is defined this text so this makes a lot of sense because in this case we have a string but let's add another one which is going to be 1/2 instance of repeated so you're going to call this repeat and say the default is 1 help is all many times circulated and this is always the fastest repeat and this is going to be an integer now and the reason is going to be an integer now is because the default is defined as an integer and click automatic derives the type of the parameter from the default value you can also be explicit by saying type and all the same effect I can still tie this float there will be a floating point value so let's do a 4x and let's run the pit okay go and if you go to the help page you can see it's not integer if you do repeat 3 it's going to print this 3 times if we've has an invalid value obviously they're going to get an error it's not a television one thing of note is that this option string here corresponds to the parameter here the only difference is if you have any dashes in it it will be converted to underscores here so that's adds and I looking here right now it always prints to standard output so let's make it print to an optional file and in this case we don't want to use an option we can use an argument arguments and options are similar the main difference is that an option is optional and it always starts with a - or a - - or another symbol those arguments come after options and they are sort of mandatory well they can become optional you can't have multiple options because otherwise it gets confusing us know which ones go to which but you can make them optional so in this case we're going to pull this argument out so we're going to write this into a certain file and be going to say that the type of this is is a click is a click type and its effect going to be a file type and we want to open this file for for writing I don't know what this means is that normally typed here would be a patent tab like int or string or something of that sort but it can also be a click type and click types a little bit more powerful and that they can customize a lot of of how click interacts with this value fences if you define it hard to be a click file type then click will automatically open this file false so we can directly write into this file and we can see this by printing this out so we can do click equals and we're going to see what it is now if you run the script again it's going to tell us that there's a missing argument out so let's add food at HD and we can see that there is an unopened file food txt past it's the first argument MSSD out argument click is very clever in how it handles these files you can also use a dash to indicate standard output we can see it opens send it out in utf-8 mode we can also set a default here so if you set the default to dash the argument has default but we also still need to set requires through a defaults required to false so because arguments by default are mandatory so if we now run the script again we can see it has open sent out by default one thing of note is that arguments cannot have helped text argument should be documented as part of the string and the reason for this is that it's very hard to automatic generate argument help text without being too limiting arguments are very specific unlike options and there usually are only one or two so this is this is how it should be used so if you want to document this you put into this string now we can use the click echo function say we want to rights to this file and instead of writing to stand it out it will automate to this file if necessary so if you do hello here it's going to write to standard out if you do food a tape Steve and it's going to write in the file through that 60 obviously we can also write into this file you need no way so this file will have fun instance a write method now one thing is important is that these files they open lazy by default which means that unless you actually start writing into this file the file will not be opened and this is useful because it means that click will not accidentally create files so if we make an error here let's say repeat would be 42 and you want to write in the file part of txt and we didn't make an error here because the palace values correct but let's say you would have written a non-integer here it will give me an error but it will not have Billa actually have opens the file so the file bar the THD doesn't exist so it will only be opened s you right into the file I can also show you this by removing the echo function there just means the pass so if we run this again with a correct value this time the file bar the txt has not been created because no writing into the finals happened twice if you actually write something into the file and you run it again Barbra keeps the actually exists what makes click very powerful is that command line applications can come back and contain some arguments so in this case if we look into our script we described is called hell and it except some options but we can also have soft arguments so let's change this UI to hold hello as it can record say and nothing has changed so far what are se like function is gone so if you would actually run this now it's going to error because there is no CLI I threw it so let's add a new one and we call this click that group in stats we are going to use the decorator click the proofing set click group works exactly I click command the difference is that any group can have sub commands and this can be done by instead of using click that commands here we're not going to see like months it's going to attach a soft mount directly to this here if you run this now we can see that there is a supplement available on this and this is going to work exactly as it before is also going to respond to help us this before but it's entirely nested below hello and now obviously there is some there's a function to this attached as well so the question is when does this function run because as we can see if we just run hello it gives me help age doesn't actually run this function here and this function here basically ever runs when a sub come on plans so we can say let's make an option here called the boss and it's passed here and the boss should enable the boss mode but it should not accept an argument so we make this a flag instead so once the flag is going to be false by default and when it's provided it's going to change it true or I can say if the balls click the leg bone we are in the boss mode and you can see this now because if you lose hello say it will little fun yeah because we are not in the boss mode so to say hello say but if we pass the verbose flag it will also run William doubles mode so as you can see these groups have the color back executed before any of the supplements of the club are executed the last thing I'm going to show you is how you can combine this here with this here so obviously this one runs before this one runs but the question is how does this one communicate any data to this function and the answer that this is basically to use the click context and for this to work we can create a helper class so we're just going to call this info instance or it's called company and this has to have an MD constructor and it can save the Possible's falls here that's all we need to do on this side and then we can use the click make pass decorator function which is going to create a decorator for us and we call this past conflict this will make a decorator which passes a config object to each of the click callbacks which is basically decorated with this decorator as a first argument so we can do a click has contact and it will now have a config object past we can do the same thing here I also have a contract request now what creates this conflict object the answer is at the moment nothing preset but we can make ensure it goes through and then in first usage this computer is going to be created so basically when this function is going to be called conflict is going to be in a new empty instance of this one and then as we call another one the object from here will also be passed to here so we can say conflict that will oppose equals or goes and then we can say if config levels click equal we are in the bowls mode and then as we run this again we are still in the boss mode but now the communication has gone from this function to the other one and this is a very useful concept because you can build very complex application displays for instance you can say you want to have an option here called home directory and this is going to be a click path I click path is similar to click file just is just a path name and we can say config that home directory is unmarked I'm noticing like this one and then if home directory is none home directory is the current directory and then we can say home directory is conflicted home directory so as we run this script say have a say the home doctor is the current folder we can say from Victoria is 10 so we can basically use we can move common arguments which are shared between all the sub argument as subscripts to the top level script and this is similar to how get for instance works so if you look at get itself it except some arguments for the gate command itself in this case it accepts for instance a work three argument it accepts an HTML path and hold on bunch of other things but then it accepts a command and command itself accepts more arguments and this exactly the same way how you would build this in wiki and that's all you have to know for start and I hope you can build some very cool applications was clicked this way

Channel: Armin Ronacher

Views: 126,939

Keywords: Command-line Interface (Computing Platform), Click, Python (Software), Software (Industry)

Id: kNke39OZ2k0

Length: 18min 18sec (1098 seconds)

Published: Sat May 24 2014