Skip to content

[New Concept Docs]: Context Manager Customization #3081

Closed
@BethanyG

Description

@BethanyG

This issue describes how to implement the context manager customization concept docs.
The related concept exercise issue 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.

✅ 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:

Documents on Language Tracks and Concepts:


🎯 Goal

The goal of the documents described in this issue is to explain the concept of 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. For example: @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

Concepts/Related Concepts
  • with
  • context-managers
  • contextlib
  • Special Methods
    • __enter__
    • __exit__

↩️ 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-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 to refer to

Resources
Additional Articles

📁 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.
  • 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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions