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
Hello code jam participants! We've put together this repository template for you to use in [our code jams](https://pythondiscord.com/events/) or even other Python events!
5
6
6
-
This document will contain the following information:
7
+
This document contains the following information:
8
+
7
9
1.[What does this template contain?](#what-does-this-template-contain)
8
-
2.[How do I use it?](#how-do-i-use-it)
9
-
3.[How do I adapt it to my project?](#how-do-i-adapt-it-to-my-project)
10
+
2.[How do I use this template?](#how-do-i-use-this-template)
11
+
3.[How do I adapt this template to my project?](#how-do-i-adapt-this-template-to-my-project)
10
12
11
-
You can also look at [our style guide](https://pythondiscord.com/events/code-jams/code-style-guide/) to get more information about what we consider a maintainable code style.
13
+
> [!TIP]
14
+
> You can also look at [our style guide](https://pythondiscord.com/events/code-jams/code-style-guide/) to get more information about what we consider a maintainable code style.
12
15
13
16
## What does this template contain?
14
17
15
18
Here is a quick rundown of what each file in this repository contains:
16
-
-`LICENSE`: [The MIT License](https://opensource.org/licenses/MIT), an OSS approved license which grants rights to everyone to use and modify your projects and limits your liability. We highly recommend you to read the license.
17
-
-`.gitignore`: A list of files that will be ignored by Git. Most of them are auto-generated or contain data that you wouldn't want to share publicly.
18
-
-`dev-requirements.txt`: Every PyPI packages used for the project's development, to ensure a common and maintainable code style. [More on that below](#using-the-default-pip-setup).
19
-
-`tox.ini`: The configurations of two of our style tools: [`flake8`](https://pypi.org/project/flake8/) and [`isort`](https://pypi.org/project/isort/).
20
-
-`.pre-commit-config.yaml`: The configuration of the [`pre-commit`](https://pypi.org/project/pre-commit/) tool.
21
-
-`.github/workflows/lint.yaml`: A [GitHub Actions](https://github.com/features/actions) workflow, a set of actions run by GitHub on their server after each push, to ensure the style requirements are met.
19
+
20
+
-[`LICENSE.txt`](LICENSE.txt): [The MIT License](https://opensource.org/licenses/MIT), an OSS approved license which grants rights to everyone to use and modify your project, and limits your liability. We highly recommend you to read the license.
21
+
-[`.gitignore`](.gitignore): A list of files and directories that will be ignored by Git. Most of them are auto-generated or contain data that you wouldn't want to share publicly.
22
+
-[`requirements-dev.txt`](requirements-dev.txt): Every PyPI package used for the project's development, to ensure a common development environment. More on that [below](#using-the-default-pip-setup).
23
+
-[`pyproject.toml`](pyproject.toml): Configuration and metadata for the project, as well as the linting tool Ruff. If you're interested, you can read more about `pyproject.toml` in the [Python Packaging documentation](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/).
24
+
-[`.pre-commit-config.yaml`](.pre-commit-config.yaml): The configuration of the [pre-commit](https://pre-commit.com/) tool.
25
+
-[`.github/workflows/lint.yaml`](.github/workflows/lint.yaml): A [GitHub Actions](https://github.com/features/actions) workflow, a set of actions run by GitHub on their server after each push, to ensure the style requirements are met.
22
26
23
27
Each of these files have comments for you to understand easily, and modify to fit your needs.
24
28
25
-
### flake8: general style rules
29
+
### Ruff: general style rules
30
+
31
+
Our first tool is Ruff. It will check your codebase and warn you about any non-conforming lines.
32
+
It is run with the command `ruff check` in the project root.
26
33
27
-
Our first and probably most important tool is flake8. It will run a set of plugins on your codebase and warn you about any non-conforming lines.
28
34
Here is a sample output:
29
-
```
30
-
~> flake8
31
-
./app.py:1:6: N802 function name 'helloWorld' should be lowercase
32
-
./app.py:1:16: E201 whitespace after '('
33
-
./app.py:2:1: D400 First line should end with a period
34
-
./app.py:2:1: D403 First word of the first line should be properly capitalized
35
-
./app.py:3:19: E225 missing whitespace around operator
35
+
36
+
```shell
37
+
$ ruff check
38
+
app.py:1:5: N802 Function name `helloWorld` should be lowercase
39
+
app.py:1:5: ANN201 Missing returntype annotation for public function`helloWorld`
40
+
app.py:2:5: D400 First line should end with a period
41
+
app.py:2:5: D403 First word of the first line should be capitalized: `docstring` ->`Docstring`
42
+
app.py:3:15: W292 No newline at end of file
43
+
Found 5 errors.
36
44
```
37
45
38
46
Each line corresponds to an error. The first part is the file path, then the line number, and the column index.
39
47
Then comes the error code, a unique identifier of the error, and then a human-readable message.
40
48
41
49
If, for any reason, you do not wish to comply with this specific error on a specific line, you can add `# noqa: CODE` at the end of the line.
42
50
For example:
51
+
43
52
```python
44
53
defhelloWorld(): # noqa: N802
45
54
...
46
-
```
47
-
will pass linting. Although we do not recommend ignoring errors unless you have a good reason to do so.
48
-
49
-
It is run by calling `flake8` in the project root.
50
55
51
-
#### Plugin List:
56
+
```
52
57
53
-
-`flake8-docstring`: Checks that you properly documented your code.
58
+
This will ignore the function naming issue and pass linting.
54
59
55
-
### ISort: automatic import sorting
60
+
> [!WARNING]
61
+
> We do not recommend ignoring errors unless you have a good reason to do so.
56
62
57
-
This second tool will sort your imports according to the [PEP8](https://www.python.org/dev/peps/pep-0008/#imports). That's it! One less thing for you to do!
63
+
### Ruff: formatting
58
64
59
-
It is run by calling `isort .` in the project root. Notice the dot at the end, it tells ISort to use the current directory.
65
+
Ruff also comes with a formatter, which can be run with the command `ruff format`.
66
+
It follows the same code style enforced by [Black](https://black.readthedocs.io/en/stable/index.html), so there's no need to pick between them.
60
67
61
68
### Pre-commit: run linting before committing
62
69
63
-
This third tool doesn't check your code, but rather makes sure that you actually *do* check it.
70
+
The second tool doesn't check your code, but rather makes sure that you actually *do* check it.
64
71
65
72
It makes use of a feature called [Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) which allow you to run a piece of code before running `git commit`.
66
-
The good thing about it is that it will cancel your commit if the lint doesn't pass. You won't have to wait for Github Actions to report and have a second fix commit.
73
+
The good thing about it is that it will cancel your commit if the lint doesn't pass. You won't have to wait for GitHub Actions to report issues and have a second fix commit.
67
74
68
75
It is *installed* by running `pre-commit install` and can be run manually by calling only `pre-commit`.
69
76
70
77
[Lint before you push!](https://soundcloud.com/lemonsaurusrex/lint-before-you-push)
71
78
72
-
#### Hooks List:
79
+
#### List of hooks
73
80
74
81
-`check-toml`: Lints and corrects your TOML files.
75
82
-`check-yaml`: Lints and corrects your YAML files.
76
83
-`end-of-file-fixer`: Makes sure you always have an empty line at the end of your file.
77
-
-`trailing-whitespaces`: Removes whitespaces at the end of each line.
78
-
-`python-check-blanket-noqa`: Forbids you from using noqas on large pieces of code.
79
-
-`isort`: Runs ISort.
80
-
-`flake8`: Runs flake8.
84
+
-`trailing-whitespace`: Removes whitespaces at the end of each line.
85
+
-`ruff`: Runs the Ruff linter.
86
+
-`ruff-format`: Runs the Ruff formatter.
81
87
82
-
## How do I use it?
88
+
## How do I use this template?
83
89
84
-
### Creating your Team Repository
90
+
### Creating your team repository
85
91
86
92
One person in the team, preferably the leader, will have to create the repository and add other members as collaborators.
87
93
88
94
1. In the top right corner of your screen, where **Clone** usually is, you have a **Use this template** button to click.
7. Insert the names of each of your teammates, and invite them. Once they have accepted the invitation in their email, they will have write access to the repository.
109
105
110
-
You are now ready to go! Now sit down, relax, and wait for the kickstart!
111
-
Don't forget to swap "Python Discord" in the `LICENSE` file for the name of each of your team members or the name of your team after the start of the jam.
106
+
You are now ready to go! Sit down, relax, and wait for the kickstart!
112
107
113
-
### Using the Default Pip Setup
108
+
> [!IMPORTANT]
109
+
> Don't forget to swap "Python Discord" in the [`LICENSE.txt`](LICENSE.txt) file for the name of each of your team members or the name of your team *after* the start of the code jam.
114
110
115
-
Our default setup includes a bare requirement file to be used with a [virtual environment](https://docs.python.org/3/library/venv.html).
111
+
### Using the default pip setup
116
112
117
-
We recommend this if you never have used any other dependency manager, although if you have, feel free to switch to it. More on that below.
113
+
Our default setup includes a bare requirements file to be used with a [virtual environment](https://docs.python.org/3/library/venv.html).
114
+
We recommend this if you have never used any other dependency manager, although if you have, feel free to switch to it. More on that [below](#how-do-i-adapt-this-template-to-my-project).
118
115
119
116
#### Creating the environment
117
+
120
118
Create a virtual environment in the folder `.venv`.
119
+
121
120
```shell
122
-
$ python -m venv .venv
121
+
python -m venv .venv
123
122
```
124
123
125
-
#### Enter the environment
124
+
#### Entering the environment
125
+
126
126
It will change based on your operating system and shell.
127
+
127
128
```shell
128
129
# Linux, Bash
129
130
$ source .venv/bin/activate
@@ -139,35 +140,45 @@ $ .venv/bin/Activate.ps1
139
140
> .venv\Scripts\Activate.ps1
140
141
```
141
142
142
-
#### Installing the Dependencies
143
+
#### Installing the dependencies
144
+
143
145
Once the environment is created and activated, use this command to install the development dependencies.
146
+
144
147
```shell
145
-
$ pip install -r dev-requirements.txt
148
+
pip install -r requirements-dev.txt
146
149
```
147
150
148
151
#### Exiting the environment
149
-
Interestingly enough, it is the same for every platform
152
+
153
+
Interestingly enough, it is the same for every platform.
154
+
150
155
```shell
151
-
$ deactivate
156
+
deactivate
152
157
```
153
158
154
-
Once the environment is activated, all the commands listed previously should work. We highly recommend that you run `pre-commit install` as soon as possible.
159
+
Once the environment is activated, all the commands listed previously should work.
160
+
161
+
> [!IMPORTANT]
162
+
> We highly recommend that you run `pre-commit install` as soon as possible.
155
163
156
-
## How do I adapt it to my project?
164
+
## How do I adapt this template to my project?
157
165
158
-
If you wish to use Pipenv or Poetry, you will have to move the dependencies in `dev-requirements.txt` to the development dependencies of your tool.
166
+
If you wish to use Pipenv or Poetry, you will have to move the dependencies in [`requirements-dev.txt`](requirements-dev.txt) to the development dependencies of your tool.
159
167
160
-
We've included a porting of `dev-requirements.txt` to both [poetry](./samples/pyproject.toml) and [pipenv](./samples/Pipfile) in the [samples folder](./samples).
161
-
If you use the poetry setup, make sure to change the project name, description, and authors at the top of the file.
168
+
We've included a porting of [`requirements-dev.txt`](requirements-dev.txt) to both [Poetry](samples/pyproject.toml) and [Pipenv](samples/Pipfile) in the [`samples` folder](samples).
169
+
If you use the Poetry setup, make sure to change the project name, description, and authors at the top of the file.
170
+
Also note that the Poetry [`pyproject.toml`](samples/pyproject.toml) file does not include the Ruff configuration, so if you simply replace the file then the Ruff configuration will be lost.
162
171
163
-
When installing new dependencies, don't forget to [pin them](https://pip.pypa.io/en/stable/user_guide/#pinned-version-numbers) by adding a version tag at the end.
164
-
For example, if I wish to install `Click`, a quick look at [PyPI](https://pypi.org/project/click/) tells me that 8.0.1 is the latest version.
165
-
I will then add `click ~= 8.0`, without the last number, to my dependency manager.
172
+
When installing new dependencies, don't forget to [pin](https://pip.pypa.io/en/stable/topics/repeatable-installs/#pinning-the-package-versions) them by adding a version tag at the end.
173
+
For example, if I wish to install [Click](https://click.palletsprojects.com/en/8.1.x/), a quick look at [PyPI](https://pypi.org/project/click/) tells me that `8.1.7` is the latest version.
174
+
I will then add `click~=8.1`, without the last number, to my requirements file or dependency manager.
166
175
167
-
A code jam project is left unmaintained after the end of the event. If the dependencies aren't pinned, the project will break after the first major change in an API.
176
+
> [!IMPORTANT]
177
+
> A code jam project is left unmaintained after the end of the event. If the dependencies aren't pinned, the project will break after any major change in an API.
168
178
169
179
## Final words
170
180
171
-
Don't forget to replace this README with an actual description of your project! Images are also welcome!
181
+
> [!IMPORTANT]
182
+
> Don't forget to replace this README with an actual description of your project! Images are also welcome!
172
183
173
184
We hope this template will be helpful. Good luck in the jam!
0 commit comments