diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index ed8f4a432bc..234b07e766c 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -6,4 +6,4 @@ updates:
- package-ecosystem: 'github-actions'
directory: '/'
schedule:
- interval: 'daily'
+ interval: 'monthly'
diff --git a/.github/workflows/ci-workflow.yml b/.github/workflows/ci-workflow.yml
index 8a8803bfb9e..c2a5519234d 100644
--- a/.github/workflows/ci-workflow.yml
+++ b/.github/workflows/ci-workflow.yml
@@ -6,20 +6,19 @@ name: Exercises check
on:
push:
branches:
- - master
- main
pull_request:
jobs:
housekeeping:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
- name: Set up Python
- uses: actions/setup-python@v4
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
with:
- python-version: 3.11.2
+ python-version: 3.13.5
- name: Download & Install dependencies
run: |
@@ -49,24 +48,20 @@ jobs:
./bin/template_status.py -v -p .problem-specifications
canonical_sync:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
needs: housekeeping
strategy:
matrix:
- python-version: [3.7, 3.8, 3.9, 3.10.6, 3.11.2]
+ python-version: [3.10.6, 3.11.2, 3.12, 3.13.5]
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
- - uses: actions/setup-python@v4
+ - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
with:
python-version: ${{ matrix.python-version }}
- - name: Install dataclasses package
- if: ${{ matrix.python-version == '3.6' }}
- run: pip install dataclasses
-
- name: Install pytest
- run: pip install pytest~=7.2.2
+ run: pip install pytest~=8.4.0
- name: Check exercises
run: |
diff --git a/.github/workflows/issue-commenter.yml b/.github/workflows/issue-commenter.yml
index dfd6c59c516..9f7631e1465 100644
--- a/.github/workflows/issue-commenter.yml
+++ b/.github/workflows/issue-commenter.yml
@@ -5,20 +5,20 @@ on:
jobs:
comment-on-new-issue:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
name: Comments for every NEW issue.
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
- name: Read issue-comment.md
id: issue-comment
- uses: juliangruber/read-file-action@v1
+ uses: juliangruber/read-file-action@271ff311a4947af354c6abcd696a306553b9ec18
with:
path: .github/issue-comment.md
- name: Base comment
- uses: jd-0001/gh-action-comment-on-new-issue@v2.0.3
+ uses: jd-0001/gh-action-comment-on-new-issue@c443e1151cc69b146fd6918cc983ec1bd27ab254
with:
message: "${{ steps.issue-comment.outputs.content }}"
ignore-label: ":anger: prickle"
diff --git a/.github/workflows/no-important-files-changed.yml b/.github/workflows/no-important-files-changed.yml
new file mode 100644
index 00000000000..812e9129668
--- /dev/null
+++ b/.github/workflows/no-important-files-changed.yml
@@ -0,0 +1,23 @@
+name: No important files changed
+
+on:
+ pull_request_target:
+ types: [opened]
+ branches: [main]
+ paths:
+ - "exercises/concept/**"
+ - "exercises/practice/**"
+ - "!exercises/*/*/.approaches/**"
+ - "!exercises/*/*/.articles/**"
+ - "!exercises/*/*/.docs/**"
+ - "!exercises/*/*/.meta/**"
+
+permissions:
+ pull-requests: write
+
+jobs:
+ check:
+ uses: exercism/github-actions/.github/workflows/check-no-important-files-changed.yml@main
+ with:
+ repository: ${{ github.event.pull_request.head.repo.owner.login }}/${{ github.event.pull_request.head.repo.name }}
+ ref: ${{ github.head_ref }}
diff --git a/.github/workflows/ping-cross-track-maintainers-team.yml b/.github/workflows/ping-cross-track-maintainers-team.yml
new file mode 100644
index 00000000000..b6ec9c5662f
--- /dev/null
+++ b/.github/workflows/ping-cross-track-maintainers-team.yml
@@ -0,0 +1,16 @@
+name: Ping cross-track maintainers team
+
+on:
+ pull_request_target:
+ types:
+ - opened
+
+permissions:
+ pull-requests: write
+
+jobs:
+ ping:
+ if: github.repository_owner == 'exercism' # Stops this job from running on forks
+ uses: exercism/github-actions/.github/workflows/ping-cross-track-maintainers-team.yml@main
+ secrets:
+ github_membership_token: ${{ secrets.COMMUNITY_CONTRIBUTIONS_WORKFLOW_TOKEN }}
diff --git a/.github/workflows/pr-commenter.yml b/.github/workflows/pr-commenter.yml
index 0bf1662006f..a70deb6b890 100644
--- a/.github/workflows/pr-commenter.yml
+++ b/.github/workflows/pr-commenter.yml
@@ -4,9 +4,9 @@ on:
jobs:
pr-comment:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
steps:
- - uses: exercism/pr-commenter-action@v1.5.0
+ - uses: exercism/pr-commenter-action@f4a6aa5acc07742989788e70fd89cdc0980f0d1e
with:
github-token: "${{ github.token }}"
config-file: ".github/pr-commenter.yml"
\ No newline at end of file
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index 41156435d82..29b31a0401e 100644
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -6,9 +6,9 @@ on:
jobs:
stale:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
steps:
- - uses: actions/stale@v8
+ - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
days-before-stale: 21
diff --git a/.github/workflows/test-runner.yml b/.github/workflows/test-runner.yml
index b3668593b8d..c9b0d21a713 100644
--- a/.github/workflows/test-runner.yml
+++ b/.github/workflows/test-runner.yml
@@ -8,8 +8,8 @@ on:
jobs:
test-runner:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
- name: Run test-runner
- run: docker-compose run test-runner
+ run: docker compose run test-runner
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index df8e36761c1..3f7813de10a 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -90,4 +90,4 @@ This policy was initially adopted from the Front-end London Slack community and
A version history can be seen on [GitHub](https://github.com/exercism/website-copy/edit/main/pages/code_of_conduct.md).
_This policy is a "living" document, and subject to refinement and expansion in the future.
-This policy applies to the Exercism website, the Exercism GitHub organization, any other Exercism-related communication channels (e.g. Slack, Twitter, email) and any other Exercism entity or event._
+This policy applies to the Exercism website, the Exercism GitHub organization, any other Exercism-related communication channels (e.g. Discord, Forum, Twitter, email) and any other Exercism entity or event._
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0bac23e0af3..6ff557f7087 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,33 +4,37 @@
Contributing
[](https://forum.exercism.org)
- [](https://exercism.org)
+ [](https://exercism.org)
[](https://exercism.org/blog/freeing-our-maintainers)
[](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22)
-
-
-We are not accepting community contributions at this time.
+>
+> please open a [thread on the forum](https://forum.exercism.org/).
+>
-We π π our community.
-**`But our maintainers are not accepting community contributions at this time.`**
-Please read this [community blog post](https://exercism.org/blog/freeing-our-maintainers) for details.
-
-
[**open a thread in our community forum**](https://forum.exercism.org) to let us know what you have found/suggest.
Our maintainers are not accepting community contributions at this time. [**open a thread in our community forum**](https://forum.exercism.org) to discuss any potential changes. Changes may or may not be approved, depending on the forum discussion.
-Once the pause ends, we will **happily** consider your PR.
-Until that time, all PRs from the larger community will be **automatically closed** with a note.
+Please read this [community blog post](https://exercism.org/blog/freeing-our-maintainers) for additional details.
+
+ Python Track Contributing Docs
In General
)`. See [Guido's Gorgeous Lasagna][guidos-gorgeous-lasagna-testfile] for an example.
-- We prefer **test data files** when test inputs/ouputs are verbose.
+- We prefer **test data files** when test inputs/outputs are verbose.
- These should be named with `_data` or `_test_data` at the end of the filename, and saved alongside the test case file.
- See the [Cater-Waiter][cater-waiter] exercise directory for an example of this setup.
- **Test data files** need to be added under an `editor` key within [`config.json "files"`][exercise-config-json].
@@ -195,13 +203,13 @@ _We know it, and trust us, we are working on fixing it._ But if you see
_test.py` (_**auto-generated from cannonical data**_)
+ - [ ] `.meta/template.j2` (_template for generating tests from canonical data_)
+ - [ ] `.meta/tests.toml` (_tests configuration from canonical data_)
+ - [ ] `_test.py` (_**auto-generated from canonical data**_)
- [ ] `.py` (**required**)
@@ -369,45 +377,32 @@ configlet generate --spec-path path/to/problem/specifications --
configlet generate --spec-path path/to/problem/specifications
```
+
--spec-path path/to/problem/specifications
[the-words-that-we-use]: https://github.com/exercism/docs/blob/main/community/good-member/words.md
[unittest]: https://docs.python.org/3/library/unittest.html#unittest.TestCase
[version-tagged-language-features]: https://docs.python.org/3/library/stdtypes.html#dict.popitem
-[website-contributing-section]: https://exercism.org/docs/building
[yapf]: https://github.com/google/yapf
diff --git a/README.md b/README.md
index 1c82f33b9d0..20c3bd1ce0c 100644
--- a/README.md
+++ b/README.md
@@ -4,22 +4,39 @@
Exercism Python Track
[](https://forum.exercism.org)
- [](https://exercism.org)
+ [](https://exercism.org)
[](https://exercism.org/blog/freeing-our-maintainers)
[](https://github.com/exercism/python/actions?query=workflow%3A%22Exercises+check%22)
We are not accepting community contributions at this time.
+>
+> please open a [thread on the forum](https://forum.exercism.org/).
+>
**But our maintainers are not accepting community contributions at this time.**
Please read this [community blog post][freeing-maintainers] for details.
+>>> my_first_variable = 'You can call me "str".' # <--Strings can be declared using single or double quote marks.
>>> print(my_first_variable)
-"Now, I'm a string." # Strings can be declared using single or double quote marks.
+You can call me "str".
-import collections
->>> my_first_variable = collections.Counter([1,1,2,3,3,3,4,5,6,7]) # Now my_first_variable has been re-bound to a Counter object.
+>>> import collections
+>>> my_first_variable = collections.Counter([1,1,2,3,3,3,4,5,6,7]) # <--Now my_first_variable has been re-bound to a Counter object.
>>> print(type(my_first_variable))
>>> print(my_first_variable)
->>> Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
+Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
```
@@ -94,19 +102,19 @@ MY_FIRST_CONSTANT = "Some other value"
## Functions
-In Python, units of functionality are encapsulated in [_functions._][functions], which are themselves [objects][objects] (_it's [turtles all the way down][turtles all the way down]_).
+In Python, units of functionality are encapsulated in [_functions_][functions], which are themselves [objects][objects] (_it's [turtles all the way down][turtles all the way down]_).
Functions can be executed by themselves, passed as arguments to other functions, nested, or bound to a class.
When functions are bound to a [class][classes] name, they're referred to as [methods][method objects].
Related functions and classes (_with their methods_) can be grouped together in the same file or module, and imported in part or in whole for use in other programs.
The `def` keyword begins a [function definition][function definition].
-Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon.
-Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_.
+Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon.
+Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_:
```python
-# The body of a function is indented by 2 spaces, & prints the sum of the numbers.
+# The body of a function is indented by 2 spaces & prints the sum of the numbers.
def add_two_numbers(number_one, number_two):
total = number_one + number_two
print(total)
@@ -118,7 +126,7 @@ def add_two_numbers(number_one, number_two):
# Inconsistent indentation in your code blocks will raise an error.
>>> def add_three_numbers_misformatted(number_one, number_two, number_three):
... result = number_one + number_two + number_three # This was indented by 4 spaces.
-... print(result) #this was only indented by 3 spaces
+... print(result) # <--This was only indented by 3 spaces.
...
...
File "", line 3
@@ -127,24 +135,69 @@ def add_two_numbers(number_one, number_two):
IndentationError: unindent does not match any outer indentation level
```
-Functions explicitly return a value or object via the [`return`][return] keyword.
-Functions that do not have an explicit `return` expression will _implicitly_ return [`None`][none].
+
+Functions _explicitly_ return a value or object via the [`return`][return] keyword:
+
```python
-# Function definition on first line.
+# Function definition on first line, explicit return used on final line.
def add_two_numbers(number_one, number_two):
- result = number_one + number_two
- return result # Returns the sum of the numbers.
+ return number_one + number_two
+
+# Calling the function in the Python shell returns the sum of the numbers.
>>> add_two_numbers(3, 4)
7
-# This function will return None.
+# Assigning the function call to a variable and printing
+# the variable will also return the value.
+>>> sum_with_return = add_two_numbers(5, 6)
+>>> print(sum_with_return)
+11
+```
+
+Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object.
+The details of `None` will be covered in a later concept.
+For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
+
+
+```python
+
+# This function will return `None`
+def square_a_number(number):
+ square = number * number
+ return # <-- note that this return is not followed by an expression
+
+# Calling the function in the Python shell appears
+# to not return anything at all.
+>>> square_a_number(2)
+>>>
+
+
+# Using print() with the function call shows that
+# the function is actually returning the **None** object.
+>>> print(square_a_number(2))
+None
+```
+
+Functions that omit `return` will also _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
+
+```python
+
+# This function omits a return keyword altogether
def add_two_numbers(number_one, number_two):
result = number_one + number_two
+>>> add_two_numbers(5, 7)
>>> print(add_two_numbers(5, 7))
None
+
+# Assigning the function call to a variable and printing
+# the variable will also show None.
+>>> sum_without_return = add_two_numbers(5, 6)
+>>> print(sum_without_return)
+None
```
@@ -154,32 +207,41 @@ Functions are [_called_][calls] or invoked using their name followed by `()`.
Dot (`.`) notation is used for calling functions defined inside a class or module.
```python
->>> def number_to_the_power_of(number_one, number_two):
- return number_one ** number_two
+>>> def raise_to_power(number, power):
+... return number ** power
...
->>> number_to_the_power_of(3,3) # Invoking the function with the arguments 3 and 3.
+>>> raise_to_power(3,3) # Invoking the function with the arguments 3 and 3.
27
# A mis-match between the number of parameters and the number of arguments will raise an error.
->>> number_to_the_power_of(4,)
+>>> raise_to_power(4,)
...
Traceback (most recent call last):
File "", line 1, in
-TypeError: number_to_the_power_of() missing 1 required positional argument: 'number_two'
+TypeError: raise_to_power() missing 1 required positional argument: 'power'
# Calling methods or functions in classes and modules.
>>> start_text = "my silly sentence for examples."
->>> str.upper(start_text) # Calling the upper() method for the built-in str class.
-"MY SILLY SENTENCE FOR EXAMPLES."
+>>> str.upper(start_text) # <--Calling the upper() method from the built-in str class on start_text.
+'MY SILLY SENTENCE FOR EXAMPLES.'
-# Importing the math module
-import math
+# Because a string is an instance of the str class, methods can also be called on them "directly".
+>>> start_text = "my silly sentence for examples."
+>>> start_text.upper() # <--Calling the upper() method on start_text directly.
+'MY SILLY SENTENCE FOR EXAMPLES.'
+
+# Alternatively, we can skip the variable assignment (although this gets messy quick).
+>>> "my silly sentence for examples.".upper()
+'MY SILLY SENTENCE FOR EXAMPLES.'
->>> math.pow(2,4) # Calling the pow() function from the math module
->>> 16.0
+
+# Importing the math module
+>>> import math
+>>> math.pow(2,4) # <--Calling the pow() function from the math module.
+16.0
```
@@ -210,14 +272,18 @@ Docstrings are declared using triple double quotes (""") indented at the same le
```python
+# An example from PEP257 of a multi-line docstring
+# reformatted to use Google style non-type hinted docstrings.
+# Some additional details can be found in the Sphinx documentation:
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#getting-started
-# An example from PEP257 of a multi-line docstring.
def complex(real=0.0, imag=0.0):
"""Form a complex number.
- Keyword arguments:
- real -- the real part (default 0.0)
- imag -- the imaginary part (default 0.0)
+ Keyword Arguments:
+ real (float): The real part of the number (default 0.0)
+ imag (float): The imaginary part of the number (default 0.0)
+
"""
if imag == 0.0 and real == 0.0:
@@ -234,33 +300,40 @@ Testing and `doctest` will be covered in a later concept.
```python
-# An example on a user-defined function.
->>> def number_to_the_power_of(number_one, number_two):
- """Raise a number to an arbitrary power.
+# An example on a user-defined function using a Google style docstring.
+>>> def raise_to_power(number, power):
+ """Raise a number to an arbitrary power.
+
+ Parameters:
+ number (int): The base number.
+ power (int): The power to raise the base number to.
+
+ Returns:
+ int: The number raised to the specified power.
+
+ Takes a number and raises it to the specified power, returning the result.
- :param number_one: int the base number.
- :param number_two: int the power to raise the base number to.
- :return: int - number raised to power of second number
-
- Takes number_one and raises it to the power of number_two, returning the result.
- """
+ """
- return number_one ** number_two
+ return number ** power
...
# Calling the .__doc__ attribute of the function and printing the result.
->>> print(number_to_the_power_of.__doc__)
+>>> print(raise_to_power.__doc__)
Raise a number to an arbitrary power.
- :param number_one: int the base number.
- :param number_two: int the power to raise the base number to.
- :return: int - number raised to power of second number
+Parameters:
+ number (int): The base number.
+ power (int): The power to raise the base number to.
- Takes number_one and raises it to the power of number_two, returning the result.
+Returns:
+ int: The number raised to the specified power.
+Takes a number and raises it to the specified power, returning the result.
+...
-# Printing the __doc__ attribute for the built-in type: str.
+# Printing the __doc__ attribute of the built-in type: str.
>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
@@ -270,10 +343,11 @@ errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
-encoding defaults to sys.getdefaultencoding().
+encoding defaults to 'utf-8'.
errors defaults to 'strict'.
```
+
[PEP257]: https://www.python.org/dev/peps/pep-0257/
[calls]: https://docs.python.org/3/reference/expressions.html#calls
[classes]: https://docs.python.org/3/reference/datamodel.html#classes
diff --git a/concepts/basics/introduction.md b/concepts/basics/introduction.md
index 34e2a8804d7..cb61a0184ab 100644
--- a/concepts/basics/introduction.md
+++ b/concepts/basics/introduction.md
@@ -2,23 +2,31 @@
Python is a [dynamic and strongly typed][dynamic typing in python] programming language.
It employs both [duck typing][duck typing] and [gradual typing][gradual typing], via [type hints][type hints].
+Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
+
+Python was created by Guido van Rossum and first released in 1991.
Imperative, declarative (e.g., functional), and object-oriented programming _styles_ are all supported, but internally **[everything in Python is an object][everythings an object]**.
-Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
+We'll dig more into what all of that means as we continue through the Python track concepts.
-Python was created by Guido van Rossum and first released in 1991.
+This first concept (`basics`) introduces 4 major Python language features:
+1. Name Assignment (_variables and constants_),
+2. Functions (_the `def` keyword and the `return` keyword_),
+3. Comments, and
+4. Docstrings.
+ = `.
-A name can be reassigned (or re-bound) to different values (different object types) over its lifetime.
+A name can be reassigned (or re-bound) to different values (different object types) over its lifetime:
```python
->>> my_first_variable = 1 # my_first_variable bound to an integer object of value one.
->>> my_first_variable = 2 # my_first_variable re-assigned to integer value 2.
+>>> my_first_variable = 1 # <--my_first_variable bound to an integer object of value one.
+>>> my_first_variable = 2 # <--my_first_variable re-assigned to integer value 2.
>>> print(type(my_first_variable))
@@ -26,31 +34,33 @@ A name can be reassigned (or re-bound) to different values (different object typ
>>> print(my_first_variable)
2
->>> my_first_variable = "Now, I'm a string." # You may re-bind a name to a different object type and value.
+>>> my_first_variable = "Now, I'm a string." # <--You may re-bind a name to a different object type and value.
>>> print(type(my_first_variable))
+>>> my_first_variable = 'You can call me "str".' # <--Strings can be declared using single or double quote marks.
>>> print(my_first_variable)
-"Now, I'm a string." # Strings can be declared using single or double quote marks.
+You can call me "str".
```
### Constants
-Constants are names meant to be assigned only once in a program.
-They should be defined at a [module][module] (file) level, and are typically visible to all functions and classes in the program.
-Using `SCREAMING_SNAKE_CASE` signals that the name should not be re-assigned, or its value mutated.
+Constants are names meant to be assigned only once in a program β although Python will not prevent re-assignment.
+Using `SCREAMING_SNAKE_CASE` signals to anyone reading the code that the name should **not** be re-assigned, or its value mutated.
+Constants should be defined at a [module][module] (file) level, and are typically visible to all functions and classes in a program.
+
## Functions
The `def` keyword begins a [function definition][function definition].
-Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon.
+Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon.
Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_.
```python
-# The body of a function is indented by 2 spaces, & prints the sum of the numbers.
+# The body of this function is indented by 2 spaces & prints the sum of the numbers.
def add_two_numbers(number_one, number_two):
total = number_one + number_two
print(total)
@@ -62,7 +72,7 @@ def add_two_numbers(number_one, number_two):
# Inconsistent indentation in your code blocks will raise an error.
>>> def add_three_numbers_misformatted(number_one, number_two, number_three):
... result = number_one + number_two + number_three # This was indented by 4 spaces.
-... print(result) #this was only indented by 3 spaces
+... print(result) # <--This was only indented by 3 spaces.
...
...
File "", line 3
@@ -71,24 +81,68 @@ def add_two_numbers(number_one, number_two):
IndentationError: unindent does not match any outer indentation level
```
-Functions explicitly return a value or object via the [`return`][return] keyword.
-Functions that do not have an explicit `return` expression will _implicitly_ return [`None`][none].
+
+Functions _explicitly_ return a value or object via the [`return`][return] keyword:
+
```python
-# Function definition on first line.
+# Function definition on first line, explicit return used on final line.
def add_two_numbers(number_one, number_two):
- result = number_one + number_two
- return result # Returns the sum of the numbers.
+ return number_one + number_two
+
+# Calling the function in the Python shell returns the sum of the numbers.
>>> add_two_numbers(3, 4)
7
-# This function will return None.
+# Assigning the function call to a variable and printing
+# the variable will also return the value.
+>>> sum_with_return = add_two_numbers(5, 6)
+>>> print(sum_with_return)
+11
+```
+
+
+Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object.
+The details of `None` will be covered in a later concept.
+For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
+
+
+```python
+# This function will return `None`
+def square_a_number(number):
+ square = number * number
+ return # <-- note that this return is not followed by an expression
+
+# Calling the function in the Python shell appears
+# to not return anything at all.
+>>> square_a_number(2)
+>>>
+
+
+# Using print() with the function call shows that
+# the function is actually returning the **None** object.
+>>> print(square_a_number(2))
+None
+```
+
+Functions that omit `return` will also _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
+
+```python
+# This function omits a return keyword altogether.
def add_two_numbers(number_one, number_two):
result = number_one + number_two
+>>> add_two_numbers(5, 7)
>>> print(add_two_numbers(5, 7))
None
+
+# Assigning the function call to a variable and printing
+# the variable will also show None.
+>>> sum_without_return = add_two_numbers(5, 6)
+>>> print(sum_without_return)
+None
```
@@ -102,29 +156,35 @@ Each line of a comment block must start with the `#` character.
## Docstrings
The first statement of a function body can optionally be a [_docstring_][docstring], which concisely summarizes the function or object's purpose.
-Docstring conventions are laid out in [PEP257][pep257].
+Docstrings are read by automated documentation tools such as [Sphinx][sphinx] and are returned by calling the special attribute `.__doc__` on the function, method, or class name.
+General docstring conventions are laid out in [PEP257][pep257], but exact formats will vary by project and team.
Docstrings are declared using triple double quotes (""") indented at the same level as the code block:
```python
-
-# An example from PEP257 of a multi-line docstring.
+# An example from PEP257 of a multi-line docstring
+# reformatted to use Google style non-type hinted docstrings.
+# Some additional details can be found in the Sphinx documentation:
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#getting-started
def complex(real=0.0, imag=0.0):
"""Form a complex number.
- Keyword arguments:
- real -- the real part (default 0.0)
- imag -- the imaginary part (default 0.0)
+ Keyword Arguments:
+ real (float): The real part of the number (default 0.0)
+ imag (float): The imaginary part of the number (default 0.0)
+
"""
if imag == 0.0 and real == 0.0:
return complex_zero
-
```
-[pep257]: https://www.python.org/dev/peps/pep-0257/
+Docstrings can also function as [lightweight unit tests][doctests], which will be covered in a later concept.
+
+
[comments]: https://realpython.com/python-comments-guide/#python-commenting-basics
[docstring]: https://docs.python.org/3/tutorial/controlflow.html#tut-docstrings
+[doctests]: https://docs.python.org/3/library/doctest.html
[duck typing]: https://en.wikipedia.org/wiki/Duck_typing
[dynamic typing in python]: https://stackoverflow.com/questions/11328920/is-python-strongly-typed
[everythings an object]: https://docs.python.org/3/reference/datamodel.html
@@ -134,6 +194,8 @@ def complex(real=0.0, imag=0.0):
[module]: https://docs.python.org/3/tutorial/modules.html
[none]: https://docs.python.org/3/library/constants.html
[parameters]: https://docs.python.org/3/glossary.html#term-parameter
+[pep257]: https://www.python.org/dev/peps/pep-0257/
[return]: https://docs.python.org/3/reference/simple_stmts.html#return
-[type hints]: https://docs.python.org/3/library/typing.html
[significant indentation]: https://docs.python.org/3/reference/lexical_analysis.html#indentation
+[sphinx]: https://www.sphinx-doc.org/en/master/usage/index.html
+[type hints]: https://docs.python.org/3/library/typing.html
diff --git a/concepts/basics/links.json b/concepts/basics/links.json
index 3e5561228ee..1d1d640c9e7 100644
--- a/concepts/basics/links.json
+++ b/concepts/basics/links.json
@@ -1,5 +1,6 @@
[
- {"url": "https://lerner.co.il/2019/06/18/understanding-python-assignment/",
+ {
+ "url": "https://lerner.co.il/2019/06/18/understanding-python-assignment/",
"description": "Reuven Lerner: Understanding Python Assignment"
},
{
@@ -14,6 +15,10 @@
"url": "https://www.pythonmorsels.com/everything-is-an-object/",
"description": "Python Morsels: Everything is an Object"
},
+ {
+ "url": "https://eli.thegreenplace.net/2012/03/23/python-internals-how-callables-work/",
+ "description": "Eli Bendersky: Python internals: how callables work"
+ },
{
"url": "https://stackoverflow.com/questions/11328920/is-python-strongly-typed",
"description": "dynamic typing and strong typing"
diff --git a/concepts/binary-octal-hexadecimal/about.md b/concepts/binary-octal-hexadecimal/about.md
index 667f3eb6cd7..67646aed2f2 100644
--- a/concepts/binary-octal-hexadecimal/about.md
+++ b/concepts/binary-octal-hexadecimal/about.md
@@ -18,7 +18,7 @@ A snippet from the base 2 system looks like this, although it continues infinite
| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
| 2 \*\* 7 | 2 \*\* 6 | 2 \*\* 5 | 2 \*\* 4 | 2 \*\* 3 | 2 \*\* 2 | 2 \*\* 1 | 2 \*\* 0 |
-So if we want to represent the number 6, it would in binary be: 110
+So if we want to represent the number 6 in binary, it would be 110.
| Place value | 4 | 2 | 1 |
| ------------- | --- | --- | --- |
@@ -41,7 +41,6 @@ In Python, we can represent binary literals using the `0b` prefix.
If we write `0b10011`, Python will interpret it as a binary number and convert it to base 10.
```python
-# 0b10011
>>> 0b10011
19
@@ -86,6 +85,8 @@ However, the usual mathematical operator rules apply: dividing two binary numbe
>>> 0b10011/3
6.333333333333333
+```
+
### Converting to and from Binary Representation
@@ -133,6 +134,9 @@ For example, `bit_count()` on '0b11011' will return 4:
```python
>>> 0b11011.bit_count()
4
+```
+
+
~~~~exercism/note
If you are working locally, `bit_count()` requires at least Python 3.10.
The Exercism online editor currently supports all features through Python 3.11.
@@ -148,7 +152,6 @@ In Python, we can represent octal numbers using the `0o` prefix.
As with binary, Python automatically converts an octal representation to an `int`.
```python
-# 0o123
>>> 0o123
83
```
@@ -157,7 +160,6 @@ As with binary, octal numbers **are ints** and support all integer operations.
Prefixing a number with `0o` that is not in the octal system will raise a `SyntaxError`.
### Converting to and from Octal Representation
-
To convert an `int` into an octal representation, you can use the built-in [`oct()`][oct] function.
This acts similarly to the `bin()` function, returning a string:
@@ -165,6 +167,8 @@ This acts similarly to the `bin()` function, returning a string:
```python
>>> oct(83)
'0o123'
+```
+
To convert an octal number to an integer, we can use the `int()` function, passing an octal string representation and the base (8) as arguments:
@@ -175,23 +179,22 @@ To convert an octal number to an integer, we can use the `int()` function, passi
As with binary, giving the wrong base will raise a `ValueError`.
-### Hexadecimal
+## Hexadecimal
[Hexadecimal][hexadecimal] is a base 16 numeral system.
It uses the digits 0 - 9 and the letters A, B, C, D, E, and F.
A is 10, B is 11, C is 12, D is 13, E is 14, and F is 15.
We can represent hexadecimal numbers in Python using the `0x` prefix.
-As with binary and octal, Python will automatically convert hexadecimal literals to `int`.
+As with binary and octal, Python will automatically convert hexadecimal literals to `int`s.
```python
-# 0x123
>>> 0x123
291
```
-As with binary and octal - hexidecimal literals **are ints**, and you can perform all integer operations.
-Prefixing a non-hexidecimal number with `0x` will raise a `SyntaxError`.
+As with binary and octal β hexadecimal literals **are ints**, and you can perform all integer operations with them.
+Prefixing a non-hexadecimal number with `0x` will raise a `SyntaxError`.
### Converting to and from Hexadecimal Representation
@@ -202,6 +205,8 @@ This acts similarly to the `bin()` function, returning a string:
```python
>>> hex(291)
'0x123'
+```
+
To convert a hexadecimal representation to an integer, we can use the `int()` function, passing a hexadecimal string with the base (16) as arguments:
@@ -216,9 +221,6 @@ As with binary and octal, giving the wrong base will raise a `ValueError`.
[binary]: https://en.wikipedia.org/wiki/Binary_number
[bit_count]: https://docs.python.org/3/library/stdtypes.html#int.bit_count
[bit_length]: https://docs.python.org/3/library/stdtypes.html#int.bit_length
-[bit_count]: https://docs.python.org/3/library/stdtypes.html#int.bit_count
-[bit_length]: https://docs.python.org/3/library/stdtypes.html#int.bit_length
[hexadecimal]: https://en.wikipedia.org/wiki/Hexadecimal
-[methods-int]: https://docs.python.org/3/library/stdtypes.html#additional-methods-on-integer-types
[numeral-systems]: https://en.wikipedia.org/wiki/Numeral_system
[octal]: https://en.wikipedia.org/wiki/Octal
diff --git a/concepts/binary-octal-hexadecimal/introduction.md b/concepts/binary-octal-hexadecimal/introduction.md
index 820aac33ee7..84ff634263d 100644
--- a/concepts/binary-octal-hexadecimal/introduction.md
+++ b/concepts/binary-octal-hexadecimal/introduction.md
@@ -1,11 +1,11 @@
-# binary, octal, hexadecimal
+# Binary, Octal, Hexadecimal
Binary, octal, and hexadecimal (_also known as hex_) are different [numeral systems][numeral-systems] with different bases.
Binary is base 2, octal is base 8, and hexadecimal is base 16.
Normal integers are base 10 in python.
Binary, octal, and hexadecimal literals are all considered `int` subtypes and Python automatically converts between them.
This means that they can only represent zero, positive, and negative numbers that do not have a fractional or decimal part.
-Binary, octal, and hexidecimal numbers support all integer operations.
+Binary, octal, and hexadecimal numbers support all integer operations.
However, division (_as with ints_) will return a `float`.
[numeral-systems]: https://en.wikipedia.org/wiki/Numeral_system
diff --git a/concepts/bitwise-operators/.meta/config.json b/concepts/bitwise-operators/.meta/config.json
index 9b9e8da5a9b..7767ff5d740 100644
--- a/concepts/bitwise-operators/.meta/config.json
+++ b/concepts/bitwise-operators/.meta/config.json
@@ -1,5 +1,5 @@
{
- "blurb": "TODO: add blurb for this concept",
- "authors": ["bethanyg", "cmccandless"],
+ "blurb": "Python supports bitwise operations such as left/right shift, and, or, xor, and not.",
+ "authors": ["BethanyG", "colinleach"],
"contributors": []
}
diff --git a/concepts/bitwise-operators/about.md b/concepts/bitwise-operators/about.md
index c628150d565..1cd5a237c29 100644
--- a/concepts/bitwise-operators/about.md
+++ b/concepts/bitwise-operators/about.md
@@ -1,2 +1,197 @@
-#TODO: Add about for this concept.
+# About
+Down at the hardware level, transistors can only be on or off: two states that we traditionally represent with `1` and `0`.
+These are the [`binary digits`][binary-digits], abbreviated as [`bits`][bits].
+Awareness of `bits` and `binary` is particularly important for systems programmers working in low-level languages.
+
+However, for most of the history of computing the programming priority has been to find increasingly sophisticated ways to _abstract away_ this binary reality.
+In Python (and many other [high-level programming languages][high-level-language]), we work with `int`, `float`, `string` and other defined _types_, up to and including audio and video formats.
+We let the Python internals take care of (eventually) translating everything to bits.
+
+Nevertheless, using [bitwise-operators][python-bitwise-operators] and [bitwise operations][python-bitwise-operations] can sometimes have significant advantages in speed and memory efficiency, even in a high-level language like Python.
+
+
+## Entering and Displaying Binary Numbers
+
+Unsurprisingly, Python interacts with the user using decimal numbers, but a programmer can override this default.
+In fact, Python will readily accept an `int` in `binary`, `hexadecimal`, or `octal` format, and will happily perform mathematical operations between them.
+For more details, you can review the [concept:python/binary-octal-hexadecimal]() concept.
+
+Binary numbers are entered with a `0b` prefix, just as `0x` can be used for hexadecimal (_hex numbers are a concise way to represent groups of 4 bits_), and `oct` can be used for octal numbers.
+
+There are multiple ways to convert integers to binary strings, varying in whether they include the `0b` prefix and whether they support left-padding with zeros:
+
+
+```python
+# Binary entry.
+>>> 0b10111
+23
+
+# Converting an int display to binary string, with prefix.
+>>> bin(23)
+'0b10111'
+
+>>> number = 23
+
+# Binary without prefix, padded to 8 digits.
+>>> format(number, '08b')
+'00010111'
+
+# Same format, but using an f-string.
+>>> f"{number} in decimal is {number:08b} in binary and {number:x} in hex"
+'23 in decimal is 00010111 in binary and 17 in hex'
+```
+
+
+## [`Bitwise Logic`][python-bitwise-operations]
+
+In the [concept:python/bools]() concept, we discussed the _logical operators_ `and`, `or` and `not` used with Boolean (_`True` and `False`_) values.
+The same logic rules apply when working with bits.
+
+However, the bitwise equivalents of the logical operators `&` (_and_), `|` (_or_), `~` (_not_), and `^` (_[XOR][xor]_), are applied to each _bit_ in a binary representation, treating `1` as `True` ("on") and `0` as `False` ("off").
+An example with the bitwise `&` might make this clearer:
+
+
+```python
+>>> x = 0b01100110
+>>> y = 0b00101010
+
+>>> format(x & y, '08b')
+'00100010'
+```
+
+Only positions with a `1` in _**both**_ the input numbers are set to `1` in the output.
+
+Bitwise `&` is commonly used as a way to isolate single bits in a compacted set of `True`/`False` values, such as user-configurable settings in an app.
+This enables the value of individual bits to control program logic:
+
+
+```python
+>>> number = 0b0110
+>>> number & 0b0001 > 0
+False
+
+>>> number & 0b0010 > 0
+True
+```
+
+
+For a bitwise `|` (or), a `1` is set in the output if there is a `1` in _**either**_ of the inputs:
+
+
+```python
+>>> x = 0b01100110
+>>> y = 0b00101010
+
+>>> format(x | y, '08b')
+'01101110'
+```
+
+
+With the `^` operator for bitwise e**x**clusive **or** (xor), a `1` is set if it appears in _**either**_ of the inputs _**but not both**_ inputs.
+This symbol might seem familiar from the [concept:python/sets]() concept, where it is used for `set` _symmetric difference_, which is the same as [xor applied to sets][symmetric-difference].
+If xor `^` seems strange, be aware that this is by far the [most common operation in cryptography][xor-cipher].
+
+
+```python
+>>> x = 0b01100110
+>>> y = 0b00101010
+
+>>> format(x ^ y, '08b')
+'01001100'
+```
+
+
+Finally, there is the `~` operator (_the [tilde][tilde] character_), which is a bitwise `not` that takes a single input and _**inverts all the bits**_, which might not be the result you were expecting!
+Each `1` in the representation changes to `0`, and vice versa.
+See the section below for details.
+
+
+## Negative Numbers and Binary Representation
+
+In decimal representation, we distinguish positive and negative numbers by using a `+` or `-` sign to the left of the digits.
+Using these symbols at a binary level proved inefficient for digital computing and raised the problem that `+0` is not the same as `-0`.
+
+Rather than using `-` and `+`, all modern computers use a [`two's complement`][twos-complement] representation for negative numbers, right down to the silicon chip level.
+This means that all bits are inverted and a number is _**interpreted as negative**_ if the left-most bit (also termed the "most significant bit", or MSB) is a `1`.
+Positive numbers have an MSB of `0`.
+This representation has the advantage of only having one version of zero, so that the programmer doesn't have to manage `-0` and `+0`.
+
+This way of representing negative and positive numbers adds a complication for Python: there are no finite-integer concepts like `int32` or `int64` internally in the core language.
+In 'modern' Python, `int`s are of unlimited size (_limited only by hardware capacity_), and a negative or bit-inverted number has a (_theoretically_) infinite number of `1`'s to the left, just as a positive number has unlimited `0`'s.
+
+This makes it difficult to give a useful example of `bitwise not`:
+
+```python
+>>> x = 0b01100110
+>>> format(x, '08b')
+'01100110'
+
+# This is a negative binary (not twos-complement display).
+>>> format(~x, '08b')
+'-1100111'
+
+ # Decimal representation.
+>>> x
+102
+
+# Using the Bitwise not, with an unintuitive result.
+>>> ~x
+-103
+```
+
+This is **not** the `0b10011001` we would see in languages with fixed-size integers.
+
+The `~` operator only works as expected with _**unsigned**_ byte or integer types, or with fixed-sized integer types.
+These numeric types are supported in third-party packages such as [`NumPy`][numpy], [`pandas`][pandas], and [`sympy`][sympy] but not in core Python.
+
+In practice, Python programmers quite often use `&`, `|`, `^`, and the shift operators described below with positive numbers only.
+Bitwise operations with negative numbers are much less common.
+One technique is to add [`2**32 (or 1 << 32)`][unsigned-int-python] to a negative value to make an `int` unsigned, but this gets difficult to manage.
+Another strategy is to work with the [`ctypes`][ctypes-module] module, and use c-style integer types, but this is equally unwieldy.
+
+
+## [`Shift operators`][bitwise-shift-operators]
+
+The left-shift operator `x << y` moves all the bits in `x` by `y` places to the left, filling the new gaps with zeros.
+Note that this is arithmetically identical to multiplying a number by `(2**y)`.
+
+The right-shift operator `x >> y` does the opposite.
+This is arithmetically identical to integer division `x // (2**y)`.
+
+Keep in mind the previous section on negative numbers and their pitfalls when shifting them in Python.
+
+
+```python
+>>> x = 8
+>>> format(x, '08b')
+'00001000'
+
+# A left bit shift.
+>>> x << 2
+32
+
+>>> format(x << 2, '08b')
+'00100000'
+
+# A right bit shift.
+>>> format(x >> 2, '08b')
+'00000010'
+```
+
+[binary-digits]: https://www.khanacademy.org/computing/computers-and-internet/xcae6f4a7ff015e7d:digital-information/xcae6f4a7ff015e7d:binary-numbers/v/the-binary-number-system
+[bits]: https://en.wikipedia.org/wiki/Bit
+[bitwise-shift-operators]: https://docs.python.org/3/reference/expressions.html#shifting-operations
+[ctypes-module]: https://docs.python.org/3/library/ctypes.html#module-ctypes
+[high-level-language]: https://en.wikipedia.org/wiki/High-level_programming_language
+[numpy]: https://numpy.org/doc/stable/user/basics.types.html
+[pandas]: https://pandas.pydata.org/docs/reference/arrays.html#nullable-integer
+[python-bitwise-operations]: https://docs.python.org/3/reference/expressions.html#binary-bitwise-operations
+[python-bitwise-operators]: https://docs.python.org/3/reference/expressions.html#binary-arithmetic-operations
+[symmetric-difference]: https://math.stackexchange.com/questions/84184/relation-between-xor-and-symmetric-difference#:~:text=It%20is%20the%20same%20thing,they%20are%20indeed%20the%20same.
+[sympy]: https://docs.sympy.org/latest/modules/codegen.html#predefined-types
+[tilde]: https://en.wikipedia.org/wiki/Tilde
+[twos-complement]: https://en.wikipedia.org/wiki/Two%27s_complement
+[unsigned-int-python]: https://stackoverflow.com/a/20768199
+[xor-cipher]: https://en.wikipedia.org/wiki/XOR_cipher
+[xor]: https://stackoverflow.com/a/2451393
diff --git a/concepts/bitwise-operators/introduction.md b/concepts/bitwise-operators/introduction.md
index bbe12ffd5e9..07833339ff2 100644
--- a/concepts/bitwise-operators/introduction.md
+++ b/concepts/bitwise-operators/introduction.md
@@ -1 +1,20 @@
-#TODO: Add introduction for this concept.
+# Introduction
+
+Down at the hardware level, [transistors can only be on or off][how-transistors-work]: two states that we traditionally represent with `1` and `0`.
+These are the [`binary digits`][binary-digits], abbreviated as [`bits`][bits].
+Awareness of `bits` and `binary` is particularly important for systems programmers working in low-level languages.
+However, for most of the history of computing the programming priority has been to find increasingly sophisticated ways to _abstract away_ this binary reality.
+
+
+In Python (and many other [high-level programming languages][high-level-language]), we work with `int`, `float`, `string` and other defined _types_, up to and including audio and video formats.
+Python internals take care of (_eventually_) translating all the higher-level data to bits.
+
+
+Nevertheless, using [bitwise-operators][python-bitwise-operators] and [bitwise operations][python-bitwise-operations] can sometimes have significant advantages in speed and memory efficiency, even in a high-level language like Python.
+
+[high-level-language]: https://en.wikipedia.org/wiki/High-level_programming_language
+[how-transistors-work]: https://www.build-electronic-circuits.com/how-transistors-work/
+[binary-digits]: https://www.khanacademy.org/computing/computers-and-internet/xcae6f4a7ff015e7d:digital-information/xcae6f4a7ff015e7d:binary-numbers/v/the-binary-number-system
+[bits]: https://en.wikipedia.org/wiki/Bit
+[python-bitwise-operations]: https://docs.python.org/3/reference/expressions.html#binary-bitwise-operations
+[python-bitwise-operators]: https://docs.python.org/3/reference/expressions.html#binary-arithmetic-operations
diff --git a/concepts/bitwise-operators/links.json b/concepts/bitwise-operators/links.json
index eb5fb7c38a5..ed251fab33a 100644
--- a/concepts/bitwise-operators/links.json
+++ b/concepts/bitwise-operators/links.json
@@ -1,18 +1,18 @@
[
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://realpython.com/python-bitwise-operators",
+ "description": "Real Python: Bitwise Operators in Python."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://stackoverflow.com/a/20768199",
+ "description": "Stack Overflow: Convert a Python int to an unsigned int."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://www.khanacademy.org/computing/computer-science/cryptography/ciphers/a/xor-bitwise-operation",
+ "description": "Khan Academy: The Ultimate Shift Cipher."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://en.wikipedia.org/wiki/XOR_cipher",
+ "description": "The XOR Cipher"
}
]
diff --git a/concepts/bools/about.md b/concepts/bools/about.md
index 4b697270659..7015fdfafa4 100644
--- a/concepts/bools/about.md
+++ b/concepts/bools/about.md
@@ -1,6 +1,6 @@
# About
-Python represents True and False values with the [bool][bool] type.
+Python represents true and false values with the [`bool`][bools] type, which is a subclass of `int`.
There are only two Boolean values in this type: `True` and `False`.
These values can be assigned to a variable and combined with the [Boolean operators][boolean-operators] (`and`, `or`, `not`):
@@ -22,10 +22,10 @@ Each of the operators has a different precedence, where `not` is evaluated befor
Brackets can be used to evaluate one part of the expression before the others:
```python
->>>not True and True
+>>> not True and True
False
->>>not (True and False)
+>>> not (True and False)
True
```
@@ -45,25 +45,25 @@ A few `built-ins` are always considered `False` by definition:
```python
->>>bool(None)
+>>> bool(None)
False
->>>bool(1)
+>>> bool(1)
True
->>>bool(0)
+>>> bool(0)
False
->>>bool([1,2,3])
+>>> bool([1,2,3])
True
->>>bool([])
+>>> bool([])
False
->>>bool({"Pig" : 1, "Cow": 3})
+>>> bool({"Pig" : 1, "Cow": 3})
True
->>>bool({})
+>>> bool({})
False
```
@@ -95,10 +95,10 @@ The `bool` type is implemented as a _sub-type_ of _int_.
```python
->>>1 == True
+>>> 1 == True
True
->>>0 == False
+>>> 0 == False
True
```
@@ -106,14 +106,14 @@ However, `bools` are **still different** from `ints`, as noted when comparing th
```python
->>>1 is True
+>>> 1 is True
False
->>>0 is False
+>>> 0 is False
False
```
-> Note: in python >= 3.8, using a literal (such as 1, '', [], or {}) on the _left side_ of `is` will raise a warning.
+> Note: in python >= 3.8, using a literal (such as `1`, `''`, `[]`, or `{}`) on the _left side_ of `is` will raise a warning.
It is considered a [Python anti-pattern][comparing to true in the wrong way] to use the equality operator to compare a boolean variable to `True` or `False`.
@@ -134,8 +134,8 @@ It is considered a [Python anti-pattern][comparing to true in the wrong way] to
```
-[bool-function]: https://docs.python.org/3/library/functions.html#bool
-[bool]: https://docs.python.org/3/library/stdtypes.html#truth
[Boolean-operators]: https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not
+[bool-function]: https://docs.python.org/3/library/functions.html#bool
+[bools]: https://docs.python.org/3/library/stdtypes.html#typebool
[comparing to true in the wrong way]: https://docs.quantifiedcode.com/python-anti-patterns/readability/comparison_to_true.html
[comparisons]: https://docs.python.org/3/library/stdtypes.html#comparisons
diff --git a/concepts/bools/introduction.md b/concepts/bools/introduction.md
index 535f90be07c..85eb032df25 100644
--- a/concepts/bools/introduction.md
+++ b/concepts/bools/introduction.md
@@ -1,6 +1,6 @@
# Introduction
-Python represents true and false values with the `bool` type.
+Python represents true and false values with the [`bool`][bools] type, which is a subclass of `int`.
There are only two values under that type: `True` and `False`.
These values can be bound to a variable:
@@ -21,3 +21,5 @@ We can evaluate Boolean expressions using the `and`, `or`, and `not` operators.
>>> true_variable = not False
>>> false_variable = not True
```
+
+[bools]: https://docs.python.org/3/library/stdtypes.html#typebool
diff --git a/concepts/class-inheritance/about.md b/concepts/class-inheritance/about.md
index 5db7909e2c7..9f1bdf30cd9 100644
--- a/concepts/class-inheritance/about.md
+++ b/concepts/class-inheritance/about.md
@@ -7,7 +7,7 @@ In situations where only a small amount of functionality needs to be customized
`Inheritance` describes `is a kind of` relationship between two or more classes, abstracting common details into super (_base_ or _parent_) class and storing specific ones in the subclass (_derived class_ or _child class_).
-To create a child class, specify the parent class name inside the pair of parenthesis, followed by it's name.
+To create a child class, specify the parent class name inside the pair of parenthesis, followed by its name.
Example
```python
class Child(Parent):
diff --git a/concepts/classes/about.md b/concepts/classes/about.md
index f50af7321d3..9b6a8a0dfb7 100644
--- a/concepts/classes/about.md
+++ b/concepts/classes/about.md
@@ -118,7 +118,7 @@ class MyClass:
def __init__(self, location):
# This is an instance or object property, attribute, or variable.
- # Note that we are unpacking the tuple argument into two seperate instance variables.
+ # Note that we are unpacking the tuple argument into two separate instance variables.
self.location_x = location[0]
self.location_y = location[1]
@@ -185,10 +185,10 @@ class Demo:
The moment that `.add_two()` is called, and `self.new_var += 2` is read, `new_var` changes from a class variable to an instance variable of the same name.
This can be useful during initialization when all instances of a class will need some attribute(s) to start with the same value.
-However, the instance variable then shadows* the class variable, making the class variable inaccessible from the instance where it is shadowed.
+However, the instance variable then [_shadows_](https://oznetnerd.com/2017/07/17/python-shadowing/) the class variable, making the class variable inaccessible from the instance where it is shadowed.
Given this situation, it may be safer and clearer to set instance attributes from the `__init__()` method as `self.`.
~~~~
-_*[_shadows_][shadowing]
+
## Methods
@@ -240,7 +240,7 @@ class MyClass:
def change_location(self, amount):
self.location_x += amount
self.location_y += amount
- return self.location_x, self.location_y
+ return self.location_x, self.location_y
# Make a new test_object with location (3,7)
>>> test_object = MyClass((3,7))
@@ -267,7 +267,7 @@ class MyClass:
def change_location(self, amount):
self.location_x += amount
self.location_y += amount
- return self.location_x, self.location_y
+ return self.location_x, self.location_y
# Alter class variable number for all instances from within an instance.
def increment_number(self):
@@ -314,12 +314,11 @@ class MyClass:
# This will compile and run without error, but has no current functionality.
def pending_functionality(self):
- # Stubbing or placholding the body of this method.
+ # Stubbing or place-holding the body of this method.
pass
```
[class method]: https://stackoverflow.com/questions/17134653/difference-between-class-and-instance-methods
-[dunder]: https://www.dataindependent.com/python/python-glossary/python-dunder/
+[dunder]: https://mathspp.com/blog/pydonts/dunder-methods
[oop]: https://www.educative.io/blog/object-oriented-programming
[dot notation]: https://stackoverflow.com/questions/45179186/understanding-the-dot-notation-in-python
-[shadowing]: https://oznetnerd.com/2017/07/17/python-shadowing/
diff --git a/concepts/classes/links.json b/concepts/classes/links.json
index 5687b92a3d1..8cc9ba5926e 100644
--- a/concepts/classes/links.json
+++ b/concepts/classes/links.json
@@ -17,7 +17,7 @@
},
{
"url": "https://dbader.org/blog/6-things-youre-missing-out-on-by-never-using-classes-in-your-python-code",
- "description": "6 Things Youre Missing out on by never using classes in your Python code."
+ "description": "6 Things You are Missing out on by never using classes in your Python code."
},
{
"url": "http://python-history.blogspot.com/2010/06/inside-story-on-new-style-classes.html",
diff --git a/concepts/comparisons/about.md b/concepts/comparisons/about.md
index c2f5faaad91..9aa681ff9f5 100644
--- a/concepts/comparisons/about.md
+++ b/concepts/comparisons/about.md
@@ -13,7 +13,7 @@ The table below shows the most common Python comparison operators:
| `<=` | "less than or equal to" | `a <= b` is `True` if `a < b` or `a == b` in value |
| `!=` | "not equal to" | `a != b` is `True` if `a == b` is `False` |
| `is` | "identity" | `a is b` is `True` if **_and only if_** `a` and `b` are the same _object_ |
-| `is not` | "negated identity" | `a is not b` is `True` if `a` and `b` are **not** the same _object_ |
+| `is not` | "negated identity" | `a is not b` is `True` if **_and only if_** `a` and `b` are **not** the same _object_ |
| `in` | "containment test" | `a in b` is `True` if `a` is member, subset, or element of `b` |
| `not in` | "negated containment test" | `a not in b` is `True` if `a` is not a member, subset, or element of `b` |
@@ -29,7 +29,7 @@ Numeric types are (mostly) an exception to this type matching rule.
An `integer` **can** be considered equal to a `float` (_or an [`octal`][octal] equal to a [`hexadecimal`][hex]_), as long as the types can be implicitly converted for comparison.
For the other numeric types ([complex][complex numbers], [decimal][decimal numbers], [fractions][rational numbers]), comparison operators are defined where they "make sense" (_where implicit conversion does not change the outcome_), but throw a `TypeError` if the underlying objects cannot be accurately converted for comparison.
-For more information on the rules that python uses for numeric conversion, see [arithmetic conversions][arithmetic conversions] in the Python documentation.
+For more information on the rules that Python uses for numeric conversion, see [arithmetic conversions][arithmetic conversions] in the Python documentation.
```python
>>> import fractions
@@ -47,7 +47,8 @@ True
>>> 6/3 == 0b10
True
-# An int can be converted to a complex number with a 0 imaginary part.
+# An int can be converted to a complex
+# number with a 0 imaginary part.
>>> 17 == complex(17)
True
@@ -60,8 +61,8 @@ True
```
Any ordered comparison of a number to a `NaN` (_not a number_) type is `False`.
-A confusing side-effect of Python's `NaN` definition is that `NaN` never compares equal to `NaN`.
-If you are curious as to why `Nan` was defined this way in Python, this [Stack Overflow Post on NaN][so nan post] around the setting of the international standard is an interesting read.
+A confusing side effect of Python's `NaN` definition is that `NaN` never compares equal to `NaN`.
+If you are curious as to why `NaN` was defined this way in Python, this [Stack Overflow Post on NaN][so nan post] around the setting of the international standard is an interesting read.
```python
>>> x = float('NaN')
@@ -145,7 +146,7 @@ True
Comparison operators can be chained _arbitrarily_.
Note that the evaluation of an expression takes place from `left` to `right`.
-For example, `x < y <= z` is equivalent to `x < y` `and` `y <= z`, except that `y` is evaluated **only once**.
+For example, `x < y <= z` is equivalent to `x < y and y <= z`, except that `y` is evaluated **only once**.
In both cases, `z` is _not_ evaluated **at all** when `x < y` is found to be `False`.
This is often called `short-circuit evaluation` - the evaluation stops if the truth value of the expression has already been determined.
@@ -179,7 +180,7 @@ Due to their singleton status, `None` and `NotImplemented` should always be comp
See the Python reference docs on [value comparisons][value comparisons none] and [PEP8][PEP8 programming recommendations] for more details on this convention.
```python
->>>
+
# A list of favorite numbers.
>>> my_fav_numbers = [1, 2, 3]
@@ -188,7 +189,7 @@ See the Python reference docs on [value comparisons][value comparisons none] and
>>> my_fav_numbers is your_fav_numbers
True
-# The returned id will differ by system and python version.
+# The returned id will differ by system and Python version.
>>> id(my_fav_numbers)
4517478208
@@ -217,7 +218,7 @@ The operators `in` and `not in` test for _membership_.
For string and bytes types, ` in ` is `True` _**if and only if**_ `` is a substring of ``.
```python
->>>
+
# A set of lucky numbers.
>>> lucky_numbers = {11, 22, 33}
>>> 22 in lucky_numbers
diff --git a/concepts/comparisons/introduction.md b/concepts/comparisons/introduction.md
index e597063c621..40c40ea8a10 100644
--- a/concepts/comparisons/introduction.md
+++ b/concepts/comparisons/introduction.md
@@ -13,7 +13,7 @@ The table below shows the most common Python comparison operators:
| `<=` | "less than or equal to" | `a <= b` is `True` if `a < b` or `a == b` in value |
| `!=` | "not equal to" | `a != b` is `True` if `a == b` is `False` |
| `is` | "identity" | `a is b` is `True` if **_and only if_** `a` and `b` are the same _object_ |
-| `is not` | "negated identity" | `a is not b` is `True` if `a` and `b` are **not** the same _object_ |
+| `is not` | "negated identity" | `a is not b` is `True` if **_and only if_** `a` and `b` are **not** the same _object_ |
| `in` | "containment test" | `a in b` is `True` if `a` is member, subset, or element of `b` |
| `not in` | "negated containment test" | `a not in b` is `True` if `a` is not a member, subset, or element of `b` |
diff --git a/concepts/comparisons/links.json b/concepts/comparisons/links.json
index ed61054b722..f16869e2b92 100644
--- a/concepts/comparisons/links.json
+++ b/concepts/comparisons/links.json
@@ -1,27 +1,19 @@
[
- {
- "url": "https://docs.python.org/3/reference/expressions.html#comparisons",
- "description": "Comparisons in Python (Python language reference)"
- },
{
"url": "https://www.tutorialspoint.com/python/python_basic_operators.htm",
"description": "Python basic operators on Tutorials Point"
},
{
- "url": "https://data-flair.training/blogs/python-comparison-operators/",
- "description": "Python comparison operators on Data Flair"
- },
- {
- "url": "https://www.python.org/dev/peps/pep-0207/",
- "description": "PEP 207 to allow Operator Overloading for Comparison"
+ "url": "https://docs.python.org/3/reference/expressions.html#comparisons",
+ "description": "Comparisons in Python (Python language reference)"
},
{
"url": "https://docs.python.org/3/reference/expressions.html#is-not",
"description": "Identity comparisons in Python (Python language reference)"
},
{
- "url": "https://docs.python.org/3/library/operator.html",
- "description": "Operators (Python Docs)"
+ "url": "https://docs.python.org/3/reference/expressions.html#value-comparisons",
+ "description": "Value comparisons in Python (Python language reference)"
},
{
"url": "https://docs.python.org/3/library/stdtypes.html#typesnumeric",
@@ -44,11 +36,11 @@
"description": "Python Object Model (Python docs)"
},
{
- "url": "https://docs.python.org/3/reference/datamodel.html#customization",
- "description": "Basic Customization (Python language reference)"
+ "url": "https://www.python.org/dev/peps/pep-0207/",
+ "description": "PEP 207 to allow Operator Overloading for Comparison"
},
{
- "url": "https://docs.python.org/3/reference/expressions.html#value-comparisons",
- "description": "Value comparisons in Python (Python language reference)"
+ "url": "https://docs.python.org/3/reference/datamodel.html#customization",
+ "description": "Basic Customization (Python language reference)"
}
]
diff --git a/concepts/complex-numbers/.meta/config.json b/concepts/complex-numbers/.meta/config.json
index 9b9e8da5a9b..ca6ccc8811d 100644
--- a/concepts/complex-numbers/.meta/config.json
+++ b/concepts/complex-numbers/.meta/config.json
@@ -1,5 +1,5 @@
{
- "blurb": "TODO: add blurb for this concept",
- "authors": ["bethanyg", "cmccandless"],
+ "blurb": "Complex numbers are a fundamental data type in Python, along with int and float. Further support is added with the cmath module, which is part of the Python standard library.",
+ "authors": ["BethanyG", "colinleach"],
"contributors": []
}
diff --git a/concepts/complex-numbers/about.md b/concepts/complex-numbers/about.md
index c628150d565..2b0de864e7b 100644
--- a/concepts/complex-numbers/about.md
+++ b/concepts/complex-numbers/about.md
@@ -1,2 +1,260 @@
-#TODO: Add about for this concept.
+# About
+
+`Complex numbers` are not complicated.
+They just need a less alarming name.
+
+They are so useful β especially in engineering and science β that Python includes [`complex`][complex] as a standard numeric type, alongside integers ([`int`s][ints]) and floating-point numbers ([`float`s][floats]).
+
+
+## Basics
+
+A `complex` value in Python is essentially a pair of floating-point numbers.
+These are called the "real" and "imaginary" parts, for unfortunate historical reasons.
+Again, it is best to focus on the underlying simplicity and not the strange names.
+
+There are two common ways to create complex numbers.
+
+1) The [`complex(real, imag)`][complex] constructor takes two `float` parameters:
+
+```python
+>>> z1 = complex(1.5, 2.0)
+>>> z1
+(1.5+2j)
+```
+
+The constructor can also parse string input.
+This has the odd limitation that it fails if the string contains spaces.
+
+```python
+>>> complex('4+2j')
+(4+2j)
+
+>>> complex('4 + 2j')
+Traceback (most recent call last):
+ File "", line 1, in
+ValueError: complex() arg is a malformed string
+```
+
+
+2) The complex number can be specified as ` + j` literal, or just `j` if the real part is zero:
+
+
+```python
+>>> z2 = 2.0 + 1.5j
+>>> z2
+(2+1.5j)
+```
+The end result is identical to using the `complex()` constructor.
+
+
+There are two rules for that imaginary part of the complex number:
+
+
+- It is designated with `j` (not `i` as you may see in math textbooks).
+
+- The `j` must immediately follow a number, to prevent Python seeing it as a variable name. If necessary, use `1j`.
+
+```python
+>>> j
+Traceback (most recent call last):
+ File "", line 1, in
+NameError: name 'j' is not defined
+
+>>> 1j
+1j
+
+>>> type(1j)
+
+```
+
+Most engineers are happy with `j`.
+Most scientists and mathematicians prefer the mathematical notation `i` for _imaginary_, but that notation conflicts with the use of `i` to mean _current_ in Electrical Engineering.
+So in designing Python, the Electrical Engineers won.
+
+
+To access the parts of a complex number individually:
+
+```python
+>>> z2.real
+2.0
+>>> z2.imag
+1.5
+```
+
+Either part can be zero and mathematicians may then talk of the number being "wholly real" or "wholly imaginary".
+However, it is still a complex number in Python:
+
+
+```python
+>>> complex(0, 1)
+1j
+>>> type(complex(0, 1))
+
+
+>>> complex(1, 0)
+(1+0j)
+```
+
+You may have heard that "`i` (or `j`) is the square root of -1".
+
+For now, all this means is that the imaginary part _by definition_ satisfies the equality
+```python
+1j * 1j == -1 # => True
+```
+
+This is a simple idea, but it leads to interesting consequences.
+
+## Arithmetic
+
+Most of the [`operators`][operators] used with floats and ints also work with complex numbers:
+
+
+```python
+>>> z1 = (1.5+2j)
+>>> z2 = (2+1.5j)
+
+
+>>> z1 + z2 # addition
+(3.5+3.5j)
+
+>>> z1 - z2 # subtraction
+(-0.5+0.5j)
+
+>>> z1 * z2 # multiplication
+6.25j
+
+>>> z1 / z2 # division
+(0.96+0.28j)
+
+>>> z1 ** 2 # exponentiation
+(-1.75+6j)
+
+>>> 2 ** z1 # another exponentiation
+(0.5188946835878313+2.7804223253571183j)
+
+>>> 1j ** 2 # j * j == -1
+(-1+0j)
+```
+
+Explaining the rules for complex number multiplication and division is out of scope for this concept (_and you are unlikely to have to perform those operations "by hand" very often_).
+
+Any [mathematical][math-complex] or [electrical engineering][engineering-complex] introduction to complex numbers will cover this, should you want to dig into the topic.
+
+Alternatively, Exercism has a `Complex Numbers` practice exercise where you can implement a complex number class with these operations from first principles.
+
+
+Integer division is ___not___ possible on complex numbers, so the `//` and `%` operators and the `divmod()` function will fail for the complex number type.
+
+
+There are two functions implemented for numeric types that are very useful when working with complex numbers:
+
+- `.conjugate()` simply flips the sign of the imaginary part of a complex number (_from + to - or vice-versa_).
+ - Because of the way complex multiplication works, this is more useful than you might think.
+- `abs()` is guaranteed to return a real number with no imaginary part.
+
+
+```python
+>>> z1
+(1.5+2j)
+
+>>> z1.conjugate() # flip the z1.imag sign
+(1.5-2j)
+
+>>> abs(z1) # sqrt(z1.real ** 2 + z1.imag ** 2)
+2.5
+```
+
+## The `cmath` module
+
+The Python standard library has a [`math`][math-module] module full of useful functionality for working with real numbers.
+
+It also has an equivalent [`cmath`][cmath] module for working with complex numbers.
+
+
+We encourage you to read through the module and experiment, but the main categories are:
+
+- Conversion between Cartesian and polar coordinates,
+- Exponential and log functions,
+- Trigonometric functions,
+- Hyperbolic functions,
+- Classification functions, and
+- Useful constants.
+
+Here is an example using some constants:
+
+```python
+>>> import cmath
+
+>>> euler = cmath.exp(1j * cmath.pi) # Euler's equation
+
+>>> euler.real
+-1.0
+>>> round(euler.imag, 15) # round to 15 decimal places
+0.0
+```
+
+So a simple expression with three of the most important constants in nature `e`, `i` (or `j`) and `pi` gives the result `-1`.
+Some people believe this is the most beautiful result in all of mathematics.
+It dates back to around 1740.
+
+-----
+
+## Optional section: a Complex Numbers FAQ
+
+This part can be skipped, unless you are interested.
+
+### Isn't this some strange new piece of pure mathematics?
+
+It was strange and new in the 16th century.
+
+500 years later, it is central to most of engineering and the physical sciences.
+
+### Why would anyone use these?
+
+It turns out that complex numbers are the simplest way to describe anything that rotates or anything with a wave-like property.
+So they are used widely in electrical engineering, audio processing, physics, computer gaming, and navigation - to name only a few applications.
+
+You can see things rotate.
+Complex numbers may not make the world go round, but they are great for explaining _what happens_ as a result of the world going round: look at any satellite image of a major storm.
+
+
+Less obviously, sound is wave-like, light is wave-like, radio signals are wave-like, and even the economy of your home country is at least partly wave-like.
+
+
+A lot of this wave processing can be done with trig functions (`sin()` and `cos()`) but that gets messy quite quickly.
+
+Complex exponentials are ___much___ easier to work with.
+
+### But I don't need complex numbers!
+
+
+Only true if you are living in a cave and foraging for your food.
+
+If you are reading this on any sort of screen, you are utterly dependent on some useful 20th-Century advances made through the use of complex numbers.
+
+
+1. __Semiconductor chips__.
+ - These make no sense in classical physics and can only be explained (and designed) by quantum mechanics (QM).
+ - In QM, everything is complex-valued by definition. (_it's waveforms all the way down_)
+
+2. __The Fast Fourier Transform (FFT) algorithm__.
+ - FFT is an application of complex numbers, and it is in _everything_ connected to sound transmission, audio processing, photos, and video.
+
+ - MP3 and other audio formats use FFT for compression, ensuring more audio can fit within a smaller storage space.
+ - JPEG compression and MP4 video, among many other image and video formats, also use FTT for compression.
+
+ - FFT is also deployed in the digital filters that allow cellphone towers to separate your personal cell signal from everyone else's.
+
+
+So, you are probably using technology that relies on complex number calculations thousands of times per second.
+
+
+[complex]: https://docs.python.org/3/library/functions.html#complex
+[cmath]: https://docs.python.org/3/library/cmath.html
+[operators]: https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
+[math-module]: https://docs.python.org/3/library/math.html
+[math-complex]: https://www.nagwa.com/en/videos/143121736364/
+[engineering-complex]: https://www.khanacademy.org/science/electrical-engineering/ee-circuit-analysis-topic/ee-ac-analysis/v/ee-complex-numbers
+[ints]: https://docs.python.org/3/library/functions.html#int
+[floats]: https://docs.python.org/3/library/functions.html#float
diff --git a/concepts/complex-numbers/introduction.md b/concepts/complex-numbers/introduction.md
index fcde74642ca..419c3f3d486 100644
--- a/concepts/complex-numbers/introduction.md
+++ b/concepts/complex-numbers/introduction.md
@@ -1,2 +1,95 @@
-#TODO: Add introduction for this concept.
+# Introduction
+`Complex numbers` are not complicated.
+They just need a less alarming name.
+
+
+They are so useful β especially in engineering and science β that Python includes [`complex`][complex] as a standard numeric type, alongside integers ([`int`s][ints]) and floating-point numbers ([`float`s][floats]).
+
+
+A `complex` value in Python is essentially a pair of floating-point numbers:
+
+```python
+>>> my_complex = 5.443+6.77j
+(5.443+6.77j)
+```
+
+These are called the "real" and "imaginary" parts.
+You may have heard that "`i` (or `j`) is the square root of -1".
+For now, all this means is that the imaginary part _by definition_ satisfies the equality `1j * 1j == -1`.
+This is a simple idea, but it leads to interesting mathematical consequences.
+
+In Python, the "imaginary" part is designated with `j` (_not `i` as you would see in math textbooks_), and
+the `j` must immediately follow a number, to prevent Python seeing it as a variable name:
+
+
+```python
+>>> j
+Traceback (most recent call last):
+ File "", line 1, in
+NameError: name 'j' is not defined
+
+>>> 1j
+1j
+
+>>> type(1j)
+
+```
+
+
+There are two common ways to create complex numbers.
+
+1) The [`complex(real, imag)`][complex] constructor takes two `float` parameters:
+
+ ```python
+ >>> z1 = complex(1.5, 2.0)
+ >>> z1
+ (1.5+2j)
+ ```
+
+ The constructor can also parse string input.
+ This has the odd limitation that it fails if the string contains spaces.
+
+ ```python
+ >>> complex('4+2j')
+ (4+2j)
+
+ >>> complex('4 + 2j')
+ Traceback (most recent call last):
+ File "", line 1, in
+ ValueError: complex() arg is a malformed string
+ ```
+
+
+2) The complex number can be specified as ` + j` literal, or just `j` if the real part is zero:
+
+
+ ```python
+ >>> z2 = 2.0 + 1.5j
+ >>> z2
+ (2+1.5j)
+ ```
+ The end result is identical to using the `complex()` constructor.
+
+
+## Arithmetic
+
+Most of the [`operators`][operators] used with floats and ints also work with complex numbers.
+
+Integer division is _**not**_ possible on complex numbers, so the `//` and `%` operators and the `divmod()` function will fail for the complex number type.
+
+Explaining the rules for complex number multiplication and division is out of scope for this concept (_and you are unlikely to have to perform those operations "by hand" very often_).
+
+Any [mathematical][math-complex] or [electrical engineering][engineering-complex] introduction to complex numbers will cover these scenarios, should you want to dig into the topic.
+
+The Python standard library has a [`math`][math-module] module full of useful functionality for working with real numbers, and the [`cmath`][cmath] module is its equivalent for working with complex numbers.
+
+
+[cmath]: https://docs.python.org/3/library/cmath.html
+[complex]: https://docs.python.org/3/library/functions.html#complex
+[engineering-complex]: https://www.khanacademy.org/science/electrical-engineering/ee-circuit-analysis-topic/ee-ac-analysis/v/ee-complex-numbers
+[floats]: https://docs.python.org/3/library/functions.html#float
+[ints]: https://docs.python.org/3/library/functions.html#int
+[math-complex]: https://www.nagwa.com/en/videos/143121736364/
+[math-module]: https://docs.python.org/3/library/math.html
+[operators]: https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
diff --git a/concepts/complex-numbers/links.json b/concepts/complex-numbers/links.json
index eb5fb7c38a5..759ef1689ff 100644
--- a/concepts/complex-numbers/links.json
+++ b/concepts/complex-numbers/links.json
@@ -1,18 +1,18 @@
[
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex/",
+ "description": "Operations on numeric types."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://docs.python.org/3/library/functions.html#complex/",
+ "description": "The complex class."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://docs.python.org/3/library/cmath.html/",
+ "description": "Module documentation for cmath."
},
{
- "url": "http://example.com/",
- "description": "TODO: add new link (above) and write a short description here of the resource."
+ "url": "https://docs.python.org/3/library/math.html/",
+ "description": "Module documentation for math."
}
]
diff --git a/concepts/conditionals/about.md b/concepts/conditionals/about.md
index 3b3d5b1ba1d..8891683f791 100644
--- a/concepts/conditionals/about.md
+++ b/concepts/conditionals/about.md
@@ -8,7 +8,6 @@ Python 3.10 introduces a variant case-switch statement called `pattern matching`
Conditional statements use expressions that must resolve to `True` or `False` -- either by returning a `bool` directly, or by evaluating ["truthy" or "falsy"][truth value testing].
-
```python
x = 10
y = 5
@@ -55,19 +54,43 @@ else:
>>> z is greater than x and y
```
-[Boolen operations][boolean operations] and [comparisons][comparisons] can be combined with conditionals for more complex testing:
+[Boolean operations][boolean operations] and [comparisons][comparisons] can be combined with conditionals for more complex testing:
+
```python
+>>> def classic_fizzbuzz(number):
+... if number % 3 == 0 and number % 5 == 0:
+... say = 'FizzBuzz!'
+... elif number % 5 == 0:
+... say = 'Buzz!'
+... elif number % 3 == 0:
+... say = 'Fizz!'
+... else:
+... say = str(number)
+...
+... return say
+
+>>> classic_fizzbuzz(15)
+'FizzBuzz!'
+
+>>> classic_fizzbuzz(13)
+'13'
+```
+
+As an alternative, the example above can be re-written to only use `if` statements with `returns`.
+However, re-writing in this way might obscure that the conditions are intended to be [_mutually exclusive_][mutually-exclusive] and could lead to future bugs or maintenance issues.
+
+```python
>>> def classic_fizzbuzz(number):
- if number % 3 == 0 and number % 5 == 0:
- return 'FizzBuzz!'
- elif number % 5 == 0:
- return 'Buzz!'
- elif number % 3 == 0:
- return 'Fizz!'
- else:
- return str(number)
+... if number % 3 == 0 and number % 5 == 0:
+... return 'FizzBuzz!'
+... if number % 5 == 0:
+... return 'Buzz!'
+... if number % 3 == 0:
+... return 'Fizz!'
+...
+... return str(number)
>>> classic_fizzbuzz(15)
'FizzBuzz!'
@@ -76,47 +99,51 @@ else:
'13'
```
+
Conditionals can also be nested.
+
```python
>>> def driving_status(driver_age, test_score):
- if test_score >= 80:
- if 18 > driver_age >= 16:
- return "Student driver, needs supervision."
- elif driver_age == 18:
- return "Permitted driver, on probation."
- elif driver_age > 18:
- return "Fully licensed driver."
- else:
- return "Unlicensed!"
+... if test_score >= 80:
+... if 18 > driver_age >= 16:
+... status = "Student driver, needs supervision."
+... elif driver_age == 18:
+... status = "Permitted driver, on probation."
+... elif driver_age > 18:
+... status = "Fully licensed driver."
+... else:
+... status = "Unlicensed!"
+...
+... return status
>>> driving_status(63, 78)
-'Unlicsensed!'
+'Unlicensed!'
>>> driving_status(16, 81)
'Student driver, needs supervision.'
>>> driving_status(23, 80)
-'Fully licsensed driver.'
+'Fully licensed driver.'
```
## Conditional expressions or "ternary operators"
While Python has no specific `?` ternary operator, it is possible to write single-line `conditional expressions`.
-These take the form of `` if `` else ``.
+These take the form of ` if else `.
Since these expressions can become hard to read, it's recommended to use this single-line form only if it shortens code and helps readability.
```python
-def just_the_buzz(number):
- return 'Buzz!' if number % 5 == 0 else str(number)
+>>> def just_the_buzz(number):
+... return 'Buzz!' if number % 5 == 0 else str(number)
>>> just_the_buzz(15)
'Buzz!'
->>> just_the_buzz(10)
-'10'
+>>> just_the_buzz(7)
+'7'
```
## Truthy and Falsy
@@ -126,33 +153,34 @@ Objects that are evaluated in this fashion are considered "truthy" or "falsy", a
```python
>>> def truthy_test(thing):
- if thing:
- print('This is Truthy.')
- else:
- print("Nope. It's Falsey.")
+... if thing:
+... print('This is Truthy.')
+... else:
+... print("Nope. It's Falsy.")
-# Empty container objects are considered Falsey.
+# Empty container objects are considered Falsy.
>>> truthy_test([])
-Nope. It's Falsey.
+"Nope. It's Falsy."
>>> truthy_test(['bear', 'pig', 'giraffe'])
-This is Truthy.
+'This is Truthy.'
-# Empty strings are considered Falsey.
+# Empty strings are considered Falsy.
>>> truthy_test('')
-Nope. It's Falsey.
+"Nope. It's Falsy."
>>> truthy_test('yes')
-This is Truthy.
+'This is Truthy.'
-# 0 is also considered Falsey.
+# 0 is also considered Falsy.
>>> truthy_test(0)
-Nope. It's Falsey.
+"Nope. It's Falsy."
```
-[if statement]: https://docs.python.org/3/reference/compound_stmts.html#the-if-statement
-[control flow tools]: https://docs.python.org/3/tutorial/controlflow.html#more-control-flow-tools
-[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
[boolean operations]: https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not
[comparisons]: https://docs.python.org/3/library/stdtypes.html#comparisons
+[control flow tools]: https://docs.python.org/3/tutorial/controlflow.html#more-control-flow-tools
+[if statement]: https://docs.python.org/3/reference/compound_stmts.html#the-if-statement
+[mutually-exclusive]: https://stackoverflow.com/a/22783232
+[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
diff --git a/concepts/conditionals/introduction.md b/concepts/conditionals/introduction.md
index 29e3e635975..ba4f098493d 100644
--- a/concepts/conditionals/introduction.md
+++ b/concepts/conditionals/introduction.md
@@ -45,10 +45,8 @@ z = 20
# The elif statement allows for the checking of more conditions.
if x > y > z:
-
print("x is greater than y and z")
elif y > x > z:
-
print("y is greater than x and z")
else:
print("z is greater than x and y")
@@ -56,19 +54,19 @@ else:
>>> z is greater than x and y
```
-[Boolen operations][boolean operations] and [comparisons][comparisons] can be combined with conditionals for more complex testing:
+[Boolean operations][boolean operations] and [comparisons][comparisons] can be combined with conditionals for more complex testing:
```python
-
>>> def classic_fizzbuzz(number):
- if number % 3 == 0 and number % 5 == 0:
- return 'FizzBuzz!'
- elif number % 5 == 0:
- return 'Buzz!'
- elif number % 3 == 0:
- return 'Fizz!'
- else:
- return str(number)
+... if number % 3 == 0 and number % 5 == 0:
+... say = 'FizzBuzz!'
+... elif number % 5 == 0:
+... say = 'Buzz!'
+... elif number % 3 == 0:
+... say = 'Fizz!'
+... else:
+... say = str(number)
+... return say
>>> classic_fizzbuzz(15)
'FizzBuzz!'
@@ -77,8 +75,9 @@ else:
'13'
```
-[if statement]: https://docs.python.org/3/reference/compound_stmts.html#the-if-statement
-[control flow tools]: https://docs.python.org/3/tutorial/controlflow.html#more-control-flow-tools
-[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
+
[boolean operations]: https://docs.python.org/3/library/stdtypes.html#boolean-operations-and-or-not
[comparisons]: https://docs.python.org/3/library/stdtypes.html#comparisons
+[control flow tools]: https://docs.python.org/3/tutorial/controlflow.html#more-control-flow-tools
+[if statement]: https://docs.python.org/3/reference/compound_stmts.html#the-if-statement
+[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
diff --git a/concepts/dict-methods/about.md b/concepts/dict-methods/about.md
index d910d3e9168..7af90a77145 100644
--- a/concepts/dict-methods/about.md
+++ b/concepts/dict-methods/about.md
@@ -1,28 +1,29 @@
# Dictionary Methods in Python
The `dict` class in Python provides many useful [methods][dict-methods] for working with dictionaries.
-Some were introduced in the concept for `dicts`.
+Some were introduced in the concept for `dict`s.
Here we cover a few more - along with some techniques for iterating through and manipulating dictionaries.
-- `dict.setdefault()` automatically adds keys without throwing a KeyError.
-- `dict.fromkeys(iterable, )` creates a new `dict` from any number of iterables.
-- `.keys()`, `.values()`, and `.items()` provide convenient iterators.
-- `sorted(.items())`. can easily re-order entries in a `dict`.
-- `dict_one.update()` updates one `dict` with overlapping values from another `dict`.
-- `dict | other_dict` and `dict |= other_dict` merges or updates two `dict`s via operators.
-- `reversed(dict.keys())`, `reversed(dict.values())`, or `reversed(dict.items())` produce _reversed_ views.
+- `.setdefault()` automatically adds keys without throwing a KeyError.
+- `.fromkeys(, )` creates a new `dict` from any number of iterables.
+- `.keys()`, `.values()`, and `.items()` provide convenient iterators.
+- `sorted(.items())` can easily re-order entries in a `dict`.
+- `.update()` updates one `dict` with overlapping values from another `dict`.
+- ` | ` and ` |= ` merges or updates two `dict`s via operators.
+- `reversed(.keys())`, `reversed(.values())`, or `reversed(.items())` produce _reversed_ views.
- `.popitem()` removes and returns a `key`, `value` pair.
## `setdefault()` for Error-Free Insertion
-The dictionary concept previously covered that `.get(key, )` returns an existing `value` or the `default value` if a `key` is not found in a dictionary, thereby avoiding a `KeyError`.
+The dictionary concept previously covered that `.get(, )` returns an existing `value` or the `default value` if a `key` is not found in a dictionary, thereby avoiding a `KeyError`.
This works well in situations where you would rather not have extra error handling but cannot trust that a looked-for `key` will be present.
-For a similarly "safe" (_without KeyError_) insertion operation, there is the `.setdefault(key, )` method.
-`setdefault(key, )` will return the `value` if the `key` is found in the dictionary.
+For a similarly "safe" (_without `KeyError`_) insertion operation, there is the `.setdefault(, )` method.
+`.setdefault(, )` will return the `value` if the `key` is found in the dictionary.
If the key is **not** found, it will _insert_ the (`key`, `default value`) pair and return the `default value` for use.
+
```python
>>> palette_I = {'Grassy Green': '#9bc400', 'Purple Mountains Majesty': '#8076a3', 'Misty Mountain Pink': '#f9c5bd'}
@@ -38,7 +39,7 @@ If the key is **not** found, it will _insert_ the (`key`, `default value`) pair
## `fromkeys()` to Populate a Dictionary from an Iterable
-To quickly populate a dictionary with various `keys` and default values, the _class method_ [`fromkeys(iterable, )`][fromkeys] will iterate through an iterable of `keys` and create a new `dict`.
+To quickly populate a dictionary with various `keys` and default values, the _class method_ [`fromkeys(, )`][fromkeys] will iterate through an iterable of `keys` and create a new `dict`.
All `values` will be set to the `default value` provided:
```python
@@ -71,13 +72,12 @@ If the dictionary is empty, calling `popitem()` will raise a `KeyError`:
# All (key, value) pairs have been removed.
>>> palette_I.popitem()
Traceback (most recent call last):
-
line 1, in
palette_I.popitem()
-
KeyError: 'popitem(): dictionary is empty'
```
+
## Iterating Over Entries in a Dictionary Via Views
The `.keys()`, `.values()`, and `.items()` methods return [_iterable views_][dict-views] of a dictionary.
@@ -136,7 +136,7 @@ This allows keys, values, or (`key`, `value`) pairs to be iterated over in Last-
('Purple baseline', '#161748')
>>> for item in reversed(palette_II.items()):
-... print (item)
+... print(item)
...
('Purple baseline', '#161748')
('Green Treeline', '#478559')
@@ -166,12 +166,12 @@ This method will take the (`key`,`value`) pairs of `` and write them i
Where keys in the two dictionaries _overlap_, the `value` in `dict_one` will be _overwritten_ by the corresponding `value` from `dict_two`:
```python
->>> palette_I = {'Grassy Green': '#9bc400',
- 'Purple Mountains Majesty': '#8076a3',
- 'Misty Mountain Pink': '#f9c5bd',
- 'Factory Stone Purple': '#7c677f',
- 'Green Treeline': '#478559',
- 'Purple baseline': '#161748'}
+>>> palette_I = {'Grassy Green': '#9bc400',
+ 'Purple Mountains Majesty': '#8076a3',
+ 'Misty Mountain Pink': '#f9c5bd',
+ 'Factory Stone Purple': '#7c677f',
+ 'Green Treeline': '#478559',
+ 'Purple baseline': '#161748'}
>>> palette_III = {'Grassy Green': (155, 196, 0),
'Purple Mountains Majesty': (128, 118, 163),
@@ -188,7 +188,7 @@ Where keys in the two dictionaries _overlap_, the `value` in `dict_one` will be
'Green Treeline': '#478559', 'Purple baseline': '#161748'}
```
-## Merge or Update Dictionaries Via the Union (`|`) Operators
+## Merge or Update Dictionaries Using Union (`|` and `|=`) Operators
Python 3.9 introduces a different means of merging `dicts`: the `union` operators.
`dict_one | dict_two` will create a **new dictionary**, made up of the (`key`, `value`) pairs of `dict_one` and `dict_two`.
@@ -214,7 +214,7 @@ When both dictionaries share keys, `dict_two` values take precedence.
'Purple baseline': '#161748'}
```
-`dict_one |= other` behaves similar to `.update()`, but in this case, `other` can be either a `dict` or an iterable of (`key`, `value`) pairs:
+`dict_one |= other` behaves similar to `.update()`, but in this case, `other` can be either a `dict` or an iterable of (`key`, `value`) pairs:
```python
>>> palette_III = {'Grassy Green': (155, 196, 0),
@@ -271,7 +271,7 @@ Unless a _sort key_ is specified, the default sort is over dictionary `keys`.
'Misty Mountain Pink': '#f9c5bd'}
```
-## Transposing a Dictionaries Keys and Values
+## Transposing Dictionary Keys and Values
Swapping keys and values reliably in a dictionary takes a little work, but can be accomplished via a `loop` using `dict.items()` or in a dictionary comprehension.
Safe swapping assumes that `dict` keys and values are both _hashable_.
@@ -333,10 +333,10 @@ If the values stored in the `dict` are not unique, extra checks become necessary
# Iterating over (key, value) pairs using .items()
>>> for key, value in extended_color_reference.items():
-... if value in consolidated_colors: #Check if key has already been created.
+... if value in consolidated_colors: # <--Check if key has already been created.
... consolidated_colors[value].append(key)
... else:
-... consolidated_colors[value] = [key] #Create a value list with the former key in it.
+... consolidated_colors[value] = [key] # <--Create a value list with the former key in it.
>>> consolidated_colors
{'Purple Mountains Majesty': ['#8076a3', (128, 118, 163), (21, 28, 0, 36)],
diff --git a/concepts/dict-methods/introduction.md b/concepts/dict-methods/introduction.md
index c15fbc113de..b1e8eb8f20a 100644
--- a/concepts/dict-methods/introduction.md
+++ b/concepts/dict-methods/introduction.md
@@ -4,13 +4,13 @@ The `dict` class in Python provides many useful [methods][dict-methods], some of
This concept tackles a few more:
-- `dict.setdefault()` automatically adds keys without throwing a `KeyError`.
-- `dict.fromkeys(iterable, )` creates a new `dict` from any number of iterables.
-- `.keys()`, `.values()`, and `.items()` provide convenient iterators.
-- `sorted(.items())`. can easily re-order entries in a `dict`.
-- `dict_one.update()` updates one `dict` with overlapping values from another `dict`.
-- `dict | other_dict` and `dict |= other_dict` merges or updates two `dict`s via operators.
-- `reversed(dict.keys())`, `reversed(dict.values())`, or `reversed(dict.items())` produce _reversed_ views.
+- `.setdefault()` automatically adds keys without throwing a KeyError.
+- `.fromkeys(, )` creates a new `dict` from any number of iterables.
+- `.keys()`, `.values()`, and `.items()` provide convenient iterators.
+- `sorted(.items())` can easily re-order entries in a `dict`.
+- `.update()` updates one `dict` with overlapping values from another `dict`.
+- ` | ` and ` |= ` merges or updates two `dict`s via operators.
+- `reversed(.keys())`, `reversed(.values())`, or `reversed(.items())` produce _reversed_ views.
- `.popitem()` removes and returns a `key`, `value` pair.
[dict-methods]: https://docs.python.org/3/library/stdtypes.html#dict
diff --git a/concepts/dicts/about.md b/concepts/dicts/about.md
index c34160b2ef6..a525f6248c7 100644
--- a/concepts/dicts/about.md
+++ b/concepts/dicts/about.md
@@ -3,9 +3,9 @@
A dictionary (`dict`) in Python is a data structure that associates [hashable][term-hashable] _keys_ to _values_ and is known in other programming languages as a resizable [hash table][hashtable-wikipedia], hashmap, or [associative array][associative-array].
Dictionaries are Python's only built-in [mapping type][mapping-types-dict].
-`Keys` must be hashable and unique across the dictionary.
-Key types can include `numbers`, `str`, or `tuples` (of _immutable_ values).
-They cannot contain _mutable_ data structures such as `lists`, `dict`s, or `set`s.
+`keys` must be hashable and unique across the dictionary.
+Key types can include `number`s, `str`s, or `tuple`s (of _immutable_ values).
+They cannot contain _mutable_ data structures such as `list`s, `dict`s, or `set`s.
As of Python 3.7, `dict` key order is guaranteed to be the order in which entries are inserted.
`values` can be of any data type or structure.
@@ -20,10 +20,10 @@ Dictionaries are especially useful in scenarios where the collection of items is
## Dictionary Construction
Dictionaries can be created in many different ways, including:
- - Using the [`fromkeys()`][fromkeys] classmethod
- - Creating [dictionary comprehensions][dict-comprehensions]
- - Merging two dictionaries via unpacking (`**`)
- - Merging dictionaries via the `|` (_update_) operator
+ - Using the [`fromkeys()`][fromkeys] class method.
+ - Using [dictionary comprehensions][dict-comprehensions].
+ - Merging two dictionaries via unpacking (`**`).
+ - Merging dictionaries via the `|` (_update_) operator.
- Using a loop to iteratively add entries to a previously created empty `dict`.
The two most straightforward methods are the dictionary _constructor_ and the dictionary _literal_.
@@ -35,17 +35,20 @@ The two most straightforward methods are the dictionary _constructor_ and the di
```python
# Passing a list of key,value tuples.
->>> wombat = dict([('name', 'Wombat'),('speed', 23),
- ('land_animal', True)])
+>>> wombat = dict([('name', 'Wombat'),
+... ('speed', 23),
+... ('land_animal', True)])
{'name': 'Wombat', 'speed': 23, 'land_animal': True}
# Using key=value arguments.
->>> bear = dict(name="Black Bear", speed=40, land_animal=True)
+>>> bear = dict(name="Black Bear",
+... speed=40,
+... land_animal=True)
{'name': 'Black Bear', 'speed': 40, 'land_animal': True}
```
-The [documentation on `dicts`][dicts-docs] outlines additional variations and options in constructor use.
+The [documentation on `dict`s][dicts-docs] outlines additional variations and options in constructor use.
### Dictionary Literals
@@ -74,41 +77,41 @@ Dictionaries can be arbitrarily nested:
```python
animals = {
- "Real" : {
- "Winged" : {
- "Sparrow" : {'name': 'sparrow','speed': 12, 'land_animal': True},
- "Kestrel" : {'name': 'kestrel', 'speed': 15, 'land_animal': True}
- },
- "Legged" : {
- "Wombat" : {'name': 'Wombat', 'speed': 23, 'land_animal': True},
- "Black Bear": {'name': 'Black Bear', 'speed': 40, 'land_animal': True},
- "Polecat" : {'name': 'Polecat', 'speed': 15, 'land_animal': True}
- },
- "Other" : {
- "Whale" : {'name': 'Blue Whale', 'speed': 35, 'land_animal': False},
- "Orca" : {'name': 'Orca', 'speed': 45, 'land_animal': False},
- "Snake" : {'name': 'Python', 'speed': 25, 'land_animal': True}
- }
- },
+ "Real" : {
+ "Winged" : {
+ "Sparrow" : {'name': 'sparrow','speed': 12, 'land_animal': True},
+ "Kestrel" : {'name': 'kestrel', 'speed': 15, 'land_animal': True}
+ },
+ "Legged" : {
+ "Wombat" : {'name': 'Wombat', 'speed': 23, 'land_animal': True},
+ "Black Bear": {'name': 'Black Bear', 'speed': 40, 'land_animal': True},
+ "Polecat" : {'name': 'Polecat', 'speed': 15, 'land_animal': True}
+ },
+ "Other" : {
+ "Whale" : {'name': 'Blue Whale', 'speed': 35, 'land_animal': False},
+ "Orca" : {'name': 'Orca', 'speed': 45, 'land_animal': False},
+ "Snake" : {'name': 'Python', 'speed': 25, 'land_animal': True}
+ }
+ },
- "Imaginary": {
- "Winged" : {
- "Dragon" : {'name': 'Fire Dragon','speed': 100, 'land_animal': True},
- "Phoenix" : {'name': 'Phoenix', 'speed': 1500, 'land_animal': True}
- },
- "Legged" : {
- "Sphinx" : {'name': 'Sphinx','speed': 10, 'land_animal': True},
- "Minotaur" : {'name': 'Minotaur', 'speed': 5, 'land_animal': True}
- },
- "Other" : {}
- }
- }
+ "Imaginary": {
+ "Winged" : {
+ "Dragon" : {'name': 'Fire Dragon','speed': 100, 'land_animal': True},
+ "Phoenix" : {'name': 'Phoenix', 'speed': 1500, 'land_animal': True}
+ },
+ "Legged" : {
+ "Sphinx" : {'name': 'Sphinx','speed': 10, 'land_animal': True},
+ "Minotaur" : {'name': 'Minotaur', 'speed': 5, 'land_animal': True}
+ },
+ "Other" : {}
+ }
+ }
```
## Accessing Values in a `dict`
You can access a `value` in a dictionary using a _key_ in square brackets.
-If a key does not exist, a `KeyError` is thrown:
+If a key does not exist in the dictionary, a `KeyError` is thrown:
```python
>>> bear["speed"]
@@ -172,7 +175,7 @@ You can change an entry `value` by assigning to its _key_:
New `key`:`value` pairs can be _added_ in the same fashion:
```python
-# Adding an new "color" key with a new "tawney" value.
+# Adding a new "color" key with a new "tawney" value.
>>> bear["color"] = 'tawney'
{'name': 'Grizzly Bear', 'speed': 40, 'land_animal': True, 'color': 'tawney'}
@@ -183,9 +186,9 @@ New `key`:`value` pairs can be _added_ in the same fashion:
## Removing (Pop-ing and del) Dictionary Entries
-You can use the `.pop()` method to delete a dictionary entry.
-`.pop()` removes the (`key`, `value`) pair and returns the `value` for use.
-Like `.get()`, `.pop()` accepts second argument (_`dict.pop(, )`_) that will be returned if the `key` is not found.
+You can use the `.pop()` method to delete a dictionary entry.
+`.pop()` removes the (`key`, `value`) pair and returns the `value` for use.
+Like `.get()`, `.pop()` accepts second argument (_`.pop(, )`_) that will be returned if the `key` is not found.
This prevents a `KeyError` being raised:
```python
@@ -208,8 +211,8 @@ KeyError: 'name'
'Unknown'
```
-You can also use the `del` statement to remove a single or multiple entries.
-A `KeError` is raised if the entry to be removed is not found in the dictionary:
+You can also use the `del` statement to remove one or more entries.
+A `KeyError` is raised if the entry to be removed is not found in the dictionary:
```python
>>> wombat = {'name': 'Wombat',
@@ -245,7 +248,7 @@ You can access _values_ within the same loop by using _square brackets_:
```python
>>> for key in bear:
->>> print((key, bear[key])) #this prints a tuple of (key, value)
+... print((key, bear[key])) # <--This prints a tuple of (key, value).
('name', 'Black Bear')
('speed', 40)
('land_animal', True)
@@ -257,7 +260,7 @@ You can also use the `.items()` method, which returns (`key`, `value`) tuples:
# dict.items() forms (key, value tuples) that can be
# unpacked and iterated over.
>>> for key, value in whale.items():
->>> print(key, ":", value)
+... print(key, ":", value)
name : Blue Whale
speed : 25
land_animal : False
@@ -271,11 +274,11 @@ For a detailed explanation of dictionaries in Python, the [official documentatio
## Extending Dictionary Functionality: The Collections Module
-The [`collections`][collections-docs] module adds specialized functionality to Python's standard collection-based datatypes (`dictionary`, `set`, `list`, `tuple`).
+The [`collections`][collections-docs] module adds specialized functionality to Python's standard collection-based datatypes (`dict`, `set`, `list`, `tuple`).
Three of the most useful dictionary-based classes are:
- [`Counter`][counter-dicts] automatically counts items and returns them in a `dict` with the items as keys and their counts as values.
-- [`OrderedDict`][ordered-dicts-docs], has methods specialized for arranging the order of dictionary entries.
+- [`OrderedDict`][ordered-dicts-docs] has methods specialized for arranging the order of dictionary entries.
- [`defaultdict`][default-dicts] uses a factory method to set a default value if a `key` is not found when trying to retrieve or assign to a dictionary entry.
[associative-array]: https://en.wikipedia.org/wiki/Associative_array#:~:text=In%20computer%20science%2C%20an%20associative,a%20function%20with%20finite%20domain.
diff --git a/concepts/dicts/introduction.md b/concepts/dicts/introduction.md
index 5c8a772480b..676bf11066d 100644
--- a/concepts/dicts/introduction.md
+++ b/concepts/dicts/introduction.md
@@ -4,9 +4,9 @@ A dictionary (`dict`) in Python is a data structure that associates [hashable][t
Dictionaries are Python's only built-in [mapping type][mapping-types-dict].
-`Keys` must be hashable and unique across the dictionary.
-Key types can include `numbers`, `str`, or `tuples` (of _immutable_ values).
-They cannot contain _mutable_ data structures such as `lists`, `dict`s, or `set`s.
+`keys` must be hashable and unique across the dictionary.
+Key types can include `number`s, `str`s, or `tuple`s (of _immutable_ values).
+They cannot contain _mutable_ data structures such as `list`s, `dict`s, or `set`s.
As of Python 3.7, `dict` key order is guaranteed to be the order in which entries are inserted.
`values` can be of any data type or structure.
diff --git a/concepts/enums/about.md b/concepts/enums/about.md
index 27b264c22e1..dacd7bfd755 100644
--- a/concepts/enums/about.md
+++ b/concepts/enums/about.md
@@ -1,14 +1,19 @@
# About
-In Python, [an enum][enum-docs] is a set of unique names that are bound unique, **constant** values. Enums are defined by inheriting an `Enum` class. Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`.
+In Python, [an enum][enum-docs] is a set of unique names that are bound unique, **constant** values.
+`Enums` are defined by inheriting an `Enum` class.
+Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`.
+
```python
+from enum import Enum
+
class Color(Enum):
RED = 1
GREEN = 2
```
-Note that the values of the enum members can be any data types such as str, tuple, float, etc.
+Note that the values of the `enum` members can be any data types such as `str`, `tuple`, `float`, etc.
```python
class Color(Enum):
@@ -16,9 +21,11 @@ class Color(Enum):
GREEN = 'green'
```
-Enums can also be created via the following [functional API][enum-functional-api].
+`Enums` can also be created using [function-call syntax][enum-functional-example].
```python
+from enum import Enum
+
Animal = Enum('Animal', 'ANT BEE CAT DOG')
list(Animal)
#=> [, , , ]
@@ -27,7 +34,7 @@ Animal.ANT.value
#=> 1
```
-When assigning the same value to two members in an enum, the latter assigned member will be an alias to the formed one. It is not allowed to use the same name for two members of an enum.
+When assigning the same value to two members in an `enum`, the latter assigned member will be an alias to the former one. It is not allowed to use the same name for two different members of an `enum`.
```python
class Color(Enum):
@@ -50,12 +57,13 @@ for member in Color:
# __members__.items() helps you to loop through alias as well
for member in Color.__members__.items():
print(member)
-#=>('RED', )
-#=>('GREEN', )
-#=>('ALIAS_OF_RED', )
+#=> ('RED', )
+#=> ('GREEN', )
+#=> ('ALIAS_OF_RED', )
```
-Enum members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise.
+`Enum` members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise:
+
```python
a = Color.RED
@@ -76,10 +84,10 @@ class Shape(Enum):
OVAL = auto()
```
-To disallow aliasing (_preventing duplicate values with different names_), the `@unique` decorator may be used.
+To disallow aliasing (_preventing duplicate values with different names_), the [class decorator][class-decorator] [`@enum.unique`][enum-unique-decorator] decorator may be used.
```python
-@unique
+@enum.unique
class Shape(Enum):
CIRCLE = 1
SQUARE = 2
@@ -87,7 +95,7 @@ class Shape(Enum):
#=> ValueError: duplicate values found in : TRIANGLE -> CIRCLE
```
-To access an enum member for a given value, this notation can be used: `EnumName(value)`.
+To access an `enum` member for a given value, this notation can be used: `()`.
```python
g = Color(2)
@@ -99,15 +107,23 @@ g
#=>
```
-A custom [restricted `Enum`][restricted-enums] can be written by subclassing `Enum` with any mix-in or data-type. For example:
+A custom [restricted `Enum`][restricted-enums] can be written by subclassing the `Enum` class with any mix-in or data-type.
+For example:
+
```python
class StrEnum(str, Enum):
pass
```
-[enum-docs]: https://docs.python.org/3/library/enum.html
-[enum-auto-docs]: https://docs.python.org/3/library/enum.html#using-auto
-[enum-functional-api]: https://docs.python.org/3/library/enum.html#functional-api
-[restricted-enums]: https://docs.python.org/3/library/enum.html#restricted-enum-subclassing
+Subclassing `Enum` is only allowed if the `enum` does **not** define any members.
+See the [`enum` how-to][enum-docs] and the [`enum` cookbook][cookbook] for more details and explanations.
+
+[class-decorator]: https://docs.python.org/3/reference/compound_stmts.html#class-definitions
+[cookbook]: https://docs.python.org/3/howto/enum.html#enum-cookbook
+[enum-auto-docs]: https://docs.python.org/3/library/enum.html#enum.auto
+[enum-docs]: https://docs.python.org/3/howto/enum.html#enum-basic-tutorial
+[enum-functional-example]: https://docs.python.org/3/library/enum.html
[identity-keyword]: https://www.w3schools.com/python/ref_keyword_is.asp
+[restricted-enums]: https://docs.python.org/3/howto/enum.html#restricted-enum-subclassing
+[enum-unique-decorator]: https://docs.python.org/3/library/enum.html#enum.unique
diff --git a/concepts/enums/introduction.md b/concepts/enums/introduction.md
index ea9c9000e07..bf4e8b9d043 100644
--- a/concepts/enums/introduction.md
+++ b/concepts/enums/introduction.md
@@ -1,14 +1,19 @@
# Introduction
-In Python, [an enum](https://docs.python.org/3/library/enum.html) is a set of names that are bound to unique `literal`, or `constant` values. Enums are defined by inheriting an `Enum` class. Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`.
+In Python, [an `enum`][enum-docs] is a set of names that are bound to unique `literal`, or `constant` values.
+`Enums` are defined by inheriting from or subclassing an `Enum` class.
+Built-in `enum` types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`.
+
```python
+from enum import Enum
+
class Color(Enum):
RED = 1
GREEN = 2
```
-Note that the values of the enum members can be any data types such as str, tuple, float, etc.
+Note that the values of the `enum` members can be any data types such as `str`, `tuple`, `float`, etc.
```python
class Color(Enum):
@@ -16,7 +21,7 @@ class Color(Enum):
GREEN = 'green'
```
-When assigning the same value to two members in an enum, the latter assigned member will be an alias to the formed one. It is not allowed to use the same name for two members of an enum.
+When assigning the same value to two members in an `enum`, the latter assigned member will be an alias to the former one. It is not allowed to use the same name for two different members of an `enum`.
```python
class Color(Enum):
@@ -31,7 +36,7 @@ Color.ALIAS_OF_RED.value
#=> 1
```
-Iterating through the members of the enum can be done with the standard `for member in` syntax:
+Iterating through the members of the `enum` can be done with the standard `for member in` syntax:
```python
for member in Color:
@@ -40,7 +45,7 @@ for member in Color:
#=> (GREEN, 2)
```
-Enum members can be compared using [`is` (_identity operator_)](https://www.w3schools.com/python/ref_keyword_is.asp) or `is not`. The `==` or `!=` (_equality_operators_) work likewise.
+`Enum` members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise:
```python
a = Color.RED
@@ -52,7 +57,7 @@ a == Color.RED
#=> True
```
-To access an enum member for a given value, `EnumName(value)` can be used:
+To access an `enum` member for a given value, `()` can be used:
```python
g = Color(2)
@@ -63,3 +68,6 @@ g is Color.GREEN
g
#=>
```
+
+[enum-docs]: https://docs.python.org/3/library/enum.html
+[identity-keyword]: https://www.w3schools.com/python/ref_keyword_is.asp
diff --git a/concepts/fractions/.meta/config.json b/concepts/fractions/.meta/config.json
new file mode 100644
index 00000000000..621a3766d84
--- /dev/null
+++ b/concepts/fractions/.meta/config.json
@@ -0,0 +1,5 @@
+{
+ "blurb": "The fractions module enables working with rational numbers, which preserve exact values and avoid the rounding errors common with floats.",
+ "authors": ["BethanyG", "colinleach"],
+ "contributors": []
+}
diff --git a/concepts/fractions/about.md b/concepts/fractions/about.md
new file mode 100644
index 00000000000..e582c53141a
--- /dev/null
+++ b/concepts/fractions/about.md
@@ -0,0 +1,122 @@
+# About
+
+The [`fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator.
+
+For example, we can store `2/3` as an exact fraction instead of the approximate `float` value `0.6666...`
+
+## Creating Fractions
+
+
+Unlike `int`, `float`, and `complex` numbers, fractions do not have a literal form.
+However, the fraction constructor is quite flexible.
+
+Most obviously, it can take two integers.
+Common factors are automatically removed, converting the fraction to its "lowest form" (_the smallest integers that accurately represent the fraction_):
+
+
+```python
+>>> from fractions import Fraction
+
+>>> f1 = Fraction(2, 3) # 2/3
+>>> f1
+Fraction(2, 3)
+
+>>> f2 = Fraction(6, 9)
+>>> f2
+Fraction(2, 3) # automatically simplified
+
+>>> f1 == f2
+True
+```
+
+The fraction constructor can also parse a string representation:
+
+
+```python
+>>> f3 = Fraction('2/3')
+>>> f3
+Fraction(2, 3)
+```
+
+It can also work with `float` parameters, but this may run into problems with the approximate nature of representing the decimal value internally as binary.
+For more on this representation issue, see the [0.30000000000000004][0.30000000000000004] website, and [Floating Point Arithmetic: Issues and Limitations ][fp-issues] in the Python documentation.
+
+For a more reliable result when using floats with fractions, there is the `.limit_denominator()` method.
+
+
+[`.limit_denominator()`][limit_denominator] can take an integer parameter if you have specific requirements, but even the default (`max_denominator=1000000`) can work well and give an acceptable, simple approximation.
+
+```python
+>>> Fraction(1.2)
+Fraction(5404319552844595, 4503599627370496)
+
+>>> Fraction(1.2).limit_denominator()
+Fraction(6, 5)
+```
+
+## Arithmetic with Fractions
+
+
+The usual [`arithmetic operators`][operators] `+ - * / **` work with fractions, as with other numeric types.
+
+Integers and other `Fraction`s can be included and give a `Fraction` result.
+Including a `float` in the expression results in `float` output, with a consequent (possible) loss in precision.
+
+
+```python
+>>> Fraction(2, 3) + Fraction(1, 4) # addition
+Fraction(11, 12)
+
+>>> Fraction(2, 3) * Fraction(6, 5) # multiply fractions
+Fraction(4, 5)
+
+>>> Fraction(2, 3) * 6 / 5 # fraction with integers
+Fraction(4, 5)
+
+>>> Fraction(2, 3) * 1.2 # fraction with float -> float
+0.7999999999999999
+
+>>> Fraction(2, 3) ** 2 # exponentiation with integer
+Fraction(4, 9)
+```
+
+## Conversions to and from Fractions
+
+
+Fractions are great for preserving precision during intermediate calculations, but may not be what you want for the final output.
+
+It is possible to get the numerator and denominator individually or as a tuple ([`tuples`][tuple] will be discussed in a later Concept):
+
+```python
+>>> Fraction(2, 3).numerator
+2
+>>> Fraction(2, 3).denominator
+3
+>>> Fraction(2, 3).as_integer_ratio()
+(2, 3)
+```
+
+Various standard Python numeric functions also give the result you might expect from working with `int` and `float` types:
+
+```python
+>>> round(Fraction(11, 3))
+4
+
+>>> from math import floor, ceil
+>>> floor(Fraction(11, 3))
+3
+>>> ceil(Fraction(11, 3))
+4
+
+>>> float(Fraction(11, 3))
+3.6666666666666665
+```
+
+[fractions]: https://docs.python.org/3/library/fractions.html
+[0.30000000000000004]: https://0.30000000000000004.com/
+[fp-issues]: https://docs.python.org/3/tutorial/floatingpoint.html#tut-fp-issues
+[tuple]: https://docs.python.org/3/tutorial/datastructures.html#tuples-and-sequences
+
+[operators]: https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
+[rational]: https://en.wikipedia.org/wiki/Rational_number
+[limit_denominator]: https://docs.python.org/3/library/fractions.html
diff --git a/concepts/fractions/introduction.md b/concepts/fractions/introduction.md
new file mode 100644
index 00000000000..156aa3ff280
--- /dev/null
+++ b/concepts/fractions/introduction.md
@@ -0,0 +1,85 @@
+# Introduction
+
+The [`fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator.
+For example, we can store `2/3` as an exact fraction instead of the approximate `float` value `0.6666...`.
+
+Unlike `int`, `float`, and `complex` numbers, fractions do not have a literal form.
+However, the fraction constructor is quite flexible.
+
+Most obviously, it can take two integers as arguments.
+Common factors are automatically removed, converting the fraction to its "lowest form" (_the smallest integers that accurately represent the fraction_):
+
+```python
+>>> from fractions import Fraction
+
+>>> f1 = Fraction(2, 3) # 2/3
+>>> f1
+Fraction(2, 3)
+
+>>> f2 = Fraction(6, 9)
+>>> f2
+Fraction(2, 3) # automatically simplified
+
+>>> f1 == f2
+True
+```
+
+The fraction constructor can also parse a string representation:
+
+```python
+>>> f3 = Fraction('2/3')
+>>> f3
+Fraction(2, 3)
+```
+
+Fractions can also work with `float` parameters, but this may run into problems with the approximate nature of representing the decimal value internally as binary.
+For more on this representation issue, see the [0.30000000000000004][0.30000000000000004] website, and [Floating Point Arithmetic: Issues and Limitations ][fp-issues] in the Python documentation.
+
+For a more reliable result when using floats with fractions, there is the `.limit_denominator()` method.
+
+
+## Arithmetic with Fractions
+
+The usual [`arithmetic operators`][operators] `+ - * / **` will work with fractions, as with other numeric types.
+
+Integers and other `Fraction`s can be included in the equation and give a `Fraction` result.
+Including a `float` in the expression results in `float` output, with a consequent (possible) loss in precision:
+
+```python
+>>> Fraction(2, 3) + Fraction(1, 4) # addition
+Fraction(11, 12)
+
+>>> Fraction(2, 3) * Fraction(6, 5) # multiply fractions
+Fraction(4, 5)
+
+>>> Fraction(2, 3) * 6 / 5 # fraction with integers
+Fraction(4, 5)
+
+>>> Fraction(2, 3) * 1.2 # fraction with float -> float
+0.7999999999999999
+
+>>> Fraction(2, 3) ** 2 # exponentiation with integer
+Fraction(4, 9)
+```
+
+Various standard Python numeric functions also give the result you might expect from working with `int` and `float` types:
+
+```python
+>>> round(Fraction(11, 3))
+4
+
+>>> from math import floor, ceil
+>>> floor(Fraction(11, 3))
+3
+>>> ceil(Fraction(11, 3))
+4
+
+>>> float(Fraction(11, 3))
+3.6666666666666665
+```
+
+[0.30000000000000004]: https://0.30000000000000004.com/
+[fp-issues]: https://docs.python.org/3/tutorial/floatingpoint.html#tut-fp-issues
+[fractions]: https://docs.python.org/3/library/fractions.html
+[operators]: https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
+[rational]: https://en.wikipedia.org/wiki/Rational_number
diff --git a/concepts/fractions/links.json b/concepts/fractions/links.json
new file mode 100644
index 00000000000..78d349bcfc3
--- /dev/null
+++ b/concepts/fractions/links.json
@@ -0,0 +1,18 @@
+[
+ {
+ "url": "https://docs.python.org/3/library/fractions.html/",
+ "description": "Documentation for the Fractions module."
+ },
+ {
+ "url": "https://docs.python.org/3/tutorial/floatingpoint.html#tut-fp-issues",
+ "description": "Limitations of Floating Point Arithmetic."
+ },
+ {
+ "url": "https://leancrew.com/all-this/2023/08/decimal-to-fraction/",
+ "description": "And now it's all this: Decimal to fraction."
+ },
+ {
+ "url": "https://nrich.maths.org/2515",
+ "description": "History of Fractions."
+ }
+]
diff --git a/concepts/function-arguments/about.md b/concepts/function-arguments/about.md
index 09b01b10862..0f2ab5dddda 100644
--- a/concepts/function-arguments/about.md
+++ b/concepts/function-arguments/about.md
@@ -4,7 +4,7 @@ For the basics on function arguments, please see the [function concept][function
## Parameter Names
-Paramater names, like variable names, must start with a letter or underscore and may contain letters, underscores, or numbers.
+Parameter names, like variable names, must start with a letter or underscore and may contain letters, underscores, or numbers.
Parameter names should not contain spaces or punctuation.
## Positional Arguments
@@ -182,7 +182,7 @@ For instance, `*` is used for multiplication, it is used for unpacking, and it i
Since a tuple can be iterated, `args` can be passed to any other function which takes an iterable.
Although `*args` is commonly juxtaposed with `**kwargs`, it doesn't have to be.
-Following is an example of an arbitrary amount of values being passed to a function:
+Following is an example of an arbitrary number of values being passed to a function:
```python
@@ -196,7 +196,7 @@ Following is an example of an arbitrary amount of values being passed to a funct
If `*args` follows one or more positional arguments, then `*args` will be what is left over after the positional arguments.
-Following is an example of an arbitrary amount of values being passed to a function after a positional argument:
+Following is an example of an arbitrary number of values being passed to a function after a positional argument:
```python
@@ -210,7 +210,7 @@ Following is an example of an arbitrary amount of values being passed to a funct
If one or more default arguments are defined after `*args` they are separate from the `*args` values.
-To put it all together is an example of an arbitrary amount of values being passed to a function that also has a positional argument and a default argument:
+To put it all together is an example of an arbitrary number of values being passed to a function that also has a positional argument and a default argument:
```python
@@ -228,7 +228,7 @@ To put it all together is an example of an arbitrary amount of values being pass
```
-Note that when an argument is already in an iterable, such as a tuple or list, it needs to be unpacked before being passed to a function that takes an arbitrary amount of separate arguments.
+Note that when an argument is already in an iterable, such as a tuple or list, it needs to be unpacked before being passed to a function that takes an arbitrary number of separate arguments.
This is accomplished by using `*`, which is the [unpacking operator][unpacking operator].
`*` in this context _unpacks_ the container into its separate elements which are then transformed by `*args` into a tuple.
@@ -257,7 +257,7 @@ The `**` transforms the group of named arguments into a [`dictionary`][dictionar
Since a dictionary can be iterated, `kwargs` can be passed to any other function which takes an iterable.
Although `**kwargs` is commonly juxtaposed with `*args`, it doesn't have to be.
-Following is an example of an arbitrary amount of key-value pairs being passed to a function:
+Following is an example of an arbitrary number of key-value pairs being passed to a function:
```python
>>> def add(**kwargs):
@@ -271,7 +271,7 @@ Note that the `dict.values()` method is called to iterate through the `kwargs` d
When iterating a dictionary the default is to iterate the keys.
-Following is an example of an arbitrary amount of key-value pairs being passed to a function that then iterates over `kwargs.keys()`:
+Following is an example of an arbitrary number of key-value pairs being passed to a function that then iterates over `kwargs.keys()`:
```python
>>> def concat(**kwargs):
diff --git a/concepts/function-arguments/introduction.md b/concepts/function-arguments/introduction.md
index 171675ce3c4..07b885f332e 100644
--- a/concepts/function-arguments/introduction.md
+++ b/concepts/function-arguments/introduction.md
@@ -4,7 +4,7 @@ For the basics on function arguments, please see the [function concept][function
## Parameter Names
-Paramater names, like variable names, must start with a letter or underscore and may contain letters, underscores, or numbers.
+Parameter names, like variable names, must start with a letter or underscore and may contain letters, underscores, or numbers.
Parameter names should not contain spaces or punctuation.
## Positional Arguments
diff --git a/concepts/functions/about.md b/concepts/functions/about.md
index 9d8fddfa956..f3630af763c 100644
--- a/concepts/functions/about.md
+++ b/concepts/functions/about.md
@@ -2,11 +2,11 @@
A [`function`][function] is a block of organized, reusable code that is used to perform a specific task.
`Functions` provide better modularity for your application and a high degree of code reuse.
-Python, like other programming languages, has [_built-in functions_][build-in functions] ([`print`][print], [`map`][map], and so on) that are readily available.
+Python, like other programming languages, has [_built-in functions_][built-in functions] ([`print`][print], [`map`][map], and so on) that are readily available.
You can also define your own functions. Those are called [`user-defined functions`][user defined functions].
Functions can run something as simple as _printing a message to the console_ or they can be quite complex.
-To execute the code inside a function, you need to call the function, which is done by using the function name followed by parenthesese [`()`].
+To execute the code inside a function, you need to call the function, which is done by using the function name followed by parentheses [`()`].
Data, known as [`arguments`][arguments], can be passed to the function by placing them inside the parenthesese.
A function definition may include zero or more [`parameters`][parameters].
Parameters define what argument(s) the function accepts.
@@ -376,7 +376,7 @@ The full list of function attributes can be found at [Python DataModel][attribut
[LEGB Rule]: https://realpython.com/python-scope-legb-rule/
[arguments]: https://www.w3schools.com/python/gloss_python_function_arguments.asp
[attributes]: https://docs.python.org/3/reference/datamodel.html#index-33
-[build-in functions]: https://docs.python.org/3/library/functions.html
+[built-in functions]: https://docs.python.org/3/library/functions.html
[def]: https://www.geeksforgeeks.org/python-def-keyword/
[dict]: https://docs.python.org/3/tutorial/datastructures.html#dictionaries
[first class objects]: https://en.wikipedia.org/wiki/First-class_object
diff --git a/concepts/functools/about.md b/concepts/functools/about.md
index 32748a45c23..cbc5cd89d96 100644
--- a/concepts/functools/about.md
+++ b/concepts/functools/about.md
@@ -1,311 +1 @@
-# About
-
-The functools module is for higher-order functions: functions that act on or return other ***[functions](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)***. It provides functions for working with other functions and callable objects to use or extend them without completely rewriting them.
-
-## Memoizing the function calls
-
-**Memoizing:** Storing the result of some expensive function, which is called with the same input again and again. So, we don't have to run the function repeatedly.
-
-### ```@functools.lru_cache(maxsize=128, typed=False)```
-
-***[@functools.lru_cache(maxsize=128, typed=False)](https://docs.python.org/3/library/functools.html#functools.lru_cache)*** Decorator to wrap a function with a memoizing callable that saves up to the maxsize most recent calls. It can save time when an expensive or I/O bound function is periodically called with the same arguments.
-
-Since a dictionary is used to cache results, the positional and keyword arguments to the function must be hashable.
-
-Here ```maxsize = 128``` means that it is going to memoize lastest 128 function calls at max.
-
-The lru_cache works the same way but it can cache at max maxsize calls and if type = True, then the function arguments of different types will be cached separately i.e. 5 and 5.0 will be cached differently.
-
-### ```@functools.cache(user_function)```
-
-***[@functools.cache(user_function)](https://docs.python.org/3/library/functools.html#functools.cache)*** the same as lru_cache(maxsize=None), creating a thin wrapper around a dictionary lookup for the function arguments. Because it never needs to evict old values, this is smaller and faster than ```lru_cache()``` with a size limit.
-
-```python
-
->>> @cache
- def factorial(n):
- return n * factorial(n-1) if n else 1
-
->>> factorial(10) # no previously cached result, makes 11 recursive calls
-3628800
->>> factorial(5) # just looks up cached value result
-120
->>> factorial(12) # makes two new recursive calls, the other 10 are cached
-479001600
-
-# The lru_cache works the same way but it can cache at max maxsize calls and if type = True, then the function arguments of different types will be cached separately.
-
-# Some types such as str and int may be cached separately even when typed is false.
-
-@lru_cache(maxsize = 128)
- def factorial(n):
- return n * factorial(n-1) if n else 1
->>> factorial(10)
-3628800
-
-# by the Following we can fetch the information about the cache.
->>> factorial.cache_info()
-CacheInfo(hits=0, misses=11, maxsize=128, currsize=11)
-```
-
-## Generic functions
-
-***[Generic functions](https://pymotw.com/3/functools/#generic-functions)*** are those which preform the operation based on the argument given to them. In statically typed languages it can be done by function overloading.
-
-In python functools provides the `singledispatch()` decorator to register a set of generic functions for automatic switching based on the type of the first argument to a function.
-
-The ```register()``` attribute of the function serves as another decorator for registering alternative implementations.To add overloaded implementations to the function, use the ```register(type)``` attribute of the generic function.
-
-When user is going to call the function with the integer argument, then it will be redirected to the function decorated with ```register(int)``` decorator.
-
-The first function wrapped with singledispatch() is the default implementation if no other type-specific function is found, default implementation will be called.
-
-```python
-
->>> from functools import singledispatch
-
->>> @singledispatch
- def fun(arg):
- print("default argument string: ", arg)
-
-
->>> fun.register(int)
- def _(arg):
- print("This is an integer: ", arg)
-
->>> fun.register(list)
- def _(arg):
- print("This is a list: ", arg)
-
->>> fun("Hello")
-"default argument string: Hello"
-
->>> fun(10)
-"This is an integer: 10"
-
->>> fun([1,2,3])
-"This is a list: [1,2,3]"
-
-# This will call the default function as we didn't registered any function with float.
->>> fun(2.45)
-"default argument string: 2.45"
-
-```
-
-For class methods we can use ***[singledispatchmethod(func)](https://docs.python.org/3/library/functools.html#functools.singledispatchmethod)*** to register a set of generic methods for automatic switching based on the type of the first non-self or non-class argument to a function.
-
-```python
-
->>> class Negator:
- @singledispatchmethod
- def neg(self, arg):
- raise NotImplementedError("Cannot negate a")
-
- @neg.register(int)
- def _(self, arg):
- return -arg
-
- @neg.register(bool)
- def _(self, arg):
- return not arg
-
->>> obj = Negator()
-
-# Going to call function which is register with bool datatype.
->>> obj.neg(True)
-False
-
-# Going to call function which is register with int datatype.
->>> obj.neg(10)
--10
-
-# Going to call default function and will display an error message.
->>> obj.neg("String")
-
-```
-
-## Partial
-
-`functools.partial(func, /, *args, **keywords)` return a new ***[partial object](https://docs.python.org/3/library/functools.html#partial-objects)*** which when called will behave like func called with the positional arguments args and keyword arguments keywords. If more arguments are supplied to the call, they are appended to args.The ***[partial](https://docs.python.org/3/library/functools.html#functools.partial)*** is used for partial function application which βfreezesβ some portion of a functionβs arguments and/or keywords resulting in a new object with a simplified signature.
-
-```python
-
->>> def add(a, b):
- print(f"got a={a}, b={b}")
- print(a+b)
-
->>> a = partial(add, 10)
->>> a(4)
-"got a=10, b=4"
-14
-
-# 10 got assigned to a because partial start assigning arguments from the left.
-
->>> a = partial(add, b=10)
->>> a(4)
-"got a=4, b=10"
-14
-
-# But By using the keywords we can assign the value to the arguments at right
-
-```
-
-### partial Objects
-
-partial objects are callable objects created by partial(). They have three read-only attributes:
-
-```partial.func```
-
-A callable object or function. Calls to the partial object will be forwarded to func with new arguments and keywords.
-
-```partial.args```
-
-The leftmost positional arguments that will be prepended to the positional arguments provided to a partial object call.
-
-```partial.keywords```
-
-The keyword arguments that will be supplied when the partial object is called.
-
-```python
-
->>> from functools import partial
-
->>> pow_2 = partial(pow, exp = 2)
-
->>> pow_2.func == pow
-True
-
->>> pow_2.args
-()
-
->>> pow_2.keywords
-{'exp': 2}
-
->>> two_pow = partial(pow, 2)
-
->>> two_pow(3) # 2(frezzed) ^ 3 = 8 == pow(2 [fixed] ,3 [passed by user])
-8
-
->>> pow_2.args
-(2,)
-
-```
-
-The ```pow_2.func``` is same as the ```pow``` function.
-
-Here ```pow_2.args``` return an empty tuple becuse we does not pass any positional argument to out partial object call.
-
-```pow_2.keywords``` return a dictionary of keywords argument which will be supplied when the partial object is called.
-
-Here ```two_pow.args``` return an ```(2,)``` tuple because we passed 2 as an argument while creating the pratial object, which fixed the value of ```base``` argument as ```2```.
-
-### ```partialmethod```
-
-***[functools.partialmethod(func, /, *args, **keywords)](https://docs.python.org/3/library/functools.html#functools.partialmethod)*** Return a new partialmethod descriptor which behaves like partial except that it is designed to be used as a method definition rather than being directly callable.
-
-```python
-
->>> class Cell:
- def __init__(self):
- self.alive = False
-
- def set_state(self, state):
- self.alive = bool(state)
-
- # going to return a method set_state with argument state = True
- set_alive = partialmethod(set_state, True)
- # going to return a method set_state with argument state = False
- set_dead = partialmethod(set_state, False)
-
->>> c = Cell()
->>> c.alive
-False
->>> c.set_alive()
->>> c.alive
-True
-
-```
-
-## Wraps
-
-### `functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`
-
-***[functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)](https://docs.python.org/3/library/functools.html#functools.update_wrapper)*** Update a wrapper function to look like the wrapped function. The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function.
-
-WRAPPER_ASSIGNMENTS (which assigns to the wrapper functionβs `__module__`, `__name__`, `__qualname__`, `__annotations__` and `__doc__`, the documentation string)
-
-WRAPPER_UPDATES (which updates the wrapper functionβs `__dict__`, i.e. the instance dictionary).
-
-```python
-
-# without update_wrapper()
-
->>> def decorator(func):
- def wrapper(name):
- """Going to say Hello"""
- print("hello",name)
- func(name)
- return wrapper
-
-
->>> @decorator
- def fun(name):
- """Going to Wish"""
- print("good morning",name)
-
-# In bigger python code base this will cause problem while debugging the code.
->>> fun.__name__
-'wrapper'
->>> fun.__doc__
-'Going to say Hello'
-
-# with update_wrapper()
-
->>> def decorator(func):
- def wrapper(name):
- """Going to say Hello"""
- print("hello",name)
- func(name)
- update_wrapper(wrapper, func)
- return wrapper
-
-
->>> @decorator
- def fun(name):
- """Going to Wish"""
- print("good morning",name)
-
-# Now the wrapper function just look like the wrapped(fun) function
->>> fun.__name__
-'fun'
->>> fun.__doc__
-'Going to Wish'
-```
-
-### `functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`
-
-***[functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)](https://docs.python.org/3/library/functools.html#functools.wraps)*** is a convenience function for invoking update_wrapper() as a function decorator when defining a wrapper function. It is equivalent to partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated).
-
-```python
-
-# This going to work same as the above where we are using the update_wrapper() function
->>> def decorator(func):
- @wraps(fun)
- def wrapper(name):
- """Going to say Hello"""
- print("hello",name)
- func(name)
- return wrapper
-
-
->>> @decorator
- def fun(name):
- """Going to Wish"""
- print("good morning",name)
-
-# Now the wrapper function just look like the wrapped(fun) function
->>> fun.__name__
-'fun'
->>> fun.__doc__
-'Going to Wish'
-```
+#TODO: Add about for this concept.
diff --git a/concepts/functools/introduction.md b/concepts/functools/introduction.md
index 15e83e3e61a..bbe12ffd5e9 100644
--- a/concepts/functools/introduction.md
+++ b/concepts/functools/introduction.md
@@ -1,43 +1 @@
-# Introduction
-
-The functools module is for higher-order functions: functions that act on or return other ***[functions](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)***. It provides functions for working with other functions and callable objects to use or extend them without completely rewriting them.
-
-## Memoizing the function calls
-
-**Memoizing:** Storing the result of some expensive function, which is called with the same input again and again. So, we don't have to run the function repeatedly.
-
-### ```@functools.lru_cache(maxsize=128, typed=False)```
-
-***[@functools.lru_cache(maxsize=128, typed=False)](https://docs.python.org/3/library/functools.html#functools.lru_cache)*** Decorator to wrap a function with a memoizing callable that saves up to the maxsize most recent calls. It can save time when an expensive or I/O bound function is periodically called with the same arguments.
-
-Since a dictionary is used to cache results, the positional and keyword arguments to the function must be hashable.
-
-Here ```maxsize = 128``` means that it is going to memoize lastest 128 function calls at max.
-
-### ```@functools.cache(user_function)```
-
-***[@functools.cache(user_function)](https://docs.python.org/3/library/functools.html#functools.cache)*** the same as lru_cache(maxsize=None), creating a thin wrapper around a dictionary lookup for the function arguments. Because it never needs to evict old values, this is smaller and faster than ```lru_cache()``` with a size limit.
-
-## Generic functions
-
-***[Generic functions](https://pymotw.com/3/functools/#generic-functions)*** are those which preform the operation based on the argument given to them.
-
-In statically typed languages it can be done by function overloading, In python functools provides the ```singledispatch(func)``` decorator to register a set of generic functions for automatic switching based on the type of the first argument to a function.
-
-For class methods we can use ***[singledispatchmethod(func)](https://docs.python.org/3/library/functools.html#functools.singledispatchmethod)*** to register a set of generic methods for automatic switching based on the type of the first non-self or non-class argument to a function.
-
-## Partial
-
-`functools.partial(func, /, *args, **keywords)` return a new ***[partial object](https://docs.python.org/3/library/functools.html#partial-objects)*** which when called will behave like func called with the positional arguments args and keyword arguments keywords. If more arguments are supplied to the call, they are appended to args.The ***[partial](https://docs.python.org/3/library/functools.html#functools.partial)*** is used for partial function application which βfreezesβ some portion of a functionβs arguments and/or keywords resulting in a new object with a simplified signature.
-
-***[functools.partialmethod(func, /, *args, **keywords)](https://docs.python.org/3/library/functools.html#functools.partialmethod)*** Return a new partialmethod descriptor which behaves like partial except that it is designed to be used as a method definition rather than being directly callable.
-
-## Wraps
-
-### `functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`
-
-***[functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)](https://docs.python.org/3/library/functools.html#functools.update_wrapper)*** Update a wrapper function to look like the wrapped function. The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function.
-
-### `functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`
-
-***[functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)](https://docs.python.org/3/library/functools.html#functools.wraps)*** is a convenience function for invoking update_wrapper() as a function decorator when defining a wrapper function. It is equivalent to partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated).
+#TODO: Add introduction for this concept.
diff --git a/concepts/generators/.meta/config.json b/concepts/generators/.meta/config.json
index 6c29169d3f4..3322727ef74 100644
--- a/concepts/generators/.meta/config.json
+++ b/concepts/generators/.meta/config.json
@@ -1,5 +1,9 @@
{
- "blurb": "Generator are functions that returns a lazy iterator, lazy iterator is an iterator like: list, tuple, etc. But doesn't need store its content in memory",
+ "blurb": "Generators are functions or expressions that return a special type of iterator called a 'generator-iterator'. Generator-iterators are lazy: they do not store their values in memory but generate them when needed.",
"authors": ["J08K"],
- "contributors": []
+ "contributors": [
+ "BethanyG",
+ "kytrinyx",
+ "meatball133"
+ ]
}
diff --git a/concepts/generators/about.md b/concepts/generators/about.md
index 5995b27c0ec..4b2e74cbad2 100644
--- a/concepts/generators/about.md
+++ b/concepts/generators/about.md
@@ -1,5 +1,13 @@
# About
+A `generator` is a function or expression that returns a special type of [iterator][iterator] called [generator iterator][generator-iterator].
+`Generator-iterators` are [lazy][lazy iterator]: they do not store their `values` in memory, but _generate_ their values when needed.
+
+A generator function looks like any other function, but contains one or more [yield expressions][yield expression].
+Each `yield` will suspend code execution, saving the current execution state (_including all local variables and try-statements_).
+When the generator resumes, it picks up state from the suspension - unlike regular functions which reset with every call.
+
+
## Constructing a generator
Generators are constructed much like other looping or recursive functions, but require a [`yield` expression](#the-yield-expression), which we will explore in depth a bit later.
@@ -27,9 +35,33 @@ The rationale behind this is that you use a generator when you do not need all t
This saves memory and processing power, since only the value you are _currently working on_ is calculated.
+
## Using a generator
-Generators may be used in place of most `iterables` in Python. This includes _functions_ or _objects_ that require an `iterable`/`iterator` as an argument.
+Generators (_technically [`generator-iterator`s][generator-iterator] β see the note below._) are a type of `iterator` and can be used anywhere in Python where an `iterator` or `iterable` is expected.
+This includes _functions_ or _objects_ that require an `iterable`/`iterator` as an argument.
+For a deeper dive, see [How to Make an Iterator in Python][how-to-iterator].
+
+
+~~~~exercism/note
+
+Generator-iterators are a special sub-set of [iterators][iterator].
+`Iterators` are the mechanism/protocol that enables looping over _iterables_.
+Generator-iterators and the iterators returned by common Python [`iterables`][iterables] act very similarly, but there are some important differences to note:
+
+- They are _[lazily evaluated][lazy evaluation]_; iteration is _one-way_ and there is no "backing up" to a previous value.
+- They are _consumed_ by iterating over the returned values; there is no resetting or saving in memory.
+- They are not sortable and cannot be reversed.
+- They are not sequence types, and _do not_ have `indexes`.
+ You cannot reference a previous or future value using addition or subtraction and you cannot use bracket (`[]`) notation or slicing.
+- They cannot be used with the `len()` function, as they have no length.
+- They can be _finite_ or _infinite_ - be careful when collecting all values from an _infinite_ `generator-iterator`!
+
+[iterator]: https://docs.python.org/3.11/glossary.html#term-iterator
+[iterables]: https://wiki.python.org/moin/Iterator
+[lazy evaluation]: https://en.wikipedia.org/wiki/Lazy_evaluation
+~~~~
+
To use the `squares_generator()` generator:
@@ -131,5 +163,10 @@ Generators are also very helpful when a process or calculation is _complex_, _ex
Now whenever `__next__()` is called on the `infinite_sequence` object, it will return the _previous number_ + 1.
+
+[generator-iterator]: https://docs.python.org/3/glossary.html#term-generator-iterator
+[how-to-iterator]: https://treyhunner.com/2018/06/how-to-make-an-iterator-in-python/#Generators:_the_easy_way_to_make_an_iterator
[iterables]: https://wiki.python.org/moin/Iterator
+[iterator]: https://docs.python.org/3.11/glossary.html#term-iterator
+[lazy iterator]: https://en.wikipedia.org/wiki/Lazy_evaluation
[yield expression]: https://docs.python.org/3.11/reference/expressions.html#yield-expressions
diff --git a/concepts/generators/introduction.md b/concepts/generators/introduction.md
index 82a686d1e05..ad1175ca0b6 100644
--- a/concepts/generators/introduction.md
+++ b/concepts/generators/introduction.md
@@ -1,7 +1,13 @@
# Introduction
-A generator in Python is a _callable function_ that returns a [lazy iterator][lazy iterator].
+A generator in Python is a _callable function_ or expression that returns a special type of [iterator][iterator] called [generator iterator][generator-iterator].
+`Generator-iterators` are [lazy][lazy iterator]: they do not store their `values` in memory, but _generate_ their values when needed.
-_Lazy iterators_ are similar to `lists`, and other `iterators`, but with one key difference: They do not store their `values` in memory, but _generate_ their values when needed.
+A generator function looks like any other function, but contains one or more [yield expressions][yield expression].
+Each `yield` will suspend code execution, saving the current execution state (_including all local variables and try-statements_).
+When the generator function resumes, it picks up state from the suspension - unlike regular functions which reset with every call.
[lazy iterator]: https://en.wikipedia.org/wiki/Lazy_evaluation
+[iterator]: https://docs.python.org/3.11/glossary.html#term-iterator
+[yield expression]: https://docs.python.org/3.11/reference/expressions.html#yield-expressions
+[generator-iterator]: https://docs.python.org/3.11/glossary.html#term-generator-iterator
diff --git a/concepts/generators/links.json b/concepts/generators/links.json
index 972bbe7ae97..134a723c693 100644
--- a/concepts/generators/links.json
+++ b/concepts/generators/links.json
@@ -1,12 +1,16 @@
[
{
- "url": "https://docs.python.org/3.10/reference/expressions.html#yield-expressions",
+ "url": "https://docs.python.org/3.11/reference/expressions.html#yield-expressions",
"description": "Official Python 3.10 docs for the yield expression."
},
{
"url": "https://en.wikipedia.org/wiki/Lazy_evaluation",
"description": "Wikipedia page about lazy evaluation"
},
+ {
+ "url": "https://www.pythonmorsels.com/iterators/",
+ "description": "Python Morsels: Iterators & Generators"
+ },
{
"url": "https://realpython.com/introduction-to-python-generators/",
"description": "Real python, introduction to generators and yield"
diff --git a/concepts/list-methods/about.md b/concepts/list-methods/about.md
index 3a5132fd0ad..00b41f325e5 100644
--- a/concepts/list-methods/about.md
+++ b/concepts/list-methods/about.md
@@ -11,7 +11,7 @@ Lists support both [common][common sequence operations] and [mutable][mutable se
Python provides many useful [methods][list-methods] for working with lists.
Because lists are mutable, list-methods **alter the original list object** passed into the method.
-If mutation is undesirable, a `shallow copy` (_at minimum__) of the original `list` needs to be made via `slice` or `.copy()`.
+If mutation is undesirable, a `shallow copy` (_at minimum_) of the original `list` needs to be made via `slice` or `.copy()`.
## Adding Items
@@ -47,7 +47,8 @@ If `` is greater than the final index on the list, the item will be added
```
An `iterable` can be _combined_ with an existing list (concatenating the two) via `.extend()`.
-`.extend()` will _unpack_ the supplied iterable, adding its elements in the same order to the end of the target list (_using `.append(- )` in this circumstance would add the entire iterable as a **single item**._).
+`
.extend()` will _unpack_ the supplied iterable, adding its elements in the same order to the end of the target list.
+Using `.append(- )` in this circumstance would add the entire iterable as a _**single item**_.
```python
@@ -136,10 +137,22 @@ The order of list elements can be reversed _**in place**_ with `
.reverse(
[3, 2, 1]
```
-List elements can be sorted _**in place**_ using `.sort()`.
- Internally, Python uses [`Timsort`][timsort] to arrange the elements.
- The default order is _ascending_.
- The Python docs have [additional tips and techniques for sorting][sorting how to] `lists` effectively.
+A list can be re-ordered _**in place**_ with the help of [`.sort()`][sort].
+Default sort order is _ascending_ from the left.
+The Python docs offer [additional tips and techniques for sorting][sorting how to].
+
+
+~~~~exercism/note
+ From 2002 to 2022, Python used an algorithm called [`Timsort`][timsort] internally to arrange lists, but switched to [`Powersort`][powersort] from `Python 3.11` onward.
+You can read more details and discussion on the change from the core Python team in the GitHub [issue 78742][78742].
+
+For technical details on the algorithm, see the J. Ian Munro and Sebastian Wild paper [Nearly-Optimal Mergesorts: Fast, Practical Sorting Methods That Optimally Adapt to Existing Runs][nearly-optimal-mergesorts]
+
+[78742]: https://github.com/python/cpython/issues/78742
+[nearly-optimal-mergesorts]: https://arxiv.org/abs/1805.04154
+[powersort]: https://www.wild-inter.net/publications/munro-wild-2018
+[timsort]: https://en.wikipedia.org/wiki/Timsort
+~~~~
```python
@@ -254,7 +267,7 @@ For a detailed explanation of names, values, list, and nested list behavior, tak
[set]: https://docs.python.org/3/library/stdtypes.html#set
[shallow vs deep]: https://realpython.com/copying-python-objects/
[slice notation]: https://docs.python.org/3/reference/expressions.html#slicings
+[sort]: https://docs.python.org/3/library/stdtypes.html#list.sort
[sorted]: https://docs.python.org/3/library/functions.html#sorted
[sorting how to]: https://docs.python.org/3/howto/sorting.html
-[timsort]: https://en.wikipedia.org/wiki/Timsort
[tuple]: https://docs.python.org/3/library/stdtypes.html#tuple
diff --git a/concepts/lists/about.md b/concepts/lists/about.md
index 014a6d56725..51c44060d5c 100644
--- a/concepts/lists/about.md
+++ b/concepts/lists/about.md
@@ -7,7 +7,7 @@ A [`list`][list] is a mutable collection of items in _sequence_.
Lists support both [common][common sequence operations] and [mutable][mutable sequence operations] sequence operations such as `min()`/`max()`, `.index()`, `.append()` and `.reverse()`.
- List elements can be iterated over using the `for item in ` construct. `for index, item in enumerate(` construct. `for index, item in enumerate()` can be used when both the element index and the element value are needed.
Lists are implemented as [dynamic arrays][dynamic array] -- similar to Java's [`Arraylist`][arraylist] type, and are most often used to store groups of similar data (_strings, numbers, sets etc._) of unknown length (_the number of entries may arbitrarily expand or shrink_).
@@ -18,7 +18,7 @@ Accessing elements, checking for membership via `in`, or appending items to the
For a similar data structure that supports memory efficient `appends`/`pops` from both sides, see [`collections.deque`][deque], which has approximately the same O(1) performance in either direction.
-Because lists are mutable and can contain references to arbitrary objects, they also take up more space in memory than a fixed-size [`array.array`][array.array] type of the same apparent length.
+Because lists are mutable and can contain references to arbitrary Python objects, they also take up more space in memory than an [`array.array`][array.array] or a [`tuple`][tuple] (_which is immutable_) of the same apparent length.
Despite this, lists are an extremely flexible and useful data structure and many built-in methods and operations in Python produce lists as their output.
@@ -49,15 +49,15 @@ For readability, line breaks can be used when there are many elements or nested
```python
>>> lots_of_entries = [
- "Rose",
- "Sunflower",
- "Poppy",
- "Pansy",
- "Tulip",
- "Fuchsia",
- "Cyclamen",
- "Lavender"
- ]
+... "Rose",
+... "Sunflower",
+... "Poppy",
+... "Pansy",
+... "Tulip",
+... "Fuchsia",
+... "Cyclamen",
+... "Lavender"
+... ]
>>> lots_of_entries
['Rose', 'Sunflower', 'Poppy', 'Pansy', 'Tulip', 'Fuchsia', 'Cyclamen', 'Lavender']
@@ -65,10 +65,10 @@ For readability, line breaks can be used when there are many elements or nested
# Each data structure is on its own line to help clarify what they are.
>>> nested_data_structures = [
- {"fish": "gold", "monkey": "brown", "parrot": "grey"},
- ("fish", "mammal", "bird"),
- ['water', 'jungle', 'sky']
- ]
+... {"fish": "gold", "monkey": "brown", "parrot": "grey"},
+... ("fish", "mammal", "bird"),
+... ['water', 'jungle', 'sky']
+... ]
>>> nested_data_structures
[{'fish': 'gold', 'monkey': 'brown', 'parrot': 'grey'}, ('fish', 'mammal', 'bird'), ['water', 'jungle', 'sky']]
@@ -135,7 +135,8 @@ TypeError: 'int' object is not iterable
## Accessing elements
-Items inside lists (_as well as elements in other sequence types such as [`str`][string] & [`tuple`][tuple]_), can be accessed using _bracket notation_. Indexes can be from **`left`** --> **`right`** (_starting at zero_) or **`right`** --> **`left`** (_starting at -1_).
+Items inside lists (_as well as elements in other sequence types such as [`str`][string] & [`tuple`][tuple]_), can be accessed using _bracket notation_.
+Indexes can be from **`left`** --> **`right`** (_starting at zero_) or **`right`** --> **`left`** (_starting at -1_).
@@ -173,9 +174,11 @@ Items inside lists (_as well as elements in other sequence types such as [`str`]
'Toast'
```
-A section of a list can be accessed via _slice notation_ (`[start:stop]`). A _slice_ is defined as an element sequence at position `index`, such that `start <= index < stop`. [_Slicing_][slice notation] returns a copy of the "sliced" items and does not modify the original `list`.
+A section of a list can be accessed via _slice notation_ (`[:]`).
+A _slice_ is defined as an element sequence at position `index`, such that `start <= index < stop`.
+[_Slicing_][slice notation] returns a copy of the "sliced" items and does not modify the original `list`.
-A `step` parameter can also be used in the slice (`[start:stop:step]`) to "skip over" or filter the returned elements (_for example, a `step` of 2 will select every other element in the section_):
+A `step` parameter can also be used in the slice (`[::]`) to "skip over" or filter the returned elements (_for example, a `step` of 2 will select every other element in the section_):
```python
>>> colors = ["Red", "Purple", "Green", "Yellow", "Orange", "Pink", "Blue", "Grey"]
@@ -204,7 +207,7 @@ Lists supply an [_iterator_][iterator], and can be looped through/over in the sa
>>> colors = ["Orange", "Green", "Grey", "Blue"]
>>> for item in colors:
... print(item)
-...
+
Orange
Green
Grey
@@ -215,7 +218,7 @@ Blue
>>> colors = ["Orange", "Green", "Grey", "Blue"]
>>> for index, item in enumerate(colors):
... print(item, ":", index)
-...
+
Orange : 0
Green : 1
Grey : 2
@@ -226,7 +229,7 @@ Blue : 3
>>> numbers_to_cube = [5, 13, 12, 16]
>>> for number in numbers_to_cube:
... print(number**3)
-...
+
125
2197
1728
@@ -269,7 +272,7 @@ Lists can also be combined via various techniques:
>>> first_one
['George', 5, 'cat', 'Tabby']
-# This loops through the first list and appends it's items to the end of the second list.
+# This loops through the first list and appends its items to the end of the second list.
>>> first_one = ["cat", "Tabby"]
>>> second_one = ["George", 5]
@@ -284,7 +287,7 @@ Lists can also be combined via various techniques:
## Some cautions
Recall that variables in Python are _labels_ that point to _underlying objects_.
-`lists` add one more layer as _container objects_ -- they hold object references for their collected items.
+`lists` add one more layer as _container objects_ -- they hold object _references_ for their collected items.
This can lead to multiple potential issues when working with lists, if not handled properly.
@@ -293,7 +296,7 @@ Assigning a `list` object to a new variable _name_ **does not copy the `list` ob
Any change made to the elements in the `list` under the _new_ name _impact the original_.
-Making a `shallow_copy` via `list.copy()` or slice will avoid this first-leve referencing complication.
+Making a `shallow_copy` via `list.copy()` or slice will avoid this first-level referencing complication.
A `shallow_copy` will create a new `list` object, but **will not** create new objects for the contained list _elements_. This type of copy will usually be enough for you to add or remove items from the two `list` objects independently, and effectively have two "separate" lists.
@@ -305,21 +308,22 @@ A `shallow_copy` will create a new `list` object, but **will not** create new ob
# Altering the list via the new name is the same as altering the list via the old name.
>>> same_list.append("Clarke")
->>> same_list
["Tony", "Natasha", "Thor", "Bruce", "Clarke"]
+
>>> actual_names
["Tony", "Natasha", "Thor", "Bruce", "Clarke"]
# Likewise, altering the data in the list via the original name will also alter the data under the new name.
>>> actual_names[0] = "Wanda"
->>> same_list
['Wanda', 'Natasha', 'Thor', 'Bruce', 'Clarke']
# If you copy the list, there will be two separate list objects which can be changed independently.
>>> copied_list = actual_names.copy()
>>> copied_list[0] = "Tony"
+
>>> actual_names
['Wanda', 'Natasha', 'Thor', 'Bruce', 'Clarke']
+
>>> copied_list
["Tony", "Natasha", "Thor", "Bruce", "Clarke"]
```
@@ -331,7 +335,7 @@ This reference complication becomes exacerbated when working with nested or mult
from pprint import pprint
# This will produce a game grid that is 8x8, pre-populated with zeros.
->>> game_grid = [[0]*8] *8
+>>> game_grid = [[0]*8]*8
>>> pprint(game_grid)
[[0, 0, 0, 0, 0, 0, 0, 0],
@@ -455,4 +459,4 @@ The collections module also provides a `UserList` type that can be customized to
[set]: https://docs.python.org/3/library/stdtypes.html#set
[slice notation]: https://docs.python.org/3/reference/expressions.html#slicings
[string]: https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str
-[tuple]: https://docs.python.org/3/library/stdtypes.html#tuple
\ No newline at end of file
+[tuple]: https://docs.python.org/3/library/stdtypes.html#tuple
diff --git a/concepts/loops/about.md b/concepts/loops/about.md
index 88bb71e6194..e3322af0e3b 100644
--- a/concepts/loops/about.md
+++ b/concepts/loops/about.md
@@ -31,7 +31,6 @@ The keywords `break`, `continue`, and `else` help customize loop behavior.
The basic [`for`][for statement] `loop` in Python is better described as a _`for each`_ which cycles through the values of any [iterable object][iterable], terminating when there are no values returned from calling [`next()`][next built-in] (_raising a [`StopIteration`][stopiteration]_).
```python
-
>>> word_list = ["bird", "chicken", "barrel", "bongo"]
>>> for word in word_list:
@@ -95,7 +94,6 @@ Interestingly, `range()` [_is not an iterator_][range is not an iterator], and c
If both values and indexes are needed, the built-in [`enumerate()`][enumerate] will return an [`iterator`][iterator] over (`index`, `value`) pairs:
```python
-
>>> word_list = ["bird", "chicken", "barrel", "apple"]
# *index* and *word* are the loop variables.
@@ -152,15 +150,15 @@ The `enumerate()` function can also be set to `start` the index count
The [`continue`][continue statement] keyword can be used to skip forward to the next iteration cycle:
```python
-word_list = ["bird", "chicken", "barrel", "bongo", "sliver", "apple", "bear"]
-
-# This will skip *bird*, at index 0
-for index, word in enumerate(word_list):
- if index == 0:
- continue
- if word.startswith("b"):
- print(f"{word.title()} (at index {index}) starts with a b.")
-
+>>> word_list = ["bird", "chicken", "barrel", "bongo", "sliver", "apple", "bear"]
+...
+... # This will skip *bird*, at index 0
+... for index, word in enumerate(word_list):
+... if index == 0:
+... continue
+... if word.startswith("b"):
+... print(f"{word.title()} (at index {index}) starts with a b.")
+...
'Barrel (at index 2) starts with a b.'
'Bongo (at index 3) starts with a b.'
'Bear (at index 6) starts with a b.'
@@ -176,9 +174,9 @@ The [`break`][break statement] (_like in many C-related languages_) keyword can
... if word.startswith("b"):
... print(f"{word.title()} (at index {index}) starts with a B.")
... elif word == "sliver":
-... break
+... break
... else:
-... print(f"{word.title()} doesn't start with a B.")
+... print(f"{word.title()} doesn't start with a B.")
... print("loop broken.")
...
'Bird (at index 0) starts with a B.'
@@ -202,11 +200,11 @@ The loop [`else` clause][loop else] is unique to Python and can be used for "wra
... word = word.title()
... if word.startswith("B"):
... print(f"{word} (at index {index}) starts with a B.")
-
-...# This executes once *StopIteration* is raised and
-...# there are no more items to iterate through.
-...# Note the indentation, which lines up with the for keyword.
-...else:
+...
+... # This executes once *StopIteration* is raised and
+... # There are no more items to iterate through.
+... # Note the indentation, which lines up with the for keyword.
+... else:
... print(f"Found the above b-words, out of {len(word_list)} words in the word list.")
...
'Bird (at index 0) starts with a B.'
@@ -227,7 +225,7 @@ The loop [`else` clause][loop else] is unique to Python and can be used for "wra
... # This statement does not run, because a *break* was triggered.
... else:
-... print(f"Found the above b-words, out of {len(word_list)} words in the word list.")
+... print(f"Found the above b-words, out of {len(word_list)} words in the word list.")
...
'Bird (at index 0) starts with a B.'
'Barrel (at index 2) starts with a B.'
@@ -235,17 +233,17 @@ The loop [`else` clause][loop else] is unique to Python and can be used for "wra
'Found an S, stopping iteration.'
```
-[loop else]: https://docs.python.org/3/tutorial/controlflow.html#break-and-continue-statements-and-else-clauses-on-loops
-[range]: https://docs.python.org/3/library/stdtypes.html#range
[break statement]: https://docs.python.org/3/reference/simple_stmts.html#the-break-statement
+[common sequence operations]: https://docs.python.org/3/library/stdtypes.html#common-sequence-operations
[continue statement]: https://docs.python.org/3/reference/simple_stmts.html#the-continue-statement
-[while statement]: https://docs.python.org/3/reference/compound_stmts.html#the-while-statement
-[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
[enumerate]: https://docs.python.org/3/library/functions.html#enumerate
-[iterator]: https://docs.python.org/3/glossary.html#term-iterator
-[common sequence operations]: https://docs.python.org/3/library/stdtypes.html#common-sequence-operations
-[range is not an iterator]: https://treyhunner.com/2018/02/python-range-is-not-an-iterator/
[for statement]: https://docs.python.org/3/reference/compound_stmts.html#for
[iterable]: https://docs.python.org/3/glossary.html#term-iterable
+[iterator]: https://docs.python.org/3/glossary.html#term-iterator
+[loop else]: https://docs.python.org/3/tutorial/controlflow.html#break-and-continue-statements-and-else-clauses-on-loops
[next built-in]: https://docs.python.org/3/library/functions.html#next
+[range is not an iterator]: https://treyhunner.com/2018/02/python-range-is-not-an-iterator/
+[range]: https://docs.python.org/3/library/stdtypes.html#range
[stopiteration]: https://docs.python.org/3/library/exceptions.html#StopIteration
+[truth value testing]: https://docs.python.org/3/library/stdtypes.html#truth-value-testing
+[while statement]: https://docs.python.org/3/reference/compound_stmts.html#the-while-statement
diff --git a/concepts/numbers/about.md b/concepts/numbers/about.md
index d5a4f7271ce..3fa63c140d9 100644
--- a/concepts/numbers/about.md
+++ b/concepts/numbers/about.md
@@ -135,7 +135,7 @@ Numbers can be converted from `int` to `floats` and `floats` to `int` using the
## Round
-Python provides a built-in function [`round(number, )`][round] to round off a floating point number to a given number of decimal places.
+Python provides a built-in function [`round(, )`][round] to round off a floating point number to a given number of decimal places.
If no number of decimal places is specified, the number is rounded off to the nearest integer and will return an `int`:
```python
@@ -177,7 +177,7 @@ This means calculations within `()` have the highest priority, followed by `**`,
## Precision & Representation
-Integers in Python have [arbitrary precision][arbitrary-precision] -- the amount of digits is limited only by the available memory of the host system.
+Integers in Python have [arbitrary precision][arbitrary-precision] -- the number of digits is limited only by the available memory of the host system.
Floating point numbers are usually implemented using a `double` in C (_15 decimal places of precision_), but will vary in representation based on the host system.
Complex numbers have a `real` and an `imaginary` part, both of which are represented by floating point numbers.
diff --git a/concepts/random/.meta/config.json b/concepts/random/.meta/config.json
new file mode 100644
index 00000000000..7319e329bad
--- /dev/null
+++ b/concepts/random/.meta/config.json
@@ -0,0 +1,5 @@
+{
+ "blurb": "The random module contains functionality to generate random values for modelling, simulations and games. It should not be used for security or cryptographic applications.",
+ "authors": ["BethanyG", "colinleach"],
+ "contributors": []
+}
diff --git a/concepts/random/about.md b/concepts/random/about.md
new file mode 100644
index 00000000000..9ed984179d3
--- /dev/null
+++ b/concepts/random/about.md
@@ -0,0 +1,245 @@
+# About
+
+Many programs need (apparently) random values to simulate real-world events.
+
+Common, familiar examples include:
+- A coin toss: a random value from `('H', 'T')`.
+- The roll of a die: a random integer from 1 to 6.
+- Shuffling a deck of cards: a random ordering of a card list.
+
+Generating truly random values with a computer is a [surprisingly difficult technical challenge][truly-random], so you may see these results referred to as "pseudorandom".
+
+In practice, a well-designed library like the [`random`][random] module in the Python standard library is fast, flexible, and gives results that are amply good enough for most applications in modelling, simulation and games.
+
+The rest of this page will list a few of the most common functions in `random`.
+We encourage you to explore the full `random` documentation, as there are many more options than what we cover here.
+
+
+
+~~~~exercism/caution
+
+The `random` module should __NOT__ be used for security and cryptographic applications.
+
+Instead, Python provides the [`secrets`][secrets] module.
+This is specially optimized for cryptographic security.
+Some of the prior issues and reasons for creating the secrets module can be found in [PEP 506][PEP 506].
+
+[secrets]: https://docs.python.org/3.11/library/secrets.html#module-secrets
+[PEP 506]: https://peps.python.org/pep-0506/
+~~~~
+
+
+
+## Importing
+
+Before you can utilize the tools in the `random` module, you must first import it:
+
+```python
+>>> import random
+
+# Choose random integer from a range
+>>> random.randrange(1000)
+360
+
+>>> random.randrange(-1, 500)
+228
+
+>>> random.randrange(-10, 11, 2)
+-8
+
+# Choose random integer between two values (inclusive)
+>>> random.randint(5, 25)
+22
+
+```
+
+To avoid typing the name of the module, you can import specific functions by name:
+
+```python
+>>> from random import choice, choices
+
+# Using choice() to pick Heads or Tails 10 times
+>>> tosses = []
+>>> for side in range(10):
+>>> tosses.append(choice(['H', 'T']))
+
+>>> print(tosses)
+['H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'H']
+
+
+# Using choices() to pick Heads or Tails 8 times
+>>> picks = []
+>>> picks.extend(choices(['H', 'T'], k=8))
+>>> print(picks)
+['T', 'H', 'H', 'T', 'H', 'H', 'T', 'T']
+```
+
+
+## Creating random integers
+
+The `randrange()` function has three forms, to select a random value from `range(start, stop, step)`:
+ 1. `randrange(stop)` gives an integer `n` such that `0 <= n < stop`
+ 2. `randrange(start, stop)` gives an integer `n` such that `start <= n < stop`
+ 3. `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop` and `n` is in the sequence `start, start + step, start + 2*step...`
+
+For the common case where `step == 1`, the `randint(a, b)` function may be more convenient and readable.
+Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as using `randrange(a, b+1)`:
+
+```python
+>>> import random
+
+# Select one number at random from the range 0, 499
+>>> random.randrange(500)
+219
+
+# Select 10 numbers at random between 0 and 9 two steps apart.
+>>> numbers = []
+>>> for integer in range(10):
+>>> numbers.append(random.randrange(0, 10, 2))
+>>> print(numbers)
+[2, 8, 4, 0, 4, 2, 6, 6, 8, 8]
+
+# roll a die
+>>> random.randint(1, 6)
+4
+```
+
+
+
+## Working with sequences
+
+The functions in this section assume that you are starting from some [sequence][sequence-types], or other container.
+
+
+This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_).
+
+
+
+### `choice()` and `choices()`
+
+The `choice()` function will return one entry chosen at random from a given sequence.
+At its simplest, this might be a coin-flip:
+
+```python
+# This will pick one of the two values in the list at random 5 separate times
+>>> [random.choice(['H', 'T']) for _ in range(5)]
+['T', 'H', 'H', 'T', 'H']
+
+We could accomplish essentially the same thing using the `choices()` function, supplying a keyword argument with the list length:
+
+
+```python
+>>> random.choices(['H', 'T'], k=5)
+['T', 'H', 'T', 'H', 'H']
+```
+
+
+In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified.
+For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random:
+
+```python
+>>> random.choices(['red', 'green'], [10, 15])
+['red']
+```
+
+
+
+### `sample()`
+
+The `choices()` example above assumes what statisticians call ["sampling with replacement"][sampling-with-replacement].
+Each pick or choice has **no effect** on the probability of future choices, and the distribution of potential choices remains the same from pick to pick.
+
+
+In the example with red and green balls: after each choice, we _return_ the ball to the bag and shake well before the next pick.
+This is in contrast to a situation where we pull out a red ball and _it stays out_.
+Not returning the ball means there are now fewer red balls in the bag, and the next choice is now _less likely_ to be red.
+
+To simulate this "sampling without replacement", the random module provides the `sample()` function.
+The syntax of `sample()` is similar to `choices()`, except it adds a `counts` keyword parameter:
+
+
+```python
+>>> random.sample(['red', 'green'], counts=[10, 15], k=10)
+['green', 'green', 'green', 'green', 'green', 'red', 'red', 'red', 'red', 'green']
+```
+
+Samples are returned in the order they were chosen.
+
+
+
+### `shuffle()`
+
+Both `choices()` and `sample()` return new lists when `k > 1`.
+In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the original ordering is lost:
+
+```python
+>>> my_list = [1, 2, 3, 4, 5]
+>>> random.shuffle(my_list)
+>>> my_list
+[4, 1, 5, 2, 3]
+```
+
+
+## Working with Distributions
+
+Until now, we have concentrated on cases where all outcomes are equally likely.
+For example, `random.randrange(100)` is equally likely to give any integer from 0 to 99.
+
+Many real-world situations are far less simple than this.
+As a result, statisticians have created a wide variety of [`distributions`][probability-distribution] to describe "real world" results mathematically.
+
+
+
+### Uniform distributions
+
+For integers, `randrange()` and `randint()` are used when all probabilities are equal.
+This is called a [`uniform`][uniform-distribution] distribution.
+
+
+There are floating-point equivalents to `randrange()` and `randint()`.
+
+__`random()`__ gives a `float` value `x` such that `0.0 <= x < 1.0`.
+
+__`uniform(a, b)`__ gives `x` such that `a <= x <= b`.
+
+```python
+>>> [round(random.random(), 3) for _ in range(5)]
+[0.876, 0.084, 0.483, 0.22, 0.863]
+
+>>> [round(random.uniform(2, 5), 3) for _ in range(5)]
+[2.798, 2.539, 3.779, 3.363, 4.33]
+```
+
+
+
+### Gaussian distribution
+
+Also called the "normal" distribution or the "bell-shaped" curve, this is a very common way to describe imprecision in measured values.
+
+For example, suppose the factory where you work has just bought 10,000 bolts which should be identical.
+You want to set up the factory robot to handle them, so you weigh a sample of 100 and find that they have an average (or `mean`) weight of 4.731g.
+This is extremely unlikely to mean that they all weigh exactly 4.731g.
+Perhaps you find that values range from 4.627 to 4.794g but cluster around 4.731g.
+
+This is the [`Gaussian distribution`][gaussian-distribution], for which probabilities peak at the mean and tails off symmetrically on both sides (hence "bell-shaped").
+To simulate this in software, we need some way to specify the width of the curve (_typically, expensive bolts will cluster more tightly around the mean than cheap bolts!_).
+
+By convention, this is done with the [`standard deviation`][standard-deviation]: small values for a sharp, narrow curve, large for a low, broad curve.
+Mathematicians love Greek letters, so we use `ΞΌ` ('mu') to represent the mean and `Ο` ('sigma') to represent the standard deviation.
+Thus, if you read that "95% of values are within 2Ο of ΞΌ" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation.
+
+```python
+>>> mu = 4.731
+>>> sigma = 0.316
+>>> [round(random.gauss(mu, sigma), 3) for _ in range(5)]
+[4.72, 4.957, 4.64, 4.556, 4.968]
+```
+
+[gaussian-distribution]: https://simple.wikipedia.org/wiki/Normal_distribution
+[probability-distribution]: https://simple.wikipedia.org/wiki/Probability_distribution
+[random]: https://docs.python.org/3/library/random.html
+[sampling-with-replacement]: https://www.youtube.com/watch?v=LnGFL_A6A6A
+[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range
+[standard-deviation]: https://simple.wikipedia.org/wiki/Standard_deviation
+[truly-random]: https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random
+[uniform-distribution]: https://www.investopedia.com/terms/u/uniform-distribution.asp#:~:text=In%20statistics%2C%20uniform%20distribution%20refers,a%20spade%20is%20equally%20likely.
diff --git a/concepts/random/introduction.md b/concepts/random/introduction.md
new file mode 100644
index 00000000000..6bf880be57f
--- /dev/null
+++ b/concepts/random/introduction.md
@@ -0,0 +1,108 @@
+# Introduction
+
+Many programs need (apparently) random values to simulate real-world events.
+
+Common, familiar examples include:
+- A coin toss: a random value from `('H', 'T')`.
+- The roll of a die: a random integer from 1 to 6.
+- Shuffling a deck of cards: a random ordering of a card list.
+- The creation of trees and bushes in a 3-D graphics simulation.
+
+Generating _truly_ random values with a computer is a [surprisingly difficult technical challenge][truly-random], so you may see these results referred to as "pseudorandom".
+
+In practice, a well-designed library like the [`random`][random] module in the Python standard library is fast, flexible, and gives results that are amply good enough for most applications in modelling, simulation and games.
+
+For this brief introduction, we show the four most commonly used functions from the module.
+We encourage you to explore the full [`random`][random] documentation, as there are many tools and options.
+
+
+~~~~exercism/caution
+
+The `random` module should __NOT__ be used for security and cryptographic applications!!
+
+Instead, Python provides the [`secrets`][secrets] module.
+This is specially optimized for cryptographic security.
+Some of the prior issues and reasons for creating the secrets module can be found in [PEP 506][PEP 506].
+
+[secrets]: https://docs.python.org/3.11/library/secrets.html#module-secrets
+[PEP 506]: https://peps.python.org/pep-0506/
+~~~~
+
+
+Before you can utilize the tools in the `random` module, you must first import it:
+
+```python
+>>> import random
+
+# Choose random integer from a range
+>>> random.randrange(1000)
+360
+
+>>> random.randrange(-1, 500)
+228
+
+>>> random.randrange(-10, 11, 2)
+-8
+
+# Choose random integer between two values (inclusive)
+>>> random.randint(5, 25)
+22
+
+```
+
+To avoid typing the name of the module, you can import specific functions by name:
+
+```python
+>>> from random import choice, choices
+
+# Using choice() to pick Heads or Tails 10 times
+>>> tosses = []
+>>> for side in range(10):
+>>> tosses.append(choice(['H', 'T']))
+
+>>> print(tosses)
+['H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'H']
+
+
+# Using choices() to pick Heads or Tails 8 times
+>>> picks = []
+>>> picks.extend(choices(['H', 'T'], k=8))
+>>> print(picks)
+['T', 'H', 'H', 'T', 'H', 'H', 'T', 'T']
+```
+
+
+
+## `randrange()` and `randint()`
+
+Shown in the first example above, the `randrange()` function has three forms:
+
+1. `randrange(stop)` gives an integer `n` such that `0 <= n < stop`
+2. `randrange(start, stop)` gives an integer `n` such that `start <= n < stop`
+3. `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop`
+ and `n` is in the sequence `start, start + step, start + 2*step...`
+
+For the most common case where `step == 1`, `randint(a, b)` may be more convenient and readable.
+Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as using `randrange(a, b+1)`.
+
+
+
+## `choice()` and `choices()`
+
+These two functions assume that you are starting from some [sequence][sequence-types], or other container.
+This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_).
+
+The `choice()` function will return one entry chosen at random from a given sequence, and `choices()` will return `k` number of entries chosen at random from a given sequence.
+In the examples shown above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified.
+
+For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random:
+
+
+```python
+>>> random.choices(['red', 'green'], [10, 15])
+['red']
+```
+
+[random]: https://docs.python.org/3/library/random.html
+[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range
+[truly-random]: https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random
diff --git a/concepts/random/links.json b/concepts/random/links.json
new file mode 100644
index 00000000000..22f60dbfb46
--- /dev/null
+++ b/concepts/random/links.json
@@ -0,0 +1,14 @@
+[
+ {
+ "url": "https://docs.python.org/3/library/random.html/",
+ "description": "Official documentation for the random module."
+ },
+ {
+ "url": "https://engineering.mit.edu/engage/ask-an-engineer/can-a-computer-generate-a-truly-random-number/",
+ "description": "MIT Engineering: Can a computer generate a truly random number?"
+ },
+ {
+ "url": "https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random",
+ "description": "Are Random Numbers Really Random?"
+ }
+]
diff --git a/concepts/recursion/about.md b/concepts/recursion/about.md
index 1c66756caf2..1cf24388269 100644
--- a/concepts/recursion/about.md
+++ b/concepts/recursion/about.md
@@ -6,7 +6,7 @@ Recursion can be viewed as another way to loop/iterate.
And like looping, a Boolean expression or `True/False` test is used to know when to stop the recursive execution.
_Unlike_ looping, recursion without termination in Python cannot not run infinitely.
Values used in each function call are placed in their own frame on the Python interpreter stack.
-If the total amount of function calls takes up more space than the stack has room for, it will result in an error.
+If the total number of function calls takes up more space than the stack has room for, it will result in an error.
## Looping vs Recursive Implementation
diff --git a/concepts/recursion/introduction.md b/concepts/recursion/introduction.md
index aebfd6596be..fb7e1970705 100644
--- a/concepts/recursion/introduction.md
+++ b/concepts/recursion/introduction.md
@@ -5,7 +5,7 @@ It can be viewed as another way to loop/iterate.
Like looping, a Boolean expression or `True/False` test is used to know when to stop the recursive execution.
_Unlike_ looping, recursion without termination in Python cannot not run infinitely.
Values used in each function call are placed in their own frame on the Python interpreter stack.
-If the total amount of function calls takes up more space than the stack has room for, it will result in an error.
+If the total number of function calls takes up more space than the stack has room for, it will result in an error.
```python
def print_increment(step, max_value):
diff --git a/concepts/secrets/.meta/config.json b/concepts/secrets/.meta/config.json
new file mode 100644
index 00000000000..152aa0eb3ba
--- /dev/null
+++ b/concepts/secrets/.meta/config.json
@@ -0,0 +1,5 @@
+{
+ "blurb": "The secrets module is a cryptographically-secure alternative to the random module, intended for security-critical uses.",
+ "authors": ["BethanyG", "colinleach"],
+ "contributors": []
+}
diff --git a/concepts/secrets/about.md b/concepts/secrets/about.md
new file mode 100644
index 00000000000..5987ab37e91
--- /dev/null
+++ b/concepts/secrets/about.md
@@ -0,0 +1,51 @@
+# About
+
+A previous concept discussed the [concept:python/random]() module, which produces [pseudo-random numbers][pseudo-random-numbers] and pseudo-random list orderings.
+
+The [`secrets`][secrets] module overlaps with `random` in some of its functionality, but the two modules are designed with very different priorities.
+
+- `random` is optimized for high performance in modelling and simulation, with "good enough" pseudo-random number generation.
+- `secrets` is designed to be crytographically secure for applications such as password hashing, security token generation, and account authentication.
+
+
+Further details on why the addition of the `secrets` module proved necessary are given in [PEP 506][PEP506].
+
+The `secrets` is relatively small and straightforward, with methods for generating random integers, bits, bytes or tokens, or a random entry from a given sequence.
+
+To use `scerets`, you mush first `import` it:
+
+
+```python
+>>> import secrets
+
+#Returns n, where 0 <= n < 1000.
+>>> secrets.randbelow(1000)
+577
+
+#32-bit integers.
+>>> secrets.randbits(32)
+3028709440
+
+>>> bin(secrets.randbits(32))
+'0b11111000101100101111110011110100'
+
+#Pick at random from a sequence.
+>>> secrets.choice(['my', 'secret', 'thing'])
+'thing'
+
+#Generate a token made up of random hexadecimal digits.
+>>> secrets.token_hex()
+'f683d093ea9aa1f2607497c837cf11d7afaefa903c5805f94b64f068e2b9e621'
+
+#Generate a URL-safe token of random alphanumeric characters.
+>>> secrets.token_urlsafe(16)
+'gkSUKRdiPDHqmImPi2HMnw'
+```
+
+
+If you are writing security-sensitive applications, you will certainly want to read the [full documentation][secrets], which gives further advice and examples.
+
+
+[PEP506]: https://peps.python.org/pep-0506/
+[pseudo-random-numbers]: https://www.khanacademy.org/computing/computer-science/cryptography/crypt/v/random-vs-pseudorandom-number-generators
+[secrets]: https://docs.python.org/3/library/secrets.html
diff --git a/concepts/secrets/introduction.md b/concepts/secrets/introduction.md
new file mode 100644
index 00000000000..04308ed0a2a
--- /dev/null
+++ b/concepts/secrets/introduction.md
@@ -0,0 +1,17 @@
+# Introduction
+
+A previous concept discussed the [concept:python/random]() module, which produces [pseudo-random numbers][pseudo-random-numbers] and pseudo-random list orderings.
+
+The [`secrets`][secrets] module overlaps with `random` in some of its functionality, but the two modules are designed with very different priorities.
+
+- `random` is optimized for high performance in modelling and simulation, with "good enough" pseudo-random number generation.
+- `secrets` is designed to be crytographically secure for applications such as password hashing, security token generation, and account authentication.
+
+
+Further details on why the addition of the `secrets` module proved necessary are given in [PEP 506][PEP506].
+
+If you are writing security-sensitive applications, you will certainly want to read the [full documentation][secrets], which gives further advice and examples.
+
+[PEP506]: https://peps.python.org/pep-0506/
+[pseudo-random-numbers]: https://www.khanacademy.org/computing/computer-science/cryptography/crypt/v/random-vs-pseudorandom-number-generators
+[secrets]: https://docs.python.org/3/library/secrets.html
diff --git a/concepts/secrets/links.json b/concepts/secrets/links.json
new file mode 100644
index 00000000000..ccf44e6fe59
--- /dev/null
+++ b/concepts/secrets/links.json
@@ -0,0 +1,18 @@
+[
+ {
+ "url": "https://docs.python.org/3/library/secrets.html/",
+ "description": "The secrets module."
+ },
+ {
+ "url": "https://peps.python.org/pep-0506/",
+ "description": "PEP 506, giving reasons why the secrets module is necessary."
+ },
+ {
+ "url": "https://en.wikipedia.org/wiki/Pseudorandomness",
+ "description": "Wikipedia: Pseudorandomness."
+ },
+ {
+ "url": "https://www.khanacademy.org/computing/computer-science/cryptography/crypt/v/random-vs-pseudorandom-number-generators",
+ "description": "Khan Academy: Pseudorandom Number Generators."
+ }
+]
diff --git a/concepts/sets/about.md b/concepts/sets/about.md
index 0b8fc842f11..944f98d1b52 100644
--- a/concepts/sets/about.md
+++ b/concepts/sets/about.md
@@ -1,18 +1,18 @@
# Sets
A [`set`][type-set] is a _mutable_ and _unordered_ collection of [_hashable_][hashable] objects.
-Set members must be distinct -- duplicate items are not allowed.
-They can hold multiple different data types and even nested structures like a `tuple` of `tuples` -- as long as all elements can be _hashed_.
-Sets also come in an immutable [`frozensets`][type-frozenset] flavor.
+Set members must be distinct β duplicate items are not allowed.
+They can hold multiple different data types and even nested structures like a `tuple` of `tuples` β as long as all elements can be _hashed_.
+Sets also come in an immutable [`frozenset`][type-frozenset] flavor.
Sets are most commonly used to quickly remove duplicates from other data structures or item groupings.
They are also used for efficient comparisons when sequencing and duplicate tracking are not needed.
Like other collection types (_dictionaries, lists, tuples_), `sets` support:
-- Iteration via `for item in `
+- Iteration via `for item in `,
- Membership checking via `in` and `not in`,
- Length calculation through `len()`, and
-- Shallow copies through `copy()`
+- Shallow copies through `copy()`.
`sets` do not support:
- Indexing of any kind
@@ -34,12 +34,13 @@ While sets can be created in many different ways, the most straightforward const
A `set` can be directly entered as a _set literal_ with curly `{}` brackets and commas between elements.
Duplicates are silently omitted:
+
```python
->>> one_element = {'π'}
-{'π'}
+>>> one_element = {'β'}
+{'β'}
->>> multiple_elements = {'π', 'π', 'π', 'π'}
-{'π', 'π', 'π', 'π'}
+>>> multiple_elements = {'β', 'π»', 'πΉ', 'π'}
+{'β', 'π»', 'πΉ', 'π'}
>>> multiple_duplicates = {'Hello!', 'Hello!', 'Hello!',
'Β‘Hola!','ΠΡΠΈΠ²ΡΡ!', 'γγγ«γ‘γ―οΌ',
@@ -108,9 +109,9 @@ Remember: sets can hold different datatypes and _nested_ datatypes, but all `set
```python
# Attempting to use a list for a set member throws a TypeError
->>> lists_as_elements = {['π
','π€£'],
- ['π','π','π'],
- ['π', 'π€ͺ', 'π']}
+>>> lists_as_elements = {['π','π¦'],
+ ['βοΈ','βοΈ','π'],
+ ['β΅οΈ', 'π²', 'π']}
Traceback (most recent call last):
File "", line 1, in
@@ -118,9 +119,9 @@ TypeError: unhashable type: 'list'
# Standard sets are mutable, so they cannot be hashed.
->>> sets_as_elements = {{'π
','π€£'},
- {'π','π','π'},
- {'π', 'π€ͺ', 'π'}}
+>>> sets_as_elements = {{'π','π¦'},
+ {'βοΈ','βοΈ','π'},
+ {'β΅οΈ', 'π²', 'π'}}
Traceback (most recent call last):
File "", line 1, in
@@ -131,14 +132,15 @@ However, a `set` of `sets` can be created via type `frozenset()`:
```python
# Frozensets don't have a literal form.
->>> set_1 = frozenset({'π', 'π', 'π€ͺ'})
->>> set_2 = frozenset({'π
', 'π€£'})
->>> set_3 = frozenset({'π', 'π', 'π'})
+>>> set_1 = frozenset({'π','π¦'})
+>>> set_2 = frozenset({'βοΈ','βοΈ','π'})
+>>> set_3 = frozenset({'β΅οΈ', 'π²', 'π'})
>>> frozen_sets_as_elements = {set_1, set_2, set_3}
>>> frozen_sets_as_elements
-{frozenset({'π', 'π', 'π€ͺ'}), frozenset({'π
', 'π€£'}),
-frozenset({'π', 'π', 'π'})}
+{frozenset({'β΅οΈ', 'π', 'π²'}),
+ frozenset({'π', 'π¦'}),
+ frozenset({'βοΈ', 'βοΈ', 'π'})}
```
@@ -172,12 +174,12 @@ Traceback (most recent call last):
Sets have methods that generally mimic [mathematical set operations][mathematical-sets].
Most (_not all_) of these methods have an [operator][operator] equivalent.
-Methods generally take any `iterable` as an argument, while operators require that both things being compared are `sets` or `frozensets`.
+Methods generally take any `iterable` as an argument, while operators require that both sides of the operation are `set`s or `frozenset`s.
### Membership Testing Between Sets
-The `.isdisjoint()` method is used to test if a `sets` elements have any overlap with the elements of another.
+The `.isdisjoint()` method is used to test if a `set`'s elements have any overlap with the elements of another.
The method will accept any `iterable` or `set` as an argument.
It will return `True` if the two sets have **no elements in common**, `False` if elements are **shared**.
@@ -266,16 +268,16 @@ False
False
# A set is always a loose superset of itself.
->>> set(animals) <= set(animals)
+>>> set(animals) >= set(animals)
True
```
### 'Proper' Subsets and Supersets
` < ` and ` > ` are used to test for _proper subsets_.
-A `set` is a proper subset if (`` <= ``) **AND** (`` != ``) for the `<` operator.
+A `set` is a proper subset if (` <= `) **AND** (` != `) for the `<` operator.
-A `set is a proper superset if `(`` >= ``) **AND** (`` != ``) for the `>` operator.
+A `set` is a proper superset if (` >= `) **AND** (` != `) for the `>` operator.
These operators have no method equivalent:
```python
@@ -334,7 +336,7 @@ The operator form of this method is ` | | | ...
### Set Differences
`.difference(*)` returns a new `set` with elements from the original `` that are not in ``.
-The operator version of this method is ` - - - ...`.
+The operator version of this method is ` - - - ... - `.
```python
>>> berries_and_veggies = {'Asparagus',
@@ -360,7 +362,7 @@ The operator version of this method is ` - - -
'Goose Berries', 'Strawberries'}
# Operators require sets.
->>> berries_and_veggies - just_berries
+>>> berries_and_veggies - berries
{'Artichokes','Asparagus','Broccoli','Kale',
'Ramps','Rhubarb','Walking Onions','Watercress'}
```
@@ -368,7 +370,7 @@ The operator version of this method is ` - - -
### Set Intersections
`.intersection(*)` returns a new `set` with elements common to the original `set` and all `` (in other words, the `set` where everything [intersects][intersection]).
-The operator version of this method is ` & & & ... `
+The operator version of this method is ` & & & ... & `
```python
>>> perennials = {'Annatto','Asafetida','Asparagus','Azalea',
@@ -383,7 +385,7 @@ The operator version of this method is ` & & & .
>>> herbs = ['Annatto','Asafetida','Basil','Chervil','Cilantro',
'Curry Leaf','Fennel','Kaffir Lime','Lavender',
- 'Marjoram','Mint','Oregano','Summer Savory'
+ 'Marjoram','Mint','Oregano','Summer Savory',
'Tarragon','Wild Bergamot','Wild Celery',
'Winter Savory']
@@ -418,8 +420,8 @@ The operator version of this method is ` ^ `.
>>> fruit_and_flowers ^ plants_1
{'π²', 'πΈ', 'π΄', 'π΅','πΊ', 'π»'}
->>> fruit_and_flowers ^ plants_2
-{ 'π₯', 'π΄','π²', 'π΅', 'π', 'π₯'}
+>>> fruit_and_flowers ^ set(plants_2)
+{'π₯', 'π΄', 'π΅', 'π', 'π²', 'π₯'}
```
~~~~exercism/note
diff --git a/concepts/sets/introduction.md b/concepts/sets/introduction.md
index 4c264f0903e..551e295e6a0 100644
--- a/concepts/sets/introduction.md
+++ b/concepts/sets/introduction.md
@@ -1,18 +1,18 @@
# Sets
A [`set`][type-set] is a _mutable_ and _unordered_ collection of [_hashable_][hashable] objects.
-Set members must be distinct -- duplicate items are not allowed.
-They can hold multiple different data types and even nested structures like a `tuple` of `tuples` -- as long as all elements can be _hashed_.
-Sets also come in an immutable [`frozensets`][type-frozenset] flavor.
+Set members must be distinct β duplicate items are not allowed.
+They can hold multiple different data types and even nested structures like a `tuple` of `tuples` β as long as all elements can be _hashed_.
+Sets also come in an immutable [`frozenset`][type-frozenset] flavor.
Sets are most commonly used to quickly remove duplicates from other data structures or item groupings.
They are also used for efficient comparisons when sequencing and duplicate tracking are not needed.
Like other collection types (_dictionaries, lists, tuples_), `sets` support:
-- Iteration via `for item in `
+- Iteration via `for item in `,
- Membership checking via `in` and `not in`,
- Length calculation through `len()`, and
-- Shallow copies through `copy()`
+- Shallow copies through `copy()`.
`sets` do not support:
- Indexing of any kind
diff --git a/concepts/string-formatting/.meta/config.json b/concepts/string-formatting/.meta/config.json
index 4e3955fc293..9f4edb07327 100644
--- a/concepts/string-formatting/.meta/config.json
+++ b/concepts/string-formatting/.meta/config.json
@@ -1,5 +1,11 @@
{
"blurb": "There are four main string formatting methods. A '%' formatting mini-language is supported, but is considered outdated. String interpolation (f-strings) and 'str.format()'are newer, and can be used for complex or conditional substitution. 'string.template()' substitution is used for internationalization, where f-strings will not translate.",
- "authors": ["valentin-p"],
- "contributors": ["j08k", "BethanyG"]
+ "authors": [
+ "valentin-p"
+ ],
+ "contributors": [
+ "j08k",
+ "BethanyG",
+ "BNAndras"
+ ]
}
diff --git a/concepts/string-formatting/about.md b/concepts/string-formatting/about.md
index f3b2756b768..be2ac0a1220 100644
--- a/concepts/string-formatting/about.md
+++ b/concepts/string-formatting/about.md
@@ -30,57 +30,94 @@ In this example, we insert two variable values in the sentence: one `str` and on
The expressions evaluated can be almost anything.
Some of the (wide range) of possibilities that can be evaluated: `str`, `numbers`, variables, arithmetic expressions, conditional expressions, built-in types, slices, functions, lambdas, comprehensions or **any** objects with either `__str__` or `__repr__` methods defined.
-Some examples:
+Going from simple to complex:
+
+**Inserting a variable** β the simplest use of a f-string is to place a variable directly into the string.
+
+```python
+# Assigning a variable
+>>> name = "World"
+
+# Inserting that variable
+>>> f'Hello, {name}!'
+'Hello, World!'
+```
+
+**Expressions inside `{}`** β any valid Python expression can be evaluated inside the braces.
+Note that using double quotes inside a single-quoted f-string (or vice versa) avoids the need for escape sequences:
```python
-# A dictionary of key:value pairs.
+# A dictionary of key:value pairs
>>> waves = {'water': 1, 'light': 3, 'sound': 5}
-# Using the name waves in an f-string.
->>> f'"A dict can be represented with f-string: {waves}."'
-'"A dict can be represented with f-string: {\'water\': 1, \'light\': 3, \'sound\': 5}."'
+# Inserting the whole dict
+>>> f'Wave ranks: {waves}'
+"Wave ranks: {'water': 1, 'light': 3, 'sound': 5}"
+
+# An expression can be evaluated inline
+>>> f"Tenfold the value of 'light' is {waves['light'] * 10}."
+"Tenfold the value of 'light' is 30."
+
+# A method call can also be evaluated inline
+>>> f'{"hello world!".title()} is a classic greeting.'
+'Hello World! is a classic greeting.'
-# Here, we pull a value from the dictionary by using the key
->>> f'Tenfold the value of "light" is {waves["light"] * 10}.'
-'Tenfold the value of "light" is 30.'
+# An f-string can be nested inside another f-string
+>>> f"{f'hello world!'.title()} is a classic greeting."
+'Hello World! is a classic greeting.'
```
-Replacement fields (_the `{}` in the f-string_) support output control mechanisms such as width, alignment, precision.
-This specification is started in the [format specification mini-language][format-mini-language].
+**Output formatting** β the [format specification mini-language][format-mini-language] can be used to control alignment, numeric precision, and much more.
+The format specification goes after the value, separated by a `:`.
-A more complex example of an `f-string` that includes output control:
+```python
+# Right-align a value to ten characters, rounding it to 3 decimal places.
+>>> value = 1 / 7
+>>> f'One seventh is {value:10.3f}.'
+'One seventh is 0.143.'
+
+# A format specification can be set using variables as well.
+>>> padding = 10
+>>> precision = 3
+>>> f'One seventh is {value:{padding}.{precision}f}.'
+'One seventh is 0.143.'
+```
+
+**Putting it all together** β variables, expressions, function calls, and output formatting:
```python
-# Assigning variables
>>> precision = 3
->>> verb = "see"
->>> the_end = ['end', 'of', 'transmission']
+>>> f"{30e8 * 111_000:6.{precision}e}"
+'3.330e+14'
-# Reassigning verb to 'meet'.
>>> verb = 'meet'
+>>> the_end = ['end', 'of', 'transmission']
+>>> f'"Have a {"NICE".lower()} day, I will {verb} you after {30e8 * 111_000:6.{precision}e} light-years."{the_end}'
+'"Have a nice day, I will meet you after 3.330e+14 light-years."[\'end\', \'of\', \'transmission\']'
-# This example includes a function, str, a nested f-string, an arithmetic expression,
-# precision formatting, bracket escaping and object formatting.
->>> f'"Have a {"NICE".lower()} day, I will {verb} you after {f"{30e8 * 111_000:6.{precision}e}"} light-years."{{{the_end}}}'
-'"Have a nice day, I will meet you after 3.330e+14 light-years."{[\'end\', \'of\', \'transmission\']}'
+# Did you notice the escaped single-quotes in the previous example?
+# Using double quotes instead of single quotes for the f-string means the list's single-quoted strings print cleanly.
+>>> f"Have a nice day. {the_end}"
+"Have a nice day. ['end', 'of', 'transmission']"
```
-There are a few limitations to be aware of.
-`f-string` expressions cannot be empty, they cannot contain comments.
+There are two main limitations to be aware of.
+`f-string` expressions can not be empty.
+[Additionally, before Python 3.12, they could not contain comments.][pep-0701]
```python
>>> f"An empty expression will error: {}"
SyntaxError: f-string: empty expression not allowed
>>> word = 'word'
->>> f"""A comment in a triple quoted f-string will error: {
+>>> f"""A comment in a triple quoted f-string: {
word # I chose a nice variable
}"""
-SyntaxError: f-string expression part cannot include '#'
+'A comment in a triple quoted f-string: word'
```
~~~~exercism/caution
-String interpolation cannot be used together with the [GNU gettext API][gnu-gettext-api] for internationalization (I18N) and localization (L10N), so it is recommended that the `string.Template(template)` class or the `str.format()` method outlined below be used instead of an `f-string` in any "string wrapping" translation scenarios.
+String interpolation can not be used together with the [GNU gettext API][gnu-gettext-api] for internationalization (I18N) and localization (L10N), so it is recommended that the `string.Template(template)` class or the `str.format()` method outlined below be used instead of an `f-string` in any "string wrapping" translation scenarios.
Also keep in mind that using expressions inside the `f-string` brackets `{}` is similar to using `eval()` or `exec()`, so it isn't very safe and should be used sparingly.
~~~~
@@ -105,7 +142,7 @@ The complete formatting specifier pattern is `{[][!][:` can be a named placeholder or a number or empty.
- `!` is optional and should be one of this three conversions: `!s` for [`str()`][str-conversion], `!r` for [`repr()`][repr-conversion] or `!a` for [`ascii()`][ascii-conversion].
By default, `str()` is used.
-- `:` is optional and has a lot of options, which we are [listed here][format-specifiers].
+- `:` is optional and controls how the value is displayed. More information about possible options can be [found here][format-specifiers].
Example of conversions for a diacritical letter:
@@ -132,13 +169,39 @@ Example of conversions for a diacritical letter:
"She said her name is not Chloe but 'ZoΓ«'."
```
-Example of using format specifiers:
+Examples of common format specifiers:
```python
-# Formats the object at index 0 as a decimal with zero places,
-# then as a right-aligned binary number in an 8 character wide field.
->>> "The number {0:d} has a representation in binary: '{0: >8b}'.".format(42)
-"The number 42 has a representation in binary: ' 101010'."
+# Integer and binary/hex representations of the same number
+>>> my_num = 42
+>>> f"{my_num} in binary is {my_num:b}. In hex, it is {my_num:x}"
+"42 in binary is 101010. In hex, it is 2a"
+
+# Alignment: left (<), right (>), and center (^) using up to ten characters total
+>>> f"[{"left":<10}] [{"right":>10}] [{"center":^10}]"
+"[left ] [ right] [ center ]"
+
+# Float precision and scientific notation up to three decimal places
+>>> pi = 3.141592653589793
+>>> f"fixed: {pi:.3} scientific: {pi:.3e}"
+"fixed: 3.142 scientific: 3.142e+00"
+
+# Thousands separator and percentage
+>>> balance = 1000
+>>> rate = 0.0225
+>>> f"Balance: ${balance:,.0f} Interest rate: {rate:.1%}"
+"Balance: $1,000 Interest rate: 2.2%"
+
+# Putting it all together
+>>> items = [("Widget", 1250, 9.991), ("Gadget", 37, 24.503), ("Doohickey", 4, 149.002)]
+>>> header = f"{"Item":<12} {"Qty":>6} {"Price":>9}"
+>>> print(header)
+Item Qty Price
+>>> for name, qty, price in items:
+... print(f"{name:<12} {qty:>6} {price:>9.2f}")
+Widget 1250 9.99
+Gadget 37 24.50
+Doohickey 4 149.00
```
More examples are shown at the end of [this documentation][summary-string-format].
@@ -177,8 +240,10 @@ If you want to add multiple variables to a string, you need to supply a [tuple][
## Template Strings
-[`string.Template()`][string.Template()] is a class from the `string` module (_as opposed to the built-in `str` type_), which is part of the Python standard library, but has to be imported for use.
-Template strings support `$`-based substitution and are much simpler and less capable than the other options mentioned here, but can be very useful for when complicated internationalization is needed, or outside inputs need to be sanitized.
+[`string.Template()`][string.Template()] (_not to be confused with Python 3.14 [t-strings]_) is a class from the `string` module (_as opposed to the built-in `str` type_), which is part of the Python standard library, but has to be imported for use.
+Template strings support `$`-based substitution and are much simpler and less capable than the other options mentioned here.
+However, they can be very useful for when complicated internationalization is needed, or outside inputs need to be sanitized.
+`string.Template` is considered safer for untrusted user input because it prevents evaluating arbitrary expressions or accessing object attributes, which mitigates format-string injection attacks.
```python
>>> from string import Template
@@ -204,8 +269,8 @@ A few quick guidelines:
If you don't need to internationalize, they should be the Python 3.6+ preferred method.
2. `str.format()` is versatile, very powerful and compatible with both `gnu gettext` and most versions of Python.
3. If simplicity, safety, and/or heavy internationalization is what you need, `string.Template()` can be used to mitigate risks when inputs from users need to be handled, and for wrapping translation strings.
-4. The `%` operator is not supported in some newer distributions of Python and should mostly be used for compatibility with old code.
-`%` formatting` can lead to issues displaying non-ascii and unicode characters and has more errors and less functionality than other methods.
+4. The `%` operator is generally considered deprecated for new code, though it still works in modern Python. It should mostly be used for compatibility with older codebases.
+`%` formatting can lead to issues displaying non-ASCII and Unicode characters and has more errors and less functionality than other methods. Check your specific Python distribution for support details if you intend to use it.
If you want to go further: [all about formatting][all-about-formatting] and [Python String Formatting Best Practices][formatting best practices] are good places to start.
@@ -216,6 +281,7 @@ If you want to go further: [all about formatting][all-about-formatting] and [Pyt
[format-specifiers]: https://www.python.org/dev/peps/pep-3101/#standard-format-specifiers
[formatting best practices]: https://realpython.com/python-string-formatting/
[pep-0498]: https://peps.python.org/pep-0498
+[pep-0701]: https://peps.python.org/pep-0701/
[printf-style-docs]: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting
[repr-conversion]: https://www.w3resource.com/python/built-in-function/repr.php
[str-conversion]: https://www.w3resource.com/python/built-in-function/str.php
@@ -224,5 +290,6 @@ If you want to go further: [all about formatting][all-about-formatting] and [Pyt
[string.Template()]: https://docs.python.org/3/library/string.html#template-strings
[summary-string-format]: https://www.w3schools.com/python/ref_string_format.asp
[template-string]: https://docs.python.org/3/library/string.html#template-strings
+[t-strings]: https://realpython.com/python-t-strings/
[tuples]: https://www.w3schools.com/python/python_tuples.asp
[zen-of-python]: https://www.python.org/dev/peps/pep-0020/
diff --git a/concepts/string-formatting/introduction.md b/concepts/string-formatting/introduction.md
index aa476de9ca0..ed88cc4d01c 100644
--- a/concepts/string-formatting/introduction.md
+++ b/concepts/string-formatting/introduction.md
@@ -3,18 +3,20 @@
## String Formatting in Python
The [Zen of Python][zen-of-python] asserts there should be "one _obvious_ way to do something in Python".
-But when it comes to string formatting, things are a little .... _less zen_.
-It can be surprising to find out that there are **four** main ways to perform string formatting in Python - each for a different scenario.
-Some of this is due to Python's long history and some of it is due to considerations like internationalization or input sanitation.
+For Python 3.6+, **literal string interpolation** (**`f-strings`**) is often the obvious and preferred way to format strings:
-With 4 different paths to take, how do you decide what to use?
+```python
+>>> adjective = "easy"
+>>> f"This is an {adjective} way to format strings!"
+'This is an easy way to format strings!'
+```
-1. `f-strings` are the newest and easiest to read.
-If you don't need to internationalize, they should be the Python 3.6+ preferred method.
-2. `str.format()` is versatile, very powerful and compatible with both `gnu gettext` and most versions of Python.
-3. If simplicity, safety, and/or heavy internationalization is what you need, `string.Template()` can be used to mitigate risks when inputs need to be handled and for wrapping translation strings.
-4. The `%` operator should mostly be used for compatibility with old code.
-`%` formatting` can lead to issues displaying non-ascii and unicode characters and has more errors and less functionality than other methods.
+However, given Python's long history and different use-cases, it might not be surprising that there are **three** other common ways to perform string formatting in Python:
+
+1. `str.format()` is versatile, very powerful and compatible with both `gnu gettext` and most versions of Python.
+2. If simplicity, safety, and/or heavy internationalization is what you need, `string.Template()` can be used to mitigate risks when inputs need to be handled and for wrapping translation strings.
+3. The `%` operator is generally considered deprecated for new code, though it still works in modern Python.
+It should mostly be used for compatibility with older codebases. `%` formatting can lead to issues displaying non-ASCII and Unicode characters and has more errors and less functionality than other methods.Check your specific Python distribution for support details if you intend to use it.
If you want to go further: [all about formatting][all-about-formatting] and [Python String Formatting Best Practices][formatting best practices] are good places to start.
diff --git a/concepts/string-methods/.meta/config.json b/concepts/string-methods/.meta/config.json
index 4bb37fcda42..d429a738102 100644
--- a/concepts/string-methods/.meta/config.json
+++ b/concepts/string-methods/.meta/config.json
@@ -1,5 +1,5 @@
{
"blurb": "The 'str' class provides many useful 'string-methods'. They can be used for cleaning, splitting, translating, or otherwise working with any 'str' object. Because strings are immutable, any functions or methods that operate on a 'str' will return a new instance or copy of the 'str' rather than modifying the original 'str' object.",
"authors": ["kimolivia"],
- "contributors": ["valentin-p", "bethanyg"]
+ "contributors": ["valentin-p", "BethanyG"]
}
diff --git a/concepts/string-methods/about.md b/concepts/string-methods/about.md
index 9ca16ffa298..6c9c843b97c 100644
--- a/concepts/string-methods/about.md
+++ b/concepts/string-methods/about.md
@@ -5,19 +5,22 @@ This may include letters, diacritical marks, positioning characters, numbers, cu
Strings implement all [common sequence operations][common sequence operations] and can be iterated through using `for item in ` or `for index, item in enumerate()` syntax.
Individual code points (_strings of length 1_) can be referenced by `0-based index` number from the left, or `-1-based index` number from the right.
- Strings can be concatenated with `+`, or via `.join()`, split via `.split(
+> [!IMPORTANT]
+> 
Here to suggest a new feature or new exercise?? **Hooray!** π
-We'd love if you did that via our [Exercism Community Forum](https://forum.exercism.org/).
+We'd love if you did that via our [Community Forum](https://forum.exercism.org/).
Please read [Suggesting Exercise Improvements][suggesting-improvements] & [Chesterton's Fence][chestertons-fence].
-_Thoughtful suggestions will likely result faster & more enthusiastic responses from volunteers._
+_Thoughtful suggestions will likely result in faster & more enthusiastic responses from volunteers._
@@ -67,7 +84,7 @@ _Thoughtful suggestions will likely result faster & more enthusiastic responses
## Python Software and Documentation
-**Copyright Β© 2001-2022 Python Software Foundation. All rights reserved.**
+**Copyright Β© 2001-2026 Python Software Foundation. All rights reserved.**
Python software and documentation are licensed under the [PSF License Agreement][psf-license].
@@ -99,7 +116,6 @@ This repository uses the [MIT License](/LICENSE).
[exercism-writing-style]: https://github.com/exercism/docs/blob/main/building/markdown/style-guide.md
[freeing-maintainers]: https://exercism.org/blog/freeing-our-maintainers
[practice-exercises]: https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md
-[prs]: https://github.com/exercism/docs/blob/main/community/good-member/pull-requests.md
[psf-license]: https://docs.python.org/3/license.html#psf-license
[python-syllabus]: https://exercism.org/tracks/python/concepts
[suggesting-improvements]: https://github.com/exercism/docs/blob/main/community/good-member/suggesting-exercise-improvements.md
diff --git a/bin/fetch-configlet b/bin/fetch-configlet
index 4800e150849..6bef43ab722 100755
--- a/bin/fetch-configlet
+++ b/bin/fetch-configlet
@@ -24,10 +24,11 @@ get_download_url() {
local latest='https://api.github.com/repos/exercism/configlet/releases/latest'
local arch
case "$(uname -m)" in
- x86_64) arch='x86-64' ;;
- *686*) arch='i386' ;;
- *386*) arch='i386' ;;
- *) arch='x86-64' ;;
+ aarch64|arm64) arch='arm64' ;;
+ x86_64) arch='x86-64' ;;
+ *686*) arch='i386' ;;
+ *386*) arch='i386' ;;
+ *) arch='x86-64' ;;
esac
local suffix="${os}_${arch}.${ext}"
curl "${curlopts[@]}" --header 'Accept: application/vnd.github.v3+json' "${latest}" |
@@ -47,7 +48,7 @@ main() {
fi
local os
- case "$(uname)" in
+ case "$(uname -s)" in
Darwin*) os='macos' ;;
Linux*) os='linux' ;;
Windows*) os='windows' ;;
@@ -58,8 +59,8 @@ main() {
local ext
case "${os}" in
- windows*) ext='zip' ;;
- *) ext='tar.gz' ;;
+ windows) ext='zip' ;;
+ *) ext='tar.gz' ;;
esac
echo "Fetching configlet..." >&2
@@ -69,16 +70,16 @@ main() {
curl "${curlopts[@]}" --output "${output_path}" "${download_url}"
case "${ext}" in
- *zip) unzip "${output_path}" -d "${output_dir}" ;;
- *) tar xzf "${output_path}" -C "${output_dir}" ;;
+ zip) unzip "${output_path}" -d "${output_dir}" ;;
+ *) tar xzf "${output_path}" -C "${output_dir}" ;;
esac
rm -f "${output_path}"
local executable_ext
case "${os}" in
- windows*) executable_ext='.exe' ;;
- *) executable_ext='' ;;
+ windows) executable_ext='.exe' ;;
+ *) executable_ext='' ;;
esac
local configlet_path="${output_dir}/configlet${executable_ext}"
diff --git a/bin/generate_tests.py b/bin/generate_tests.py
index 6c9b1c38b98..2ad23a9b5f1 100755
--- a/bin/generate_tests.py
+++ b/bin/generate_tests.py
@@ -138,7 +138,7 @@ def parse_datetime(string: str, strip_module: bool = False) -> datetime:
]| # OR
o(?:[0-8]{1,3}) # an octal value
| # OR
- x(?:[0-9A-Fa-f]{2}) # a hexidecimal value
+ x(?:[0-9A-Fa-f]{2}) # a hexadecimal value
| # OR
N # a unicode char name composed of
\{ # an opening brace
@@ -204,6 +204,8 @@ def regex_find(s: str, find: str) -> List[Any]:
def regex_split(s: str, find: str) -> List[str]:
return re.split(find, s)
+def join_test_inputs(test_inputs: list) -> str:
+ return "\n".join(test_inputs)
def filter_test_cases(cases: List[TypeJSON], opts: TestsTOML) -> List[TypeJSON]:
"""
@@ -409,6 +411,7 @@ def generate(
env.filters["regex_replace"] = regex_replace
env.filters["regex_find"] = regex_find
env.filters["regex_split"] = regex_split
+ env.filters["join_test_inputs"] = join_test_inputs
env.filters["zip"] = zip
env.filters["parse_datetime"] = parse_datetime
env.filters["escape_invalid_escapes"] = escape_invalid_escapes
diff --git a/concepts/basics/about.md b/concepts/basics/about.md
index 30ea083022f..6f932bfd16f 100644
--- a/concepts/basics/about.md
+++ b/concepts/basics/about.md
@@ -6,7 +6,8 @@ Imperative, declarative (e.g., functional), and object-oriented programming _sty
Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
-Python was created by Guido van Rossum and first released in 1991. The [Python Software Foundation][psf] manages and directs resources for Python and CPython development and receives proposals for changes to the language from [members][psf membership] of the community via [Python Enhancement Proposals or PEPs][peps].
+Python was created by Guido van Rossum and first released in 1991.
+The [Python Software Foundation][psf] manages and directs resources for Python and CPython development and receives proposals for changes to the language from [members][psf membership] of the community via [Python Enhancement Proposals or PEPs][peps].
Complete documentation for the current release can be found at [docs.python.org][python docs].
@@ -18,8 +19,14 @@ Complete documentation for the current release can be found at [docs.python.org]
- [Python FAQs][python faqs]
- [Python Glossary of Terms][python glossary of terms]
+