[Improve Concept Docs]: `functools` Module in Python

[BethanyG]

This issue describes desired additions and improvements to the functools module concept docs.. The related concept exercise issue and specs can be found here,

If you have not yet contributed to concept documents, this issue will require some upfront reading to give you the needed background knowledge. Additionally, we recommend reading the existing about.md docs here, and an example of completed concept docs here.

✅ Getting started

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.

General Contributing Docs:

• Contributing to Exercism | Exercism and GitHub | - Contributor Pull Request Guide
• What are those Weird Task Tags about?
• Exercism Formatting and Style Guide
• Exercism Markdown Specification
• Reputation

Documents on Language Tracks and Concepts:

• Building Language Tracks: An Overview
• What are Concepts?
• Concept Specifications

🙏🏽 Desired Improvements and Changes

Generally, re-read the documents from a student perspective, improving tone, explanations, and examples. Currently, the documents read as if they are documentation, and not teaching docs.

• [ ] Clean up introduction.md, so that it only introduces the module, and gives reasons why one would use the tools. It's also OK to list the tools that will be covered, but not to go into detail. Please also remove the function signatures and highlighting. Remember: this is the doc a student sees before going through the exercise, so it is best not to bog them down with too much detail.
• [ ] Add more about what the module does, and why one would want to use the tools in the module to both the about.md and the introduction.md
• [ ] Add real links to links.json for further student study/learning
• [ ] Remove the highlighted function signatures from the doc, and re-work the text to be more narrative and focused on usage and explanation, rather than reading like a copy of the Python documentation.
• [ ] Provide better use-cases and real-world code examples for the functions covered.
• [ ] Provide better use-case, explanation and examples for update_wrapper and wraps. If this feels forced, remove the methods and let a maintainer know. We may move these to the decorators concept.

---

🌟 Original Specifications

Below are the original specifications from the Concept issue. Please use these as a guide in addition to the change list above.

This issue describes how to implement the functools module concept docs.. You can find the related concept exercise issue here

If you have not yet contributed to concept documents, this issue will require some upfront reading to give you the needed background knowledge.

✅ Getting started

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.

General Contributing Docs:

• Contributing to Exercism | Exercism and GitHub | - Contributor Pull Request Guide
• What are those Weird Task Tags about?
• Exercism Formatting and Style Guide
• Exercism Markdown Specification
• Reputation

Documents on Language Tracks and Concepts:

• Building Language Tracks: An Overview
• What are Concepts?
• Concept Specifications

🎯 Goal

These concept docs are meant to teach an understanding/use of the functools module in Python.

💡 Learning objectives

Learn more about the functional tools the Python Standard Library provides through the functools module. Build and understanding of and use the following methods and decorators from the module:

• functools.partial()
  • partial.func
  • partial.args
  • partial.keywords
• class functools.partialmethod()
• class functools.singledispatchmethod()
• functools.cache()
• @functools.lru_cache()
• @functools.singledispatch
  • @<function>.register()
• @functools.wraps() -- (these might move to the decorators exercise, depending on how difficult they are to work in)
  • functools.update_wrapper()
• ~~@functools.cached_property()~~ (this seems better in class_customization)
• ~~@functools.total_ordering~~ (this method seems more appropriate in therich comparisons exercise)

🚫 Out of scope

Concepts and Subjects that are Out of Scope

• classes & class customization beyond the direct use of the class methods in this module.
• comprehensions
• comprehensions in lambdas
• decorators (these have their own exercise. See issue #2356 )
• map(), filter() or functools.reduce() in a comprehension
• functools.reduce()(this was already covered with map() and filter())
• generators, beyond what is in this module
• using an assignment expression or "walrus" operator (:=) in a lambda
• class decorators beyond the ones described in this module.
• enums

🤔 Concepts

Concepts/Related Concepts Under this Topic

• functional tools in python
• functools module
• generic functions
• decorators
• higher-order functions
• partial objects in python/partial evaluation in python
• single dispatch

↩️ Prerequisites

These are the concepts/concept exercises the student should be familiar with before taking on/learning this concept.

Prereqs

• basics
• bools
• classes
• class-customization
• class-components
• comparisons
• rich-comparisons
• decorators
• descriptors
• dicts
• dict-methods
• functions
• function-arguments
• higher-order-functions
• iteration
• lists
• list-methods
• numbers
• sequences
• sets
• strings
• string-methods
• tuples

📚 Resources to refer to

Resources

• Python Docs: Defining Functions
• Python Docs: functional programming HOWTO
• Python Docs: functools module
• Pthon Module of the Week: functools - Tools for Maniputlating Fuctions
• Florian Dahlitz: Introduction to Python's Functools Module
• PyDanny: Python Partials are Fun!
• Composing Programs: Higher-Order Functions
• Trey Hunner: Ist it a Class or a Function? It's a callable!
• built-ins: Python Docs
  • map() & filter()
  • any() & all()
  • min() & max()
  • sum()
• Real Python: Functional Programming in Python: When and How to Use it

📁 Files to Be Created

File Detail for this Exercise

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. Concept .meta/config.json Entries For more information, see Concept .meta/config.json This file is likely already stubbed out. Remember to add a concept blurb of less than 350 characters. Please also add your GitHub username to the "authors" array, and any contributor GitHub usernames to the "contributors" array.

🎶 Implementation Notes

• Example code should only use syntax & concepts introduced within these docs or one of the prerequisite concept exercises or documents. Where possible, please use REPL formatting, unless you are demonstrating pseudo code or a long code block. Please do not use syntax not previously covered in prerequisite topics or exercises. Please also follow PEP8 guidelines.
• 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.

🆘 Next Steps & Getting Help

1. If you'd like to work on this issue, comment saying "I'd like to work on this" (there is no real need to wait for a response, just go ahead, we'll assign you and put a [claimed] label on the issue).
2. If you have any questions while implementing, please post the questions as comments in here, or contact one of the maintainers on our Slack channel.

[BethanyG]

@Metallifax -- This is the "improve concept docs. Comment to be assigned. 😄

[Metallifax]

:wave: Comment!

[BethanyG]

@Metallifax -

Evidently, the bot is anxious 🙄 Will fix that up tomorrow my time. Apologies for the ping.

[BethanyG]

@Metallifax -- Checking in here .. do you still want to work on this? Anything I can do to help?

[BethanyG]

Putting back in the [help wanted] pile.