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
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 acontext-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 thewith
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 ofcontext-managers
(we are leavingasync-io
andasync
off our concept list right now due to their complexity)classes
&class customization
class-inheritance
comprehensions
comprehensions
inlambdas
coroutiens
decorators
error-handling
raising errors
functions
andhigher-order functions
functools
and relatedmap()
,filter()
andfunctools.reduce()
generators
lambdas
- using an
assignment expression
or "walrus" operator (:=
) enums
testing
andassert
🤔 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
- Python Docs: Compound Statements
- Python Docs: With Statement Context Managers
- Python Docs: With Statement
- 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
- 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.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.
- The same resources listed in this issue can be used as a starting point for the
-
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.
- This can also be a summary/paraphrase of the
-
Concept
.meta/config.json
EntriesFor 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.