Pyproject.toml: The modern Python project definition file, explained

foreign here and in this episode of Dev with sword  art we're going to look at the basics of the   new Pi Project dot tomal definition file for  python projects Pi project.tomo is the way to   describe a Project's metadata and dependencies  for modern python projects it's what you want   to equip a project with if that project is going  to someday be installed and used by other people   it's not as vital if you're only creating  a project for your own use but if you have   plans to turn your project into something  you distribute Pi Project is the way to go   so let's take a look at a simple project and  its corresponding Pi Project file I have here a   program that reads in text in the markdown format  and converts it to HTML using the common mark   library and that's its only external dependency  you'll notice that the project layout we have   for it the code is in a source directory and this  layout is what's recommended for Pi Project Style   projects now my project file needs to have at the  very least information about the project and its   dependencies and since we have dependencies listed  here that means we don't need a requirements.txt   file for this project we use Pi Project automal  instead of requirements.txt because it does more   so the tomal format looks a little bit like the  any file format there are sections that are named   in braces and then in each section we have key  value pairs that are designed to look like python   variable declarations this makes it easy for a  python developer to look at a Tome file and just   parse it by eye and in this particular file right  now we only have one section enabled the rest is   commented out and that section is called project  and that as you can guess holds the metadata   about this project so an absolutely minimal Pi  Project file would only need two pieces of data   the project name and its version but since  we have external dependencies we have to list   those as well and we list them as if they  were a python list each one separated by   commas and we use the same format for describing  dependencies that we also use in requirements.txt   now to install the requirements that we have  here we use a slight variation on pip install   normally we'd use the r flag to pass  the requirements from requirements.txt   but here instead we use the e-flag E for  editable which I will explain in a moment   and then for what to install we just pass a DOT  which means use the package in this directory   so when you run this pip will take your Pi Project  file install the base requirements and also set up   your project as a package in this environment  and this last step is done in such a way that   instead of copying the files into the vem it  just references them in place that's what the   E for editable means you can continue editing  the source code for your project and running it   as is without having to rerun the setup process  every time you make a minor change to the source   now the rationale for installing a project into  the environment is that it gives you a way to   test it in the same way that your users will  be installing it and running it now you'll also   notice that after the install process finishes up  there are a couple of new directories for instance   we have the egg info directory and you can  leave that stuff as is it doesn't cause any harm   and once the process finishes we can perform a  pip list and you can see we have our dependencies   installed in the environment and again we also  have the project itself installed as a package as   part of the build process and you'll notice our  project has the project directory itself listed   as its source okay so much for setting up base  dependencies now what if we want to add things   like optional dependencies for development  work so to do that we can add another section   to Pi Project we call it project dot optional  dependencies and there we can give a name we use   for a different group of dependencies in this  case Dev and the dependencies to install with   it this is another way Pi Project is a little  more flexible than things like requirements.txt   because everything can be kept in one file  and described in a much more flexible way   so if we save this and we run pip install  again we can specify the extra dependency set   to install by passing it at the command line  like this you do pip install Dash e dot Dev   and after the setup process finishes we now  have black as our development dependency   so this gives you an idea of how you  can use a dependency set with Pi Project   now one last neat little trick I'll show and  which gives you an idea of what kinds of other   useful things you can do with Pi Project is  to create a command line script version of   your app so for instance if I wanted to run my  program by just typing rendering render HTML   at the command line after installing it in this  environment this is how I could accomplish that   so first we need to add a couple of extra  sections in Pi Project one of them is the   build system section this is basically a piece  of boilerplate that we copy as is it just invokes   Python's native setup tools functionality  there are other tool sets that could in   theory eclipse this functionality but we want to  use the Baseline stuff so we have to specify it   and the other thing is that we add a section  that describes the entry points for each   of the project scripts that we're going to  create we could create more than one command   so if I want a command line app named render  HTML I use this syntax here to define the name   and what entry point in my app to invoke when  I type that command so in this case it's the   module renderhtml dot render and the function  Main in that module and again this command name   could be anything it could be just render if I  wanted but I'm using render HTML to be explicit   so if I save this and rerun pip install after  that's finished you'll see that now we have in   our van the renderhtml.exe which we can invoke  from the command line and run our app with   by the way one more fun little thing for Microsoft  Windows users if you want your command to run   headless with no window and no console except  for one that you create manually you can use   project.guyscripts instead of project.scripts to  achieve this one more thing I should point out   about this trick is that it is not a standalone  python app builder it just creates a shortcut in   the form of an exe to the program that's installed  in our environment but that still makes it very   handy so to sum up piproject.tomo is what modern  python projects should use for metadata and   dependencies especially if you're creating a  project to be reused by others you don't need   much in pi project.tomo for starters just enough  to describe your project and its base dependencies   if any but over time you can add dependency sets  for development and testing and you can add other   instructions for the build process such as how  to create a command line script version of your   app for deployments so that's it for now if you  like this video leave a comment below and don't   forget to follow Dev with cerdar and inforal  on Facebook YouTube and infoworld.com [Music] foreign

Channel: InfoWorld

Views: 12,936

Keywords: How to code, Coding tutorial, App dev, App developer, Python, Python projects, pyproject.toml

Id: QMY-OkckDwo

Length: 7min 17sec (437 seconds)

Published: Thu Jul 20 2023