Package: python_vscode_template
OverviewThis is a highly opininated guide on how to setup VScode for Python Development the way I personally like it, with a baseline Python project the way I also like it.This doesn't mean I am correct, or someone with other preferences is incorrect, but this is what works for me.Note this only works for pure Python projects. If your project requires C extensions or rust code, you will need to replace the flit builder with one that supports those things.What is included in this skeletonMy vscode setup for Python, including what plugins I use (in.vscode/settings.json)Examples for automated formatting withblackandisort.Examples for automated testing withpytest.Examples for automatically testing the documentation examples with pytest.Examples for automated documentation building withmkdocsExamples for automatic linting withpylintExamples for automatic type checking withmypyExamples for automatic testing in multiple environments withtoxExamples forGithub Actionsautomation for running your tox test suite.Software you needMake sure the following applications are installed on your system globally. How you do this obviously varies depending on if you are using Windows, OSX or Linux.Python3GitVisual Studio CodeNote on Debian/Ubuntu based distributions, you will need toapt-get install python3 python3-pip python3-venv git code.How to setupCopy the contents of this git repo to your new project directory.Make a venv withpython -m venv .venv.Update theLICENSEfile with your appropriate license information.Replace thisREADME.mdfile with an appropriate readme file.You then need to install the development dependancies, and then the package in installable mode.pip install -r requirements-dev.txtflit installMy developer workflowUse vscode tools while developing, running tests out of vscode.View the "problems" tab.When ready to commit, I runtoxfrom the command line.Iftoxreturns no errors, I can commit and push.I can then verify github actions produces no errors on that push.Use the package. It is fully installed and usable$python>>> import python_vscode_template.arithmetic as ar>>> ar.add_ints(2,3)5Format it with theblackformatter$black.All done! ✨ 🍰 ✨6 files left unchanged.Correct the import order withisort$isort.Skipped 5 filesRun the tests (from the commmand line)$pytest======================================= test session starts ========================================platform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0rootdir: /home/dwg/CODE/Python-VSCode-Templateconfigfile: pyproject.tomltestpaths: testsplugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0asyncio: mode=Mode.STRICTcollected 5 itemstests/test_arithmetic.py ....                                                                [ 80%]tests/test_pokemon.py .                                                                      [100%]======================================== 5 passed in 0.27s =========================================Verify the documentation tests (from the command line)$pytest--doctest-modulessrc/====================================== test session starts ======================================platform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0rootdir: /home/dwg/CODE/Python-VSCode-Templateconfigfile: pyproject.tomlplugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0asyncio: mode=Mode.STRICTcollected 1 itemsrc/python_vscode_template/arithmetic.py .                                                [100%]====================================== 1 passed in 0.03s =======================================Verify the type checking$mypysrc/Success: no issues found in 4 source filesBuild the documentation and place the results insite/mkdocs buildStart a documentation mini-webserver, that automatically updatesmkdocs serveRun tests in multiple python environmentstoxFrom within vscodeYou can verify the tests using the testing flask icon on the left.Brings up the testing dialog.Can run or debug individual tests, by selecting them and using the icons.Can rediscover, run all tests or debug all tests.On githubA small icon will have been added to github by github actions. It will be a ✅ if the tests are passing, a ❌ if they are failing and a 🟤 if the tests are still running.You can click on it to view the logs and see what tests have passed, or what tests are still running.Stuff you will need to edittox.ini: Make sureenvlistcontains the versions of Python you want to test again. This example inclujdesrequirements-dev.txt: Make sure this includes any developer only dependancies.requirements.txt: This should contain dependancies required to run the application or library. If you are making an application, you should pin each package to a specific version. If you are making a library, you should accept the minimum required version to allow users more choice. A library with a pinned version FORCES the user to install that version too, and is likely to clash with other libraries.docs/: The entry document is index.md, but you should write the docs as you see fit.src/: Update this with your package name.tests/: This is where to write your tests. Files must starttest_to be picked up by tests/DocstringsSeearithmetic.pyfor example docstrings. These are inGoogle Docstring Format.Distflit buildwill put two files in thedist/directory. A source file and a wheel. Both of these are directly usable by pip to install.Publishing docs to Github pagesYou can do this withmkdocs gh-pages. This will push the documentation insite/to a github page.
You will get the URL to it from the command.Uploading to pypiIf you have never done this before, you need to make an account atPypi.
Then inPypi - Manage Accounts, add 2FA and an API token.Then repeat this forTestPypiandTestPypi - Manage Accounts, add 2FA and a API token.Then edit.pypircin your home directory, and make it similar to.pypirc-templatein this repo, except with the appropriate real usernames and tokens.My Global VSCode SettingsPressCTRL KthenCTRL T, and selectDark+as the theme (or your prefered theme).PressCTRL ,then make sureAuto Saveis set toAfter Delay.In the File menu, make sureAuto Saveis ticked.