Mailman 3 September 2021 - docs

A suggestion for improving the documentation of chapter 10.9. Data Compression
by Guy Goldner 22 May '24

22 May '24

Hello dear Python gods :) I'm new at Python and was going over the documentation . This useful paragraph : https://docs.python.org/3.7/tutorial/stdlib.html#data-compression provides info for compressing text but IMHO some important additional info is needed, without which I expect nearly all users would get stuck just as I have. Moreover, while looking for a solution I noticed a lot of articles with outdated examples which no longer work - this confused me even more to the point I started suspecting something was amiss on my end... Anyhow, adding this info would do the trick : zlib works only with bytes and in Python 3.x strings are no longer bytes. Example : *>>> zlib.compress('this is a sample string which does not work in zlib because it requires bytes and not unicode')Traceback (most recent call last): File "<stdin>", line 1, in <module>TypeError: a bytes-like object is required, not 'str'>>>* Luckily Python has a very simple solution for this : encode to utf-8, compress, decode back to unicode like so : *>>> text = 'this is a sample string which does not work in zlib because it requires bytes and not unicode with chars like this »שלום '>>> encoded = text.encode()>>> text = 'this is a sample with unicode chars »שלום '>>> encoded = text.encode()>>> compressed = zlib.compress(encoded)>>> decompressed = zlib.decompress(compressed)>>> decoded = decompressed.decode()>>> len(text),len(encoded),len(compressed) #notice that compression of short strings can be larger than the original(42, 47, 54)>>> print(text,'\n',encoded,'\n',compressed)this is a sample with unicode chars »שלום b'this is a sample with unicode chars \xc2\xbb\xd7\xa9\xd7\x9c\xd7\x95\xd7\x9d ' b'x\x9c+\xc9\xc8,V\x00\xa2D\x85\xe2\xc4\xdc\x82\x9cT\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xcc\xe4\xfc\x94T\x85\xe4\x8c\xc4\xa2b\x85C\xbb\xaf\xaf\xbc>\xe7\xfa\xd4\xebs\x15\x00\xb2K\x14|'>>> text == decodedTrue* Thank you ! You are doing a great thing ! B.R., Guy Goldner

2 2

SMTPHandler secure argument without credentials
by William Edwards 15 Sep '22

15 Sep '22

logging.handlers.SMTPHandler only uses the 'secure' argument when credentials are specified. https://docs.python.org/3/library/logging.handlers.html#logging.handlers.SM… says: "To specify the use of a secure protocol (TLS), pass in a tuple to the secure argument. This will only be used when authentication credentials are supplied." The docstring confirms this, but I can't find an explanation of the intent behind this behaviour. Perhaps it would be a good idea to describe this as well.

1 1

Bug in Python.
by Prakash Mudholkar 07 Feb '22

07 Feb '22

Hello - I wish to bring to your kind notice a bug in Python. Given any matrix X. While trying to compute the CoVariance matrix of that matrix X, Python does NOT compute the CoVarianceof the given matrix X. Instead, Python comptes the CoVariance of the Transpose of the given matrix X. This appears to be a bug in Python. Please refer to the below website for a given matrix and what the result should be after the computation of it's CoVariance. And I have provided a screenshot of what Python is returning. https://www.itl.nist.gov/div898/handbook/pmc/section5/pmc541.htm Please let me know if you have any questions. Regards, Prakash

3 2

Re: <documentation>In section 4.6. Defining Functions, It should be print(a,end==' ') in place of print(a, end=' ') (Ruchi Sharma)
by Twinkle Toes 26 Sep '21

26 Sep '21

Hi Rushi Sharma, The documentation is correct, it is print(a, end = ‘ ’). The syntax error is from your code. Regards, Lateefah. On Sun, 26 Sep 2021 at 5:35 PM, <docs-request(a)python.org> wrote: > Send docs mailing list submissions to > docs(a)python.org > > To subscribe or unsubscribe via the World Wide Web, visit > https://mail.python.org/mailman3/lists/docs.python.org/ > or, via email, send a message with subject or body 'help' to > docs-request(a)python.org > > You can reach the person managing the list at > docs-owner(a)python.org > > When replying, please edit your Subject line so it is more specific > than "Re: Contents of docs digest..."Today's Topics: > > 1. <documentation>In section 4.6. Defining Functions, It should be > print(a,end==' ') in place of print(a, end=' ') > (Ruchi Sharma) > 2. Re: <documentation>In section 4.6. Defining Functions, It should be > print(a,end==' ') in place of print(a, end=' ') > (Ruchi Sharma) > > > > ---------- Forwarded message ---------- > From: Ruchi Sharma <rohilla.ruchi(a)gmail.com> > To: docs(a)python.org > Cc: > Bcc: > Date: Sat, 25 Sep 2021 22:57:46 +0530 > Subject: [docs] <documentation>In section 4.6. Defining Functions, It > should be print(a,end==' ') in place of print(a, end=' ') > Hi Team, > > I am a beginner in python. I was going through the documentation for the > first time. > > This link: https://docs.python.org/3.8/tutorial/controlflow.html > In section 4.6. Defining Functions, It should be print(a,end==' '). "==" > in place of "=". > Please correct it. Let me correct if I am wrong. > > >>> def fib(n): # write Fibonacci series up to n ... """Print a Fibonacci > series up to n.""" ... a, b = 0, 1 ... while a < n: ... print(a, end=' ') ... > a, b = b, a+b ... print() ... >>> # Now call the function we just defined: ... > fib(2000) > > Regards, > Ruchi Sharma > > > > > ---------- Forwarded message ---------- > From: Ruchi Sharma <rohilla.ruchi(a)gmail.com> > To: docs(a)python.org > Cc: > Bcc: > Date: Sat, 25 Sep 2021 23:10:46 +0530 > Subject: [docs] Re: <documentation>In section 4.6. Defining Functions, It > should be print(a,end==' ') in place of print(a, end=' ') > In the reference to below email : > print(a, end=' ') > I am getting SyntaxError: invalid syntax after the above line code > Kindly help > > On Sat, 25 Sept 2021 at 22:57, Ruchi Sharma <rohilla.ruchi(a)gmail.com> > wrote: > >> Hi Team, >> >> I am a beginner in python. I was going through the documentation for the >> first time. >> >> This link: https://docs.python.org/3.8/tutorial/controlflow.html >> In section 4.6. Defining Functions, It should be print(a,end==' '). "==" >> in place of "=". >> Please correct it. Let me correct if I am wrong. >> >> >>> def fib(n): # write Fibonacci series up to n ... """Print a >> Fibonacci series up to n.""" ... a, b = 0, 1 ... while a < n: ... print(a, >> end=' ') ... a, b = b, a+b ... print() ... >>> # Now call the function >> we just defined: ... fib(2000) >> >> Regards, >> Ruchi Sharma >> >> _______________________________________________ > docs mailing list -- docs(a)python.org > To unsubscribe send an email to docs-leave(a)python.org > https://mail.python.org/mailman3/lists/docs.python.org/ >

1 0

<documentation>In section 4.6. Defining Functions, It should be print(a,end==' ') in place of print(a, end=' ')
by Ruchi Sharma 26 Sep '21

26 Sep '21

Hi Team, I am a beginner in python. I was going through the documentation for the first time. This link: https://docs.python.org/3.8/tutorial/controlflow.html In section 4.6. Defining Functions, It should be print(a,end==' '). "==" in place of "=". Please correct it. Let me correct if I am wrong. >>> def fib(n): # write Fibonacci series up to n ... """Print a Fibonacci series up to n.""" ... a, b = 0, 1 ... while a < n: ... print(a, end=' ') ... a, b = b, a+b ... print() ... >>> # Now call the function we just defined: ... fib(2000) Regards, Ruchi Sharma

2 2

RFC: New/update the Docs Sphinx theme: responsive, edit page links,
by Wes Turner 22 Sep '21

22 Sep '21

Where would be the best place to discuss or just improve the CPython docs sphinx theme? What would Python need in a {PyData,} Sphinx theme fork: - [ ] ENH: add <edit on github> links to every docs page - [ ] ENH: responsive breakpoints for mobile devices - [ ] ENH: responsive fonts - [ ] ENH: toggle-able dark theme - [ ] ENH: interactive code examples (in WASM with pyodide like JupyterLite) - [ ] ENH?: Two sidebars: {Global TOC} {Content} {Document TOC} The PyData theme [bandwagon, feature justification, maintenance burden justification] Src: https://github.com/pydata/pydata-sphinx-theme Docs: https://pydata-sphinx-theme.readthedocs.io/en/latest/ ```quote Other sites that are using this theme: - Pandas: https://pandas.pydata.org/docs/ - NumPy: https://numpy.org/doc/stable/ - SciPy: https://scipy.github.io/devdocs/ - NetworkX: https://networkx.org/documentation/latest/ - Bokeh: https://docs.bokeh.org/en/latest/ - JupyterHub and Binder: https://docs.mybinder.org/, http://z2jh.jupyter.org/en/latest/, https://repo2docker.readthedocs.io/en/latest/, https://jupyterhub-team-compass.readthedocs.io/en/latest/ - Jupyter Book beta version uses an extension of this theme: https://beta.jupyterbook.org - Fairlearn: https://fairlearn.org/main/about/ ``` The sphinx-book-theme theme (Jupyter Book theme) has a few possibly necessary features for the {CPython, Devguide, *} docs: https://github.com/executablebooks/sphinx-book-theme https://sphinx-book-theme.readthedocs.io/en/latest/ :: ```quote A Sphinx theme with a clean design, support for interactive content, and a modern book-like look and feel. Flexible content layout: Inspired by beautiful online books, such as the Edward Tufte CSS guide Visual classes designed for Jupyter Notebooks: Cell inputs, outputs, and interactive functionality are all supported. Launch buttons for online interactivity: For pages that are built with computational material, connect your site to an online BinderHub for interactive content. Bootstrap 4: To style visual elements and add functionality. International: All text integrated in the theme is translated to the specified Sphinx language. ``` https://github.com/python/cpython/blob/main/Doc/conf.py#L68 : ```python html_theme = 'python_docs_theme' ``` https://github.com/python/cpython/blob/main/Doc/requirements.txt#L12 ``` # The theme used by the documentation is stored separately, so we need # to install that as well. python-docs-theme ``` Pypi: https://pypi.org/project/python-docs-theme/ Src: https://github.com/python/python-docs-theme/ What are some better ways to add {Source RST, Source, Edit, History, and Annotate} links to every sphinx doc page than sphinxcontrib-srclinks? https://github.com/westurner/sphinxcontrib-srclinks#usage - sphinxcontrib-srclinks: Source RST, Source, Edit, History, and Annotate, Clone URL - [ ] copy clone URL to clipboard button - pydata-theme: 'Edit this page' on the document TOC sidebar - sphinx-book-theme: {gh, bb, gl} icon > 'Suggest edit' - [ ] ENH: add collapsible sidebar to whatever is chosen as a suitable replacement for the current non-responsive theme

1 0

Re: Typo in contextvars.Token.old_value (Eric Irrgang)
by Twinkle Toes 21 Sep '21

21 Sep '21

Hello all, Has anyone fixed it yet? Regards. On Tue, 14 Sep 2021 at 5:00 PM, <docs-request(a)python.org> wrote: > Send docs mailing list submissions to > docs(a)python.org > > To subscribe or unsubscribe via the World Wide Web, visit > https://mail.python.org/mailman3/lists/docs.python.org/ > or, via email, send a message with subject or body 'help' to > docs-request(a)python.org > > You can reach the person managing the list at > docs-owner(a)python.org > > When replying, please edit your Subject line so it is more specific > than "Re: Contents of docs digest..."Today's Topics: > > 1. Typo in contextvars.Token.old_value (Eric Irrgang) > > > > ---------- Forwarded message ---------- > From: Eric Irrgang <ericirrgang(a)gmail.com> > To: docs(a)python.org > Cc: > Bcc: > Date: Thu, 9 Sep 2021 16:57:52 +0300 > Subject: [docs] Typo in contextvars.Token.old_value > For > https://docs.python.org/3.7/library/contextvars.html#contextvars.contextvar… > and newer, an "is" should be "if". > > Token.old_value says "It points to Token.MISSING is the variable..." > instead of "It points to Token.MISSING if the variable..." > > (Per https://docs.python.org/3/bugs.html#documentation-bugs, I am "short > on time") > Cheers._______________________________________________ > docs mailing list -- docs(a)python.org > To unsubscribe send an email to docs-leave(a)python.org > https://mail.python.org/mailman3/lists/docs.python.org/ >

1 0

Typo in contextvars.Token.old_value
by Eric Irrgang 09 Sep '21

09 Sep '21

For https://docs.python.org/3.7/library/contextvars.html#contextvars.contextvar… and newer, an "is" should be "if". Token.old_value says "It points to Token.MISSING is the variable..." instead of "It points to Token.MISSING if the variable..." (Per https://docs.python.org/3/bugs.html#documentation-bugs, I am "short on time") Cheers.

1 0

Thank you.
by Aaron Essilfie 06 Sep '21

06 Sep '21

Hi Python Foundation, I'm from Ghana and I chanced on this beautiful pdf from your foundation on the Internet and I want to say thank you. I'm a beginner and I'm glad to have this material. Thank you so much. I want to use python in automation and chemical engineering so it's a great start for me. Thank you. Regards Aaron

1 0

Epub version
by trimder＠protonmail.com 05 Sep '21

05 Sep '21

The epub version of docs is too big and therefore slow to use comfortably with the average e-reader. Maybe it would be better to split up the documentation into separate parts instead of combining it all together.

1 0