Package: makepackage
makepackage: A Python package for packaging Python codeInstallationInstall the package fromPyPi:$pipinstallmakepackageTL;DR: How to usemakepackageTo create a package that does not need a command-line argument, go to a directory where you want to create the structure of your package and run in shell$makepackagemypackagewheremypackageis the name of your package. That's it! You will have a self-standing package that you can now develop. Remember to fill in[MAKEPACKAGE]fields in setup.py and LICENSE.If you want to create a package with a command-line argument, add acliflag after the name of the package:$makepackagemypackagecliand here you are. Your package will get the command-line argument that is the same as the package's name.Now let's go into detail.Rationale and backgroundOrganizing Python code in a package has a lot of advantages and can significantly simplify development — but the first hours can be tricky. To facilitate this process, you can use tools such asCookiecutter, but they themselves are quite advanced and offer a lot of functionalities that you need to learn — quite often, this complexity makes development more difficult, sometimes changing the hours spent with the tool into a nightmare.To facilitate this step, I created a package template and have been using it for about a year. Life got easier. But the template required some manual work that could be automated. This is when I thought that a script would be better, so I wrote one. It worked fine indeed, and things got even easier. And then I thought, as this is so useful for me, why not make it useful for others? So, I made this package, and now you can use it just like me.makepackageoffers only one function, available via shell. The only thing you need to do is to installmakepackage(preferably in a virtual environment you will use only to create new packages) and run a simple shell command (which works under both Linux and Windows). The command, as you will see below, takes one required argument: a package's name; you can add--clito create a CLI package, as otherwise (without the flag) it will not have command-line interface.The use ofmakepackageis very simple, but this does not come without costs: it creates just one type of structure, though you can change it manually:you have to fill in some fields in setup.pysetup.py will includepytest,wheel,blackandmypyin thedevmode; you can remove them manually before installing the package in the editable modethe package will usepytestfor unit testing anddoctestfor documentation testingYou will find annotated code inziuziu(given the simplicity of the functions, the annotations are very simple), and you can runmypyon it, with success.The idea behindmakepackageis to offer a tool that creates a working package with a simple but common structure, which can be then extended and developed. And indeed, you will find in it tests (bothpytests anddoctests) that pass; you can install the package in the editable mode, and after that you will be able to import it. So, the resulting package is just fine, and you can immediately move to development.makepackageoffers one of many possible structures, and it assumes you will usepytestfor testing. If you want to use other solutions, you should either create a package manually or use another tool.UsingmakepackageThetestsfolder contains six shell scripts. Two of them show how to usemakepackagein Linux, and two others do the same for Windows. One of the scripts shows how to create a package that does not need command-line interface while the other with CLI. Check out these two files for Linux:makepackagewithout CLIandmakepackagewith CLI; and for Windows, these two files:makepackagewithout CLIandmakepackagewith CLI.It's best to install and usemakepackagein a virtual environment. So, for example,$python-mvenvvenv-makepackage
$venv-package/bin/activate(venv-makepackage)$python-mpipinstallmakepackageExamples show Linux commands, but any Windows user will know how to replace them with the corresponding Windows commands (though most commands will be the same in Linux and Windows; you simply need to change paths when activating a virtual environment in Windows).Now that we have activated the virtual environment and installedmakepackagein it, we are ready to create a package of our own. First, navigate to a folder where you want to create the package, and run the following command:(venv-makepackage)$makepackageziuziuThis creates aziuziupackage;ziuziuwill not have command-line interface. You will now see a ziuziu folder:(venv-makepackage)$ls
ziuziuIf you want to create a package with command-line interface, use a command-line flag--cli, like this:(venv-makepackage)$makepackageziuziu--cliAs we used the same name —ziuziu— again, we would get an error; so, you should first remove the previous installation ofziuziu, use a different name for the package, or create the package in a different location.With this, you will be able to run your package using theziuziucommand in shell.The only thing you now need to do is to create a virtual environment and install theziuziupackage there, in the editable mode:(venv-package)$deactivate
$python-mpipinstallvenv-ziuziu(venv-ziuziu)$cdziuziu(venv-ziuziu)$python-mpipinstall-e.[dev]And that's it, you're ready to developziuziu. Now you can run tests:(venv-ziuziu)$python-mpytest(venv-ziuziu)$python-mdoctestziuziu/ziuziu.pyYou will see that the package is created with 11pytesttests, and they should all pass (you will see the output frompytest). Alldoctests should pass, too — that means you should see no output fromdoctest.When you create a package usingmakepackage, you can read the README file of the new package. It contains some essential information about package development, such as building the package, installing it, and uploading to PyPi.Structure of a package created usingmakepackageYou can use various structures to create a Python package.makepackageuses one of them, a simple (though not the simplest) but quite common one. You will see the following structure of the ziuziu/ folder (so, of theziuziupackage):.
+--.gitignore
+--LICENSE
+--README.md
+--pytest.ini
+--setup.py
+--tests|+--__init__.py|+--conftest.py|+--test_ziuziu.py
+--ziuziu/|+--ziuziu.py|+--__init__.pyWhen you used themakepackagecommand with thecliargument, theziuziu/ziuziufolder will also include a__main__.pyfile.Here are the assumptionsmakepackagemakes:the package is developed usingpytestanddoctest(you will find both implemented in the code ofziuziu)MIT license is used (you can change it to any license you want, but remember also to change the license in setup.py)in the development mode,pytest,wheel,blackandmypypackages are additionally installed in the virtual environment (used for development); they arenotinstalled when one installs the package from PyPiyou will need to fill in setup.py in several places (namely, fieldsauthor,author_email, anddescription) and LICENSE in one place; you can easily find those places, as they are indicated with the"[MAKEPACKAGE]"mark.Of course, this is a starting point, and you can now extend the package however you want. Once installed,ziuziu(or however you name the package) works. It has three functions,foo(),bar()andbaz(), which all have tests implemented in the tests/ folder, and you can run them using thepytestcommand as shown above.Those who tried to create such a package manually know that quite often something does not work — an import does not work,pytestdoes not see the package, and the like. When usingmakepackage, you get a fully working structure of the package. The only thing you need to do is to replace the existing functions with your functions, and of course to adapt the package to this change.makepackagecomes with some functionalities that you can get rid of:a conftest.py file in the tests/ foldersimple annotations in thefoo(),bar()andbaz()functions of the newly created packagedoctests in the above functionspackages installed in the editable modeNotes on further development of your packageAs mentioned before, the first step is to fill in several fields in setup.py and author in LICENSE. Then you need to create a virtual environment, in which you install the package in the editable mode. And that's all you need to start development.From now on, you're on your own. However, a package created usingmakepackagecomes with some help for inexperienced users. They can see how to write tests (usingpytest), how to use a conftest.py file (forpytesting), how to write fixtures and parametrized tests (again forpytesting), how to import the package's modules and functions, how to writedoctests, and the like. These are just some basic development tools.There is one thing I'd like to stress, and it's related to imports. (The truth is, imports sometimes happen to pose some unexpected problems during Python coding). When you add a new module to the source folder (in our example, this is ziuziu/), e.g., ziuziu/another_ziuziu.py, then in the mainziuziumodule you can import it asfrom ziuziu import another_ziuziuorfrom ziuziu.another_ziuziu import another_foo. Note that the regular approach you would use, that is,import another_ziuziu, will not work here.TestingTesting ofmakepackagecombines shell scripts andpytest. Therefore, running tests on Linux and Windows requires running different shell scripts. You will learn more fromhere.ContributionEveryone is invited to developmakepackage. You can submit an issue or a pull request. Nonetheless, be aware that I will only accept proposals thatkeep the current API of the package, unless the proposed change is so great that the cost of changing the API is relatively small compared to what the new functionality offersare covered by unit testsare well documented (if needed)are coded in a similar style that the current code useswork under both Windows and LinuxBelow, you can read more about these aspects.Do remember to incrementmakepackage's version. Usesemantic versioning 2.0.0.In technical terms, to contribute,fork the repository and clone it to your machinecreate a new branch:$ git checkout -b new-branch, wherenew-branchis the name of a branch, so remember to name it in a way that reflects what the branch changes (and please, do not use the name ofnew-branchor similar)once you're done with all the changes and are ready to commit the changes, you can usegit add pathto add each file separately (pathbeing a relative path to a file you want to commit); after each such command, do$ git commit -m "What I did", the comment explaining what is changed in the committed file. If you want to add all the files at the same time, do$ git add ..$ git push --set-upstream origin new-branch— this will create the branch in the repo and will push the changes to it.create a pull request to the original repository; when doing so, please explain the changes in detailIf someone else is developingmakepackageat the same time, you may have to solve the resulting conflicts. How to say it... be patient and don't break down! Don't break down your computer, either! Keep your nerves in check!Now, you can sit and wait for a review of your proposal; use this time for thinking about how to improve the package even more :smiley:.Keep the current API of the packageThis, for instance, means thatmakepackage's API does not offer different licences, structures of the root folder, and the like. Also, the API does not offer numerous arguments to enable the user to fill in the required fields of setup.py; the user can do it directly in the file, an approach that is easier than providing this information through command-line arguments. No GUI, too: just a simple shell command.The simpler the API, the easier the package is to use. The idea behindmakepackagewas to bring areallysimple API to create a package. This simplicity cannot come without cost, but the cost does not seem that great. True, if one wants to create a different organization of the package or wants to useunittestinstead ofpytest, then one will have to choose a different tool or do it manually. This is the main cost of simplicity we have to pay, but hadmakepackageenabled the user to choose from different options, the package's API would have been far more complicated. This would mean the main purpose behind creating the package — crreating the structure of a Python package in an easy way — would not have been accomplished.Simply put,makepackagehas a simple API and does not offer too many choices, and I want to keep it that way.Cover all functionality by unit testsAdd unit tests to every new functionality or change, unless the change does not change the package's functioning whatsoever. Remember thatmakepackageis tested withpytestanddoctest.Use readable and sufficient documentationIf you add a new functionality or change the existing one, you have to document it in documentation: README and docstrings. Of course, don't overdo, but note that this README is long and detailed. It has theTL;DR: How to use makepackagesection, which is short and concise. Then, we go deep when explaining the details. Keep this approach.Maintain the current coding styleThis is important. Keep the current style, and please useblackto format code. By coding style I do not only mean whatblackchanges; I mean other important things, such as the following:Have you noticed that the only classes that are defined in the package are those for custom exceptions? Try not to change that and do not base any new functionality on a class, unless this is a better and more natural approach.makepackageuses custom exceptions to handle the user's mistakes. Throwing custom errors insidemakepackagefunctions improves traceback, by using well-named exception classes and moving the traceback into the actual location in code where the exception occurred.Work under both Windows and Linuxmakepackageworks in both these OSs, so if you want to propose something new, make sure this works under both these OSs. If you have problems with doing so, please contant the repo's maintainer.However, if you can check ifmakepackageworks fine under a different OS, please do so and add it to this section.