Initial commit

.devcontainer/Dockerfile

@@ -0,0 +1 @@
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}

.devcontainer/devcontainer.json

@@ -0,0 +1,40 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.0/containers/python-3
+{
+	"name": "Python 3",
+	"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11-bullseye",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Set *default* container specific settings.json values on container create.
+			"settings": {
+                "python.defaultInterpreterPath": "/usr/local/bin/python",
+                "python.testing.pytestEnabled": true,
+                "python.testing.unittestEnabled": false,
+                "files.exclude": {
+                    ".coverage": true,
+                    ".pytest_cache": true,
+                    "__pycache__": true
+                }
+			},
+
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				"ms-python.python",
+                "charliermarsh.ruff",
+                "ms-python.black-formatter"
+			]
+		}
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "pip3 install --user -r requirements-dev.txt && pre-commit install",
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+}

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Microsoft Open Source Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+
+Resources:
+
+- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
+- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+- Contact [[email protected]](mailto:[email protected]) with questions or concerns

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,33 @@
+<!--
+IF SUFFICIENT INFORMATION IS NOT PROVIDED VIA THE FOLLOWING TEMPLATE THE ISSUE MIGHT BE CLOSED WITHOUT FURTHER CONSIDERATION OR INVESTIGATION
+-->
+> Please provide us with the following information:
+> ---------------------------------------------------------------
+
+### This issue is for a: (mark with an `x`)
+```
+- [ ] bug report -> please search issues before submitting
+- [ ] feature request
+- [ ] documentation issue or request
+- [ ] regression (a behavior that used to work and stopped in a new release)
+```
+
+### Minimal steps to reproduce
+>
+
+### Any log messages given by the failure
+>
+
+### Expected/desired behavior
+>
+
+### OS and Version?
+> Windows 7, 8 or 10. Linux (which distribution). macOS (Yosemite? El Capitan? Sierra?)
+
+### Versions
+>
+
+### Mention any other details that might be useful
+
+> ---------------------------------------------------------------
+> Thanks! We'll be in touch soon.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+## Purpose
+<!-- Describe the intention of the changes being proposed. What problem does it solve or functionality does it add? -->
+* ...
+
+## Does this introduce a breaking change?
+<!-- Mark one with an "x". -->
+```
+[ ] Yes
+[ ] No
+```
+
+## Pull Request Type
+What kind of change does this Pull Request introduce?
+
+<!-- Please check the one that applies to this PR using "x". -->
+```
+[ ] Bugfix
+[ ] Feature
+[ ] Code style update (formatting, local variables)
+[ ] Refactoring (no functional changes, no api changes)
+[ ] Documentation content changes
+[ ] Other... Please describe:
+```
+
+## How to Test
+*  Get the code
+
+```
+git clone [repo-address]
+cd [repo-name]
+git checkout [branch-name]
+npm install
+```
+
+* Test the code
+<!-- Add steps to run the tests suite and/or manually test -->
+```
+```
+
+## What to Check
+Verify that the following are valid
+* ...
+
+## Other Information
+<!-- Add any other helpful information that may be needed here. -->

.github/dependabot.yaml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/python.yaml

@@ -0,0 +1,28 @@
+name: Python checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v3
+        - name: Set up Python 3
+          uses: actions/setup-python@v3
+          with:
+            python-version: "3.11"
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            pip install -r requirements-dev.txt
+        - name: Lint with ruff
+          run: ruff .
+        - name: Check formatting with black
+          run: black . --check --verbose
+        - name: Run unit tests
+          run: |
+            pytest

.gitignore

@@ -0,0 +1,3 @@
+.venv
+__pycache__
+.coverage

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.0
+    hooks:
+    -   id: ruff
+-   repo: https://github.com/psf/black
+    rev: 23.9.1
+    hooks:
+    -   id: black

CHANGELOG.md

@@ -0,0 +1,13 @@
+## [project-title] Changelog
+
+<a name="x.y.z"></a>
+# x.y.z (yyyy-mm-dd)
+
+*Features*
+* ...
+
+*Bug Fixes*
+* ...
+
+*Breaking Changes*
+* ...

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to [project-title]
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+ - [Code of Conduct](#coc)
+ - [Issues and Bugs](#issue)
+ - [Feature Requests](#feature)
+ - [Submission Guidelines](#submit)
+
+## <a name="coc"></a> Code of Conduct
+Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+
+## <a name="issue"></a> Found an Issue?
+If you find a bug in the source code or a mistake in the documentation, you can help us by
+[submitting an issue](#submit-issue) to the GitHub Repository. Even better, you can
+[submit a Pull Request](#submit-pr) with a fix.
+
+## <a name="feature"></a> Want a Feature?
+You can *request* a new feature by [submitting an issue](#submit-issue) to the GitHub
+Repository. If you would like to *implement* a new feature, please submit an issue with
+a proposal for your work first, to be sure that we can use it.
+
+* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr).
+
+## <a name="submit"></a> Submission Guidelines
+
+### <a name="submit-issue"></a> Submitting an Issue
+Before you submit an issue, search the archive, maybe your question was already answered.
+
+If your issue appears to be a bug, and hasn't been reported, open a new issue.
+Help us to maximize the effort we can spend fixing issues and adding new
+features, by not reporting duplicate issues.  Providing the following information will increase the
+chances of your issue being dealt with quickly:
+
+* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
+* **Version** - what version is affected (e.g. 0.1.2)
+* **Motivation for or Use Case** - explain what are you trying to do and why the current behavior is a bug for you
+* **Browsers and Operating System** - is this a problem with all browsers?
+* **Reproduce the Error** - provide a live example or a unambiguous set of steps
+* **Related Issues** - has a similar issue been reported before?
+* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
+  causing the problem (line of code or commit)
+
+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].
+
+### <a name="submit-pr"></a> Submitting a Pull Request (PR)
+Before you submit your Pull Request (PR) consider the following guidelines:
+
+* Search the repository (https://github.com/[organization-name]/[repository-name]/pulls) for an open or closed PR
+  that relates to your submission. You don't want to duplicate effort.
+
+* Make your changes in a new git fork:
+
+* Commit your changes using a descriptive commit message
+* Push your fork to GitHub:
+* In GitHub, create a pull request
+* If we suggest changes then:
+  * Make the required updates.
+  * Rebase your fork and force push to your GitHub repository (this will update your Pull Request):
+
+    ```shell
+    git rebase master -i
+    git push -f
+    ```
+
+That's it! Thank you for your contribution!

LICENSE.md

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

README.md

@@ -0,0 +1,76 @@
+# Python project template
+
+This is a template repository for any Python project that comes with the following dev tools:
+
+* `ruff`: identifies many errors and style issues (`flake8`, `isort`, `pyupgrade`)
+* `black`: auto-formats code
+
+Those checks are run as pre-commit hooks using the `pre-commit` library.
+
+It includes `pytest` for testing plus the `pytest-cov` plugin to measure coverage.
+
+The checks and tests are all run using Github actions on every pull request and merge to main.
+
+This repository is setup for Python 3.11. To customize that, change the `VARIANT` argument in `.devcontainer/devcontainer.json`, change the config options in `.precommit-config.yaml` and change the version number in `.github/workflows/python.yaml`.
+
+## Development instructions
+
+## With devcontainer
+
+This repository comes with a devcontainer (a Dockerized Python environment). If you open it in Codespaces, it should automatically initialize the devcontainer.
+
+Locally, you can open it in VS Code with the Dev Containers extension installed.
+
+## Without devcontainer
+
+If you can't or don't want to use the devcontainer, then you should first create a virtual environment:
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Then install the dev tools and pre-commit hooks:
+
+```
+python3 -m pip install --user -r requirements-dev.txt
+pre-commit install
+```
+
+## Adding code and tests
+
+This repository starts with a very simple `main.py` and a test for it at `tests/main_test.py`.
+You'll want to replace that with your own code, and you'll probably want to add additional files
+as your code grows in complexity.
+
+When you're ready to run tests, run:
+
+```
+python3 -m pytest
+```
+
+# File breakdown
+
+Here's a short explanation of each file/folder in this template:
+
+* `.devcontainer`: Folder containing files used for setting up a devcontainer
+  * `devcontainer.json`: File configuring the devcontainer, includes VS Code settings
+  * `Dockerfile`: File with commands to build the devcontainer's Docker image
+* `.github`: Folder for Github-specific files and folders
+  * `workflows`: Folder containing Github actions config files
+    * `python.yaml`: File configuring Github action that runs tools and tests
+* `tests`: Folder containing Python tests
+  * `main_test.py`: File with pytest-style tests of main.py
+* `.gitignore`: File describing what file patterns Git should never track
+* `.pre-commit-config.yaml`: File listing all the pre-commit hooks and args
+* `main.py`: The main (and currently only) Python file for the program
+* `pyproject.toml`: File configuring most of the Python dev tools
+* `README.md`: You're reading it!
+* `requirements-dev.txt`: File listing all PyPi packages required for development
+* `requirements.txt`: File listing all PyPi packages required for production
+
+For a longer explanation, read [this blog post](http://blog.pamelafox.org/2022/09/how-i-setup-python-project.html).
+
+# 🔎 Found an issue or have an idea for improvement?
+
+Help me make this template repository better by letting us know and opening an issue!

main.py

@@ -0,0 +1,2 @@
+def add_numbers(a, b):
+    return a + b