You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is an example [PyPI](https://pypi.org/) (Python Package Index) package set up with automated tests and package publishing workflow using GitHub Actions CI/CD. It is made primarily for GitHub + VS Code (Windows / Mac / Linux) users who are about to write and publish their first PyPI package. The package could serve as a starter / boilerplate / demo and the tutorial could give you a quick and concise explaination to solve some small but annoying problems you might encounter, such as package / module name confusion, and VS Code test configuration issues.
8
-
9
-
<details><summary><strong>Differences from pypa/sampleproject (click to show/hide)</strong></summary>
10
-
11
-
This example package is inspired by / based on the [official sample project pypa/sampleproject](https://github.com/pypa/sampleproject), but this package:
12
-
13
-
- is a simplified version of pypa/sampleproject (and the [official Python Packaging User Guide](https://packaging.python.org/))
14
-
- uses GitHub Actions for both testing and publishing, instead of Travis CI
7
+
- uses GitHub Actions for both testing and publishing
15
8
- is tested when pushing `master` or `main` branch, and is published when create a release
16
9
- includes test files in the source distribution
17
10
- uses **setup.cfg** for [version single-sourcing](https://packaging.python.org/guides/single-sourcing-package-version/) (setuptools 46.4.0+)
18
-
- has **.vscode\settings.json** and **vscode.env** which adds **src/** folder to `PYTHONPATH`, so that test files don't have linting errors and may run with pytest in VS Code
19
-
- does not use flake8 for automated linting - it is sometimes too strict and inflexible, you may use pylint locally instead
20
-
- has this tutorial that covers everything you need to know in one page. Everything that might not be very useful, is hidden in collapsible sections that you can click to show
21
-
- has **[.editorconfig](https://editorconfig.org/#download)** file
22
-
23
-
</details>
24
-
25
-
## Make necessary changes
26
-
27
-
### Use as a template
28
-
29
-
[](https://github.com/tomchen/example_pypi_package/generate)
30
-
31
-
(Click the above button to use this example package as a template for your new GitHub repo, this will initialize a new repository and my commits will not be in your git history)
32
-
33
-
(If you do not use GitHub, you can [download the archive of the example package](https://github.com/tomchen/example_pypi_package/archive/main.zip))
34
-
35
-
### Package, module name
36
-
37
-
Many use a same package and module name, you could definitely do that. But this example package and its module's names are different: `example_pypi_package` and `examplepy`.
38
-
39
-
Open `example_pypi_package` folder with Visual Studio Code, <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>F</kbd> (Windows / Linux) or <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>F</kbd> (MacOS) to find all occurrences of both names and replace them with your package and module's names. Also remember to change the name of the folder **src/examplepy**.
40
-
41
-
Simply and very roughly speaking, package name is used in `pip install <PACKAGENAME>` and module name is used in `import <MODULENAME>`. Both names should consist of lowercase basic letters (a-z). They may have underscores (`_`) if you really need them. Hyphen-minus (`-`) should not be used.
42
-
43
-
You'll also need to make sure the URL "https://pypi.org/project/example-pypi-package/" (replace `example-pypi-package` by your package name, with all `_` becoming `-`) is not occupied.
44
-
45
-
<details><summary><strong>Details on naming convention (click to show/hide)</strong></summary>
46
-
47
-
Underscores (`_`) can be used but such use is discouraged. Numbers can be used if the name does not start with a number, but such use is also discouraged.
48
-
49
-
Name starting with a number and/or containing hyphen-minus (`-`) should not be used: although technically legal, such name causes a lot of trouble − users have to use `importlib` to import it.
50
-
51
-
Don't be fooled by the URL "[pypi.org/project/example-pypi-package/](https://pypi.org/project/example-pypi-package/)" and the name "example-pypi-package" on pypi.org. pypi.org and pip system convert all `_` to `-` and use the latter on the website / in `pip` command, but the real name is still with `_`, which users should use when importing the package.
52
-
53
-
There's also [namespace](https://packaging.python.org/guides/packaging-namespace-packages/) to use if you need sub-packages.
54
-
55
-
</details>
56
-
57
-
### Other changes
58
-
59
-
Make necessary changes in **setup.py**.
60
-
61
-
The package's version number `__version__` is in **src/examplepy/\_\_init\_\_.py**. You may want to change that.
62
-
63
-
The example package is designed to be compatible with Python 3.6, 3.7, 3.8, 3.9, and will be tested against these versions. If you need to change the version range, you should change:
64
-
65
-
-`classifiers`, `python_requires` in **setup.py**
66
-
-`envlist` in **tox.ini**
67
-
-`matrix: python:` in **.github/workflows/test.yml**
68
11
69
-
If you plan to upload to [TestPyPI](https://test.pypi.org/) which is a playground of [PyPI](https://pypi.org/) for testing purpose, change `twine upload --repository pypi dist/*` to `twine upload --repository testpypi dist/*` in the file **.github/workflows/release.yml**.
12
+
### Automated tests
70
13
71
-
## Development
14
+
Test code is in **tests/** folder using [unittest](https://docs.python.org/3/library/unittest.html).
72
15
73
-
### pip
74
-
75
-
pip is a Python package manager. You already have pip if you use Python 3.4 and later version which include it by default. Read [this](https://pip.pypa.io/en/stable/installing/#do-i-need-to-install-pip) to know how to check whether pip is installed. Read [this](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py) if you need to install it.
76
-
77
-
### Use VS Code
78
-
79
-
Visual Studio Code is the most popular code editor today, our example package is configured to work with VS Code.
80
-
81
-
Install VS Code extension "[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)".
82
-
83
-
"Python" VS Code extension will suggest you install pylint. Also, the example package is configured to use pytest with VS Code + Python extensions, so, install pylint and pytest:
84
-
85
-
```bash
86
-
pip install pylint pytest
87
-
```
88
-
89
-
(It's likely you will be prompted to install them, if that's the case, you don't need to type and execute the command)
90
-
91
-
**vscode.env**'s content is now `PYTHONPATH=/;src/;${PYTHONPATH}` which is good for Windows. If you use Linux or MacOS, you need to change it to `PYTHONPATH=/:src/:${PYTHONPATH}` (replacing `;` with `:`). If the PATH is not properly set, you'll see linting errors in test files and pytest won't be able to run **tests/test\_\*.py** files correctly.
92
-
93
-
Close and reopen VS Code. You can now click the lab flask icon in the left menu and run all tests there, with pytest. pytest seems better than the standard unittest framework, it supports `unittest` thus you can keep using `import unittest` in your test files.
94
-
95
-
The example package also has a **.editorconfig** file. You may install VS Code extension "[EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)" that uses the file. With current configuration, the EditorConfig tool can automatically use spaces (4 spaces for .py, 2 for others) for indentation, set `UTF-8` encoding, `LF` end of lines, trim trailing whitespaces in non Markdown files, etc.
96
-
97
-
In VS Code, you can go to File -> Preferences -> Settings, type "Python Formatting Provider" in the search box, and choose one of the three Python code formatting tools (autopep8, black and yapf), you'll be prompted to install it. The shortcuts for formatting of a code file are <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>F</kbd> (Windows); <kbd>Shift</kbd> + <kbd>Option (Alt)</kbd> + <kbd>F</kbd> (MacOS); <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> (Linux).
98
-
99
-
### Write your package
100
-
101
-
In **src/examplepy/** (`examplepy` should have been replaced by your module name) folder, rename **module1.py** and write your code in it. Add more module .py files if you need to.
102
-
103
-
### Write your tests
104
-
105
-
In **tests/** folder, rename **test_module1.py** (to **test\_\*.py**) and write your unit test code (with [unittest](https://docs.python.org/3/library/unittest.html)) in it. Add more **test\_\*.py** files if you need to.
106
-
107
-
<details><summary><strong>The testing tool `tox` will be used in the automation with GitHub Actions CI/CD. If you want to use `tox` locally, click to read the "Use tox locally" section</strong></summary>
16
+
The testing tool `tox` will be used in the automation with GitHub Actions CI/CD.
108
17
109
18
### Use tox locally
110
19
@@ -123,11 +32,7 @@ The automated tests are run against several Python versions, but on your machine
123
32
tox -e py39
124
33
```
125
34
126
-
</details>
127
-
128
-
If you add more files to the root directory (**example_pypi_package/**), you'll need to add your file to `check-manifest --ignore` list in **tox.ini**.
129
-
130
-
<details><summary><strong>Thanks to GitHub Actions' automated process, you don't need to generate distribution files locally. But if you insist, click to read the "Generate distribution files" section</strong></summary>
35
+
Thanks to GitHub Actions' automated process, you don't need to generate distribution files locally. But if you insist, click to read the "Generate distribution files" section.
-[PyPA's Python Packaging User Guide](https://packaging.python.org/tutorials/packaging-projects/)
257
-
-[Stackoverflow questions and answers](https://stackoverflow.com/questions/41093648/how-to-test-that-pypi-install-will-work-before-pushing-to-pypi-python)
258
-
-[GitHub Actions Guides: Building and testing Python](https://docs.github.com/en/free-pro-team@latest/actions/guides/building-and-testing-python)
259
-
260
-
Btw, if you want to publish TypeScript (JavaScript) package to the npm registry, go to [Example TypeScript Package ready to be published on npm for 2021](https://github.com/tomchen/example-typescript-package).
0 commit comments