 Hello everybody, welcome to the afternoon sessions at Europe height in 2014. My name is Stefan deal. I'm member of the local Python user group and Please welcome Felix week. He will talk about how to set up a new point project Thanks and welcome to my talk. So As we already heard so this will be about how to set up a new Python project So this will be quite often introductory talk, but there might also be a few interesting tweaks for Maybe more advanced Python users. So it might also be interesting for them So what to do when you start a new Python project? So the first thing you you need to do is you want to start implementing But before you can start implementing you have to set up all that stuff So you you just have all your ideas together, you know, which Packages you want to use and everything but first of all you have to do the boring stuff before you can really start coding and What you usually need first is you need an environment so You might have on Python interpreter installed on your system and the site packages on your system But you usually have several projects and not just one so you need some kind of tool to to manage the different projects and the different dependencies which you might have and you just need Let's say project specific environment for you for all your different projects and their virtual Enf is a is a really cool tool to do that and You can just use pip to install all your stuff there. So first of all a few words about virtual Enf So as I said, this is just a tool to create an isolated Python environment And what I mean with isolated is that you get an own Python interpreter for each of your projects And you get an own site packages for each of your projects. So the only thing you need to have to install it is you You just yeah, you just need to have virtual Enf on your on your global let's say Global Python interpreter package. So you just install it via pip Or the sources and then you can create a new virtual environment by just typing in virtual Enf And then the name of the virtual environment. It's just as easy as that and this then directly comes with with setup tools and pip installed into your new into your new virtual environment and You can then there's a small helper script Activate which you can use to just add your new virtual Enf to your to your path variable. So That means you can when you when the type pipe install of something else afterwards It just gets installed to your virtual environment For example and to get out of it You just type deactivate and then you can directly jump to another virtual environment if you Work on different projects at the same time. So this is really a very good tool for that So then a few words about pip. So you probably all of you know it, but so this is just a tool to install and manage all your packages and It offers installation from the package index if it's a local or global Or source or binary distribution. So whatever you have. So For example to get to get an install the latest version of a package in this case I just chose the package py scaffold which you will learn about in a few minutes From the public py PI you just type in pip install py scaffold. So this you have done very often I think so but it gets more interesting if you have something like Versions of your packages which you which you are which are different in your different projects, for example So then you can use the requirements specifiers in pip install. So for example here you just Take only versions which are higher than 0.7 or equal 0.7 So and what's even nicer is that you can also use just a whole requirement file to To get all your all your dependencies in once. So you just use this minus r option and you do all your Requirements you just type them in in your package in your file requirements txt for example So if you then afterwards type in pip freeze, you see what you have installed. So in this case It's just py scaffold and a few other things you will see it later in the truck demonstration So okay, so now you have your your environment. So you can really start with your project So what what you need to do to organize it? So the first thing is you need of course a version control system. So this you need all the time and For this talk and for the demonstration later. I just use git because I think this is a good choice But there are a lot of other good tools also So and after you have this this set up So this is another thing which you have to do then you need the reasonable Directory structure and you need of course tests and documentation So these are also things which you have to take care that they have a good folder structure for it And that you have to the right tools and so on and so on So what is a good directory structure for it? So first of all if you are a few words about what I mean in the in the following with module and package So module is nothing ends then a file containing Python code So something which with the dot pi ending for example and a package This is a this is a folder which Contains an in a pie file and all of your other Python modules which you want to have in this package So in this case you have the you have the package my package Which is in a bro check which has the same name So this is usually a good practice that you would just name your project after your package or vice versa and In this my package you have this in a pie file. So this just does in principle that you can import all the stuff with the Inside of your directory structure and you have your your modules in which do the actual stuff So your actual implementation in what you'll want and what you'll do in this case And you might also have some pack the sub packages in if you are doing different things in your package And then in each of your sub package sub packages. There's another in a pie file that you can import All that stuff afterwards properly So this is the first step. So and then you need to test the tests and the documentation So this usually should go to separate folders So which I just call here tests for the unit tests and docs for for example is things documentation and inside your tests tests folder you should have another in a pie file and You should have all your for each of your modules You should have a separate test module which just starts with the with test underscore and then the module name So then you have it really in a ordered way And you know what belongs to what and you can start afterwards the test with For example set up tools or whatever. So this will you will see in a moment So in a docs folder, you have all your restructured text text files for example So this might be this index RST, which is the more or less index HTML of Sphinx And you might have a configuration pie and a make file if you have first things set up beforehand and There's also another file which is called setup pie about which I will also talk in a few minutes So or actually even now so how is your the next step if you you have then implemented everything have everything in order And what you need to do then is you you want to To to tell the stuff to other people so you want to distribute it in some way so how to do that so the Python comes with with an On-board tool, which is called this details. So this this is actually this Basically the setup pie, which I which I showed you so but there's also something called setup tools, which you heard in the Which is which comes with ritual and so which is more or less just an extension of this of this duty So usually I would just recommend to you set up tools then you have all this stuff inside and There might also be referred might also of distribute. So this is another thing which is Something in between so this was kind of a fork of setup tools, but it's more or less an older version. So Just you set up tools or just you tools if you don't want The additional features Okay, then if you have your package everything in order and you want to install it now in your virtual nth So then you just type in Python setup by install and this installs every Everything which you have just implemented into your virtual environment And what is helpful during development is this setup by develop command Because then there were just links created in your site packages in in your virtual environment And this means that if you change something in your source code implementation, then it directly changed the installation in the virtual environment otherwise, you would have to type in pip install Python setup by install again afterwards you have Changed something Okay And if you want to pack it and ship it then you can just use the setup by estus or set up by edis commands So this means a source distribution or a binary distribution So per default this will be a zipped tar ball and for the binary distribution This is of course dependent on the machine. So this we will also see later in the demonstration Okay, so now we have done all this stuff So but if you want to ship something to somebody then you have to give it a version because afterwards you have will then have a new version a few weeks later a few months later and then One was maybe one oh point zero and some at some time you have a one point zero or something So you need to update that version stuff all the time so that means you need to update the version attribute of your package or module and You need to to to get the self identification in the in a pie file and you need to update an argument in this in in setup by itself That so a meta information of the setup by that you just have the right name for your package And also have the the right thing in them for the meta information for the PI PI server for example And this is really cumbersome to do this manually because then if you really have to do this all the time You will forget it and then you will have to do it again So you need something which is just dust is automatically for you and what is is a cool small tool is this version your package So this this manages just the versions by git So this means that you can just do a git tag if you want to release so you just the git tag version 0.0 and Afterwards you directly have the right version number and if you then do an s-test or a b-test Then you directly have the the version of your last get tech So this is really cool. What makes it really simple Okay, so this would be the let's say base basic behavior of of the setup pie and if you then want to do your tests and your documentation also with setup pie so That that comes with what are for you for the unit test package It comes on board So you just type pies and set up by test and it runs all your tests in your test folder if you have Set up your setup pie correctly. It just runs them all through with unit test So maybe you want to to use pies the pie test instead because Unit test is okay, but maybe you want to do coverage or something else so then there's the possibility to have in in setup pie this Command class argument so there you can just define your own command classes Let's say where you can use then pie test instead of unit test for example And just run it with setup pie test or you want to do something like pie flakes or whatever So you can just do everything you want within set up a set up high and What is a quite good thing to do for example is to run the documentation by it so you overwrite your command this command class thing and Then you can for example do set up by docs and you just run your documentation with with set up by itself Otherwise you would have to type in all the type make item a html or something like that Okay, so now I have talked a lot about setup pie. So you'll see a bit of this boring code now so in this case I just imported from setup tools the setup function, which is basically what is in there and a small helping function find packages and What is really the the basic of this of this setup function is the name and the version? So this is also what your package will be called afterwards So your tarpaul for example if you're doing as test and You need to to tell them why are packages what has to be included in the distribution? So and there you can for example use this find packages where you include everything But just exclude the test folders for example and this install requires this is This is testing in beforehand before you install your package if all the stuff is already there And if it's not there it would install it afterwards wires are easy install But as we have already done it beforehand with with our pip requirements file We can also at this position just use the requirements file for example And we have it also again in one in one place. Yes, you will also see later So the test suit this is just a test which need to be run by the by our set up by test command as we have already seen and What is a nice functionality is this entry points? So there in this in our package my package which we had before there was this module one and inside this module one There might be a function run and this function run gets maybe some arguments and you can just if you if you Set it up this way You can just afterwards in the on the command line type run and then the options of this and then you just run This functions rule so this is an interesting thing if you for example want to start a web server or whatever just why are you? Why are this entry point? Okay, so to To set up a Python project you you need to do quite a few things So you need to think about a good project structure You have to set up a git repository or something or another version control system you have to To do all the tweaks with your setup pie So there are a lot of a lot more commands than the ones I've shown you you have to take care of the versioning and everything So all this stuff is Is pretty let's say tough if you if you are a new Python user or at least borrowing if you if you are experienced So you don't want to do this all the time again. So There this was the case also for us when we when we did this over and over again for small projects So this was why we just implemented a small tool, which is called by a pie scaffold Which just does this for you. So you can just install it via PI PI. So if you install Pie scaffold and the sources are available on GitHub so and it only requires virtual and and git to be installed on your system and setting up a project is then just as simple as Put up my project afterwards and then you will have everything. So Now I just give you a small a short demonstration So let's say we we want to have a virtual environment first So already done. So now we have a virtual environment in our directory So we saw that we have to to activate it. So now it's activated it changed The prompt which you which you also saw in the slides. So now what do we want to do? We want to just install by scaffold and if the network works This will do it. Okay done. So Check what we have inside our virtual environment. So that pie scaffold is there in the version 0.7 at the moment. So now we need a new project so Just put it up already done. So then we have our project folder my project Inside there we have now For example, this setup pie. We have the The project folder my project. We have our test folder and our documentation folder So for example, we look into test. There's only the init pion Also in my project. So there's there's another thing this version and version your pie This comes from version year. So don't have to go into details about that. So you don't need to care about it usually So and then we have this requirements file for example So there you could now put all your requirements. For example, there would be an umpire or scipy environment and This manifest in is also something which you which you might know This is about a stist. So this is a kind of a template file where you can just include what you want to include in your source distribution and What is good practice is to have something like a read me here. So which you could also use then in your As meta information in your setup pie for example to have this directly on on PI PI and Now let's see what we wanted to do we wanted to Install it so already done. So our Version was was unknown for the moment. So we might attack now a first version so which might be version 0.1 and We call it first or something so then if we look to To get Kate and you see oh you see almost nothing, but there's now a new a new tag in there and So now we could for example do Pies and set up high as this so and now we have a Folder this in here and here we have now our our Our table. So this is my project 0.1 touch each side. So this is now the The version which is gets from version here via this the skid tag and the name which we gave in in our setup Hi, so let's have a look in the In the setup by shortly so that you see what's actually happening there. So you need you We didn't need to to do anything of this by our own It just took a fill all the meta information which we have there use this command class and also has the This docs and setup docs and testing already configured. So Yeah basically What else we wanted to do so we wanted to have maybe something like an Beat is also that you see this this too. So this is then and in this another another top ball which is dependent on the on your machine and if we want to run now for example to test so This is as easy as that So as we has no test also the coverage is perfect. So and If you want to now to run a for example this dox thing So there will see this will fail because we have no not in installed Sphinx up to now. This is the only thing which you which you would then need to do oops this way so done and This will then just build your documentation takes a moment So then we have everything in our docs file for example So if we now want to To have a look how this would just close this And so we have our project and Have the the stocks folder and then it comes into the the HTML and there you have then just the index HTML and you see your your documentation for example which we Just wrote so this is now more or less the module reference and what you what you could have in your in your readme txt so and that's basically it so yeah as As you want to know more so you can now of course Ask now or you just come to our to our booth afterwards and then we can discuss everything Thanks a lot for the talk. Are there any questions? Yeah, please come forward to the microphone so everybody can hear thanks. What about the wheel packaging? Yeah, the wheel packaging you could just do with with set up high Beatest wheel for example, and then you have directly the wheel there So usually wheel is a good thing to do so we can just Just do it. So this you watch Do something like that You need to of course install wheel beforehand No, okay, not a good choice this question That's why I'm asking it's always missing like it's the new cool format and it's somehow not adopted So no you can you can do it. It's Sorry ah Good thing to do. Yeah, of course we need to do that first and then We can do it and then you also have it as wheel in our in our test. Thank you. Are there any more questions? Okay, thanks a lot