Updated Contributing and readme for contribution pause.
This commit is contained in:
BethanyG
268
CONTRIBUTING.md
268
CONTRIBUTING.md
@@ -3,68 +3,66 @@
|
||||
<img align="left" width="90" height="90" src="https://github.com/exercism/website-icons/blob/main/tracks/python.svg">
|
||||
<p vertical-align="middle"><h1>Contributing</h1></p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
|
||||
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.
|
||||
[](https://forum.exercism.org)
|
||||
[](https://exercism.org)
|
||||
[](https://exercism.org/blog/freeing-our-maintainers)
|
||||
[](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22)
|
||||
|
||||
<br>
|
||||
|
||||
<img align="left" width="100" height="90" src="https://github.com/exercism/website-icons/blob/main/exercism/logo-big-bordered.png">
|
||||
|
||||
🌟🌟 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]
|
||||
Hi. 👋🏽 👋 **We are happy you are here.** 🎉 🌟
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<br>
|
||||
<img align="left" width="85" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/word-search.svg">
|
||||
<img align="left" width="90" height="85" src="https://github.com/exercism/website-icons/blob/main/exercises/health-statistics.svg">
|
||||
|
||||
✨ 🦄 _**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]._)
|
||||
We 💛 💙 our community.
|
||||
**`But our maintainers are not accepting community contributions at this time.`**
|
||||
Please read this [community blog post](https://exercism.org/blog/freeing-our-maintainers) for details.
|
||||
|
||||
</tr>
|
||||
</table>
|
||||
<br>
|
||||
|
||||
**`exercism/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.7` - `3.10.6`.
|
||||
Exceptions to this support are noted where they occur.
|
||||
🌟 Track tooling (_test-runner, representer, analyzer, and Continuous Integration_) runs on Python `3.10.6`.
|
||||
|
||||
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.
|
||||
|
||||
<br>
|
||||
|
||||
## 🐛 **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 (❗ ).
|
||||
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.
|
||||
While contributions are paused, we ask that you [`open a thread in our community forum`](https://forum.exercism.org) to let us know what you have found/suggest.
|
||||
|
||||
<br>
|
||||
|
||||
## 🚧 **Did you write a patch that fixes a bug?**
|
||||
_Before you get started, please review [Pull Requests][prs]._
|
||||
## 🚧 **Did you write a patch that fixes a bug?**
|
||||
|
||||
**`Our maintainers are not accepting community contributions at this time.`**
|
||||
Please read this [community blog post](https://exercism.org/blog/freeing-our-maintainers) for details.
|
||||
|
||||
💛 💙 **We Warmly Welcome Pull Requests that are:**
|
||||
Once the pause ends, we will **happily** consider your PR.
|
||||
Until that time, all PRs from the larger community will be **automatically closed** with a note.
|
||||
|
||||
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._
|
||||
We're leaving the general contributing docs below for our long-term collaborators and maintainers.
|
||||
|
||||
<br>
|
||||
<img align="left" width="90" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/hello-world.svg">
|
||||
<p vertical-align="middle"><h2>In General</h2></p>
|
||||
<img align="left" width="80" height="75" src="https://github.com/exercism/website-icons/blob/main/exercises/hello-world.svg">
|
||||
<p vertical-align="middle"><h2 id="in-general">In General</h2></p>
|
||||
<br>
|
||||
|
||||
- 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.
|
||||
@@ -78,62 +76,47 @@ When in doubt, 📛 [ Open an issue ][open-an-issue]📛 . We wil
|
||||
- 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.
|
||||
- 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.
|
||||
- Continuous Integration is going to run **a lot** of checks. Pay attention to failures & try to understand and fix them.
|
||||
|
||||
<br>
|
||||
|
||||
<details>
|
||||
<summary>⚠️ <b><em>Pre-Commit Checklist</em></b> ⚠️</summary>
|
||||
<br>
|
||||
<table>
|
||||
<td>
|
||||
<br>
|
||||
|
||||
- [ ] 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.
|
||||
1. Run [`configlet-lint`][configlet-lint] if the track [config.json](config-json) has been modified.
|
||||
2. Run [Prettier][prettier] on all markdown files.
|
||||
3. (_Optionally_) run [yapf][yapf] ([_config file_][.style.yapf]) to help format your code, and give you a head start on making the linters happy.
|
||||
4. Run [flake8][flake8] ([_config file_][.flake8]) & [pylint][pylint] ([_config file_][pylintrc]) to ensure all Python code files conform to general code style standards.
|
||||
5. Run `test/check-exercises.py [EXERCISE]` to check if your test changes function correctly.
|
||||
6. Run the `example.py` or `exemplar.py` file against the exercise test file to ensure that it passes without error.
|
||||
7. If you modified or created a `hints.md` file for a practice exercise, [regenerate](#generating-practice-exercise-documents) it.
|
||||
|
||||
</td>
|
||||
</table>
|
||||
</details>
|
||||
</details>
|
||||
<br>
|
||||
|
||||
<img align="left" width="90" height="80" src="https://github.com/exercism/website-icons/blob/main/exercism/logo-big-bordered.png">
|
||||
<p vertical-align="middle"><h2 id="prose-writing-style-and-standards">Prose Writing Style and Standards</h2></p>
|
||||
<br>
|
||||
<img align="left" width="60" height="50" src="https://user-images.githubusercontent.com/5923094/204436863-2ebf34d1-4b16-486b-9e0a-add36f4c09c1.svg">
|
||||
<p vertical-align="middle"><h2 id="prose-writing-style-and-standards">Prose Writing Style & Standards</h2></p>
|
||||
|
||||
<br>
|
||||
|
||||
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].
|
||||
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.
|
||||
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]. ✨
|
||||
|
||||
|
||||
<br>
|
||||
<img align="left" width="70" height="65" src="https://github.com/exercism/website-icons/blob/main/tracks/python.svg">
|
||||
<p vertical-align="middle"><h2 id="coding-standards">Coding Standards</h2></p>
|
||||
<p vertical-align="middle"><h2 id="coding-standars">Coding Standards</h2></p>
|
||||
|
||||
<br>
|
||||
|
||||
1. We follow [PEP8][PEP8] (["For Humans" version here][pep8-for-humans]).
|
||||
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.
|
||||
@@ -153,7 +136,7 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
|
||||
- **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.
|
||||
- **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.
|
||||
@@ -162,20 +145,20 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
|
||||
- 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.
|
||||
- Two lines between `Classes`, one line between `functions`. Other vertical whitespace as needed to help readability.
|
||||
- Always use an **`EOL`** to end a file.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Test File Style (<em>concept exercises</em>)<a name="Test-File_style"></summary>
|
||||
<summary>Test File Style (<em>concept exercises</em>)</summary>
|
||||
<br>
|
||||
|
||||
- [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 `<ExerciseSlug>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.
|
||||
- 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].
|
||||
@@ -184,20 +167,19 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
|
||||
- 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.
|
||||
- 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=<task-number-here>)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example.
|
||||
- We prefer **test data files** when test inputs/outputs are verbose.
|
||||
- We prefer **test data files** when test inputs/ouputs 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()`.
|
||||
- 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=<check-name>`][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.
|
||||
- Where necessary, deploy the [`#noqa`][flake8-noqa] or [`#pylint disable=<check-name>`][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.
|
||||
|
||||
</details>
|
||||
<br>
|
||||
@@ -205,30 +187,28 @@ Our documents use [Markdown][markdown-language], with certain [alterations][exer
|
||||
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! 🌈
|
||||
_We know it, and trust us, we are working on fixing it._ But if you see 👀 something, 👄 say something. It'll motivate us to fix it! 🌈
|
||||
|
||||
<br>
|
||||
|
||||
<img align="left" width="70" height="65" src="https://github.com/exercism/website-icons/blob/main/tracks/python.svg">
|
||||
<p vertical-align="middle"><h2>Python Versions</h2></p>
|
||||
<p vertical-align="middle"><h2>Language Versions</h2></p>
|
||||
|
||||
<br>
|
||||
|
||||
This track officially supports Python = `3.8`
|
||||
The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.9-slim`.
|
||||
This track officially supports Python `3.7 - 3.10.6` for students completing exercises.
|
||||
The track `test runner`, `analyzer`, and `representer` run in docker on `python:3.10.6-slim`.
|
||||
|
||||
- All exercises should be written for compatibility with Python = `3.8` or `3.9`.
|
||||
- Version backward _incompatibility_ (*e.g* an exercise using a `3.8` or `3.9` **only** feature) should be clearly noted in any exercise hits, links, introductions or other notes.
|
||||
Although the majority of test cases are written using `unittest.TestCase`,
|
||||
|
||||
- Here is an example of how the Python documentation handles [version-tagged 🏷 ][version-tagged-language-features] feature introduction.
|
||||
- All exercises should be written for compatibility with Python `3.7` - `3.10.6`.
|
||||
- Version backward _incompatibility_ (_e.g_ an exercise using features introduced in `3.8`, `3.9`, or `3.10`) should be clearly noted in any exercise hints, links, introductions or other notes.
|
||||
|
||||
- _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python `2.7+`.
|
||||
- Please do not change existing exercises to add new language features without consulting with a maintainer first.
|
||||
- We 💛 💙 modern Python, but we _also_ want to avoid student confusion when it comes to which Python versions support brand-new features.
|
||||
- Here is an example of how the Python documentation handles [version-tagged 🏷 ][version-tagged-language-features] feature introduction.
|
||||
|
||||
- All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers.
|
||||
- _Most_ exercises will work with Python `3.6+`, and _many_ are compatible with Python `2.7+`. Please do not change existing exercises to add new language features without consulting with a maintainer first. We 💛 💙 modern Python, but we _also_ want to avoid student confusion when it comes to which Python versions support brand-new features.
|
||||
|
||||
<br>
|
||||
* All test suites and example solutions must work in all Python versions that we currently support. When in doubt about a feature, please check with maintainers.
|
||||
|
||||
<br>
|
||||
|
||||
@@ -237,22 +217,19 @@ The track `test runner`, `analyzer`, and `representer` run in docker on `python:
|
||||
|
||||
<br>
|
||||
|
||||
- Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the Command line Interface.
|
||||
- Each exercise must be self-contained. Please do not use or reference files that reside outside the given exercise directory. "Outside" files will not be included if a student fetches the exercise via the CLI.
|
||||
|
||||
- Each exercise/problem should include
|
||||
- a complete test suite,
|
||||
- an example/exemplar solution,
|
||||
- a stub file ready for student implementation.
|
||||
- Each exercise/problem should include a complete test suite, an example/exemplar solution, and a stub file ready for student implementation.
|
||||
|
||||
- For specifications, refer to the links below, depending on which type of exercise you are contributing to.
|
||||
- [Concept Exercise Anatomy][concept-exercise-anatomy]
|
||||
- [Practice Exercise Anatomy][practice-exercise-anatomy]
|
||||
- For specifications, refer to [Concept Exercise Anatomy][concept-exercise-anatomy], or [Practice Exercise Anatomy][practice-exercise-anatomy] depending on which type of exercise you are contributing to.
|
||||
|
||||
- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository.
|
||||
|
||||
- **Practice exercise**, descriptions and instructions come from a centralized, cross-track [problem specifications][problem-specifications] repository.
|
||||
- Any updates or changes need to be proposed/approved in `problem-specifications` first.
|
||||
- If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository.
|
||||
- If Python-specific changes become necessary, they need to be appended to the canonical instructions by creating a `instructions.append.md` file in this (`exercism/Python`) repository.
|
||||
|
||||
- Practice Exercise **Test Suits** for many practice exercises are similarly [auto-generated](#auto-generated-files) from data in [problem specifications][problem-specifications].
|
||||
|
||||
- Any changes to them need to be proposed/discussed in the `problem-specifications` repository and approved by **3 track maintainers**, since changes could potentially affect many (_or all_) exercism language tracks.
|
||||
- If Python-specific test changes become necessary, they can be appended to the exercise `tests.toml` file.
|
||||
- 📛 [ **Please file an issue**][open-an-issue] 📛 and check with maintainers before adding any Python-specific tests.
|
||||
@@ -265,18 +242,18 @@ The track `test runner`, `analyzer`, and `representer` run in docker on `python:
|
||||
</summary>
|
||||
<br>
|
||||
|
||||
- [ ] `.docs/hints.md`
|
||||
- [ ] `.docs/instructions.md`
|
||||
- [ ] `.docs/introduction.md`
|
||||
- [ ] `.meta/config.json`
|
||||
- [ ] `.meta/design.md`
|
||||
- [ ] `.meta/exemplar.py` (_exemplar solution_)
|
||||
- [ ] `<exercise-slug>_test.py` (_test file_)
|
||||
- [ ] `<exercise-slug>.py` (_stub file_)
|
||||
- [ ] `concepts/../introduction.md`
|
||||
- [ ] `concepts/../about.md`
|
||||
- [ ] `concepts/../links.json`
|
||||
- [ ] `concepts/../.meta/config.json`
|
||||
- [ ] `.docs/hints.md`
|
||||
- [ ] `.docs/instructions.md`
|
||||
- [ ] `.docs/introduction.md`
|
||||
- [ ] `.meta/config.json`
|
||||
- [ ] `.meta/design.md`
|
||||
- [ ] `.meta/exemplar.py` (_exemplar solution_)
|
||||
- [ ] `<exercise-slug>_test.py` (_test file_)
|
||||
- [ ] `<exercise-slug>.py` (_stub file_)
|
||||
- [ ] `concepts/../introduction.md`
|
||||
- [ ] `concepts/../about.md`
|
||||
- [ ] `concepts/../links.json`
|
||||
- [ ] `concepts/../.meta/config.json`
|
||||
|
||||
</details>
|
||||
|
||||
@@ -286,50 +263,46 @@ The track `test runner`, `analyzer`, and `representer` run in docker on `python:
|
||||
</summary>
|
||||
<br>
|
||||
|
||||
- [ ] `.docs/instructions.md`(**required**)
|
||||
- [ ] `.docs/introduction.md`(_optional_)
|
||||
- [ ] `.docs/introduction.append.md`(_optional_)
|
||||
- [ ] `.docs/instructions.append.md` (_optional_)
|
||||
- [ ] `.docs/hints.md`(_optional_)
|
||||
- [ ] `.meta/config.json` (**required**)
|
||||
- [ ] `.meta/example.py` (**required**)
|
||||
- [ ] `.meta/design.md` (_optional_)
|
||||
- [ ] `.meta/template.j2` (_template for generating tests from canonical data_)
|
||||
- [ ] `.meta/tests.toml` (_tests configuration from canonical data_)
|
||||
- [ ] `<exercise-slug>_test.py` (_**auto-generated from canonical data**_)
|
||||
- [ ] `<exercise-slug>.py` (**required**)
|
||||
- [ ] `.docs/instructions.md`(**required**)
|
||||
- [ ] `.docs/introduction.md`(_optional_)
|
||||
- [ ] `.docs/introduction.append.md`(_optional_)
|
||||
- [ ] `.docs/instructions.append.md` (_optional_)
|
||||
- [ ] `.docs/hints.md`(_optional_)
|
||||
- [ ] `.meta/config.json` (**required**)
|
||||
- [ ] `.meta/example.py` (**required**)
|
||||
- [ ] `.meta/design.md` (_optional_)
|
||||
- [ ] `.meta/template.j2` (_template for generating tests from cannonical data_)
|
||||
- [ ] `.meta/tests.toml` (_tests configuration from cannonical data_)
|
||||
- [ ] `<exercise-slug>_test.py` (_**auto-generated from cannonical data**_)
|
||||
- [ ] `<exericse-slug>.py` (**required**)
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
<br>
|
||||
<img align="left" width="80" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/anagrams.svg">
|
||||
<p vertical-align="middle"><h2>External Libraries and Dependencies</h2></p>
|
||||
|
||||
<br>
|
||||
|
||||
Our tooling (_runners, representers, and analyzers_) runs in isolated containers within the exercism website. Because of this isolation, exercises cannot rely on third-party or external libraries. Any library needed for an exercise or exercise tests must be incorporated as part of a tooling build, and noted for students who are using the CLI to solve problems locally.
|
||||
Our tooling (_runners, analyzers and representers_) runs in isolated containers within the exercism website. Because of this, **exercises cannot rely on third-party or external libraries.** Any library needed for an exercise or exercise tests must be incorporated as part of the tooling build, and noted for students who are using the CLI to solve problems locally.
|
||||
|
||||
If your exercise depends on a third-party library (_aka not part of standard Python_), please consult with maintainers about it. We may or may not be able to accommodate the package.
|
||||
If your exercise depends on a third-party library (_aka not part of standard Python_), please consult with maintainers about it. We may or may not be able to accommodate the package.
|
||||
|
||||
<br>
|
||||
<img id="auto-generated-files" align="left" width="85" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/forth.svg">
|
||||
<img id="auto-generated-files" align="left" width="95" height="90" src="https://github.com/exercism/website-icons/blob/main/exercises/forth.svg">
|
||||
<p vertical-align="middle"><h2>Auto-Generated Test Files and Test Templates</h2></p>
|
||||
|
||||
<br>
|
||||
|
||||
[**Practice exercises**][practice-exercise-files] inherit their definitions from the [problem-specifications][problem-specifications] repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are then machine-generated for each language track.
|
||||
[**Practice exercises**][practice-exercise-files] inherit their definitions from the [problem-specifications][problem-specifications] repository in the form of _description files_. Exercise introductions, instructions and (_in the case of **many**, but not **all**_) test files are then machine-generated for each language track.
|
||||
|
||||
Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications][problem-specifications] and approved by **3 track maintainers**. After an exercise change has gone through that process , related documents and tests for the Python track will need to be [re-generated](#generating-practice-exercise-documents) via [configlet][configlet]. Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks.
|
||||
Changes to practice exercise _specifications_ should be raised/PR'd in [problem-specifications][problem-specifications] and approved by **3 track maintainers**. After an exercise change has gone through that process, related documents and tests for the Python track will need to be [re-generated](#generating-practice-exercise-documents) via [configlet][configlet]. Configlet is also used as part of the track CI, essential track and exercise linting, and other verification tasks.
|
||||
|
||||
If a practice exercise has an auto-generated `<exercise_slug>_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation.
|
||||
If a practice exercise has an auto-generated `<exercise_slug>_test.py` file, there will be a `.meta/template.j2` and a `.meta/tests.toml` file in the exercise directory. If an exercise implements Python track-specific tests, there may be a `.meta/additional_tests.json` to define them. These `additional_tests.json` files will automatically be included in test generation.
|
||||
|
||||
_Exercise Structure with Auto-Generated Test Files_
|
||||
|
||||
```Graphql
|
||||
```Bash
|
||||
[<exercise-slug>/
|
||||
├── .docs
|
||||
│ └── instructions.md
|
||||
@@ -341,9 +314,10 @@ _Exercise Structure with Auto-Generated Test Files_
|
||||
├── <exercise_slug>.py #stub file
|
||||
└── <exercise_slug_test.py #test file
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
Practice exercise `<exercise_slug>_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator].
|
||||
Practice exercise `<exercise_slug>_test.py` files are generated/regenerated via the [Python Track Test Generator][python-track-test-generator].
|
||||
Please reach out to a maintainer if you need any help with the process.
|
||||
|
||||
<br>
|
||||
@@ -361,6 +335,7 @@ If an unimplemented exercise does not have a `canonical-data.json` file, the tes
|
||||
<br>
|
||||
|
||||
**Example solution files serve two purposes only:**
|
||||
|
||||
1. Verification of the tests
|
||||
2. Example implementation for mentor/student reference
|
||||
|
||||
@@ -376,7 +351,7 @@ Implementing Track-specific Practice Exercises is similar to implementing a `can
|
||||
|
||||
<br>
|
||||
|
||||
<p verticle-align="middle"><img id="generating-practice-exercise-documents" align="left" width="70" height="70" src="https://github.com/exercism/website-icons/blob/main/exercises/rest-api.svg"><h2>Generating Practice Exercise Documents</h2></p>
|
||||
<p verticle-align="middle"><img id="generating-practice-exercise-documents" align="left" width="75" height="75" src="https://github.com/exercism/website-icons/blob/main/exercises/rest-api.svg"><h2>Generating Practice Exercise Documents</h2></p>
|
||||
<br>
|
||||
<b>You will need</b>
|
||||
|
||||
@@ -388,6 +363,7 @@ Implementing Track-specific Practice Exercises is similar to implementing a `can
|
||||
```bash
|
||||
configlet generate <path/to/track> --spec-path path/to/problem/specifications --only example-exercise
|
||||
```
|
||||
|
||||
<p><b>For all Practice Exercises</b><p><img id="regenerating-all-practice-exercise-documents" align="left" width="45" height="45" src="https://github.com/exercism/website-icons/blob/main/exercises/doubly-linked-list.svg"></p>
|
||||
|
||||
```bash
|
||||
@@ -396,12 +372,8 @@ configlet generate <path/to/track> --spec-path path/to/problem/specifications
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
[.flake8]: https://github.com/exercism/python/blob/main/.flake8
|
||||
[.style.yapf]: https://github.com/exercism/python/blob/main/.style.yapf
|
||||
[EOL]: https://en.wikipedia.org/wiki/Newline
|
||||
[PEP8]: https://www.python.org/dev/peps/pep-0008/
|
||||
[american-english]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md
|
||||
[being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member
|
||||
[card-games-testfile]: https://github.com/exercism/python/blob/main/exercises/concept/card-games/lists_test.py
|
||||
@@ -409,10 +381,12 @@ configlet generate <path/to/track> --spec-path path/to/problem/specifications
|
||||
[concept-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md
|
||||
[concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md
|
||||
[config-json]: https://github.com/exercism/javascript/blob/main/config.json
|
||||
[configlet-general]: https://github.com/exercism/configlet
|
||||
[configlet-lint]: https://github.com/exercism/configlet#configlet-lint
|
||||
[configlet]: https://github.com/exercism/docs/blob/main/building/configlet/generating-documents.md
|
||||
[distinguishing-test-iterations]: https://docs.python.org/3/library/unittest.html#distinguishing-test-iterations-using-subtests
|
||||
[enumerate]: https://docs.python.org/3/library/functions.html#enumerate
|
||||
[eol]: https://en.wikipedia.org/wiki/Newline
|
||||
[exercise-config-json]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md#full-example
|
||||
[exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md
|
||||
[exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md
|
||||
@@ -437,12 +411,12 @@ configlet generate <path/to/track> --spec-path path/to/problem/specifications
|
||||
[markdown-language]: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf
|
||||
[open-an-issue]: https://github.com/exercism/python/issues/new/choose
|
||||
[pep8-for-humans]: https://pep8.org/
|
||||
[pep8]: https://www.python.org/dev/peps/pep-0008/
|
||||
[practice-exercise-anatomy]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md
|
||||
[practice-exercise-files]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md#exercise-files
|
||||
[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md
|
||||
[prettier]: https://prettier.io/
|
||||
[problem-specifications]: https://github.com/exercism/problem-specifications
|
||||
[prs]: https://github.com/exercism/docs/blob/main/community/good-member/pull-requests.md
|
||||
[pylint-disable-check]: https://pylint.pycqa.org/en/latest/user_guide/message-control.html#block-disables
|
||||
[pylint]: https://pylint.pycqa.org/en/v2.11.1/user_guide/index.html
|
||||
[pylintrc]: https://github.com/exercism/python/blob/main/pylintrc
|
||||
|
||||
91
README.md
91
README.md
@@ -3,66 +3,68 @@
|
||||
<img align="left" width="90" height="90" src="https://github.com/exercism/website-icons/blob/main/tracks/python.svg">
|
||||
<p vertical-align="middle"><h1>Exercism Python Track</h1></p>
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
[](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22)
|
||||
[](https://forum.exercism.org)
|
||||
[](https://exercism.org)
|
||||
[](https://exercism.org/blog/freeing-our-maintainers)
|
||||
[](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22)
|
||||
|
||||
<br>
|
||||
|
||||
Hi. 👋🏽 👋 **We are happy you are here.** 🎉 🌟
|
||||
|
||||
<br>
|
||||
|
||||
**`exercism/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.
|
||||
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`.
|
||||
🌟 Track exercises support Python `3.7` - `3.10.6`.
|
||||
Exceptions to this support are noted where they occur.
|
||||
🌟 Track tooling (_test-runner, representer, analyzer, and Continuous Integration_) runs on Python `3.10.6`.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
<br><br>
|
||||
|
||||
<div>
|
||||
<span>
|
||||
<img align="left" height="60" width="85" src="https://user-images.githubusercontent.com/5923094/204436863-2ebf34d1-4b16-486b-9e0a-add36f4c09c1.svg">
|
||||
</span>
|
||||
<span align="left">
|
||||
|
||||
🌟🌟 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].
|
||||
|
||||
Some defined roles in our community: [Contributors][exercism-contributors] **|** [Mentors][exercism-mentors] **|** [Maintainers][exercism-track-maintainers] **|** [Admins][exercism-admins]
|
||||
|
||||
</span></div>
|
||||
|
||||
<br>
|
||||
<img align="left" width="90" height="85" src="https://github.com/exercism/website-icons/blob/main/exercises/health-statistics.svg">
|
||||
|
||||
We 💛 💙 our community.
|
||||
**`But our maintainers are not accepting community contributions at this time.`**
|
||||
Please read this [community blog post](https://exercism.org/blog/freeing-our-maintainers) for details.
|
||||
|
||||
<br>
|
||||
<img align="left" width="95" height="85" src="https://github.com/exercism/website-icons/blob/main/exercises/boutique-suggestions.svg">
|
||||
|
||||
Here to suggest a new feature or new exercise?? **Hooray!** 🎉
|
||||
We'd love if you did that via our [Exercism Community Forum](https://forum.exercism.org/). Please keep in mind [Chesterton's Fence][chestertons-fence].
|
||||
_Thoughtful suggestions will likely result faster & more enthusiastic responses from volunteers._
|
||||
|
||||
<br>
|
||||
|
||||
<img align="left" width="100" height="90" src="https://github.com/exercism/website-icons/blob/main/exercism/logo-big-bordered.png">
|
||||
|
||||
🌟🌟 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]
|
||||
|
||||
<br>
|
||||
<img align="left" width="85" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/two-fer.svg">
|
||||
|
||||
We 💛 💙 Pull Requests. **But our maintainers generally can't accept _unsolicited_ PRs.**
|
||||
Check our [help wanted][open-issues] list or [open an issue ][open-an-issue] for discussion first.
|
||||
We ✨💙 💛 💙 ✨ [PRs][prs] that follow our **[Contributing Guidelines][contributing-guidelines]**.
|
||||
|
||||
|
||||
<br>
|
||||
<img align="left" width="85" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/word-search.svg">
|
||||
|
||||
✨ 🦄 _**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] (_✨ version in [contributing][website-contributing-section] on exercism.org_)
|
||||
|
||||
<br>
|
||||
<img align="left" width="85" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/bomb-defuser.svg">
|
||||
|
||||
If you are here to help out with [open issues][open-issues], you have our gratitude 🙌 🙌🏽.
|
||||
Anything with [`help wanted`] and without a [`Claimed`] tag is up for grabs.
|
||||
Comment on the issue and we will reserve it for you. 🌈 ✨
|
||||
|
||||
<br>
|
||||
<img align="left" width="90" height="80" src="https://github.com/exercism/website-icons/blob/main/exercises/boutique-suggestions.svg">
|
||||
|
||||
Here to suggest a new feature or new exercise?? **Hooray!** 🎉
|
||||
Please keep in mind [Chesterton's Fence][chestertons-fence].
|
||||
_Thoughtful suggestions will likely result faster & more enthusiastic responses from maintainers._
|
||||
|
||||
<br>
|
||||
<br><br>
|
||||
|
||||
## Python Software and Documentation
|
||||
|
||||
**Copyright © 2001-2021 Python Software Foundation. All rights reserved.**
|
||||
**Copyright © 2001-2022 Python Software Foundation. All rights reserved.**
|
||||
|
||||
Python software and documentation are licensed under the [PSF License Agreement][psf-license].
|
||||
|
||||
@@ -70,17 +72,16 @@ Starting with `Python 3.8.6`, examples, recipes, and other code in the Python do
|
||||
|
||||
Some software incorporated into Python is under different licenses. The licenses are listed with code falling under that license. See [Licenses and Acknowledgements for Incorporated Software](https://docs.python.org/3/license.html#otherlicenses) for an incomplete list of these licenses.
|
||||
|
||||
<br>
|
||||
|
||||
## Exercism Python Track License
|
||||
|
||||
This repository uses the [MIT License](/LICENSE).
|
||||
|
||||
|
||||
|
||||
[being-a-good-community-member]: https://github.com/exercism/docs/tree/main/community/good-member
|
||||
[chestertons-fence]: https://github.com/exercism/docs/blob/main/community/good-member/chestertons-fence.md
|
||||
[concept-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/concept-exercises.md
|
||||
[config-json]: https://github.com/exercism/python/blob/main/config.json
|
||||
[contributing-guidelines]: https://github.com/exercism/python/blob/main/CONTRIBUTING.md
|
||||
[exercise-presentation]: https://github.com/exercism/docs/blob/main/building/tracks/presentation.md
|
||||
[exercism-admins]: https://github.com/exercism/docs/blob/main/community/administrators.md
|
||||
[exercism-code-of-conduct]: https://exercism.org/docs/using/legal/code-of-conduct
|
||||
@@ -93,10 +94,8 @@ This repository uses the [MIT License](/LICENSE).
|
||||
[exercism-track-structure]: https://github.com/exercism/docs/tree/main/building/tracks
|
||||
[exercism-website]: https://exercism.org/
|
||||
[exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md
|
||||
[open-an-issue]: https://github.com/exercism/python/issues/new/choose
|
||||
[open-issues]: https://github.com/exercism/python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
|
||||
[prs]: https://github.com/exercism/docs/blob/main/community/good-member/pull-requests.md
|
||||
[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md
|
||||
[prs]: https://github.com/exercism/docs/blob/main/community/good-member/pull-requests.md
|
||||
[psf-license]: https://docs.python.org/3/license.html#psf-license
|
||||
[python-syllabus]: https://exercism.org/tracks/python/concepts
|
||||
[the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md
|
||||
|
||||
Reference in New Issue
Block a user