| Name | python_vscode_template JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | None |
| Summary | python_vscode_template example |
| upload_time | 2023-08-23 17:13:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Overview
This 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 skeleton
1. My vscode setup for Python, including what plugins I use (in `.vscode/settings.json`)
1. Examples for automated formatting with [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
1. Examples for automated testing with [pytest](https://docs.pytest.org/).
1. Examples for automatically testing the documentation examples with pytest.
1. Examples for automated documentation building with [mkdocs](https://www.mkdocs.org/)
1. Examples for automatic linting with [pylint](https://pypi.org/project/pylint/)
1. Examples for automatic type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
1. Examples for automatic testing in multiple environments with [tox](https://tox.wiki/)
1. Examples for [Github Actions](https://github.com/features/actions) automation for running your tox test suite.
## Software you need
Make 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.
- Python3
- Git
- Visual Studio Code
Note on Debian/Ubuntu based distributions, you will need to `apt-get install python3 python3-pip python3-venv git code`.
## How to setup
- Copy the contents of this git repo to your new project directory.
- Make a venv with `python -m venv .venv`.
- Update the `LICENSE` file with your appropriate license information.
- Replace this `README.md` file with an appropriate readme file.
You then need to install the development dependancies, and then the package in installable mode.
```console
pip install -r requirements-dev.txt
flit install
```
## My developer workflow
1. Use vscode tools while developing, running tests out of vscode.
1. View the "problems" tab.
1. When ready to commit, I run `tox` from the command line.
1. If `tox` returns no errors, I can commit and push.
1. I can then verify github actions produces no errors on that push.
### Use the package. It is fully installed and usable
```console
$ python
>>> import python_vscode_template.arithmetic as ar
>>> ar.add_ints(2,3)
5
```
### Format it with the [black](https://black.readthedocs.io/en/stable/) formatter
```console
$ black .
All done! ✨ 🍰 ✨
6 files left unchanged.
```
### Correct the import order with [isort](https://pycqa.github.io/isort/)
```console
$ isort .
Skipped 5 files
```
### Run the tests (from the commmand line)
```console
$ pytest
======================================= test session starts ========================================
platform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0
rootdir: /home/dwg/CODE/Python-VSCode-Template
configfile: pyproject.toml
testpaths: tests
plugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0
asyncio: mode=Mode.STRICT
collected 5 items
tests/test_arithmetic.py .... [ 80%]
tests/test_pokemon.py . [100%]
======================================== 5 passed in 0.27s =========================================
```
### Verify the documentation tests (from the command line)
```console
$ pytest --doctest-modules src/
====================================== test session starts ======================================
platform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0
rootdir: /home/dwg/CODE/Python-VSCode-Template
configfile: pyproject.toml
plugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0
asyncio: mode=Mode.STRICT
collected 1 item
src/python_vscode_template/arithmetic.py . [100%]
====================================== 1 passed in 0.03s =======================================
```
### Verify the type checking
```console
$ mypy src/
Success: no issues found in 4 source files
```
### Build the documentation and place the results in `site/`
```console
mkdocs build
```
### Start a documentation mini-webserver, that automatically updates
```console
mkdocs serve
```
### Run tests in multiple python environments
```console
tox
```
***
## From within vscode
You can verify the tests using the testing flask icon on the left.
1. Brings up the testing dialog.
2. Can run or debug individual tests, by selecting them and using the icons.
3. Can rediscover, run all tests or debug all tests.
## On github
A 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 edit
- [tox.ini](tox.ini): Make sure `envlist` contains the versions of Python you want to test again. This example inclujdes
- [requirements-dev.txt](requirements-dev.txt): Make sure this includes any developer only dependancies.
- [requirements.txt](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/](docs/): The entry document is index.md, but you should write the docs as you see fit.
- [src/](src/): Update this with your package name.
- [tests/](tests/): This is where to write your tests. Files must start `test_` to be picked up by tests/
## Docstrings
See [arithmetic.py](src/python_vscode_template/arithmetic.py) for example docstrings. These are in [Google Docstring Format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
## Dist
`flit build` will put two files in the `dist/` directory. A source file and a wheel. Both of these are directly usable by pip to install.
## Publishing docs to Github pages
You can do this with `mkdocs gh-pages`. This will push the documentation in `site/` to a github page.
You will get the URL to it from the command.
## Uploading to pypi
If you have never done this before, you need to make an account at [Pypi](https://pypi.org/).
Then in [Pypi - Manage Accounts](https://pypi.org/manage/account/), add 2FA and an API token.
Then repeat this for [TestPypi](https://test.pypi.org/) and [TestPypi - Manage Accounts](https://test.pypi.org/manage/account), add 2FA and a API token.
Then edit `.pypirc` in your home directory, and make it similar to [.pypirc-template](.pypirc-template) in this repo, except with the appropriate real usernames and tokens.
## My Global VSCode Settings
- Press `CTRL K` then `CTRL T`, and select `Dark+` as the theme (or your prefered theme).
- Press `CTRL ,` then make sure `Auto Save` is set to `After Delay`.
- In the File menu, make sure `Auto Save` is ticked.
Raw data
{
"_id": null,
"home_page": null,
"name": "python_vscode_template",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "David Groves <github@fibrecat.org>",
"download_url": "https://files.pythonhosted.org/packages/4d/74/972e099f8f1b7e81815da670ccd04d73c49ddd092e1c5c9fe85423c14f88/python_vscode_template-0.0.1.tar.gz",
"platform": null,
"description": "# Overview\n\nThis 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.\n\nThis doesn't mean I am correct, or someone with other preferences is incorrect, but this is what works for me.\n\nNote 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.\n\n## What is included in this skeleton\n\n1. My vscode setup for Python, including what plugins I use (in `.vscode/settings.json`)\n1. Examples for automated formatting with [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).\n1. Examples for automated testing with [pytest](https://docs.pytest.org/).\n1. Examples for automatically testing the documentation examples with pytest.\n1. Examples for automated documentation building with [mkdocs](https://www.mkdocs.org/)\n1. Examples for automatic linting with [pylint](https://pypi.org/project/pylint/)\n1. Examples for automatic type checking with [mypy](https://mypy.readthedocs.io/en/stable/)\n1. Examples for automatic testing in multiple environments with [tox](https://tox.wiki/)\n1. Examples for [Github Actions](https://github.com/features/actions) automation for running your tox test suite.\n\n## Software you need\n\nMake 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.\n\n- Python3\n- Git\n- Visual Studio Code\n\nNote on Debian/Ubuntu based distributions, you will need to `apt-get install python3 python3-pip python3-venv git code`.\n\n## How to setup\n\n- Copy the contents of this git repo to your new project directory.\n- Make a venv with `python -m venv .venv`.\n- Update the `LICENSE` file with your appropriate license information.\n- Replace this `README.md` file with an appropriate readme file.\n\nYou then need to install the development dependancies, and then the package in installable mode.\n\n```console\npip install -r requirements-dev.txt\nflit install\n```\n\n## My developer workflow\n\n1. Use vscode tools while developing, running tests out of vscode.\n1. View the \"problems\" tab.\n1. When ready to commit, I run `tox` from the command line.\n1. If `tox` returns no errors, I can commit and push.\n1. I can then verify github actions produces no errors on that push. \n\n### Use the package. It is fully installed and usable\n\n```console\n$ python\n>>> import python_vscode_template.arithmetic as ar\n>>> ar.add_ints(2,3)\n5\n```\n\n### Format it with the [black](https://black.readthedocs.io/en/stable/) formatter\n\n```console\n$ black .\nAll done! \u2728 \ud83c\udf70 \u2728\n6 files left unchanged.\n```\n\n### Correct the import order with [isort](https://pycqa.github.io/isort/)\n\n```console\n$ isort .\nSkipped 5 files\n```\n\n### Run the tests (from the commmand line)\n\n```console\n$ pytest\n======================================= test session starts ========================================\nplatform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0\nrootdir: /home/dwg/CODE/Python-VSCode-Template\nconfigfile: pyproject.toml\ntestpaths: tests\nplugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0\nasyncio: mode=Mode.STRICT\ncollected 5 items \n\ntests/test_arithmetic.py .... [ 80%]\ntests/test_pokemon.py . [100%]\n\n======================================== 5 passed in 0.27s =========================================\n```\n\n### Verify the documentation tests (from the command line)\n\n```console\n$ pytest --doctest-modules src/\n====================================== test session starts ======================================\nplatform linux -- Python 3.11.4, pytest-7.4.0, pluggy-1.2.0\nrootdir: /home/dwg/CODE/Python-VSCode-Template\nconfigfile: pyproject.toml\nplugins: asyncio-0.21.1, anyio-3.7.1, cov-4.1.0\nasyncio: mode=Mode.STRICT\ncollected 1 item \n\nsrc/python_vscode_template/arithmetic.py . [100%] \n====================================== 1 passed in 0.03s =======================================\n```\n\n### Verify the type checking\n\n```console\n$ mypy src/\nSuccess: no issues found in 4 source files\n```\n\n### Build the documentation and place the results in `site/`\n\n```console\nmkdocs build\n```\n\n### Start a documentation mini-webserver, that automatically updates\n\n```console\nmkdocs serve\n```\n\n### Run tests in multiple python environments\n\n```console\ntox\n```\n\n***\n\n## From within vscode\n\nYou can verify the tests using the testing flask icon on the left.\n\n1. Brings up the testing dialog.\n2. Can run or debug individual tests, by selecting them and using the icons.\n3. Can rediscover, run all tests or debug all tests.\n\n![vscode testing example](images/vscode_testing.png \"VSCode Testing Example\")\n\n## On github\n\nA small icon will have been added to github by github actions. It will be a \u2705 if the tests are passing, a \u274c if they are failing and a \ud83d\udfe4 if the tests are still running.\n\nYou can click on it to view the logs and see what tests have passed, or what tests are still running.\n\n![github tests example](images/github_tests_passing.png \"Github Tests Passing\")\n\n## Stuff you will need to edit\n\n- [tox.ini](tox.ini): Make sure `envlist` contains the versions of Python you want to test again. This example inclujdes\n- [requirements-dev.txt](requirements-dev.txt): Make sure this includes any developer only dependancies.\n- [requirements.txt](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.\n- [docs/](docs/): The entry document is index.md, but you should write the docs as you see fit.\n- [src/](src/): Update this with your package name.\n- [tests/](tests/): This is where to write your tests. Files must start `test_` to be picked up by tests/\n\n## Docstrings\n\nSee [arithmetic.py](src/python_vscode_template/arithmetic.py) for example docstrings. These are in [Google Docstring Format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).\n\n## Dist\n\n`flit build` will put two files in the `dist/` directory. A source file and a wheel. Both of these are directly usable by pip to install.\n\n## Publishing docs to Github pages\n\nYou can do this with `mkdocs gh-pages`. This will push the documentation in `site/` to a github page.\nYou will get the URL to it from the command.\n\n## Uploading to pypi\n\nIf you have never done this before, you need to make an account at [Pypi](https://pypi.org/).\nThen in [Pypi - Manage Accounts](https://pypi.org/manage/account/), add 2FA and an API token.\n\nThen repeat this for [TestPypi](https://test.pypi.org/) and [TestPypi - Manage Accounts](https://test.pypi.org/manage/account), add 2FA and a API token.\n\nThen edit `.pypirc` in your home directory, and make it similar to [.pypirc-template](.pypirc-template) in this repo, except with the appropriate real usernames and tokens.\n\n\n\n## My Global VSCode Settings\n\n- Press `CTRL K` then `CTRL T`, and select `Dark+` as the theme (or your prefered theme).\n- Press `CTRL ,` then make sure `Auto Save` is set to `After Delay`.\n- In the File menu, make sure `Auto Save` is ticked.\n",
"bugtrack_url": null,
"license": null,
"summary": "python_vscode_template example",
"version": "0.0.1",
"project_urls": {
"Home": "https://github.com/davidgroves/Python-VSCode-Template"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "af0a1177be644f4407d70f37e3388e2199a52e019e59c78898172b1525bf994a",
"md5": "01008f0155b663815255979509b2b13a",
"sha256": "4fa707683078f61c840895a105561c9420c3c4e1403debc83efed49546fa8ba7"
},
"downloads": -1,
"filename": "python_vscode_template-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01008f0155b663815255979509b2b13a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6644,
"upload_time": "2023-08-23T17:13:01",
"upload_time_iso_8601": "2023-08-23T17:13:01.131267Z",
"url": "https://files.pythonhosted.org/packages/af/0a/1177be644f4407d70f37e3388e2199a52e019e59c78898172b1525bf994a/python_vscode_template-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d74972e099f8f1b7e81815da670ccd04d73c49ddd092e1c5c9fe85423c14f88",
"md5": "17fa3ff5bb34de9edfcfdd4185246941",
"sha256": "f33ab4df0a37c07753adb7c3c21aed4fb8061cd34ef6712ac5b45a33bace5800"
},
"downloads": -1,
"filename": "python_vscode_template-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "17fa3ff5bb34de9edfcfdd4185246941",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39848,
"upload_time": "2023-08-23T17:13:03",
"upload_time_iso_8601": "2023-08-23T17:13:03.760526Z",
"url": "https://files.pythonhosted.org/packages/4d/74/972e099f8f1b7e81815da670ccd04d73c49ddd092e1c5c9fe85423c14f88/python_vscode_template-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 17:13:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davidgroves",
"github_project": "Python-VSCode-Template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "python_vscode_template"
}
