CONTRIBUTING.md

Contributing

                                  

Hi.  👋🏽  👋  We are happy you are here.  🎉 🌟

We 💛 💙   our community.
But our maintainers are not accepting community contributions at this time.
Please read this community blog post for details.

exercism/Python is one of many programming language tracks on exercism(dot)org.
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.11.2. Exceptions to this support are noted where they occur.
🌟   Track tooling (test-runner, representer, analyzer, and Continuous Integration) runs on Python 3.11.2.

Exercises are grouped into concept exercises which teach the 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, and under the python/exercises directory.

🐛 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! 🌟🌟
While contributions are paused, we ask that you open a thread in our community forum to let us know what you have found/suggest.

🚧 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 for details.

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.

We're leaving the general contributing docs below for our long-term collaborators and maintainers.

In General

• 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 📛  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 ("For Humans" version here).
• All files should have a proper 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. Pay attention to failures & try to understand and fix them.

⚠️  Pre-Commit Checklist ⚠️

1.  Run configlet-lint if the track config.json has been modified.
2.  Run Prettier on all markdown files.
3.  (Optionally) run yapf (config file) to help format your code, and give you a head start on making the linters happy.
4.  Run flake8 (config file) & pylint (config file) 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 it.

Prose Writing Style & Standards

Non-code content (exercise introductions & instructions, hints, concept write-ups, documentation etc.) should be written in American English. We strive to watch the words 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, with certain alterations & additions. Here is our full Markdown Specification.  📐 We format/lint our Markdown with Prettier. ✨

Coding Standards

1. We follow PEP8 ("For Humans" version here). In particular, we (mostly) follow the Google flavor of PEP8.
2. We use flake8 to help us format Python code nicely. Our flake8 config file is .flake8 in the top level of this repo.
3. We use pylint to catch what flake8 doesn't. Our pylint config file is pylintrc in the top level of this repo.
4. We use yapf to auto-format our python files. Our .style.yapf config file is .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 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 syntax, with 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.
• Favor parameterizing tests that only vary input data. Use unittest.TestCase.subTest for parameterization.
  • An example from Guido's Gorgeous Lasagna.
  • A second example from Card Games.
• 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() where possible when indexes are needed. See Card Games 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 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.
  • These take the form of @pytest.mark.task(taskno=<task-number-here>). See Guido's Gorgeous Lasagna 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 exercise directory for an example of this setup.
  • Test data files need to be added under an editor key within config.json "files".
  • 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 or #pylint disable=<check-name> comments to suppress false-positive warnings. - See line 16 of Guido's Gorgeous Lasagna 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'll motivate us to fix it! 🌈

Language Versions

This track officially supports Python 3.7 - 3.11.2 for students completing exercises.
The track test runner, analyzer, and representer run in docker on python:3.11.2-slim.

Although the majority of test cases are written using unittest.TestCase,

• All exercises should be written for compatibility with Python 3.7 - 3.11.2.

• 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.

• Here is an example of how the Python documentation handles version-tagged  🏷  feature introduction.

• 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.

• 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.

A Little More on Exercises

• 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, and a stub file ready for student implementation.

• For specifications, refer to Concept Exercise Anatomy, or 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 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.

• Practice Exercise Test Suits for most practice exercises are similarly auto-generated from data in 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 📛  and check with maintainers before adding any Python-specific tests.
  
  
  
  ✅   Concept Exercise Checklist

  
  

  • .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
  ✅   Practice Exercise Checklist

  
  

  • .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)
  • <exericse-slug>.py (required)

External Libraries and Dependencies

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.

Auto-Generated Test Files and Test Templates

Practice exercises inherit their definitions from the 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 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 via 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.

Exercise Structure with Auto-Generated Test Files

[<exercise-slug>/
├── .docs
│   └── instructions.md
├── .meta
│   ├── config.json
│   ├── example.py
│   ├── template.j2
│   └── tests.toml
├── <exercise_slug>.py #stub file
└── <exercise_slug_test.py #test file

Practice exercise <exercise_slug>_test.py files are generated/regenerated via the Python Track Test Generator.
Please reach out to a maintainer if you need any help with the process.

Implementing Practice Exercise Tests

If an unimplemented exercise has a canonical-data.json file in the problem-specifications repository, a generation template must be created. See the Python track test generator documentation for more information.

If an unimplemented exercise does not have a canonical-data.json file, the test file must be written manually.

Implementing Practice Exercise Example Solutions

Example solution files serve two purposes only:

1. Verification of the tests
2. Example implementation for mentor/student reference

Unlike concept exercise, practice exercise example.py files are NOT intended as as a "best practice" or "standard".
They are provided as proof that there is an acceptable and testable answer to the practice exercise.

Implementing Track-specific Practice Exercises

Implementing Track-specific Practice Exercises is similar to implementing a canonical exercise that has no canonical-data.json. But in addition to the tests, the exercise documents (instructions, etc.) will also need to be written manually. Carefully follow the structure of generated exercise documents and the exercism practice exercise specification.

Generating Practice Exercise Documents

You will need

1.  A local clone of the problem-specifications repository.
2.  configlet

For Individual Exercises

configlet generate <path/to/track> --spec-path path/to/problem/specifications --only example-exercise

For all Practice Exercises

configlet generate <path/to/track> --spec-path path/to/problem/specifications