Skip to content

Latest commit

 

History

History
145 lines (111 loc) · 7.85 KB

implementing-a-concept-exercise.md

File metadata and controls

145 lines (111 loc) · 7.85 KB

How to implement a Python concept exercise

This document describes the steps required to implement a concept exercise for the Python track.

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read the following documents:

Please also watch the following video:

As this document is generic, the following placeholders are used:

  • <SLUG>: the slug of the exercise story title in kebab-case (e.g. calculator-conundrum).
  • <CONCEPT_NAME>: the name of the exercise's concept in snake_case (e.g. anonymous_functions).
  • <CONCEPT-SLUG>: the slug of an exercise's concept in kebab-case (e.g. anonymous-functions).

Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what should not be taught). This information can be found in the exercise's GitHub issue, under the Learning Objectives and Out of Scope sections.

We suggest using a git branch titled after the concept you are writing the exercise for. Please use [Python] in the title of your PR, so that it can be easily filtered and note the GitHub issue number in the PR message.

To implement a concept exercise, the following files under python/concepts and python/exercises will need to be created:

languages
└── python
    ├── concepts
    |   └── <CONCEPT-SLUG>
    |       ├── about.md
    |       └── links.json
    └── exercises
        └── concept
            └── <SLUG>
                ├── .docs
                |   ├── instructions.md
                |   ├── introduction.md
                |   └── hints.md
                ├── .meta
                |   ├── config.json
                |   ├── design.md
                |   └── exemplar.py
                ├── <CONCEPT_NAME>.py
                └── <CONCEPT_NAME>_test.py

Step 1: Add .py code files

These are files specific to the Python track, and can be added in any order:

  • <SLUG>/<CONCEPT_NAME>.py The stub implementation file, which will be the starting point for students to work on the exercise (example stub file). Please use pass as necessary, and descriptive TODO comments for clarification if the student needs to define a class/function/constant themselves (example TODO).

  • <SLUG>/<CONCEPT_NAME>_test.py The test suite a submitted solution will be tested against. Tests should be written using unittest.TestCase (example test file). We do use PyTest as our test runner, but please check with a maintainer before using any PyTest-specific methods.

  • .meta/exemplar.py An idiomatic implementation that passes all the provided tests. This solution file should only use syntax & concepts introduced in the concept exercise itself, or one of its prerequisites.. This means avoiding the use of classes, comprehensions, generators, slice assignment, regex, filter/map/reduce, standard library modules (like datetime), or 3rd-party libraries unless the exercise has introduced these concepts or they appear in the exercise's prerequisite tree. Please follow the PEP8 formatting guidelines. Additionally, we'd like you to avoid any single-letter or cryptic variable names.

Step 2: Add exercise documentation files

How to create the files common to all tracks is described in the how to implement a concept exercise document. All of these files are written in Markdown, and you can find the Exercism Formatting and Style Guide here. Please pay close attention to the auto-formatting section, to avoid CI test failures.

As a reminder, code elements (functions, keywords, operators) should be wrapped in backticks:

A `set` is an unordered collection of distinct hashable objects. To add something to a `set`, use `set.add()`

Which will render:

A set is an unordered collection of distinct hashable objects. To add something to a set, use set.add()

Unless your code is intended to represent a .py file, please format longer in-text code examples for the Python REPL -- in the same way the Python Docs do:

# Elements given to the constructor are iterated through and added to the tuple in order.
>>> multiple_elements_string = tuple("Timbuktu")
('T', 'i', 'm', 'b', 'u', 'k', 't', 'u')

>>> multiple_elements = tuple(("Parrot", "Bird", 334782))
("Parrot", "Bird", 334782)

# Iterating through a tuple with a for loop.
>>> for item in multiple_elements_string:
...   print(item)
...
T
i
m
b
u
k
t
u

For resource links, we strongly favor linking into relevant parts of the Python docs as a first source, with other useful and interesting links as a follow-on. Please avoid any paywalled, subscription-based or signup-required links.

Inspiration

When implementing an exercise, it can be very useful to look at already implemented Python exercises. Browsing through concept exercise stories here can also help "jump-start" concept exercise writing. And you can also check the cross-track general concepts directory to see if other language tracks have already implemented an exercise for a particular concept. If you adapt a story or exercise, please make sure to include a credit in your exercise .meta/config.json file `"forked_from" field:

{
  "authors": [
    {
      "github_username": "aldraco",
      "exercism_username": "aldraco"
    }
  ],
  "editor": {
    "solution_files": ["strings.py"],
    "test_files": ["strings_test.py"]
  },
  "forked_from": ["csharp/strings"]
}

Help

If you have any questions regarding implementing the exercise, please post them as comments in the exercise's GitHub issue, or in the exercism Slack channel.