Prior to 3.7, re.escape escaped many characters that don't have
special meaning in Python, but that use to require escaping in other
tools and languages. This commit aims to make it clear which characters
were, but are no longer escaped.
Mention frame.f_trace in sys.settrace docs, as well as the fact you still
need to call `sys.settrace` to enable the tracing machinery before setting
`frame.f_trace` will have any effect.
* Add a note to the PyModule_AddObject docs.
* Correct example usages of PyModule_AddObject.
* Whitespace.
* Clean up wording.
* 📜🤖 Added by blurb_it.
* First code review.
* Add < 0 in the tests with PyModule_AddObject
* bpo-36260: Add pitfalls to zipfile module documentation
We saw vulnerability warning description (including zip bomb) in Doc/library/xml.rst file.
This gave us the idea of documentation improvement.
So, we moved a little bit forward :P
And the doc patch can be found (pr).
* fix trailing whitespace
* 📜🤖 Added by blurb_it.
* Reformat text for consistency.
This is a restructuring of the datetime documentation to hopefully make
them more user-friendly and approachable to new users without losing any
of the detail.
Changes include:
- Creating dedicated subsections for some concepts such as:
- "Constants"
- "Naive vs Aware"
- "Determining if an Object is Aware"
- Give 'naive vs aware' its own subsection
- Give 'constants' their own subsection
- Overhauling the strftime-strptime section by:
- Breaking it into logical, linkable, and digestable parts
- Adding a high-level comparison table
- Moving the technical detail to bottom: readers come to this
section primarily to remind themselves to things:
- How do I write the format code for X?
- strptime/strftime: which one is which again?
- Touching up fromisoformat + isoformat sections by:
- Revising fromisoformat + isoformat for date, time, and
datetime
- Adding basic examples
- Enforcing consistency about putting formats (i.e. ``HH:MM``)
in double backticks. This was previously done in some places
but not all
- Putting long 'supported formats', on their own line to improve
readability
- Moving the 'seealso' section to the top and add a link to dateutil
Rationale: This doesn't really belong nested under the
'constants' section. Let readers know right away that
datetime is one of several related tools.
- Moving common features of several types into one place:
Previously, each type went out of its way to note separately
that it was hashable and picklable. These can be brought
into one single place that is more prominent.
- Reducing some verbose explanations to improve readability
- Breaking up long paragraphs into digestable chunks
- Displaying longer "equivalent to" examples, as short code blocks
- Using the dot notation for datetime/time classes:
Use :class:`.time` and :class:`.datetime` rather than :class:`time` and
:class:`datetime`; otherwise, the generated links will route to the
respective modules, not classes.
- Rewording the tzinfo class description
The top paragraph should get straight to the point of telling the reader
what subclasses of tzinfo _do_. Previously, that was hidden in a later
paragraph.
- Adding a note on .today() versus .now()
- Rearranging and expanding example blocks, including:
- Moved long, multiline inline examples to standalone examples
- Simplified the example block for timedelta arithmetic:
- Broke the example into two logical sections:
1. normalization/parameter 'merging'
2. timedelta arithmetic
- Reduced the complexity of the some of the examples. Show
reasonable, real-world uses cases that are easy to follow
along with and progres in difficult slightly.
- Broke up the example sections for date and datetime sections by putting
the easy examples first, progressing to more esoteric situations and
breaking it up into logical sections based on what the methods are
doing at a high level.
- Simplified the KabulTz example:
- Put the class definition itself into a non-REPL block since there is
no interactive output involved there
- Briefly explained what's happening before launching into the code
- Broke the example section into visually separate chunks
- Various whitespace, formatting, style and grammar fixes including:
- Consistently using backctics for 'date_string' formats
- Consistently using one space after periods.
- Consistently using bold for vocab terms
- Consistently using italics when referring to params:
See https://devguide.python.org/documenting/#id4
- Using '::' to lead into code blocks
Per https://devguide.python.org/documenting/#source-code, this will
let the reader use the 'expand/collapse' top-right button for REPL
blocks to hide or show the prompt.
- Using consistent captialization schemes
- Removing use of the default role
- Put 'example' blocks in Markdown subsections
This is a combination of 66 commits.
See bpo-36960: https://bugs.python.org/issue36960
* Update documentation for plistlib
- Update "Mac OS X" to "Apple" since plists are used more widely than just macOS
- Re-add the UID class documentation (oops, removed in GH-15615)
* Rename PyThreadState_DeleteCurrent()
to _PyThreadState_DeleteCurrent()
* Move it to the internal C API
Co-Authored-By: Carol Willing <carolcode@willingconsulting.com>
Adds a link to `dateutil.parser.isoparse` in the documentation.
It would be nice to set up intersphinx for things like this, but I think we can leave that for a separate PR.
CC: @pitrou
[bpo-37979](https://bugs.python.org/issue37979)
https://bugs.python.org/issue37979
Automerge-Triggered-By: @pitrou
There are plenty of legitimate scripts in the tree that begin with a
`#!`, but also a few that seem to be marked executable by mistake.
Found them with this command -- it gets executable files known to Git,
filters to the ones that don't start with a `#!`, and then unmarks
them as executable:
$ git ls-files --stage \
| perl -lane 'print $F[3] if (!/^100644/)' \
| while read f; do
head -c2 "$f" | grep -qxF '#!' \
|| chmod a-x "$f"; \
done
Looking at the list by hand confirms that we didn't sweep up any
files that should have the executable bit after all. In particular
* The `.psd` files are images from Photoshop.
* The `.bat` files sure look like things that can be run.
But we have lots of other `.bat` files, and they don't have
this bit set, so it must not be needed for them.
Automerge-Triggered-By: @benjaminp
* bpo-37256: Wording in Request class docs
* 📜🤖 Added by blurb_it.
* Update Misc/NEWS.d/next/Documentation/2019-07-16-14-48-12.bpo-37256.qJTrBb.rst
Co-Authored-By: Kyle Stanley <aeros167@gmail.com>
Hi,
I've faced an issue w/ `mailbox.Maildir()`. The case is following:
1. I create a folder with `tempfile.TemporaryDirectory()`, so it's empty
2. I pass that folder path as an argument when instantiating `mailbox.Maildir()`
3. Then I receive an exception happening because "there's no such file or directory" (namely `cur`, `tmp` or `new`) during interaction with Maildir
**Expected result:** subdirs are created during `Maildir()` instance creation.
**Actual result:** subdirs are assumed as existing which leads to exceptions during use.
**Workaround:** remove the actual dir before passing the path to `Maildir()`. It will be created automatically with all subdirs needed.
**Fix:** This PR. Basically it adds creation of subdirs regardless of whether the base dir existed before.
https://bugs.python.org/issue30088
Fix importlib examples to insert any newly created modules via importlib.util.module_from_spec() immediately into sys.modules instead of after calling loader.exec_module().
Thanks to Benjamin Mintz for finding the bug.
https://bugs.python.org/issue37521
For datetime.datetime.strptime(), the leading zero for some two-digit formats is optional.
This adds a footnote to the strftime/strptime documentation to reflect this fact, and adds some tests to ensure that it is true.
bpo-34903
Removes more legacy distutils documentation, and more clearly
marks what is left as potentially outdated, with references to
setuptools as a replacement.
I have added documentation for `PyInterpreterState_Main()`.
I chose to place it under Advanced Debugger Support together with similar functions like `PyInterpreterState_Head()`, `PyInterpreterState_Next(`), and `PyInterpreterState_ThreadHead()` .
https://bugs.python.org/issue36157
* changes to html file -> added contributing to docs link at the end of the page
* revisions to the dealing with bugs page. added more links in the documentation bugs section
* 📜🤖 Added by blurb_it.
* Update Doc/bugs.rst
Updated Doc/bugs.rst in accordance with willingc and JulienPalard suggestions.
Co-Authored-By: suhearsawho <susansu.software@gmail.com>
Let .chm document display non-ASCII characters properly
Escape the `body` part of .chm source file to 7-bit ASCII, to fix visual effect on some MBCS Windows systems.
The documentation for CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED were
misleading and partly wrong. It fails to explain that OpenSSL behaves
differently in client and server mode. Also OpenSSL does validate the
cert chain everytime. With SSL_VERIFY_NONE a validation error is not
fatal in client mode and does not request a client cert in server mode.
Also discourage people from using CERT_OPTIONAL in client mode.
While locale coercion and UTF-8 mode turned out to
be complementary ideas rather than competing ones,
it isn't immediately obvious why it's useful to
have both, or how they interact at runtime.
This updates both the Python 3.7 What's New doc
and the PYTHONCOERCECLOCALE and PYTHONUTF8
documentation in an attempt to clarify that
relationship:
- in the respective What's New sections, add a closing paragraph
explaining which problem each one solves, and pointing to the
other PEP's section for the specific aspects it relies on the other
PEP to solve
- use "locale-aware mode" as a more descriptive term for the
default non-UTF-8 mode
- improve wording conistenccy between the PYTHONCOERCECLOCALE
and PYTHONUTF8 docs when they cover the same thing (mostly
related to legacy locale detection and setting the standard
stream error handler)
- improve the description of the locale coercion trigger conditions
(including pointing out that setting LC_ALL turns off locale coercion)
- port the full description of the UTF-8 mode behaviour changes
from PEP 540 into the PYTHONUTF8 documentation
- be explicit that PYTHONIOENCODING still overrides the settings
for the standard streams
- mention concrete examples of things that do and don't get their
text encoding assumptions adjusted by the two text encoding
assumption override techniques
Andrey Doroschenko
Marco Rougeth
Ricardo Bánffy
Ram Rachum
Ashwin Ramaswami
Brandt Bucher
JunWei Song
Brennan D Baraban
native-api
Brad
Nikhil
Jean-François B
Anthony Sottile
Jon Janzen
Joannah Nanjekye
Miro Hrončok
Daniel Pope
Paul Ganssle
Greg Price
Ngalim Siregar
sweeneyde
Raymond Hettinger
mental
Derek Keeler
Giovanni Cappellotto
Sviatoslav Sydorenko
Brett Cannon
Kyle Stanley
Terry Jan Reedy
Mike Gleen
Łukasz Langa
Christian Heimes
Matthias Bussonnier
Akshay Sharma
sbstp
Rémi Lapeyre
Cheryl Sabella
Jelle Zijlstra
Geoff Shannon
Toshio Kuratomi
Vinodhini Balusamy
Nick Coghlan
Edison A
Marcin Niemira
josh
Stéphane Wirtel
Jakub Molinski
Sebastian Rittau
Susan Su
zhsj
Andre Delfino
Yasser A
Lysandros Nikolaou
Eivind Teig
Chris Rands
Beomsoo Kim
Zhiming Wang
Julien Palard
Serhiy Storchaka
animalize
Yury Selivanov
Tim Hoffmann
Windson yang
wim glenn
Lew Kurtz
Dong-hee Na
Eric Snow