On Monday, August 27, 2018, kirby urner <kirby.urner@gmail.com> wrote:

My flight plan for sharing Python this evening, adult audience, real time in cyberspace, includes going backstage to survey the Python for Developers view. 

That will mean optionally cloning the Github site that's mainly a Sphinx HTML document about how to participate in Python's evolution. 

https://github.com/python/devguide  (show how Sphinx works)

ReadTheDocs might be a helpful segue from Sphinx and the devguide.
https://github.com/rtfd/readthedocs-docker-images/blob/master/README.rst#usage

$ docker pull readthedocs/build:latest

(Building a PDF with Sphinx requires installing a lot of LaTeX packages)

https://github.com/yoloseem/awesome-sphinxdoc

cookiecutter-pypackage has a good Sphinx template that extends the one generated by sphinx-quickstart with e.g. how to include README.rst in the Sphinx docs and the package long_description in setup.py (with cool badges)
https://cookiecutter.readthedocs.io/en/latest/readme.html#available-cookiecutters

https://packaging.python.org
 

I don't plan on actually compiling Python tonight, but we'll be right where one needs to be to learn how.  Just looking at the issues tracker (first time) and PEPs (again) will inspire students with how well-oiled a machine is the Python "sausage making" factory.

In my estimation, a well-rounded knowledge of Python includes understanding how to make one's own decorators and context managers.  

The following categories of type should also be made clear:

* Mutable vs Immutable
* Callable vs not
* Collections: Sequences vs Mappings
* Iterator vs Iterable 
* Generator as Iterator
* Context Manager
* Descriptor

We recognize these types based on the assortment of "__ribs__" (special names) they contain e.g. callables have __call__, mutables support __setitem__, iterators have __next__, context managers __enter__ and __exit__, Descriptors __fget__, __fset__ and so on.  We're like bird watcher with binoculars, identifying species based on these tell-tale characteristics (APIs.

This is the most unified reference on __dunder_methods__ ('magic methods') I've ever seen:
"A Guide to Python's Magic Methods"
https://rszalski.github.io/magicmethods/
 

A grand synthesis involves using the @contextmanager decorator from contextlib to turn a generator into a context manager.  That's a high point (summit) in my curriculum.

The Descriptor concept works in tandem with decorator syntax to bring us the @property type.  I use a "magic circle" type for properties, meaning you can set radius or circumference or area of a Circle, and the other two attributes reset automatically.  I believe Raymond Hettinger uses the same approach.

ipywidgets (and IPython) are built atop traitlets (which are like properties with event handlers that are observable)
https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Events.html#Traitlet-events

> Widget properties are IPython traitlets and traitlets are eventful. To handle changes, the observe method of the widget can be used to register a callback. 
 

One of my most computer sciency types is the Permutation class, with many soft links to Group Theory.  My P class randomly generates a dict with [a-z] plus space (' ') mapped to the same set, keys to values in a different order.  I have voluminous writings on how one might use this class to explore elementary group theory on math-teach @ Math Forum, public archives, no longer open to new comments.


Kirby