This issue describes how to implement the iteratorsconcept 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.
These concept docs are meant to teach an understanding, creation, and use of itertators in Python.
π‘ Learning objectives
Learn more about how looping / iteration and the iterator protocol work in Python, and the options available for creating & customizing iterators.
How loops in Python implement the iterator protocol
iteration "under the covers"
How iterables are defined
Understand and use the built-in iter() to return an iterator
Create/use one or more custom iterators via defining a class
Understand how class -created iterators relate to generators, and the pros and cons of each approach
π« Out of scope
Concepts and Subjects that are Out of Scope
- `classes` & `class customization` beyond the use of the `iterator` dunder methods and `iterator protocol`
- `class-inheritance` beyond what is needed to customize `iteration` for a `container type` or other `class`
- `comprehensions`
- `comprehensions` in `lambdas`
- `coroutines`
- `decorators`
- `functools` and related `map()`, `filter()` and `functools.reduce()`
- `generators` in-depth as a specific form of iterators (_these have their own exercise_)
- `higher-order functions`
- `lambdas`
- using an `assignment expression` or "walrus" operator (`:=`)
- class decorators
- `enums`
π€ Concepts
Concepts and Related Concepts this Concept Covers
- `loops` in Python
- `iteration` in Python
- `iterators` & `iterator types`
- The `iterator protocol`
- `iterables` & `enumeration`
Resources
- [Python Docs: iterator definition](https://docs.python.org/3/glossary.html#term-iterator) | [Python Docs: iterator types](https://docs.python.org/3/library/stdtypes.html#iterator-types)
- [Python Docs: iterable](https://docs.python.org/3/glossary.html#term-iterable)
- [Python Tutorial: iterators](https://docs.python.org/3/tutorial/classes.html#iterators) | [Python Functional Programming HOWTO: Iterators](https://docs.python.org/3/howto/functional.html#iterators)
- [Python Docs: sequence](https://docs.python.org/3/glossary.html#term-sequence)
- [Python Docs: the `for` statement](https://docs.python.org/3/tutorial/controlflow.html#for-statements)
- [Trey Hunner: The Iterator Protocol: How `for` Loops Work in Python](https://treyhunner.com/2016/12/python-iterator-protocol-how-for-loops-work/)
- [Dan Bader: Python Iterators - A Step-by-Step Introduction](https://dbader.org/blog/python-iterators)
- [`iter()`](https://docs.python.org/3/library/functions.html#iter)
- [Python Docs: emulating container types](https://docs.python.org/3/reference/datamodel.html#emulating-container-types)
- [Trey Hunner: How to make an `iterator` in Python](https://treyhunner.com/2018/06/how-to-make-an-iterator-in-python/)
- [Python Patterns Guide: Gang of Four `iterator` Pattern](https://python-patterns.guide/gang-of-four/iterator/)
- [Python Docs C-API: Iterator Protocol](https://docs.python.org/3/c-api/iter.html)
- [Python Docs C-API: Iterator Objects](https://docs.python.org/3/c-api/iterator.html#iterator-objects)
π Files to Be Created
File Detail for this Concept
Please see the following for more details on these files: [concepts](https://exercism.org/docs/building/tracks/concepts)
* ### `links.json`
For more information, see [concept links file](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-linksjson)
- The same resources listed in this issue can be used as a starting point for the [ `concepts/links.json`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-linksjson) 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`](https://github.com/exercism/docs/blob/main/anatomy/tracks/concepts.md#file-aboutmd)
- 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`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-aboutmd)
* 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`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-metaconfigjson)
* 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.
This issue describes how to implement the
iterators
concept docs. You can find the related concept exercise issue hereIf 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
These concept docs are meant to teach an understanding, creation, and use of
itertators
in Python.π‘ Learning objectives
Learn more about how
looping
/iteration
and theiterator protocol
work in Python, and the options available for creating & customizingiterators
.loops
in Python implement theiterator protocol
iteration
"under the covers"iterables
are definediter()
to return aniterator
iterators
via defining aclass
class
-created iterators relate togenerators
, and the pros and cons of each approachπ« Out of scope
Concepts and Subjects that are Out of Scope
- `classes` & `class customization` beyond the use of the `iterator` dunder methods and `iterator protocol` - `class-inheritance` beyond what is needed to customize `iteration` for a `container type` or other `class` - `comprehensions` - `comprehensions` in `lambdas` - `coroutines` - `decorators` - `functools` and related `map()`, `filter()` and `functools.reduce()` - `generators` in-depth as a specific form of iterators (_these have their own exercise_) - `higher-order functions` - `lambdas` - using an `assignment expression` or "walrus" operator (`:=`) - class decorators - `enums`
π€ Concepts
Concepts and Related Concepts this Concept Covers
- `loops` in Python - `iteration` in Python - `iterators` & `iterator types` - The `iterator protocol` - `iterables` & `enumeration`
β©οΈ Prerequisites
These are the concepts/concept exercises the student should be familiar with before taking on/learning this concept.
Prereqs
- `basics` - `booleans` - `classes` - `comparisons` - `rich-comparisons` - `decorators` - `descriptors` - `dicts` - `dict-methods` - `functions` - `higher-order-functions` - `lists` - `list-methods` - `numbers` - `sequences` - `sets` - `strings` - `string-methods` - `tuples`
π Resources to refer to
Resources
- [Python Docs: iterator definition](https://docs.python.org/3/glossary.html#term-iterator) | [Python Docs: iterator types](https://docs.python.org/3/library/stdtypes.html#iterator-types) - [Python Docs: iterable](https://docs.python.org/3/glossary.html#term-iterable) - [Python Tutorial: iterators](https://docs.python.org/3/tutorial/classes.html#iterators) | [Python Functional Programming HOWTO: Iterators](https://docs.python.org/3/howto/functional.html#iterators) - [Python Docs: sequence](https://docs.python.org/3/glossary.html#term-sequence) - [Python Docs: the `for` statement](https://docs.python.org/3/tutorial/controlflow.html#for-statements) - [Trey Hunner: The Iterator Protocol: How `for` Loops Work in Python](https://treyhunner.com/2016/12/python-iterator-protocol-how-for-loops-work/) - [Dan Bader: Python Iterators - A Step-by-Step Introduction](https://dbader.org/blog/python-iterators) - [`iter()`](https://docs.python.org/3/library/functions.html#iter) - [Python Docs: emulating container types](https://docs.python.org/3/reference/datamodel.html#emulating-container-types) - [Trey Hunner: How to make an `iterator` in Python](https://treyhunner.com/2018/06/how-to-make-an-iterator-in-python/) - [Python Patterns Guide: Gang of Four `iterator` Pattern](https://python-patterns.guide/gang-of-four/iterator/) - [Python Docs C-API: Iterator Protocol](https://docs.python.org/3/c-api/iter.html) - [Python Docs C-API: Iterator Objects](https://docs.python.org/3/c-api/iterator.html#iterator-objects)
π Files to Be Created
File Detail for this Concept
Please see the following for more details on these files: [concepts](https://exercism.org/docs/building/tracks/concepts) * ### `links.json` For more information, see [concept links file](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-linksjson) - The same resources listed in this issue can be used as a starting point for the [ `concepts/links.json`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-linksjson) 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`](https://github.com/exercism/docs/blob/main/anatomy/tracks/concepts.md#file-aboutmd) - 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`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-aboutmd) * 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`](https://github.com/exercism/docs/blob/main/building/tracks/concepts.md#file-metaconfigjson) * 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
π 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).