Skip to content

Commit b8a8cb8

Browse files
pamelafoxpamelafox
authored
Initial commit
0 parents  commit b8a8cb8

17 files changed

+409
-0
lines changed

‎.devcontainer/devcontainer.json

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
2+
// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.0/containers/python-3
3+
{
4+
"name": "Python 3",
5+
"image": "mcr.microsoft.com/devcontainers/python:3.11-bullseye",
6+
7+
// Configure tool-specific properties.
8+
"customizations": {
9+
// Configure properties specific to VS Code.
10+
"vscode": {
11+
// Set *default* container specific settings.json values on container create.
12+
"settings": {
13+
"python.defaultInterpreterPath": "/usr/local/bin/python",
14+
"python.testing.pytestEnabled": true,
15+
"python.testing.unittestEnabled": false,
16+
"files.exclude": {
17+
".coverage": true,
18+
".pytest_cache": true,
19+
"__pycache__": true
20+
}
21+
},
22+
23+
// Add the IDs of extensions you want installed when the container is created.
24+
"extensions": [
25+
"ms-python.python",
26+
"charliermarsh.ruff",
27+
"ms-python.black-formatter"
28+
]
29+
}
30+
},
31+
32+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
33+
// "forwardPorts": [],
34+
35+
// Use 'postCreateCommand' to run commands after the container is created.
36+
"postCreateCommand": "pip3 install --user -r requirements-dev.txt && pre-commit install",
37+
38+
// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
39+
"remoteUser": "vscode"
40+
}

‎.github/CODE_OF_CONDUCT.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Microsoft Open Source Code of Conduct
2+
3+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
4+
5+
Resources:
6+
7+
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
8+
- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
9+
- Contact [[email protected]](mailto:[email protected]) with questions or concerns

‎.github/ISSUE_TEMPLATE.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!--
2+
IF SUFFICIENT INFORMATION IS NOT PROVIDED VIA THE FOLLOWING TEMPLATE THE ISSUE MIGHT BE CLOSED WITHOUT FURTHER CONSIDERATION OR INVESTIGATION
3+
-->
4+
> Please provide us with the following information:
5+
> ---------------------------------------------------------------
6+
7+
### This issue is for a: (mark with an `x`)
8+
```
9+
- [ ] bug report -> please search issues before submitting
10+
- [ ] feature request
11+
- [ ] documentation issue or request
12+
- [ ] regression (a behavior that used to work and stopped in a new release)
13+
```
14+
15+
### Minimal steps to reproduce
16+
>
17+
18+
### Any log messages given by the failure
19+
>
20+
21+
### Expected/desired behavior
22+
>
23+
24+
### OS and Version?
25+
> Windows 7, 8 or 10. Linux (which distribution). macOS (Yosemite? El Capitan? Sierra?)
26+
27+
### Versions
28+
>
29+
30+
### Mention any other details that might be useful
31+
32+
> ---------------------------------------------------------------
33+
> Thanks! We'll be in touch soon.

‎.github/PULL_REQUEST_TEMPLATE.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
## Purpose
2+
<!-- Describe the intention of the changes being proposed. What problem does it solve or functionality does it add? -->
3+
* ...
4+
5+
## Does this introduce a breaking change?
6+
<!-- Mark one with an "x". -->
7+
```
8+
[ ] Yes
9+
[ ] No
10+
```
11+
12+
## Pull Request Type
13+
What kind of change does this Pull Request introduce?
14+
15+
<!-- Please check the one that applies to this PR using "x". -->
16+
```
17+
[ ] Bugfix
18+
[ ] Feature
19+
[ ] Code style update (formatting, local variables)
20+
[ ] Refactoring (no functional changes, no api changes)
21+
[ ] Documentation content changes
22+
[ ] Other... Please describe:
23+
```
24+
25+
## How to Test
26+
* Get the code
27+
28+
```
29+
git clone [repo-address]
30+
cd [repo-name]
31+
git checkout [branch-name]
32+
npm install
33+
```
34+
35+
* Test the code
36+
<!-- Add steps to run the tests suite and/or manually test -->
37+
```
38+
```
39+
40+
## What to Check
41+
Verify that the following are valid
42+
* ...
43+
44+
## Other Information
45+
<!-- Add any other helpful information that may be needed here. -->

‎.github/dependabot.yaml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# To get started with Dependabot version updates, you'll need to specify which
2+
# package ecosystems to update and where the package manifests are located.
3+
# Please see the documentation for all configuration options:
4+
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5+
6+
version: 2
7+
updates:
8+
9+
- package-ecosystem: "github-actions"
10+
directory: "/"
11+
schedule:
12+
interval: "weekly"
13+
14+
- package-ecosystem: "pip"
15+
directory: "/" # Location of package manifests
16+
schedule:
17+
interval: "weekly"

‎.github/workflows/python.yaml

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Python checks
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Set up Python 3
15+
uses: actions/setup-python@v5
16+
with:
17+
python-version: "3.11"
18+
- name: Install dependencies
19+
run: |
20+
python -m pip install --upgrade pip
21+
pip install -r requirements-dev.txt
22+
- name: Lint with ruff
23+
run: ruff .
24+
- name: Check formatting with black
25+
run: black . --check --verbose
26+
- name: Run unit tests
27+
run: |
28+
pytest

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.venv
2+
__pycache__
3+
.coverage

‎.pre-commit-config.yaml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v4.5.0
4+
hooks:
5+
- id: check-yaml
6+
- id: end-of-file-fixer
7+
- id: trailing-whitespace
8+
- repo: https://github.com/astral-sh/ruff-pre-commit
9+
rev: v0.1.0
10+
hooks:
11+
- id: ruff
12+
- repo: https://github.com/psf/black
13+
rev: 23.9.1
14+
hooks:
15+
- id: black

‎CHANGELOG.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## [project-title] Changelog
2+
3+
<a name="x.y.z"></a>
4+
# x.y.z (yyyy-mm-dd)
5+
6+
*Features*
7+
* ...
8+
9+
*Bug Fixes*
10+
* ...
11+
12+
*Breaking Changes*
13+
* ...

‎CONTRIBUTING.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributing to [project-title]
2+
3+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
4+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
5+
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
6+
7+
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
8+
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
9+
provided by the bot. You will only need to do this once across all repos using our CLA.
10+
11+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
12+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
13+
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
14+
15+
- [Code of Conduct](#coc)
16+
- [Issues and Bugs](#issue)
17+
- [Feature Requests](#feature)
18+
- [Submission Guidelines](#submit)
19+
20+
## <a name="coc"></a> Code of Conduct
21+
Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
22+
23+
## <a name="issue"></a> Found an Issue?
24+
If you find a bug in the source code or a mistake in the documentation, you can help us by
25+
[submitting an issue](#submit-issue) to the GitHub Repository. Even better, you can
26+
[submit a Pull Request](#submit-pr) with a fix.
27+
28+
## <a name="feature"></a> Want a Feature?
29+
You can *request* a new feature by [submitting an issue](#submit-issue) to the GitHub
30+
Repository. If you would like to *implement* a new feature, please submit an issue with
31+
a proposal for your work first, to be sure that we can use it.
32+
33+
* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr).
34+
35+
## <a name="submit"></a> Submission Guidelines
36+
37+
### <a name="submit-issue"></a> Submitting an Issue
38+
Before you submit an issue, search the archive, maybe your question was already answered.
39+
40+
If your issue appears to be a bug, and hasn't been reported, open a new issue.
41+
Help us to maximize the effort we can spend fixing issues and adding new
42+
features, by not reporting duplicate issues. Providing the following information will increase the
43+
chances of your issue being dealt with quickly:
44+
45+
* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
46+
* **Version** - what version is affected (e.g. 0.1.2)
47+
* **Motivation for or Use Case** - explain what are you trying to do and why the current behavior is a bug for you
48+
* **Browsers and Operating System** - is this a problem with all browsers?
49+
* **Reproduce the Error** - provide a live example or a unambiguous set of steps
50+
* **Related Issues** - has a similar issue been reported before?
51+
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
52+
causing the problem (line of code or commit)
53+
54+
You can file new issues by providing the above information at the corresponding repository's issues link: https://github.com/[organization-name]/[repository-name]/issues/new].
55+
56+
### <a name="submit-pr"></a> Submitting a Pull Request (PR)
57+
Before you submit your Pull Request (PR) consider the following guidelines:
58+
59+
* Search the repository (https://github.com/[organization-name]/[repository-name]/pulls) for an open or closed PR
60+
that relates to your submission. You don't want to duplicate effort.
61+
62+
* Make your changes in a new git fork:
63+
64+
* Commit your changes using a descriptive commit message
65+
* Push your fork to GitHub:
66+
* In GitHub, create a pull request
67+
* If we suggest changes then:
68+
* Make the required updates.
69+
* Rebase your fork and force push to your GitHub repository (this will update your Pull Request):
70+
71+
```shell
72+
git rebase master -i
73+
git push -f
74+
```
75+
76+
That's it! Thank you for your contribution!

‎LICENSE.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Microsoft Corporation.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE

‎README.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Python project template
2+
3+
This is a template repository for any Python project that comes with the following dev tools:
4+
5+
* `ruff`: identifies many errors and style issues (`flake8`, `isort`, `pyupgrade`)
6+
* `black`: auto-formats code
7+
8+
Those checks are run as pre-commit hooks using the `pre-commit` library.
9+
10+
It includes `pytest` for testing plus the `pytest-cov` plugin to measure coverage.
11+
12+
The checks and tests are all run using Github actions on every pull request and merge to main.
13+
14+
This repository is setup for Python 3.11. To change the version:
15+
1. Change the `image` argument in `.devcontainer/devcontainer.json` (see [https://github.com/devcontainers/images/tree/main/src/python](https://github.com/devcontainers/images/tree/main/src/python#configuration) for a list of pre-built Docker images)
16+
1. Change the config options in `.precommit-config.yaml`
17+
1. Change the version number in `.github/workflows/python.yaml`
18+
19+
## Development instructions
20+
21+
## With devcontainer
22+
23+
This repository comes with a devcontainer (a Dockerized Python environment). If you open it in Codespaces, it should automatically initialize the devcontainer.
24+
25+
Locally, you can open it in VS Code with the Dev Containers extension installed.
26+
27+
## Without devcontainer
28+
29+
If you can't or don't want to use the devcontainer, then you should first create a virtual environment:
30+
31+
```
32+
python3 -m venv .venv
33+
source .venv/bin/activate
34+
```
35+
36+
Then install the dev tools and pre-commit hooks:
37+
38+
```
39+
python3 -m pip install --user -r requirements-dev.txt
40+
pre-commit install
41+
```
42+
43+
## Adding code and tests
44+
45+
This repository starts with a very simple `main.py` and a test for it at `tests/main_test.py`.
46+
You'll want to replace that with your own code, and you'll probably want to add additional files
47+
as your code grows in complexity.
48+
49+
When you're ready to run tests, run:
50+
51+
```
52+
python3 -m pytest
53+
```
54+
55+
# File breakdown
56+
57+
Here's a short explanation of each file/folder in this template:
58+
59+
* `.devcontainer`: Folder containing files used for setting up a devcontainer
60+
* `devcontainer.json`: File configuring the devcontainer, includes VS Code settings
61+
* `.github`: Folder for Github-specific files and folders
62+
* `workflows`: Folder containing Github actions config files
63+
* `python.yaml`: File configuring Github action that runs tools and tests
64+
* `tests`: Folder containing Python tests
65+
* `main_test.py`: File with pytest-style tests of main.py
66+
* `.gitignore`: File describing what file patterns Git should never track
67+
* `.pre-commit-config.yaml`: File listing all the pre-commit hooks and args
68+
* `main.py`: The main (and currently only) Python file for the program
69+
* `pyproject.toml`: File configuring most of the Python dev tools
70+
* `README.md`: You're reading it!
71+
* `requirements-dev.txt`: File listing all PyPi packages required for development
72+
* `requirements.txt`: File listing all PyPi packages required for production
73+
74+
For a longer explanation, read [this blog post](http://blog.pamelafox.org/2022/09/how-i-setup-python-project.html).
75+
76+
# 🔎 Found an issue or have an idea for improvement?
77+
78+
Help me make this template repository better by letting us know and opening an issue!

‎main.py

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
def add_numbers(a, b):
2+
return a + b

0 commit comments

Comments
 (0)