Creating your first PyPI package

if you're anything like I was it's on your bucket list to create a package for the python package index I'd been wanting to do it forever but I'd always been too scared to because it was you know too hard or I didn't think I was ready for it and then I actually did it and it wasn't that hard at all and I wanted to make this video to show you that it's not that hard to do it yourself as long as you have a good idea and a way to do it it's actually very easy to put something onto the python package index and share it with the world and maybe who knows your package will become the leading package in its field or maybe you're breaching into I'm calling a new market as though anyone sells anything on this thing but you know you're creating something new that no one's ever done on the python package index before I actually originally started this video in the code editor and I finished it and I realized actually should probably show you around the console first um so I'm going to do that and then I'm going to go back into the past just the way these videos work sometimes uh so this is the main console for the test python package index I used the test one I didn't want to push um a test package onto the live repository this test one is a good one um or a good place to like test your packages to make sure everything's working properly and to make sure everything looks okay I would recommend using this uh first before you use the main one this is your main projects as you can see I've tested quite a few uh some of these actually came inter frish some of these did not see a number of these didn't really go anywhere uh this is the one that I I just finished making a video of uh you have your organizations you have your account settings in here which is actually pretty useful we're going to need to be doing something in here you also have this publishing thing um which is just documentation by looks of things okay so we want to go into the account settings because I want to show you how to create a a token first because it's actually quite useful to have um you know regardless of whether you're going to be uh uploading them in your own shell or whether you're going to be doing it in GitHub actions I'll talk about that in aure future video you're going to want to have a token so you want to come down to where it says API tokens um and then you want to click add API token you want to give it a name so we're going to do like I don't know video permissions upload packages that's the only one you get and then you have your scope so you can choose to um create a token for all projects or you can choose to create a token for just an individual project if you are wanting to create one for just an indiv idual project the project already needs to exist so you need to have already pushed it once uh using your username and password so do keep that in mind that also um means that you can't push the very first version using GitHub actions or any other CI like that so you perhaps your all projects one is is the better way to go because then you can just create a new project using it and you just need to create a token and you have your token here I'm not going to bother blowing this out cuz I'm going to delete this um um but you need to copy the token and put it somewhere it doesn't really matter where but if you forget it then that's it this token is gone it won't actually show you this token ever again um so do keep that in mind it gives you some instructions but I also um talk about that a little bit more uh in here and you can also um one thing I don't talk about this might have been new is that you can set uh your environment variables in this piy RC file pii RC file it's not piy because that that gets confus of distribution uh but you can put them in here like that um so you don't ever have to supply them with twine but we'll talk about that a little bit later so now that we've created our API token we now need to create the actual um all the files that needed to build and upload the package so I'm going to go back to past me and he'll explain everything you need to know so I have this folder over to the side called carbur and this is our package um and it's named after What's called the name space so it doesn't have to be exactly the same as the package name so for example discord.py um uses Discord as the namespace not discord.py but this name is how you import it um so in this case it would be you know import carbra or import carbra CBR or from carbra import this that and the other in the same way that it' be you know import numpy or import pandas the numpy and pandas folders in those instances would be called numpy and pandas um so make sure that the name space is at least related to the package uh in some description and inside that you need an init.py file or Dunder init.py file so that's two underscores either side um and this is just here it doesn't have to have anything in it but it's just here to tell python that this is a package and should be treated as such um in here I just have a a function you can put functions in here um and it will just be you know if you did from carbur import ad uh You' be importing this function here uh but you can you know do all sorts of stuff uh in the in it over here we also have a Dunder main now this is entirely optional uh but this is more for like um loading as a module uh using the CLI and I'll show that off a little bit later um but you can just have you know something simple like this a simple print statement uh with lyrics to a song I'm not really I'm not really sure what it is I've just kind of seen it around the internet a lot um so yeah it's also worth noting that you can have a single file package uh by doing in this case carbo dop and then you don't have to have a photo at all but that's only really useful for small uh packages ironically like this one um because it is just the one file to do it but it will work exactly the same which is kind of cool so first things first we need to create let's create a readme first a readme is always good to have and this is actually useful to the uh to the tutorial um I should say also this is going to be a kind of have a lot of copy pasting just to keep the time down but I will explain everything as we go so I've just got some basic you know uh read me stuff in here some more lyrics I keep seeing these around I don't know where they're coming from um but yeah this is a test package for a test package for video tutorial um you know just a little description as you would do your read me I'm sure everyone knows what they are next up we are going to have our P project. toml file ma come on play with me here um and we're going to copy this and put that in here so you can have other stuff in your p projecto as well this is mainly for like tool configurations so if you had something like black or isort installed then you could configure them in here there are other ways but I generally like to configure everything in power Tomo if you use poetry you'll also be particularly familiar with this file um but in this case we just want have a build system that requires setup tools and I'm not sure if greater not equal to 42 is the best thing to have anymore um but I I believe version 42 changed something and I'm pretty sure this came straight from the PPI documentation but you can probably put a future version there it' be fine AE wheel as well and this build backend uh setup tools. build meta it just tells um the tool we're going to be using to build our python package how to build it you don't really need to understand what it does per se um but yeah that is our P project. Tomo file next I'm going to have our setup.py file and this is where the vast majority of our time in this video is going to be spent so there's quite a lot in here we are going to type this one out so first we're going to import path lib uh and we're also going to import setup tools and then we're going to have setup tools do setup and in here as you can see from the uh the to TI there there is quite a lot of things we can do and I am going to be talking about quite a few of them because a lot of them are very useful so we're going to start with the name uh which is just the name of the package now I tend to put the name of the name space here uh just to be kind of uniform I suppose then you have the version so in this case it's just going to be version 0.1.0 you can put anything in there you like so long as it conforms to pep oh I'm going to get this wrong on only 449 might be$ 459 I'll put it on screen uh there is a pep that defines uh version kind of schematics or version semantics that you have to follow and if you don't follow those uh then your package won't get accepted so do make sure you uh you look at that and then you have your brief description which is the on line uh thing I'll show you real quick so analytics is one of my projects that I put on the python package index and the brief description is this bit here so it's this kind of one line introduction and it also appears here uh as well so we're just going to put I'm just going to put a brief description uh for this just so we could differentiate it from the long description and the long description is where is it this it is uh is this bit down here um and this will generally be your read me so to do that we can do p path li. paath uh readme.md do read text and that will read that file and set it as the long description however because it's marked down we do actually need to tell setup tools that it's marked down so we can do a long description uh content type and we can set this as text markdown obviously if your read me is in rst format then you'll need to uh specify that if it's in HTML format you'll need to specify that etc etc but mine is in markdown so we do that next is the URL and I will say at this point it doesn't actually matter what order you do these things in and a lot of them are optional so these kind of four or five things at the top these are sort of necessary it won't shout at you if the description the long description aren't there but you generally want them everything else is kind of optional from this point in um but generally very useful so we have a URL so this is kind of just you know a URL for yourself uh generally speaking a lot of the time this is just the link to your source code though I'm just going to use my website uh for example sake and you have your author so that'll be your author name and you have your author email so this will be your author email address so I'm going to use my business email address uh here any business inquiries do feel free to get in touch then we have our license and this isn't the full license this is just the name of the license so in this case we're going to use the unlicense uh but you can put obviously any license you want in there next up is we'll do the project URLs next uh project URLs and these are these down here so I'm where it says project links so on mine I have the homepage Bud tracker change log C documentation Source these are all set in here so for example you could have I'm just going to actually copy paste this one you can have something like this where you have your documentation is um is this URL this URL doesn't exist I'm just putting it here for example sake and the source you could have it something like this again it might be the same as URL but it's good to have it um here uh this also doesn't exist at the moment I might put this on GitHub I haven't decided yet uh so watch this space if you really want it on there then leave a comment and uh I'll I'll put it on there um but yeah uh these will go I keep going that way these will go here next up we have our classifiers now these are if I just bring them up are sort of like tags in a way oops oh go away there we go I don't know want to what was up with that so these are tags um so you can have as many tags as you want and they are basically like little things to say Well they're descriptors I guess they tell you know the users what states uh your project is in whether it's in planning or alpha or production tells you what environment um they expect to use it tells you what framework they're in tended audience license natural language operating system programming languages topics all sorts it tells you a lot of stuff as I said you can have as many as you want so it's good to put on as many relevant ones as you can because you can actually like filter uh buy classifiers uh so it's just good to have them for discoverability sake I'm going to have just a simple list here uh so we're going to say that our development status is in Alpha going to say that our intended audience are developers so this is probably you know some sort of uh tool to help with coding like black r or something like that uh then we're specify our programming language to be 3.10 and 3.11 compatible and then we're going to say that the topic is it's just a utility it's something to help out and you can be as detailed or as undetailed as you want to be with this it's really up to you uh then we're going to have python requires and we're going to set this to three uh greater than or equal to 3.10 and less than 3.11 now it's it's oh sorry less than 3.12 cuz we support both Python 3.10 and python 3.11 as we specified in our classifiers it is important that this is accurate because Pi pip sorry does actually check against this so if this is wrong then it's not going to be installed on versions you want it to be installed on so make sure this is correct I I used to have checks near the top um well I actually still do but I don't really know if you need them um because of this uh yeah just do make sure this is correct uh a lot of libraries don't actually have this less than and that can cause compatibility problems when you then try and install it so say like TL panel or something if you install it on python 3. well 12 it's not going to work on there at the moment and it will try because they haven't specified this and it will break so just keep that in mind uh we're then going to have install uh requires and these are your dependencies so you can have requests as an example and you can have like pandas greater than or equal to 2.0 so you can have request so this will take any version of requests uh but it will only um accept Panda's version 2.0 or higher and again you can have as many of these as you want you can pass requirements.txt files if you want that's what I do but as I said I'm keeping this simple so I'm not going to do that in this video explicitly on top of a series of required dependencies we can also Supply a series of optional dependencies as well using things called extras and we can provide these using extras require and this is a dictionary of the extra I guess identifier so in this case we'll use Excel and a list of dependencies that you need um when supplying that extra so in this case we want to use Open PI XL because Open PI XL provides uh a me mechanism of working with Excel spreadsheets and that would be if the user were to do something like uh this uh so we now installed the CRA package uh with Excel support as well uh so not all python packages are going to need this um but especially something to do with data you know if you want to have well your Excel dependencies for example or you know the ability to write to a pandas but you don't necessarily want to install pandas uh by default because you know a lot of people probably want use it uh then you can use it um for these things discord.py as um kind of a a channel relevant example per se uh had the voice um extra which allowed or which installed extra uh libraries to do with voice compatibility and stuff like that so the final few things I want to talk about are the packages one which is just setup tools. find packages not fund packages that's very different uh that's more an npm thing uh and including package data which equals true uh this include package data is technically optional though I've had problems uh it defaults to false and I've had problems if this is set as false so I always set it as true um and it seems to fix everything and those are kind of the two fun little things uh there is one more other thing that I want to talk about but this is only really um applicable if you're writing a command line interface application and that will be the entry points uh and you can define a series of entry points I don't know what the other ones are other than console scripts but console scripts are your CLI programs and then you provide um the command itself so let's say you know just carbur and then you provide the function it's going to run so carbur dot and we're going to have to actually write this I think but say cara. CLI uh colon Main and then if we were to go into the carbur create a C.P and then then quickly do a main and then print oops uh this is the CLI when we install uh when we pip install our package locally if we were to run the carbur command in the Shell then we would get this output in return uh which is actually what we're going to do now so to install your pip um package locally what you can do is PIP install d e oh actually there's one more thing we need to talk about before we do that I'm getting ahead of myself again uh we need to do I suppose this is an optional um file so I can sort of get away with forgetting about it but this is the manifest. file and there are a few defaults what it comes to the Manifest file but it is always good to specify your own just in case um and we're going to do graft carbur so the graft is essentially include directory uh so this will include everything in this directory here and then we have our include which is just include file and we want to include our P project. tomal we also want to include our setup.py uh not self project and then we want to Global exclude star. py uh c um so in certain instances you would want to include additional files if there's like any additional configuration files perhaps uh the global exclude here is just excluding um any temp FS so the pi C uh Pi o and Pi D fars is what this means Pi C is your Pi cach Pi o is your Pi object PD I actually don't know I don't think I've ever seen a PD file um but you see a lot of this cod in a in like GE ignores and stuff in um automatically generated ones you do tend to see this pattern a lot so I just tend to roll with it if anyone does know what a PD file is let me know CU I've always wondered and I've never bothered to look it up uh but now that we done that we are actually going to install our library locally so we can do that using pip install d e do and dashy stands for editable so it installs it kind of in place I guess it installs it in such a way that if you make edits to these files then the PIP installed version will react to it if you to just do pip installed D and then if you want to make a change to any of these files uh when you try to run say the carbur command it wouldn't actually pick up the changes so make sure to type- e and the dot um it's just your local directory in setup as you've provided this uh setup tools. find packages it'll automatically find this one for you because it just knows pip is not how is PIP not found oh goodness hang on a second okay so now I've restarted P because it was being annoying this should work hey it worked this time yeah I don't really know what happened there but as you can see it is installing all of our stuff it's also installing um all of our dependencies as well so it's installed pandas it's installed um I forget which other one we had it was request yeah there we go and if we were to do our pip install d e do and then this going to have to be quotes cuz it's zsh extras not extras that's not what I did at all it was XL uh you can see that it will now go ahead and install Open PI EXL as well see Open PI XL wasn't installed before because we didn't Supply the XL extra but now that we did it's installed it wo so now that we know how to install it locally I'm going to show you how to build it and push it to piie now we are specific why is going on here why is why is there two okay that was weird we're specifically going to be pushing to the test pii I keep saying pii I just realized um it's PPI I got to remember that um uh but yeah we're going to be pushing to the test repository cuz I don't really want to be putting a tutorial on the main one but the process is exactly the same for pushing to the main one um so it's fine so we're first going to start by doing pip install build this might actually already be installed it's not installed by default oh no it wasn't installed oh is build 1.0.0 I think that's new fancy that uh so we're going to do pi- M build and this will now build our um environment one thing I should have pointed out is that when you did pip install - e it installed this um car. egg info which just has you know various I don't I'm not sure why it's called an egg really um maybe snake egg or something for python I don't know that seems tenuous um but uh yeah this just includes a lot of stuff you can look through and now that we've built our thing it also has a disc with our p3-- dowh and GZ ignore the fact that this is now version 0.2 uh I had some issues uh doing this before this is actually not my first take at this bit so so it's .2 and it's fine also ignore when we install it from the repository later it's not going to install any of our dependencies ignore that as well that's the problem with the test repository because when you install stuff in the test repository if your requirements or if your dependencies uh don't update their test repositories it's not actually going to install it's going to error um which is a bit you won't have that problem with the main repo uh but for the sake of again I don't want to push a test repo to the live repository particularly um so we're having to make do this is the fun with the test you should use the test the first time you push something up uh just to make sure that everything looks right because if you push onto the main one then you can't actually go back and change it you have to push another version and that just looks weird um people will judge you and if they don't I will do it for them uh so make sure we don't make that mistake take uh but now that we've uh built it we can now push it to the repository and to do that we need uh a library called twine so we're going to do pip install twine uh there is also a way to do this using GitHub actions but I'm actually going to cover that in a different video I want to do a separate video on GitHub actions I've been mean to for a while and I think that would be a good example of a workflow so I'm going to save that for that um also so I'm not over complicating this video uh so we're going to do pi- M twine and in this case we're going to do repository uh test Pi piie dist SL star if you're pushing to the main repository so if you've already done it to the test one everything looks fine and you want to push into the main one for real you would emit everything highlighted completely um the default repository is the main one so you don't need to worry about that press that and then oh that's the wrong command I need to do twine upload I'm sure it used to be just twine but maybe I was wrong about that uh now we need our username and you don't necessarily want to put in your um your pii username and password cuz you can get tokens uh from the admin console and then you can pass token with um I should say Dunder token as your username and then I'm going to copy paste this token from this other window into here and I believe it won't show there you go so it's there and it's uploading and it's there and you get a URL and if we go to that URL if you open it it should open on this screen it does that's good and there we go our library is available on the python package index and here are my previous versions my previous attempts that I made so you have this release history here uh you have your project link so your homepage your documentation and your Source The Source One probably won't work this one will the homepage one will work it will take you to my actual website you can go to woohoo you other two don't know you don't have your license information author information your requires information your maintainers and you have your various classifiers that appear down here you also have your brief description up here so this is the you know the on line bit and then your main read me is inside this project description bit which is pretty cool now I'm going to copy this uh Comm on here and I'm actually going to pip uninstall uh see if this work do it like that there we go that did work and now if we paste that in here so pip install dasi and then we're getting it from the test repository we should be able to collect it and as you can see it's not installing our requirements because I took them out because of conflict but we actually managed to install our library through the test pipy and if I were to do our Command this is the CLI it all works and that is everything you need to know about creating a package on the python package index if you like this video make sure to leave a like to let me know and maybe subscribe if you want to see more videos like this if you have any questions or comments make sure to leave them down below I read every single one so your feedback is greatly appreciated if you want to support this channel monetarily you can do so by becoming a patron or a member1 pound a month on either in you can be this at these people and I'll see you in the next video for probably a rundown of GitHub actions again I've been meaning to do it for some time but I never got around to it so it'd be good to do that now I've done this I can then show you how to kind of Advance even further in your PPI Journey so I'll see you for that

Channel: Carberra

Views: 6,519

Keywords: pyfhon, pytho, pytbon, pytjon, ptyhon, pytyon, ptthon, pyyhon, pythn, pythoh, pythpn, ython, pytgon, pyhon, pytohn, phthon, oython, pthon, pyghon, pythoj, pythno, pythkn, ypthon, pytuon, lython, pyrhon, pythom, pythob, puthon, pgthon, python, pyhton, pythln, pythin, pytnon, pyton

Id: WGsMydFFPMk

Length: 27min 42sec (1662 seconds)

Published: Wed Sep 06 2023