Skip to content

OLD functions concept exercise #2353

Closed
Closed
@BethanyG

Description

@BethanyG

This issue describes how to implement the functions concept and 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:

Goal

This functions concept + concept exercise is meant to teach a deeper understanding and use of functions in Python. It should also explain how Python treats/views functions (as callable objects).

Learning Objectives

In Scope
  • Understand more about Python scopes and namespaces
    • understand the difference between the global and nonlocal keywords and when to use them
  • Get familiar with the special attributes of Python functions
  • Get familiar with best practices when using return, and the difference between explicit and implicit return
    • functions without an explicit return will return the singleton object None
  • Understand what is meant by "functions are first class objects in Python".
    • understand that functions are objects in Python, and that they have types
    • understand that functions can be assigned to variables, used in expressions, and stored in various data structures such as dicts or lists
    • create functons that are assigned to variables, used in expressions, and stored in different data structures.
    • understand and create functions that are/can be nested inside one another
  • Understand that Python considers a function a form of callable object.
  • Understand that a user-defined function object is created by a function definition.
Out of scope
  • named parameters (these can be touched on if needed)
  • default parameters (these can be touched on, if needed)
  • arbitrary parameters
  • *args & **kwargs
  • keyword-only arguments
  • / and * for requiring parameter types
  • functions-as-arguments (this can be mentioned, but shouldn't be required for the exercise)
  • functions-as-returns(_this can be mentioned, but will be covered in-depth in higher-order functions)
  • closures (these will be covered in a different exercise)
  • decorators (these will be covered in a different exercise)
  • functools.wraps (this is used mostly for decorators)
  • functools (this will get its own exercise)
  • comprehensions
  • generators
  • lambda, anonymous functions (these will be covered in a different exercise)
  • recursion

Concepts

  • callable objects
  • first-class functions
  • global
  • nested functions
  • nonlocal
  • return, implicit return, explicit return
  • scope
  • special function attributes

Prerequisites

Proposed Prerequisites

These are the concepts/concept exercises the student needs to complete/understand before solving this concept exercise. Since functions is a a bit of a "meta" topic, these can be adjusted to fit the parameters of the exercise, if needed.

  • basics
  • bools
  • comparisons
  • lists
  • list-methods
  • loops
  • numbers
  • strings
  • string-methods

Resources to Refer To

Links to resources

Concept Files to Be Created

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

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

    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 about.md document listed above, and will provide a brief introduction of the concept for a student who has not yet completed the associated concept or practice exercises. It should contain a good summation of the concept, but not go into lots of detail.

Exercise Files to Be Created

  • Exercise introduction.md

    For more information, see Exercise introduction.md

    • This should also summarize/paraphrase the above concept documents (either the about or the introduction), and can copy the concept introduction verbatim. But the summary does need to have enough information and examples for the student to complete all the tasks outlined for this concept exercise.
  • Exercise instructions.md

    For more information, see instructions.md

    Instructions for an exercise usually center on a story that sets up the code challenge to be solved. You can create your own story, or fork one from the ones listed here. Please make sure to give credit to the original authors if you use a story or fork an exercise.

  • Exercise Exemplar Solution

    For more information, see exemplar implementation.

    This file should not use syntax or datas structures not introduced in this exercise or in this exercise's prerequisites. It will be used as an "ideal" solution for the challenge, so make sure it conforms to PEP8 and other formatting conventions, and does not use single letter variable names. It should also include proper module and function-level docstrings. However, it should NOT include typehinting or type aliases.

  • Exercise Stub for Implementation

    For more information, see stub implementation.

    This file should provide the expected function names imported for testing, and optionally TODO comments and or docstrings to aid the student in their implementation. TODOs and docstrings are not required.

  • Exercise Test Files

    For more information, see Tests.
    Additionally, please note that Python associates exercise tasks to tests via a Pytest Marker, and uses unittest subtests as a form of test paramaterization. See the test file for Little Sisters Vocab for examples of how these techniques work.

  • Exercise Hints

    For more information on writing hints see hints.md

    • Hints should provide enough information to get most students "un-stuck" and moving toward a solution. They should not provide a student with a direct solution.
    • You can refer to one or more of the resources linked in this issue 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.
  • 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.

Exercise Metadata - Track

For more information on concept exercises and formatting for the Python track config.json , please see config.json. The track config.json file can be found in the root of the 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 : ``
  • concepts should be filled in from the Concepts section in this issue
  • prerequisites should be filled in from the Prerequisites section in this issue

Implementation Notes

  • As a reminder, 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 strictly 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 either in the introduction to this exercise, or to one of its prerequisites. 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 to students, so be as clear as you can).
    • 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-specific 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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions