[Leap]: Add calendar-isleap approach and improved benchmarks (exercism#3583)

* [Leap]: Add `calendar-isleap` approach and improved benchmarks * added comments on `isleap()` implementation and operator precedence * Approach and Chart Edits Various language edits and touchups. Added chart reference and alt-textm as well as link to long description. Probably unnecessary for this particular article but wanted to establish an example of what to do when alt-texting a chart. See https://www.w3.org/WAI/tutorials/images/complex/ for more information and examples on how to alt-text complex images. * Fixed Awkward Chart Intro * Another try on alt-text * Trying Yet Again * Attempt to align figcaption * Giving up and going for description location in alt --------- Co-authored-by: BethanyG <[email protected]>

Author: colinleach

exercises/practice/leap/.approaches/boolean-chain/content.md

@@ -6,13 +6,15 @@ def leap_year(year):
 
 ```
 
+This might be considered the "most idiomatic" or "most Pythonic" solution, as it is exactly the same as the code implemented by the maintainers of the Python language for the [`calendar.isleap()`][isleap-source] method.
+
 The first boolean expression uses the [modulo operator][modulo-operator] to check if the year is evenly divided by `4`.
-- If the year is not evenly divisible by `4`, then the chain will "short circuit" due to the next operator being a [logical AND][logical-and]{`and`), and will return `False`.
+- If the year is _not_ evenly divisible by `4`, then the chain will [short circuit][short-ciruiting] due to the next operator being a [logical AND][logical-and]{`and`), and will return `False`.
 - If the year _is_ evenly divisible by `4`, then the year is checked to _not_ be evenly divisible by `100`.
-- If the year is not evenly divisible by `100`, then the expression is `True` and the chain will "short-circuit" to return `True`,
-since the next operator is a [logical OR][logical-or] (`or`).
+- If the year is not evenly divisible by `100`, then the expression is `True` and the interpreter will stop the evaluation to return `True`, since the next operator is a [logical OR][logical-or] (`or`).
 - If the year _is_ evenly divisible by `100`, then the expression is `False`, and the returned value from the chain will be if the year is evenly divisible by `400`.
 
+
 | year | year % 4 == 0 | year % 100 != 0 | year % 400 == 0 | is leap year |
 | ---- | ------------- | --------------- | --------------- | ------------ |
 | 2020 | True | True | not evaluated | True |
@@ -21,13 +23,24 @@ since the next operator is a [logical OR][logical-or] (`or`).
 | 1900 | True | False | False | False |
 
 
-The chain of boolean expressions is efficient, as it proceeds from testing the most likely to least likely conditions.
+The chain of boolean expressions is efficient, as it proceeds from testing the most to least likely conditions.
 It is the fastest approach when testing a year that is not evenly divisible by `100` and is not a leap year.
 
+
+## Operator precedence
+
+The implementation contains one set of parentheses, around the `or` clause:
+- One set is enough, because the `%` operator is highest priority, then the `==` and `!=` relational operators.
+- Those parentheses are required, because `and` is higher priority than `or`.
+In Python, `a and b or c` is interpreted as `(a and b) or c`, which would give the wrong answer for this exercise.
+
+If in doubt, it is always permissible to add extra parentheses for clarity.
+
+
 ## Refactoring
 
 By using the [falsiness][falsiness] of `0`, the [`not` operator][not-operator] can be used instead of comparing equality to `0`.
-For example
+For example:
 
 ```python
 defleap_year(year):
@@ -42,3 +55,5 @@ It can be thought of as the expression _not_ having a remainder.
 [logical-or]: https://realpython.com/python-or-operator/
 [falsiness]: https://www.pythontutorial.net/python-basics/python-boolean/
 [not-operator]: https://realpython.com/python-not-operator/
+[short-ciruiting]: https://mathspp.com/blog/pydonts/boolean-short-circuiting#short-circuiting-in-plain-english
+[isleap-source]: https://github.com/python/cpython/blob/main/Lib/calendar.py#L141-L143

exercises/practice/leap/.approaches/calendar-isleap/content.md

@@ -0,0 +1,38 @@
+# The `calendar.isleap()` function
+
+```pythoon
+from calendar import isleap
+
+def leap_year(year):
+ return isleap(year)
+```
+
+~~~~exercism/caution
+This approach may be considered a "cheat" for this exercise, which is intended to practice Boolean operators and logic.
+~~~~
+
+
+The Python standard library includes a [`calendar`][calendar] module for working with many aspects of dates in the [Gregorian calendar][gregorian-calendar].
+
+One of the methods provided is [`isleap()`][isleap], which implements exactly the same functionality as this exercise.
+
+This is not a good way to practice the use of Booleans, as the exercise intends.
+However, it may be convenient (_and better tested_) if you are working with calendar functions more broadly.
+
+## The library function
+
+This is the [implementation][implementation]:
+
+```python
+defisleap(year):
+"""Return True for leap years, False for non-leap years."""
+return year %4==0and (year %100!=0or year %400==0)
+```
+
+We can see that `calendar.isleap()` is just syntactic sugar for the `boolean-chain` approach.
+
+
+[calendar]: https://docs.python.org/3/library/calendar.html
+[gregorian-calendar]: https://en.wikipedia.org/wiki/Gregorian_calendar
+[implementation]: https://github.com/python/cpython/blob/main/Lib/calendar.py
+[isleap]: https://docs.python.org/3/library/calendar.html

exercises/practice/leap/.approaches/calendar-isleap/snippet.txt

@@ -0,0 +1,4 @@
+from calendar import isleap
+
+def leap_year(year):
+ return isleap(year)

exercises/practice/leap/.approaches/config.json

@@ -1,7 +1,7 @@
 {
 "introduction":{
 "authors": ["bobahop"],
-"contributors": []
+"contributors": ["colinleach"]
  },
 "approaches": [
 {
@@ -24,6 +24,14 @@
 "title": "datetime addition",
 "blurb": "Use datetime addition.",
 "authors": ["bobahop"]
+ },
+{
+"uuid": "d85be356-211a-4d2f-8af0-fa92e390b0b3",
+"slug": "calendar-isleap",
+"title": "calendar.isleap() function",
+"blurb": "Use the calendar module.",
+"authors": ["colinleach",
+"BethanyG"]
  }
  ]
 }

exercises/practice/leap/.approaches/datetime-addition/content.md

@@ -11,11 +11,14 @@ def leap_year(year):
 ```
 
 ~~~~exercism/caution
-This approach may be considered a "cheat" for this exercise.
+This approach may be considered a "cheat" for this exercise, which is intended to practice Boolean operators and logic.
+It also adds a tremendous amount of overhead in both performance and memory, as it imports all of the `datetime` module and requires the instantiation of both a `datetime` object and a `datetime.timedelta` object. 
+
+For more information, see this exercises performance article.
 ~~~~
 
-By adding a day to February 28th for the year, you can see if the new day is the 29th or the 1st.
-If it is the 29th, then the function returns `True` for the year being a leap year.
+By adding a day to February 28th for a given year, you can see if the new day falls on the 29th of February, or the 1st of March.
+If it is February 29th, then the function returns `True` for the year being a leap year.
 
 - A new [datetime][datetime] object is created for February 28th of the year.
 - Then the [timedelta][timedelta] of one day is added to that `datetime`,

exercises/practice/leap/.approaches/introduction.md

@@ -1,58 +1,78 @@
 # Introduction
 
-There are various idiomatic approaches to solve Leap.
-You can use a chain of boolean expressions to test the conditions.
-Or you can use a [ternary operator][ternary-operator].
+There are multiple idiomatic approaches to solving the Leap exercise.
+You can use a chain of boolean expressions to test the conditions, a [ternary operator][ternary-operator], or built-in methods from the `datetime` or `calendar` modules.
 
-## General guidance
 
-The key to solving Leap is to know if the year is evenly divisible by `4`, `100` and `400`.
+## General Guidance
+
+The key to efficiently solving Leap is to calculate if the year is evenly divisible by `4`, `100` and `400`.
 For determining that, you will use the [modulo operator][modulo-operator].
 
-## Approach: Chain of Boolean expressions
+
+## Approach: Chain of Boolean Expressions
 
 ```python
 defleap_year(year):
 return year %4==0and (year %100!=0or year %400==0)
 
 ```
 
-For more information, check the [Boolean chain approach][approach-boolean-chain].
+For more information, see the [Boolean chain approach][approach-boolean-chain].
+
 
-## Approach: Ternary operator of Boolean expressions
+## Approach: Ternary Operator of Boolean Expressions
 
 ```python
 defleap_year(year):
 return (not year %400ifnot year %100elsenot year %4)
 
 ```
 
-For more information, check the [Ternary operator approach][approach-ternary-operator].
+For more information, see the [Ternary operator approach][approach-ternary-operator].
 
-## Other approaches
+
+## Other Approaches
 
 Besides the aforementioned, idiomatic approaches, you could also approach the exercise as follows:
 
-### Approach: datetime addition
 
-Add a day to February 28th for the year and see if the new day is the 29th. For more information, see the [`datetime` addition approach][approach-datetime-addition].
+### Approach: `datetime` Addition
+
+Add a day to February 28th for the year and see if the new day is the 29th.
+However, this approach may trade speed for convenience.
+For more information, see the [`datetime` addition approach][approach-datetime-addition].
+
+
+### Approach: The `calendar` module
+
+It is possible to use `calendar.isleap(year)` from the standard library, which solves this exact problem.
+
+This is self-defeating in an Exercism practice exercise intended to explore ways to use booleans.
+In a wider context, anyone testing for leap years may already be using `calendar` or related modules, and it is good to know what library functions are available.
+
 
 ## Which approach to use?
 
-- The chain of boolean expressions should be the most efficient, as it proceeds from the most likely to least likely conditions.
+- The chain of boolean expressions should be the most efficient, as it proceeds from the most to least likely conditions and takes advantage of short-circuiting.
 It has a maximum of three checks.
-It is the fastest approach when testing a year that is not evenly divisible by `100`and is not a leap year.
+It is the fastest approach when testing a year that is not evenly divisible by `100`that is not a leap year.
 Since most years fit those conditions, it is overall the most efficient approach.
-- The ternary operator has a maximum of only two checks, but it starts from a less likely condition.
+It also happens to be the approach taken by the maintainers of the Python language in [implementing `calendar.isleap()`][calendar_isleap-code].
+
+
+- The ternary operator approach has a maximum of only two checks, but it starts from a less likely condition.
 The ternary operator was faster in benchmarking when the year was a leap year or was evenly divisible by `100`,
-but those are the least likely conditions.
-- Using `datetime` addition may be considered a "cheat" for the exercise, and it was slower than the other approaches in benchmarking.
+but those are the _least likely_ conditions.
+- Using `datetime` addition may be considered a "cheat" for the exercise, and it was slower by far than the other approaches in benchmarking.
 
-For more information, check the [Performance article][article-performance].
+For more information, check out the [Performance article][article-performance].
 
-[modulo-operator]: https://realpython.com/python-modulo-operator/
-[ternary-operator]: https://www.pythontutorial.net/python-basics/python-ternary-operator/
 [approach-boolean-chain]: https://exercism.org/tracks/python/exercises/leap/approaches/boolean-chain
-[approach-ternary-operator]: https://exercism.org/tracks/python/exercises/leap/approaches/ternary-operator
 [approach-datetime-addition]: https://exercism.org/tracks/python/exercises/leap/approaches/datetime-addition
+[approach-ternary-operator]: https://exercism.org/tracks/python/exercises/leap/approaches/ternary-operator
 [article-performance]: https://exercism.org/tracks/python/exercises/leap/articles/performance
+[calendar_isleap-code]: https://github.com/python/cpython/blob/3.9/Lib/calendar.py#L100-L102
+[modulo-operator]: https://realpython.com/python-modulo-operator/
+[ternary-operator]: https://www.pythontutorial.net/python-basics/python-ternary-operator/
+

exercises/practice/leap/.articles/config.json

@@ -5,7 +5,8 @@
 "slug": "performance",
 "title": "Performance deep dive",
 "blurb": "Deep dive to find out the most performant approach for determining a leap year.",
-"authors": ["bobahop"]
+"authors": ["bobahop",
+"colinleach"]
  }
  ]
 }

exercises/practice/leap/.articles/performance/code/Benchmark.py

@@ -1,88 +1,91 @@
 importtimeit
-
+importpandasaspd
+importnumpyasnp
+importmatplotlibasmpl
+importmatplotlib.pyplotasplt
+importseabornassns
+frommatplotlib.colorsimportListedColormap
+
+# Setting up the Data
 loops=1_000_000
 
-val=timeit.timeit("""leap_year(1900)""",
-"""
-def leap_year(year):
- return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+row_headers= ["if-statements", "ternary", "datetime-add", "calendar-isleap"]
+col_headers= ["1900", "2000", "2019", "2020"]
 
-""", number=loops) /loops
+# empty dataframe will be filled in one cell at a time later
+df=pd.DataFrame(np.nan, index=row_headers, columns=col_headers)
 
-print(f"if statements 1900: {val}")
+setups={}
 
-val=timeit.timeit("""leap_year(2000)""",
-"""
+setups["if-statements"] ="""
 def leap_year(year):
  return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+"""
 
-""", number=loops) /loops
-
-print(f"if statements 2000: {val}")
-
-
-val=timeit.timeit("""leap_year(2019)""",
-"""
-def leap_year(year):
- return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
-
-""", number=loops) /loops
-
-print(f"if statements 2019: {val}")
-
-val=timeit.timeit("""leap_year(2020)""",
-"""
+setups["ternary"] ="""
 def leap_year(year):
- return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
-
-""", number=loops) /loops
+ return not year % 400 if not year % 100 else not year % 4
+"""
 
-print(f"if statements 2020: {val}")
+setups["datetime-add"] ="""
+from datetime import datetime, timedelta
 
-val=timeit.timeit("""leap_year(1900)""",
-"""
 def leap_year(year):
- return not year % 400 if not year % 100 else not year % 4
-
-""", number=loops) /loops
+ return (datetime(year, 2, 28) + timedelta(days=1)).day == 29
+"""
 
-print(f"ternary 1900: {val}")
+setups["calendar-isleap"] ="""
+from calendar import isleap
 
-val=timeit.timeit("""leap_year(2000)""",
-"""
 def leap_year(year):
- return not year % 400 if not year % 100 else not year % 4
+ return isleap(year)
+"""
 
-""", number=loops) /loops
 
-print(f"ternary 2000: {val}")
+# Conducting ghe timings
+fordescriptorinrow_headers:
+val=timeit.timeit("""leap_year(1900)""", setups[descriptor], number=loops) /loops
+year='1900'
+print(f"{descriptor}{year}: {val}")
+df.loc[descriptor, year] =val
 
-val=timeit.timeit("""leap_year(2019)""",
-"""
-def leap_year(year):
-return not year % 400 if not year % 100 else not year % 4
+val=timeit.timeit("""leap_year(2000)""",setups[descriptor], number=loops) /loops
+year='2000'
+print(f"{descriptor}{year}: {val}")
+df.loc[descriptor, year] =val
 
-""", number=loops) /loops
+val=timeit.timeit("""leap_year(2019)""", setups[descriptor], number=loops) /loops
+year='2019'
+print(f"{descriptor}{year}: {val}")
+df.loc[descriptor, year] =val
 
-print(f"ternary 2019: {val}")
+val=timeit.timeit("""leap_year(2020)""", setups[descriptor], number=loops) /loops
+year='2020'
+print(f"{descriptor}{year}: {val}")
+df.loc[descriptor, year] =val
 
-val=timeit.timeit("""leap_year(2020)""",
-"""
-def leap_year(year):
- return not year % 400 if not year % 100 else not year % 4
 
-""", number=loops) /loops
+# Settng up chart details and colors
+mpl.rcParams['axes.labelsize'] =18
+bar_colors= ["#AFAD6A", "#B1C9FD", "#CDC6FD",
+"#FABD19", "#3B76F2", "#7467D1",
+"#FA9A19", "#85832F", "#1A54CE","#4536B0"]
 
-print(f"ternary 2020: {val}")
+my_cmap=ListedColormap(sns.color_palette(bar_colors, as_cmap=True))
 
-val=timeit.timeit("""leap_year(2019)""",
-"""
-import datetime
+# bar plot of actual run times
+ax=df.plot.bar(figsize=(10, 7),
+ylabel="time (s)",
+fontsize=14,
+width=0.8,
+rot=0,
+colormap=my_cmap)
 
-def leap_year(year):
- return (datetime.datetime(year, 2, 28) + 
- datetime.timedelta(days=1)).day == 29
+# Saving the graph for later use
+plt.savefig('../timeit_bar_plot.svg')
 
-""", number=loops) /loops
 
-print(f"datetime add 2019: {val}")
+# The next bit will be useful for `introduction.md`
+# pd.options.display.float_format = '{:,.2e}'.format
+print('\nDataframe in Markdown format:\n')
+print(df.to_markdown(floatfmt=".1e"))