OLD decorators concept exercise

This issue describes how to implement the decorators concept exercise for the python track.

Getting started

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 up on the following documents:

• Contributing to Exercism | Exercism and GitHub | Contributor Pull Request Guide
• What are those Weird Task Tags about?
• Building Language Tracks: An Overview
• What are Concepts?
• Concept Exercise Specifications
• Concept Specifications
• Exercism Formatting and Style Guide
• Exercism Markdown Specification
• Reputation

Goal

This concept exercise is meant to teach an understanding/creation of decorators in python.

Learning objectives

• Review/understand more details on higher-order functions in Python
  • returning functions from functions
  • passing a function as an argument to another function
  • inner or nested functions
• Understand that the decorator form and the @ symbols are syntatic sugar for making/calling higher-order functions
• Know that decorators extend the behavior of an “inner”, “wrapped”, or passed function without explicitly modifying it.
• Create & use simple function decorators
• Create & use a more “complex” function decorator
• Use *args and **kwargs to decorate a function with different arguments
• Understand that a decorator is not required to wrap and modify a function, but can simply return it.

Out of scope

• comprehensions
• class decorators
• classes as decorators
• functools (this will get its own exercise)
• functools.wraps
• generators
• lambda, anonymous functions
• map(), filter(), and reduce() (these will get their own exercise)
• nested decorators
• stateful decorators

Concepts

• decorators
• functions, higher-order functions
• functions as arguments
• functions as returns
• nested funcitons
• *args and **kwargs

Prerequisites

These are the concepts/concept exercises the student needs to complete/understand before solving this concept exercise.

• basics
• bools
• comparisons
• dicts
• dict-methods
• functions
• function-arguments
• higher-order-functions
• iteration
• lists
• list-methods
• numbers
• sequences
• sets
• strings
• string-methods
• tuples

Resources to refer to

• Python Docs: Defining Functions
• Python Docs: Term - decorator
• Functions as Objects in Python
• Composing Programs: Higher-Order Functions
• Real Python: Primer on Python Decorators
• Dan Bader: Python Decorators: A Step-by-Step Introduction
• Learn by Example: Python Decorators
• PEP 0318 (Python.org)

• Hints

  For more information on writing hints see hints

  • You can refer to one or more of the resources linked above, or analogous resources from a trusted source. We prefer using links within the Python Docs as the primary go-to, but other resources listed above are also good. Please try to avoid paid or subscription-based links if possible.

• links.json

  For more information, see concept links file

  • The same resources listed in this issue can be used as a starting point for the concepts/links.json file, if it doesn’t already exist.
  • If there are particularly good/interesting information sources for this concept that extend or supplement the concept exercise material & the resources already listed – please add them to the links.json document.

Concept Description

Please see the following for more details on these files: concepts & concept exercises

• Concept about.md

Concept file/issue: decorators directory with stubbed files – Content is TBD and should be completed as part of this exercise creation. Decorator concept write-ups and associated files can be included in the PR for this issue, or as a separate PR linked to this issue.

For more information, see Concept about.md

• This file provides information about this concept for a student who has completed the corresponding concept exercise. It is intended as a reference for continued learning.

• Concept introduction.md

  For more information, see Concept introduction.md

  • This can also be a summary/paraphrase of the document listed above, and will provide a brief introduction of the concept for a student who has not yet completed the concept exercise. It should contain a good summation of the concept, but not go into lots of detail.

• Exercise introduction.md

  For more information, see Exercise introduction.md

  • This should also summarize/paraphrase the above document, but with enough information and examples for the student to complete the tasks outlined in this concept exercise.

Test-runner

No changes required to the Python Test Runner at this time.

Representer

No changes required to the Python Representer at this time.

Analyzer

No changes required to the Python Analyzer at this time.

Exercise Metadata - Track

For more information on concept exercises and formatting for the Python track config.json , please see concept exercise metadata. The track config.json file can be found in the root of this Python repo.

You can use the below for the exercise UUID. You can also generate a new one via exercism configlet, uuidgenerator.net, or any other favorite method. The UUID must be a valid V4 UUID.

• Exercise UUID : a9e59661-c687-45fb-93e5-622ed612a060
• concepts should be filled in from the Concepts section in this issue
• prerequisites should be filled in from the Prerequisites section in this issue

Exercise Metadata Files Under .meta/config.json

For more information on exercise .meta/ files and formatting, see concept exercise metadata files

• .meta/config.json - see this link for the fields and formatting of this file.
• .meta/design.md - see this link for the formatting of this file. Please use the Goal, Learning Objectives,Concepts, Prerequisites and , Out of Scope sections from this issue.

Implementation Notes

• Code in the .meta/examplar.py file should only use syntax & concepts introduced in this exercise or one of its prerequisite exercises. We run all our examplar.py files through PyLint, but do not require module docstrings. We do require function docstrings similar to PEP257. See this concept exercise exemplar.py for an example.

• Please do not use comprehensions, generator expressions, or other syntax not previously covered. Please also follow PEP8 guidelines.

• In General, tests should be written using unittest.TestCase and the test file should be named <EXERCISE-NAME>_test.py.

  • All asserts should contain a “user friendly” failure message (these will display on the webiste).
  • We use a PyTest custom mark to link test cases to exercise task numbers.
  • We also use unittest.subtest to parameterize test input where/when needed. Here is an example testfile that shows all three of these in action.

• While we do use PyTest as our test runner and for some implementation tests, please check with a maintainer before using a PyTest test method, fixture, or feature.

• Our markdown and JSON files are checked against prettier . We recommend setting prettier up locally and running it prior to submitting your PR to avoid any CI errors.

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue, or contact one of the maintainers on our Slack channel.

[BethanyG]

I think I will do both! If I don’t write good explanations etc. that is what the review process is for!

I love your “can-do” spirit! And yes – as you have probably seen, the review process can be lengthy. But it can also be very collaborative and fun – all of our exercises are a work in progress, and all of them could be improved. In fact, we’re going back over all of our concept exercises over the holidays and seeing where we can make them better.

What do you think is easier to do first?

😄 This is a personal thing. I myself usually do the concept about.md first. It gives me a chance to read up on all the details, go through a bunch of links (which I can then use in the links.json file later), and practice a bunch of things in preparation for writing the exercise. Once I have an about.md, I summarize it for the concept introduction.md, and usually paraphrase it, shorten it, or add specific code examples to it for the exercise introduction.md.

Usually, in the process of “researching” for the concept about.md, a story or problem comes to me for the exercise. But it also depends on the concept. Many early concepts are harder, because you cannot use code or techniques that haven’t been introduced as part of the exercise prerequisites. But decorators are far enough “down the tree”, that you can use most common techniques in your problem setup or solution. We also have a “library” of exercise stories and implementations – so there may be an exercise from Ruby, Go-lang, JavaScript, C#, Elixir, or another language that could be ported or adapted for use here.

I might not get much done over the next few weeks due to school! After that Christmas holidays give me loooooooooads of time

No worries there! I am one of the world’s slowest writers … so even when I am working on an exercise, it takes me several weeks! Just give us (myself or @J08K ) a ping if you get stuck, want to discuss things via chat or call, or if you decided you’d rather work on something else. And good luck with any pending papers or tests! 🌟

[BethanyG]

Also – because of the prerequisites and flags for setting an exercise live – it is probably best if @J08K or I do the edits to the track python/config.json. We’ll do it as a last step when we finalize your PR. 😄