Package: python-starter-pack
Python Starter PackQuickly setup a Python 3 library complete with continuous integration, code coverage and automatic deployment to PyPi in 5 minutes.What's this about?Have you ever wanted to make a Python library available on PyPi, but struggled with all the fuss aboutsetup.py, continuous integration, unit testing, and such? Been there ;).After reading a bunch of tutorials and trying a few different ways on my own, this is the most condensed and streamlined checklist I've come up with. Just by forking this project and following the next few steps you'll be up on your own with a brand new Python library project, together with unit testing, continuous integration, code coverage, and automatic deployment to PyPi. Tag along.A Python starter packStarting a new Python library project? Follow these steps:Step 1: Setting up the environmentFirst, it should go without saying, get aGithub accountif you haven't.Next,fork this project, and then clone your own version, or directly clone the project:$gitclonegit@github.com:apiad/python-starter-pack<my-project>Now you can head over to your project's folder and see what's inside:$cd<my-project>
$ls

total48K
-rw-r--r--1useruser1,1Kmay1918:44LICENSE
-rw-r--r--1useruser321may2215:29makefile
-rw-r--r--1useruser16may1919:34MANIFEST.in
-rw-r--r--1useruser206may1919:36Pipfile
-rw-r--r--1useruser13Kmay1919:36Pipfile.lock
drwxr-xr-x2useruser4,0Kmay2215:31python_starter_pack
-rw-r--r--1useruser2,2Kmay2215:40Readme.md
-rw-r--r--1useruser2,1Kmay2215:31setup.py
drwxr-xr-x2useruser4,0Kmay2215:31testsWe'll go in depth on the contents of each file later on. The most important things now is to notice that we have aPipfile, hence, we will be usingpipenvfor dependency management.So, if you haven't already,install pipenv. The easiest way, in Linux, is simply to run:$makeinstall

pipinstallpipenv
...
pipenvinstall--dev--skip-lock
InstallingdependenciesfromPipfile…🐍▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉5/5—00:00:01
...This will use ourmakefiledefinition forinstallwhich basically installspipenvand updates the dependencies.Step 2: Adding your codeNow that you have the dependencies and development environment in place, you can start adding your code.
We have sample code in thepython_starter_packfolder. Check the folder and files' content if you need a little guidance, or simply replace with your own code.For starters, thepython_starter_packfolder is what we call aPython module, because it contains a__init__.pyfile which allows it to be imported from Python code.There are also some basic functions in there just to illustrate the basic functionality for importing code and, as we'll see next, for testing.Step 3: Running testsThetestsfolder will contain all your unit tests. We'll be using the awesomepytestmodule, and alsopylintfor ensuring our code is Pythonic and beautiful.If you have been changing code, you will need to make some changes tomakefileto ensure everything is consistent. Open it and update the value of thePROJECTvariable to point to your project's folder. In Linux you can just hack your way with the following (where<my-project>is your project's folder):$sed-i-E"/^PROJECT/s/(.*)/PROJECT=<my-project>/"makefileIn any case, now you can test your code with:$maketestThis will runpylintand thenpytest, testing doc-strings and unit tests in thetestsfolder. Check the filetests/test_module.pyfor head-start on unit testing in Python.
This will also create and printcodecovcoverage reports, telling you how much of your code is tested.
Make sure to re-test every time you change something.Step 4: Publishing on GithubIf you forked your project then your git remote is set. Otherwise, you will needto create a new projecton Github and set up your remote. In any case, when ready, you can just push your code:$gitpushoriginmasterStep 5: Setup continuous integrationNow that your project is on Github, the next step is to setup continuous integration withTravis-CI. If you don't still have an account on Travis-CI, register there andactivate your repository.Travis-CI will ask you to link with your Github account, and install thetravisapp in your Github profile. Once that is done, every push will automatically trigger Travis-CI to run the tests online.Plus, Travis-CI will automatically push coverage reports toCodecov. Make sure to register there as well, and you will see coverage statistics automatically (there is no need to "activate" a repository there, it happens automatically when Travis pushes coverage stats).This all just works because of the file.travis.ymlwhich you are free to open and modify according to your preferences (e.g., change the preferred Python version).Once Travis-CI and Codecov are setup, make sure to modify the top of thisReadme.mdfile and update these links:<imgalt="Travis (.org)"src="https://img.shields.io/travis/apiad/python-starter-pack/master.svg"><imgalt="Codecov"src="https://img.shields.io/codecov/c/github/apiad/python-starter-pack.svg">Change theapiad/python-starter-packpart to match your Github user/repository and you will immediately get these nice badges on your Readme file.Step 6: Automatic deploy on PyPiThe next step is to setup automatic deployment on the Python Package Index. We will start with deploying to the test channel before moving on deploying to the real channel.First, to keep things tidy up, let me explain the how the workflow will be. We will create adevelopbranch:$gitbranch-Cdevelop
$gitcheckoutdevelopNow, on this branch, we will test that deployment to PyPi works. Head over totest.pypi.organd register there. Remember yourusernameandpassword.Now it's time to setup up your package configuration. Open the filesetup.pyand modify the necessary lines. They all sayTODOon top. You should define there your project's name and modules, copyright info, entry-points (if any) and other metadata (known as classifiers).Once that is ready,make sure to changetheVERSIONvariable on top. ThisVERSIONvariable is what PyPi will use to determine the current version, and if you push twice with the same version you'll get an error because you cannot override something published to PyPi.Now head over toTravis-CIand navigate to your project's settings. There you will need to set twoenvironment variables:TEST_PYPI_USERandTEST_PYPI_PASSWORDwith the values of your username and password fortest.pypi.org.Once that is done, you can now push to Github from thedevelopbranch and your project will be automatically published ontest.pypi.org. You can check it there.By now you should have a workflow cycle that looks something like this:Work on thedevelopbranch (or afeature-*and them merge todevelop).Commit as much as you like.Runmake testoften to make sure everything works.When you are confident the next feature is working, go over tosetup.pyand bump theVERSIONvariable to your new version.Push thedevelopbranch to Github.CheckTravis-CIandtest.pypi.orgto make sure everything is Ok.Step 7: Deploy on PyPi for realNow you are going to setup deployment on therealPyPi index. Head over topypi.organd register there.Now go over to Travis-CI settings for your project and set theenvironment variablesPYPI_USERNAMEandPYPI_PASSWORD. Once this is ready, Travis will be able to push to PyPi when you commit and push tomaster.However, for safety reasons, wedo notdeploy on PyPI on every commit tomaster, butonly on tags. Hence, the workflow is the following:Develop on thedevelopbranch and commit, bump version, push, rinse, repeat.Once you are confident everything is Ok ondevelop, navigate toGithub, and in your project's page, create apull requestfromdeveloptomaster.When the pull request has been created, you will notice that automatically Travis and Codecov start working and basically block your commit until all tests pass.Once everything is green, you will be able tomergetomaster.Finally,create a releaseon Github, with a proper version number (please, the same as insetup.py) and then, and only then, will Travis deploy to PyPi.When everything is working, make sure to change the remaining<img>tags in thisReadme.mdto match your repository's name.Enjoy!CollaborationLicense is MIT, so you know the drill.MIT LicenseCopyright (c) 2019 Alejandro PiadPermission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.