Contributing

Hi. 👋🏽 👋 **We are happy you are here.** 🎉🌟 Thank you so much for your interest in contributing! **`exercsim/Python`** is one of many programming language tracks on [exercism(dot)org][exercism-website]. This repo holds all the instructions, tests, code, & support files for Python *exercises* currently under development or implemented & available for students. 🌟 Track exercises support Python `3.8`. 🌟 Track tooling (_test-runner, representer, analyzer, and Continuous Integration_) runs on Python `3.9`. Exercises are grouped into **concept** exercises which teach the [Python syllabus][python-syllabus], and **practice** exercises, which are unlocked by progressing in the syllabus tree 🌴 . Concept exercises are constrained to a small set of language or syntax features. Practice exercises are open-ended, and can be used to practice concepts learned, try out new techniques, and _play_. These two exercise groupings can be found in the track [config.json][config-json], and under the `python/exercises` directory.

🌟🌟 If you have not already done so, please take a moment to read our [Code of Conduct][exercism-code-of-conduct]. 🌟🌟 It might also be helpful to look at [Being a Good Community Member][being-a-good-community-member] & [The words that we use][the-words-that-we-use], and [Pull Requests][prs]. Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins]

✨ 🦄 _**Want to jump directly into Exercism specifications & detail?**_ [Structure][exercism-track-structure] **|** [Tasks][exercism-tasks] **|** [Concepts][exercism-concepts] **|** [Concept Exercises][concept-exercises] **|** [Practice Exercises][practice-exercises] **|** [Presentation][exercise-presentation] [Writing Style Guide][exercism-writing-style] **|** [Markdown Specification][exercism-markdown-specification] (_ ✨ versions available in [contributing][website-contributing-section] on [exercism(dot)org][exercism-website]._)
## 🐛 **Did you find a bug?** It is not uncommon to discover typos, confusing directions, or incorrect implementations of certain tests or code examples. Or you might have a great suggestion for a hint to aid students ( 💙 ), see optimizations for exemplar or test code, find missing test cases to add, or want to correct factual and/or logical errors. Or maybe you have a great idea for an exercise or feature (❗ ). _Our track is always a work in progress!_ 🌟🌟 Please 📛 [ Open an issue ][open-an-issue]📛 , and let us know what you have found/suggest.
## 🚧 **Did you write a patch that fixes a bug?** _Before you get started, please review [Pull Requests][prs]._ 💛 💙 **We Warmly Welcome Pull Requests that are:** 1️⃣ Small, contained fixes for typos/grammar/punctuation/code syntax on [one] exercise, 2️⃣ Medium changes that have been agreed/discussed via a filed issue, 3️⃣ Contributions from our [help wanted][help-wanted] issue list, 4️⃣ Larger (_and previously agreed-upon_) contributions from recent & regular (_within the last 6 months_) contributors. When in doubt, 📛 [ Open an issue ][open-an-issue]📛 . We will happily discuss your proposed change. 🐍 _But we should talk before you take a whole lot of time or energy implementing anything._

In General

- Please make sure to have a quick read-through of our Exercism [Pull Requests][prs] document before jumping in. 😅 - Maintainers are happy to review your work and help troubleshoot with you. 💛 💙 - Requests are reviewed as soon as is practical/possible. - (❗ ) Reviewers may be in a different timezone ⌚ , or tied up 🧶 with other tasks. - **Please wait at least 72 hours before pinging.** - If you need help, comment in the Pull Request/issue. 🙋🏽‍♀️ - If you would like in-progress feedback/discussion, please mark your Pull Request as a **`[draft]`** - Pull Requests should be focused around a single exercise, issue, or change. - Pull Request titles and descriptions should make clear **what** has changed and **why**. - Please link 🔗 to any related issues the PR addresses. - 📛 [ Open an issue ][open-an-issue]📛 and discuss it with 🧰 maintainers _**before**_: - creating a Pull Request making significant or breaking changes. - for changes across multiple exercises, even if they are typos or small. - anything that is going to require doing a lot of work (_on your part or the maintainers part_). - Follow coding standards found in [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). - All files should have a proper [EOL][EOL]. This means one carriage return at the end of the final line of text files. - Otherwise, watch out ⚠️ for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines. - Continuous Integration is going to run **a lot** of checks. Try to understand & fix any failures.

⚠️ Pre-Commit Checklist ⚠️

- [ ] Update & rebase your branch with any (recent) upstream changes. - [ ] Spell and grammar check all prose changes. - [ ] Run [Prettier](https://prettier.io/) on all markdown and JSON files. - (_Optionally_) run [yapf](https://github.com/google/yapf) ([_yapf config_](https://github.com/exercism/python/blob/main/.style.yapf)) to help format your code. - [ ] Run [flake8](http://flake8.pycqa.org/) with [_flake8 config_](https://github.com/exercism/python/blob/main/.flake8) to check general code style standards. - [ ] Run [pylint](https://pylint.pycqa.org/en/v2.11.1/user_guide/index.html) with [_pylint config_](https://github.com/exercism/python/blob/main/pylintrc) to check extended code style standards. - [ ] Use pytest or the [python-track-test-runner](https://github.com/exercism/python-test-runner) to test any changed `example.py`/`exemplar.py`files against their associated test files. - [ ] Similarly, use [pytest](https://docs.pytest.org/en/6.2.x/contents.html) or the [python-track-test-runner](https://github.com/exercism/python-test-runner) to test any changed _**test**_ files. - Check that tests **fail** properly, as well as succeed. (_**e.g.**, make some tests fail on purpose to "test the tests" & failure messages_). - [ ] Double-check all files for proper EOL. - [ ] [Regenerate](https://github.com/exercism/python/blob/main/CONTRIBUTING.md#generating-practice-exercise-documents) exercise documents when you modified or created a `hints.md` file for a practice exercise. - [ ] [Regenerate the test file](https://github.com/exercism/python/blob/main/CONTRIBUTING.md#auto-generated-test-files-and-test-templates) if you modified or created a `JinJa2` template file for a practice exercise. - Run the generated test file result against its `example.py`. - [ ] Run [`configlet-lint`](https://github.com/exercism/configlet#configlet-lint) if the track [config.json](https://github.com/exercism/docs/blob/main/building/tracks/config-json.md), or any other exercise `config.json` has been modified.

Prose Writing Style and Standards

Non-code content (_exercise introductions & instructions, hints, concept write-ups, documentation etc._) should be written in [American English][american-english]. We strive to watch [the words we use][the-words-that-we-use]. When a word or phrase usage is contested/ambiguous, we default to what is best understood by our international community of learners, even if it "sounds a little weird" to a "native" American English speaker. Our documents use [Markdown][markdown-language], with certain [alterations][exercism-markdown-widgets] & [additions][exercism-internal-linking]. Here is our full [Markdown Specification][exercism-markdown-specification]. 📐 We format/lint our Markdown with [Prettier][prettier]. ✨

Coding Standards

1. We follow [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]). In particular, we (mostly) follow the [Google flavor][google-coding-style] of PEP8. 2. We use [flake8][flake8] to help us format Python code nicely. Our `flake8` config file is [.flake8][.flake8] in the top level of this repo. 3. We use [pylint][pylint] to catch what `flake8` doesn't. Our `pylint` config file is [pylintrc][pylintrc] in the top level of this repo. 4. We use [yapf][yapf] to auto-format our python files. Our `.style.yapf` config file is [.style.yapf][.style.yapf] in the top level of this repo.

General Code Style Summary

- _**spaces**_, never `Tabs` - **4 space** indentation - **120 character per line limit** (_as opposed to the default limit of 79_) - Variable, function, and method names should be `lower_case_with_underscores` (_aka "snake case"_) - Classes should be named in `TitleCase` (_aka "camel case"_) - **No single letter variable names** outside of a `lambda`. This includes loop variables and comprehensions. - Refrain from putting `list`, `tuple`, `set`, or `dict` members on their own lines. Fit as many data members as can be easily read on one line, before wrapping to a second. - If a data structure spreads to more than one line and a break (_for clarity_) is needed, prefer breaking after the opening bracket. - Avoid putting closing brackets on their own lines. Prefer closing a bracket right after the last element. - Use **`'`** and not **`"`** as the quote character by default. - Use **`"""`** for docstrings. - Prefer [implicit line joining][implicit-line-joining] for long strings. - Prefer enclosing imports in **`()`**, and putting each on their own line when importing multiple methods. - Two lines between `Classes`, one line between `functions`. Other vertical whitespace as needed to help readability. - Always use an **`EOL`** to end a file.

Test File Style (concept exercises)

- [Unittest.TestCase][unittest] syntax, with [PyTest][pytest] as a test runner. - We are transitioning to using more PyTest features/syntax, but are leaving `Unittest` syntax in place where possible. - Always check with a maintainer before introducing a PyTest feature into your tests. - Test **Classes** should be titled `Test`. **e.g.** `class CardGamesTest(unittest.TestCase):` - Test method names should begin with `test_`. Try to make test case names descriptive but not too long. - Favor [_parameterizing_][distinguishing-test-iterations] tests that only vary input data. Use [unittest.TestCase.subTest][subtest] for parameterization. - An [example from Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile]. - A second [example from Card Games][card-games-testfile]. - Avoid excessive line breaks or indentation - particularly in parameterized tests. - Excessive breaks & indentation within the `for` loops cause issues when formatting the test code for display on the website. - Use [`enumerate()`][enumerate] where possible when indexes are needed. See [Card Games][card-games-testfile] for example usage. - Favor using names like `inputs`, `data`, `input_data`, `test_data`, or `test_case_data` for test inputs. - Favor using names like `results`, `expected`, `result_data`, `expected_data`, or `expected_results` for test outcomes. - Favor putting the assert failure message outside of `self.assert()`. Name it `failure_msg`. See [Card Games][card-games-testfile] for example usage. - Favor `f-strings` for dynamic failure messages. Please make your error messages as relevant and human-readable as possible. - We relate test cases to **task number** via a custom [PyTest Marker][pytestmark]. - These take the form of `@pytest.mark.task(taskno=)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example. - We prefer **test data files** when test inputs/outputs are verbose. - These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file. - See the [Cater-Waiter][cater-waiter] exercise directory for an example of this setup. - **Test data files** need to be added under an `editor` key within [`config.json "files"`][exercise-config-json]. - Check with a maintainer if you have questions or issues, or need help with an exercise `config.json`. - For new test files going forward, omit `if __name__ == "__main__": unittest.main()`. - Lint with both `flake8` and `pylint`. - Both linters are known to toss false-positives for some testing patterns. - Where necessary, deploy the [`#noqa`][flake8-noqa] or [`#pylint disable=`][pylint-disable-check] comments to suppress false-positive warnings. - See **line 16** of [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] test file for an example of an override.

If you have any questions or issues, don't hesitate to ask the maintainers -- they're always happy to help 💛 💙 Some of our code is old and does not (yet) conform to all these standards. _**We know it, and trust us, we are working on fixing it.**_ But if you see 👀 something, 👄 say something. It will motivate us to fix it! 🌈