OLD Context Manager Customization Concept Exercise

[BethanyG]

This issue describes how to implement the context-manager customization concept exercise for the Python track.
The related concept documents issue can be found here.

✅ Getting started

If you have not yet created or contributed to a concept exercise, this issue will require some upfront reading to give you the needed background knowledge. Some good example exercises to look at in the repo:

💡Example Exercises💡

1. Little Sister's Vocabulary
2. Meltdown Mitigation
3. Making the Grade
4. Ellen's Alien Game

We also recommend completing one or more of the concept exercises (they're called "learning exercises") on the website.

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 go through the following documents:

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 Concept Exercises

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

🎯 Goal

The goal of the concept exercise described in this issue is to teach context- manager customization (the machinery behind the with keyword) in Python.

💡 Learning objectives

• Review what the with keyword is and what it does in Python
  • context-handling & scope
  • setup and teardown processes
  • memory and resource allocation
• Understand different context-manager Types and their uses
• Get familiar with some of the utilities & decorators in contextlib, and how they're used to customize a context-manager
  • @contextlib.contextmanager
  • contextlib.closing()
  • contextlib.nullcontext()
  • contextlib.suppress
  • conextlib.redirect_stdout()
  • contextlib.redirect_stderr()
  • class contextlib.ContextDecorator
• Understand how customized context-managers are used with the with statement
  • __enter__
  • __exit__
• Implement some of the most common use cases for managing / customizing management of resources with the with keyword (maybe some of the recipes listed in the docs?)
  • file opening/closing/processing
  • database connectivity
  • error handling
  • logging
  • testing

🚫 Topics that are Out of scope

While many of these topics could be considered prerequisites or necessary building blocks for this concept, we've marked them as "out of scope".

This means that we'd like you to focus instruction and examples primarily on the topic of this concept (context managers and customization), and save any specific instruction or custom use of the topics below for exercises that focus on those concepts in detail.

Some examples: @contextmanager requires a generator to act as a factory. But this exercise should not teach the making of or customization of a generator, since generators have their own exercise. The same goes for creating classes, raising & handling errors, or using assert for testing. The overall goal should be to use just enough to explain/instruct the student in the context-manager customization concept, and assume they have learned or will learn the other details. If you have additional questions, please reach out to one of the maintainers.

Out of Scope Topics for Context Manager Customization

• async versions of context-managers (we are leaving async-io and async off our concept list right now due to their complexity)
• classes & class customization
• class-inheritance
• comprehensions
• comprehensions in lambdas
• coroutiens
• decorators
• error-handling
• raising errors
• functions and higher-order functions
• functools and related map(), filter() and functools.reduce()
• generators
• lambdas
• using an assignment expression or "walrus" operator (:=)
• enums
• testing and assert

🤔 Concepts

• with
• context-managers
• contextlib
• Special Methods
  • __enter__
  • __exit__

↩️ Prerequisites

Prereqs

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

• basics
• bools
• classes
• class customization
• class-inheritance
• comparisons
• rich-comparisons
• decorators
• dicts
• dict-methods
• raising-and-handling-errors
• functions
• generators
• higher-order-functions
• lists
• list-methods
• loops
• numbers
• sequences
• sets
• strings
• testing
• tuples
• with-statement

📚 Resources for Writing & Reference

Resources

• Python Docs: Compound Statements
• Python Docs: With Statement Context Managers
• Python Docs: With Statement
  • Python Docs: Reading and Writing Files
• Python Docs: Context Manager Types
• PEP 0343: The with Statement
• PEP 0343: Examples
• Python Docs: contextlib
• Python Module of the Week: contextlib
• Python Morsels: Context-managers
• Dan Bader: Context Managers and the with statement in Python
• Real Python: Context managers
• Innoplex: Fun With Context Managers
• Siv Scripts: A Gentle Introduction to Context Managers
• arnavk.org: Context Managers in the Real World
• Abhinav Gupta: Go Antipatterns - With* Context Managers

Additional Articles

• David Beazley at (Unenix.org) Python: With That - 5 Easy Context Managers
• Jeff Knupp: Python with Context Managers
• Red's Digressions: The Curious Case of Python's Context Manager
• Cambridge Spark: Python Context manager

📁 Exercise Files to Be Created

File Detail for this Exercise

Exercise introduction.md For more information, see Exercise introduction.md This can summarize/paraphrase the linked concept documents if they have already been created (either the about or the introduction). 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.py 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>.py (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.py 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.md 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 : a59b4983-29b3-4519-bb86-eb3de45c89b0
• 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.

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