Repository files navigation

Hello code jam participants! We've put together this repository template for you to use inour code jams or even other Python events!

This document contains the following information:

1. What does this template contain?
2. How do I use this template?
3. How do I adapt this template to my project?

Here is a quick rundown of what each file in this repository contains:

• LICENSE.txt:The MIT License, 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.
• .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.
• pyproject.toml: Configuration and metadata for the project, as well as the linting tool Ruff. If you're interested, you can read more aboutpyproject.toml in thePython Packaging documentation.
• .pre-commit-config.yaml: The configuration of thepre-commit tool.
• .github/workflows/lint.yaml: AGitHub Actions workflow, a set of actions run by GitHub on their server after each push, to ensure the style requirements are met.

Each of these files have comments for you to understand easily, and modify to fit your needs.

Our first tool is Ruff. It will check your codebase and warn you about any non-conforming lines.It is run with the commandruff check in the project root.

Here is a sample output:

$ ruff checkapp.py:1:5: N802 Function name`helloWorld` should be lowercaseapp.py:1:5: ANN201 Missingreturntype annotationfor publicfunction`helloWorld`app.py:2:5: D400 First line should end with a periodapp.py:2:5: D403 First word of the first line should be capitalized:`docstring` ->`Docstring`app.py:3:15: W292 No newline at end of fileFound 5 errors.

Each line corresponds to an error. The first part is the file path, then the line number, and the column index.Then comes the error code, a unique identifier of the error, and then a human-readable message.

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.For example:

defhelloWorld():# noqa: N802    ...

This will ignore the function naming issue and pass linting.

Ruff also comes with a formatter, which can be run with the commandruff format.It follows the same code style enforced byBlack, so there's no need to pick between them.

The second tool doesn't check your code, but rather makes sure that you actuallydo check it.

It makes use of a feature calledGit hooks which allow you to run a piece of code before runninggit commit.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.

It isinstalled by runningpre-commit install and can be run manually by calling onlypre-commit.

Lint before you push!

• check-toml: Lints and corrects your TOML files.
• check-yaml: Lints and corrects your YAML files.
• end-of-file-fixer: Makes sure you always have an empty line at the end of your file.
• trailing-whitespace: Removes whitespaces at the end of each line.
• ruff-check: Runs the Ruff linter.
• ruff-format: Runs the Ruff formatter.

One person in the team, preferably the leader, will have to create the repository and add other members as collaborators.

1. In the top right corner of your screen, whereClone usually is, you have aUse this template button to click.
2. Give the repository a name and a description.
3. ClickCreate repository from template.
4. ClickSettings in your newly created repository.
5. In the "Access" section of the sidebar, clickCollaborators.
6. ClickAdd people.
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.

You are now ready to go! Sit down, relax, and wait for the kickstart!

Our default setup includes a dependency group to be used with avirtual environment.It works with pip and uv, and we recommend this if you have never used any other dependency manager, although if you have, feel free to switch to it.More on thatbelow.

Dependency groups are a relatively new feature, specified inPEP 735.You can read more about them in thePython Packaging User Guide.

Create a virtual environment in the folder.venv.

python -m venv .venv

It will change based on your operating system and shell.

# Linux, Bash$source .venv/bin/activate# Linux, Fish$source .venv/bin/activate.fish# Linux, Csh$source .venv/bin/activate.csh# Linux, PowerShell Core$ .venv/bin/Activate.ps1# Windows, cmd.exe> .venv\Scripts\activate.bat# Windows, PowerShell> .venv\Scripts\Activate.ps1

Once the environment is created and activated, use this command to install the development dependencies.

pip install --group dev

Interestingly enough, it is the same for every platform.

deactivate

Once the environment is activated, all the commands listed previously should work.

If you wish to use Pipenv or Poetry, you will have to move the dependencies inpyproject.toml to the development dependencies of your tool.

We've included a porting to bothPoetry andPipenv in thesamples folder.Note that the Poetrypyproject.toml file does not include the Ruff configuration, so if you simply replace the file then the Ruff configuration will be lost.

When installing new dependencies, don't forget topin them by adding a version tag at the end.For example, if I wish to installClick, a quick look atPyPI tells me that8.1.7 is the latest version.I will then addclick~=8.1, without the last number, to my requirements file or dependency manager.

We hope this template will be helpful. Good luck in the jam!