-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Description
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:
- 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:
🎯 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
withkeyword is and what it does in Python- context-handling & scope
- setup and teardown processes
- memory and resource allocation
- Understand different
context-managerTypes and their uses - Get familiar with some of the utilities & decorators in
contextlib, and how they're used to customize acontext-manager@contextlib.contextmanagercontextlib.closing()contextlib.nullcontext()contextlib.suppressconextlib.redirect_stdout()contextlib.redirect_stderr()class contextlib.ContextDecorator
- Understand how customized
context-managersare used with thewithstatement__enter____exit__
- Implement some of the most common use cases for managing / customizing management of resources with the
withkeyword (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
asyncversions ofcontext-managers(we are leavingasync-ioandasyncoff our concept list right now due to their complexity)classes&class customizationclass-inheritancecomprehensionscomprehensionsinlambdascoroutiensdecoratorserror-handlingraising errorsfunctionsandhigher-order functionsfunctoolsand relatedmap(),filter()andfunctools.reduce()generatorslambdas- using an
assignment expressionor "walrus" operator (:=) enumstestingandassert
🤔 Concepts
Concepts/Related Concepts
withcontext-managerscontextlib- Special Methods
__enter____exit__
↩️ Prerequisites
These are the concepts/concept exercises the student should be familiar with before taking on/learning this concept.
Prereqs
basicsboolsclassesclass customizationclass-inheritancecomparisonsrich-comparisonsdecoratorsdictsdict-methodsraising-and-handling-errorsfunctionsgeneratorshigher-order-functionslistslist-methodsloopsnumberssequencessetsstringstestingtupleswith-statement
📚 Resources to refer to
Resources
- Python Docs: Compound Statements
- Python Docs: With Statement Context Managers
- Python Docs: With Statement
- Python Docs: Context Manager Types
- PEP 0343: The
withStatement - PEP 0343: Examples
- Python Docs:
contextlib - Python Module of the Week:
contextlib - Python Morsels: Context-managers
- Dan Bader: Context Managers and the
withstatement in Python - Real Python: Context managers
- Martin Heinz: The Magic of 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
📁 Files to Be Created
Please see the following for more details on these files: concepts
-
links.jsonFor more information, see concept links file
- The same resources listed in this issue can be used as a starting point for the
concepts/links.jsonfile, 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.jsondocument.
- The same resources listed in this issue can be used as a starting point for the
-
Concept
about.mdFor 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.mdFor more information, see Concept
introduction.md- This can also be a summary/paraphrase of the
about.mddocument 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.
- This can also be a summary/paraphrase of the
-
Concept
.meta/config.jsonEntriesFor 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
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).- 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.