python/CONTRIBUTING.md

Contributing

Hi.  👋🏽  👋  

Thank you so much for your interest in contributing to the Python track! We are happy you are here. 🌟   🎉

exercsim/Python is one of the many tracks on exercism. This repo holds all the instructions, tests, code, & support files for Python exercises currently under development or implemented & available for students.

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's not uncommon that people 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 📛 , and let us know what you have found or suggest.

🚧 Did you write a patch that fixes a bug?

💛 💙  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 issue list,
             4️⃣     Larger (and previously agreed-upon) contributions from recent & regular (within the last 6 months) contributors.

When in doubt, 📛  Open an issue 📛. We will happily discuss your proposed change. 🐍

But let's talk before you take a whole lot of time or energy implementing anything.

📚 Want to jump directly into Exercism specifications & detail?

✨ 🦄  Here is the good stuff:

Track Structure | Tasks | Concepts | Concept Exercises | Practice Exercises | Presentation | Writing Style Guide | Markdown Specification

Web-formatted  🕸️   versions are available in the contributing section of exercsim.org.

🌍   The Exercism Community   🌏

🌟🌟  If you have not already done so, please take a moment to read our Code of Conduct & Being a Good Community Member documents. It might also be helpful to take a look at The words that we use.

Some defined roles in our community: Community Member | Contributors | Mentors | Maintainers | Admins

In General

• Maintainers are happy to review your work and help you. 💛 💙 
  • They may be in a different timezone ⌚ , or tied up  🧶  with other tasks. They will review your request as soon as they are able to.
  • Please wait at least 72 hours before pinging.
• If you'd like in-progress feedback or discussion, please mark your Pull Request as a [draft]
• Pull requests should be focused on 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 before creating a Pull Request making significant or breaking changes to an existing exercise.
  • The same rule holds true for changes across multiple exercises.
  • It is best to quickly discuss most changes with  🧰  maintainers before doing a lot of work.
• Follow coding standards found in PEP8 ("For Humans" version here).
  • We do have some more specific requirements. More on that a little later.
• All files should have a proper EOL at the end. This means one carriage return at the end of the final line of text in files.
• Otherwise, watch out  ⚠️  for trailing spaces, extra blank lines, extra spaces, and spaces in blank lines.
• The CI is going to run a lot of checks on your PR. Pay attention to the failures, try to understand and fix them.
  • If you need help, comment in the PR or issue.  🙋🏽‍♀️   The maintainers are happy to help troubleshoot.

 ⚠️  Before committing ⚠️ 

• Run configlet-lint if the track config.json has been modified.
• Run Prettier on all markdown files.
• Run flake8 & pylint to ensure all Python code files conform to general code style standards.
• (Optionally) run yapf to help format your code, and give you a head start on making the linters happy.
• Run test/check-exercises.py [EXERCISE] to check if your test changes function correctly.
• Run the example.py or exemplar.py file against the exercise test file to ensure that it passes without error.
• If you modified or created a hints.md file for a practice exercise, regenerate it.

📄 A Little More on Prose Writing Style and 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. ✨

A Little More on 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.

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're fixing it. But if you see  👀  something,  👄  say something. It'll motivate us to fix it! 🌈

General Code Style TL;DR:

• spaces, never Tabs
• 4 space indentation
• 120 character per line limit (as opposed to the Google limit of 80)
• Variables, functions and methods should be lower_case_with_underscores (aka "snake case")
• Classes are 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 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 from a library.
• Two lines between Classes, one line between functions. Other vertical whitespace as needed to help readability.
• Always use an EOL to end a file.

Concept Exercise Test Files

• We have historically used Unittest.TestCase syntax, with PyTest as a test runner.
• We are transitioning to using (many) more PyTest features and syntax, but are leaving Unittest syntax in place where possible.
• Always check with a maintainer before introducing a PyTest feature in your tests. Not all PyTest features may be supported.
• Test Classes should be titled <ExerciseSlug>Test. e.g. class CardGamesTest(unittest.TestCase): This is to help our test runner re-write them for display on the website.
• Test methods or functions should begin with test_, and follow PEP8 naming. Try to make test case names descriptive but not too long.
• Favor parameterizing tests that vary only by input data. We use unittest.TestCase.subTest for this. An example from Guido's Gorgeous Lasagna. A second example from Card Games.
• Avoid excessive line breaks or indentation - especially 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 looping in test cases. See Card Games for example usage.
• Favor using variable names like inputs, data, input_data, test_data, or test_case_data for test inputs.
• Favor using variable names like results, expected, result_data, expected_data, expected_results or expected_outputs for expected test outcomes.
• Favor putting the (not optional) assert failure message on it's own line outside of the self.assert method, and naming it failure_msg. See Card Games for example usage.
• Use f-strings over other methods for test failure messages. Make your messages as relevant and human-readable as possible.
• We relate the test cases for a particular task in an exercise to the task number via a custom PyTest Marker. These are decorators that take the form of ``@pytest.mark.task(taskno=)`. See Guido's Gorgeous Lasagna for an example usage.
• For exercises that have large sets of data for inputs/outputs, we prefer to have test data files. 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 how we set this up.
• Test data files need to be added to the editor key within an exercises config.json files key. Check with a maintainer if you have questions or issues.
• For new test files going forward, omit if __name__ == "__main__": unittest.main(). Unittest will not be able to run these files stand-alone.
• Test files should be linted with both flake8 and pylint. Both are known to toss false positives for imports and unused variables in test code. 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 a pylint "skip".

🏋️ 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.

  • See Concept Exercise Anatomy, or Practice Exercise Anatomy depending on which type of exercise you are contributing to.
  Concept Exercise Checklist

  >
  
  
  Practice Exercise Checklist

  >

• 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 many practice exercises are similarly [auto-generated][##Auto-Generated Test Files and Test Templates] 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.

Python Versions

This track officially supports Python >= 3.8 The track test runner, analyzer, and representer run in docker on python:3.9-slim.

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

• All exercises should be written for compatibility with Python >= 3.8,.

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

• 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 3.6+ features without consulting with a maintainer first. We  💛 💙  modern Python, but we also want to avoid student confusion when it comes to 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.

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.

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.

Python Practice Exercise structure for auto-generated tests

[<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

Generating Practice Exercise Documents

You will need:

• A local clone of the problem-specifications repository.
• configlet

Regenerating all Practice Exercise Documents:

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

Regenerating an Individual Exercises Documents:

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

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.

Practice Exercise Example solutions

Example solution files serve two purposes:

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

Similar to implementing a canonical exercise that has no canonical-data.json, but the exercise documents will also need to be written manually. Carefully follow the structure of generated exercise documents and the exercism practice exercise specification.