[Python-Dev] Re: In what tense should the changelog be written?

[Wes Turner]

On Fri, Apr 30, 2021, 16:28  wrote:

> This was also my understanding. The last time I looked at writing good
> commit messages (a similar form), the standard was to finish the sentence:
> "This commit will...", e.g. "This commit will fix buffalo.spam" from "Fix
> buffalo.spam".
>

I like this a lot.

This commit/PR will ___.


Is it the objective or what is actually done?

There could be a recommended set of "codelabels" for which there are also
gh issue/pr labels.

Where in the devguide should this be summarized?
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/R3IFKCBT5ZVWGOURGKCYKDGRE2ZBVDPM/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Greg Ewing]

On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano > wrote:


Without a subject of the sentence, that's not present tense, it is the
imperative mood.


     "Fix buffalo.spam ..."

is a command or suggestion.


While it could be read that way, I don't think that's the intention.

I'm not sure it fits any of the usual grammatical categories. It
might be best understood as an abbreviated infinitive, i.e. there's
an implied "The purpose of this commit is to..." in front of it.

--
Greg

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/LWB7RV67BIYZILBYDPNZC7INS2RFMMM4/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Victor Stinner]

By the way, https://docs.python.org/dev/whatsnew/3.10.html#improved-modules
is inconsistent:

"asyncio: Added missing ..."

versus

"base64: Add base64.b32hexencode() ..."

You can also find such inconsistencies in "versionchanged" markups.

Victor

On Fri, Apr 30, 2021 at 5:01 AM Larry Hastings  wrote:
>
>
> When one writes one's "blurb" for the changelog, in what tense should it be?  
> I mostly see entries in present tense:
>
> bpo-43660: Fix crash that happens when replacing sys.stderr with a callable 
> that can remove the object while an exception is being printed. Patch by 
> Pablo Galindo.
>
> bpo-41561: Add workaround for Ubuntu’s custom OpenSSL security level policy.
>
> But occasionally I see entries in past tense:
>
> bpo-26053: Fixed bug where the pdb interactive run command echoed the args 
> from the shell command line, even if those have been overridden at the pdb 
> prompt.
>
> bpo-40630: Added tracemalloc.reset_peak() to set the peak size of traced 
> memory blocks to the current size, to measure the peak of specific pieces of 
> code.
>
> I couldn't find any guidance in the Python Dev Guide after sixty seconds of 
> poking around.
>
>
> Obviously this isn't a big deal.  But it might be nice to try and nudge 
> everybody in the same direction.  It'd be pleasant if the changelog read in a 
> more unified voice, and using the same tense and sentence structure would 
> help towards that goal.
>
> If we arrived at a firm decision, maybe "blurb" et al could add a little text 
> suggesting the proper style.
>
>
> Cheers,
>
>
> /arry
>
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at 
> https://mail.python.org/archives/list/python-dev@python.org/message/SUEPLPRN2IY7EGC7XBLWWN2BOLM3GYMQ/
> Code of Conduct: http://python.org/psf/codeofconduct/



-- 
Night gathers, and now my watch begins. It shall not end until my death.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BG7AI3YKZ6S2NR5556ZJ6XY6N5NHZWFL/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[David Mertz]

A lot of times the present tense in changelogs and similar is the English
"historical present", also called "narrative present." When the verb comes
first, it is usually imperative, but these shade with context. E.g.

* Give class Froz a .bar() method
* Adding metaclass gives class Froz a .bar() method

I prefer this feeling of narrative present in commits or "what's new"
myself.




On Fri, Apr 30, 2021, 4:05 PM Guido van Rossum  wrote:

> Hm, I actually like the imperative. In a commit or news message it feels
> very natural to me. And in that context there is no confusion about whether
> we’re commanding anyone (maybe we’re commanding git? :-).
>
> But I am the ultimate intuitive writer — I never took a class in English
> grammar or writing style, I just pattern match based on what I have read
> elsewhere. I don’t even know the names for the tenses (I only use
> “imperative” because you did).
>
> On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano  wrote:
>
>> On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
>> >
>> >
>> > D'oh!  I have a second draft already.
>> >
>> >Your NEWS entry should be written in the /present tense,/ and should
>> >start with a verb:
>>
>> Without a subject of the sentence, that's not present tense, it is the
>> imperative mood.
>>
>>
>> "Fix buffalo.spam ..."
>>
>> is a command or suggestion. The imperative is suitable for a list of
>> things which should be done, a TODO list, not a list of things which
>> have already been done.
>>
>> https://grammar.collinsdictionary.com/easy-learning/the-imperative
>>
>> When it comes to "the" present tense, there are (at least?) four, and
>> one looks superficially like the imperative, but they need a subject:
>>
>>
>> # present simple tense
>> "Larry fixes buffalo.spam ..."
>>
>> # present continuous tense
>> "Larry is fixing buffalo.spam ..."
>>
>> # present perfect tense
>> "Larry has fixed buffalo.spam ..."
>>
>> # present perfect continuous tense
>> "Larry has been fixing buffalo.spam ..."
>>
>>
>>
>> https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense
>>
>>
>> One might get away with an implicit "I" in the present simple tense:
>>
>>
>> [I] fix buffalo.spam ...
>>
>>
>> and readers with a good understanding of English will probably be able
>> to infer the intention (tasks which have already been done, not tasks
>> still to be done) but those whose English skills are not as good will
>> probably struggle.
>>
>> ___
>> Python-Dev mailing list -- python-dev@python.org
>> To unsubscribe send an email to python-dev-le...@python.org
>> https://mail.python.org/mailman3/lists/python-dev.python.org/
>> Message archived at
>> https://mail.python.org/archives/list/python-dev@python.org/message/BEED5L4Y72YJF5Z3HG7VY55AF5T6NYWQ/
>> Code of Conduct: http://python.org/psf/codeofconduct/
>>
> --
> --Guido (mobile)
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/K4AKXIOXID5UWBJSXHAJZKIVUTRALHHJ/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/IWRVAFAMKZ26GWHBWNBPYF7C5FP2RDOV/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 654: Exception Groups and except* [REPOST]

[Jim J. Jewett]

Nathaniel Smith (in a conversation with Irit) wrote:

> ... suggested having each
> 'except Blah as exc' clause be executed once, receiving an
> ExceptionGroup containing all the Blah exceptions. Guido pointed out
> that this broke typing -- 'exc' would not longer have type 'Blah' --
> and I was like... okay yeah that's a fatal flaw, never mind.

The fact that "Blah as exc" could return either a single Blah or a collection 
of Blahs would be annoying, but not fatal -- that seems well within the level 
of ambiguity typing can deal with.  

> never seriously raised the 'execute a single clause multiple times'
> option, because of the issue where in the nested design, taking
> individual exceptions out of an ExceptionGroup breaks tracebacks.

This also seems like something that isn't hard to work around.  The obvious way 
would involve shared (parts of) tracebacks, but even that isn't required.

> multiple-except-executions option should be rejected because users
> have written code like 'except SomeError: ...' with the expectation
> that the 'except' clause would run exactly once.

That is indeed a problem, because some error handlers would do bad things if 
rerun.

> The problem is, *all* our options for how 'except' should interact
> with ExceptionGroups will somehow break previous expectations.

agreed.

> Concretely: imagine you have a pre-existing 'except SomeError', and
> some new code inside the 'try' block raises some number of
> 'SomeError's wrapped in an ExceptionGroup. There are three options:
> - Execute the 'except' block multiple times. This breaks the
> expectation that it should be executed at most once.

Do we know how bad this really is?  A second rollback or cancel or 
endConnection won't do what is expected, but they normally won't do much harm 
either.  A second logError does the right thing.

> - Execute the 'except' block exactly once. But if there are multiple
> SomeError's, this require they be grouped and delivered as a single
> exception, which breaks typing.

I'm not worried about typing, but I am worried about silently dropping all but 
the "first" SomeError.  

On the other hand, in practice were they all (including the "first") dropped 
before, in favor of some sort of superseding asyncCancelledError?

> - Execute the 'except' block zero times. This is what the current PEP
> chooses, and breaks the expectation that 'except SomeError' should
> catch 'SomeError'.

To me, this seems the worst of the three options, but ... maybe it is 
effectively the status quo often enough that it becomes the least bad?

> > I'm confused about the flattening suggestion - above you talk about "flat 
> > EG", but below about tracebacks. It's not clear to me whether you want EG 
> > to be flat (ie no nesting of EGs) or just the traceback to be flat (but you 
> > can still have a nested EG).
> > Hmm, I was thinking about making both of them flat, so no nested EGs.
> In all my designs, the only reason I ever had nesting was because I
> couldn't figure out any other way to make the tracebacks work. Do you
> have some other motivation for wanting nesting? If so that would be
> interesting, because it might point to why we're talking past each
> other and help us understand the problem better...

When I view this as strictly a typing problem, it matters which exceptions got 
joined at which junction; the shape of the tree is part of the type.

When I view this as a production support programmer, I really don't care about 
that ... I only care what triggered each SomeException so that I can account 
for all the bad data instead of just one piece.  Having to dig through multiple 
layers of grouping to get to each original SomeException separately is just an 
annoyance that *will* cause juniors to sometimes miss part of the bad data.  
("Open the door and check for problems" is a lot easier to learn and remember 
than a recursive "Open the door and check for problems or other doors, and then 
repeat on each door you find.")

-jJ
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/VO5I7DMRYAB7EPUYSYEHHQFLGZAYWUB4/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[nchristopherfox]

This was also my understanding. The last time I looked at writing good commit 
messages (a similar form), the standard was to finish the sentence: "This 
commit will...", e.g. "This commit will fix buffalo.spam" from "Fix 
buffalo.spam".
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/QX22GIKH7AFA767E7F462LAL2XVAWFRG/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Guido van Rossum]

Hm, I actually like the imperative. In a commit or news message it feels
very natural to me. And in that context there is no confusion about whether
we’re commanding anyone (maybe we’re commanding git? :-).

But I am the ultimate intuitive writer — I never took a class in English
grammar or writing style, I just pattern match based on what I have read
elsewhere. I don’t even know the names for the tenses (I only use
“imperative” because you did).

On Fri, Apr 30, 2021 at 02:22 Steven D'Aprano  wrote:

> On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
> >
> >
> > D'oh!  I have a second draft already.
> >
> >Your NEWS entry should be written in the /present tense,/ and should
> >start with a verb:
>
> Without a subject of the sentence, that's not present tense, it is the
> imperative mood.
>
>
> "Fix buffalo.spam ..."
>
> is a command or suggestion. The imperative is suitable for a list of
> things which should be done, a TODO list, not a list of things which
> have already been done.
>
> https://grammar.collinsdictionary.com/easy-learning/the-imperative
>
> When it comes to "the" present tense, there are (at least?) four, and
> one looks superficially like the imperative, but they need a subject:
>
>
> # present simple tense
> "Larry fixes buffalo.spam ..."
>
> # present continuous tense
> "Larry is fixing buffalo.spam ..."
>
> # present perfect tense
> "Larry has fixed buffalo.spam ..."
>
> # present perfect continuous tense
> "Larry has been fixing buffalo.spam ..."
>
>
>
> https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense
>
>
> One might get away with an implicit "I" in the present simple tense:
>
>
> [I] fix buffalo.spam ...
>
>
> and readers with a good understanding of English will probably be able
> to infer the intention (tasks which have already been done, not tasks
> still to be done) but those whose English skills are not as good will
> probably struggle.
>
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/BEED5L4Y72YJF5Z3HG7VY55AF5T6NYWQ/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
-- 
--Guido (mobile)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/K4AKXIOXID5UWBJSXHAJZKIVUTRALHHJ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Summary of Python tracker Issues

[Python tracker]

ACTIVITY SUMMARY (2021-04-23 - 2021-04-30)
Python tracker at https://bugs.python.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open7453 (-21)
  closed 48273 (+86)
  total  55726 (+65)

Open issues with patches: 2968 


Issues opened (48)
==

#42737: PEP 563: drop annotations for complex assign targets
https://bugs.python.org/issue42737  reopened by BTaskaya

#43926: Clean metadata (importlib_metadata 4.0)
https://bugs.python.org/issue43926  opened by jaraco

#43927: Remove IOError references from the tutorial
https://bugs.python.org/issue43927  opened by hugetim

#43928: Fix the typo in documentation
https://bugs.python.org/issue43928  opened by jeffreytse

#43930: Update bundled pip to 21.1 and setuptools to 56.0.0
https://bugs.python.org/issue43930  opened by sbidoul

#43931: Add the Python version to the API data.
https://bugs.python.org/issue43931  opened by Gabriele Tornetta

#43935: Fix typo in Turtle.back docstring
https://bugs.python.org/issue43935  opened by tarjeiba

#43936: os.path.realpath() normalizes paths before resolving links on 
https://bugs.python.org/issue43936  opened by barneygale

#43937: Turtle uses the default root window
https://bugs.python.org/issue43937  opened by serhiy.storchaka

#43939: Deadlock in logging
https://bugs.python.org/issue43939  opened by DaRoee

#43941: Unit test failure in test_gdb only with -O0
https://bugs.python.org/issue43941  opened by larry

#43942: RawDescriptionHelpFormatter seems to be ignored for argument d
https://bugs.python.org/issue43942  opened by rrt

#43943: test_ssl fails in the macos CI
https://bugs.python.org/issue43943  opened by pablogsal

#43944: Processes in Python 3.9 exiting with code 1 when It's created 
https://bugs.python.org/issue43944  opened by Genarito

#43945: [Enum] standardize format() behavior
https://bugs.python.org/issue43945  opened by ethan.furman

#43946: unpickling a subclass of list fails when it implements its own
https://bugs.python.org/issue43946  opened by gregory.p.smith

#43948: sysconfig???s osx_framework_user puts headers in different loc
https://bugs.python.org/issue43948  opened by uranusjr

#43949: binascii.Error raised in smtplib when initial_response_ok=Fals
https://bugs.python.org/issue43949  opened by junpengruan

#43950: Include column offsets for bytecode instructions
https://bugs.python.org/issue43950  opened by pablogsal

#43952: Multiprocessing UNIX socket connection: client freeze if authk
https://bugs.python.org/issue43952  opened by anon01

#43953: InitVar should not be available on a @dataclass-decorated clas
https://bugs.python.org/issue43953  opened by superbobry

#43956: C-API: Incorrect default value for Py_SetProgramName
https://bugs.python.org/issue43956  opened by joukewitteveen

#43957: [Enum] update __contains__ to return True for valid values
https://bugs.python.org/issue43957  opened by ethan.furman

#43962: test_interpreters: when TestInterpreterAttrs.test_id_type() is
https://bugs.python.org/issue43962  opened by vstinner

#43964: ctypes CDLL search path issue on MacOS
https://bugs.python.org/issue43964  opened by Victor.Lazzarini

#43965: dataclasses.replace breaks when __init__ is overrriden in subc
https://bugs.python.org/issue43965  opened by SebastianSpeitel

#43967: Valgrind memcheck on Py_Initialize
https://bugs.python.org/issue43967  opened by simonaldrich

#43968: os.path.realpath() unexpected breaking change: resolves subst'
https://bugs.python.org/issue43968  opened by sfmc

#43969: "bad magic number" when Python 2's pyc file exists without py 
https://bugs.python.org/issue43969  opened by mitchhentges

#43971: documentation: no spacing around default args in annotated fun
https://bugs.python.org/issue43971  opened by moselhy

#43972: Simple HTTP Request Handler in http.server does not set a cont
https://bugs.python.org/issue43972  opened by sirosen

#43974: setup.py should set Py_BUILD_CORE_MODULE as defined macro
https://bugs.python.org/issue43974  opened by christian.heimes

#43975: Incorrect MIME type returned for .js files Windows 10.
https://bugs.python.org/issue43975  opened by smeans

#43976: Introduce mechanism to allow Python distributors to add custom
https://bugs.python.org/issue43976  opened by FFY00

#43977: Implement the latest semantics for PEP 634 for matching collec
https://bugs.python.org/issue43977  opened by Mark.Shannon

#43978: Incorrect "versionadded" info in typing.NoReturn documentation
https://bugs.python.org/issue43978  opened by Mariatta

#43979: Simplify urllib.parse_qsl
https://bugs.python.org/issue43979  opened by cito

#43980: netrc module looks for .netrc even on Windows where the conven
https://bugs.python.org/issue43980  opened by jheiselman

#43981: test_idle is leaking references
https://bugs.python.org/issue43981  opened by pablogsal

#43982: Code coverage on the CI: validate codecov shell script checksu

[Python-Dev] Re: In what tense should the changelog be written?

[Barry Warsaw]

On Apr 30, 2021, at 04:11, Antoine Pitrou  wrote:
> 
> On Thu, 29 Apr 2021 21:52:14 -0700
> Larry Hastings  wrote:
>> D'oh!  I have a second draft already.
>> 
>>Your NEWS entry should be written in the /present tense,/ and should
>>start with a verb:
>> 
>>  * Add foo [...]
>>  * Change bar [...]
>>  * Remove bat [...]
>>  * Fix buffalo.spam [...]
>> 
>>Function and class names should not be followed by parentheses,
>>unless demonstrating an example call.
>> 
>> 
>> Slapping my forehead,
> 
> You probably mean "Slap my forehead”.

Actually, he probably meant “Slappa da bayss”.

-Barry

P.S. I was going to say that I prefer past tense when writing news items, but 
then I looked at the change log files for some of my personal projects and I 
came to the shocking realization that I actually don’t!  Looks like the FLUFL 
prefers present tense.

I do however like to use parentheses for functions and methods.

-Barry





signature.asc
Description: Message signed with OpenPGP
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/2AJW22GLM2YXCCAZBMARGU3UI4MFWV4Y/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: SC feedback: PEP 648 -- Extensible customizations of the interpreter at startup

[Mario Corchero]

Hello All,

I've pushed a change to rework a bit the pep wording and add further
details on its working. It needed indeed some extra work. PR still in
flight: https://github.com/python/peps/pull/1941
I've also changed it to target 3.11. I believe most of your concerns should
be answered in the PEP now, but I will answer them here as well.

Let me know if there is any additional question or any section you think
can benefit from additional work.

> Thank you for your submission of PEP 648

Thank you for reviewing and considering it :).

> We would like to eventually go farther, including deprecation of pth
files entirely, but that is outside the scope of this PEP.

Agree on deprecating only code execution as Nick pointed out. This PEP
includes that in the Backward compatibility a mention to adding a warning
already to code execution in pth files.

> The introduction of the section titled “Benefits of __sitecustomize__”
seems out of place.

Agree, I've restructured it to make things (IMHO) clearer. Happy to apply
further changes if you think it is still confusing.

> Some of the terminology used in the PEP could be clarified.

Changes applied.

> Another ambiguity is what the PEP means by “executing” said “scripts”.

Read + exec. It used to be import but there seemed to be a general
preference on read+exec on the discourse thread. (Info now included in the
PEP).

> The “Backward compatibility” section has this incomplete sentence

Fixed

> There’s this odd grammar in the “Do nothing” section

Thanks for pointing it out, updated with your suggestion. Please let me
know if you see anything else like that, I'm not an English native speaker.

> Definition of “site path”

Clarified in the PEP. I'm purposely leaving site-path definition to the
`site` module rather than saying something too concrete. Hopefully the
updates make it clearer now.

> Order of Execution

I've added a section for this. The work plans to piggyback on the discovery
of `pth` files.

> How do pth file sys.path extensions affect the search for
__sitecustomize__ directories?

They should not, I've added a section to the PEP to explain it.

> Impact on startup time

I've added a more detailed benchmark that can be reproduced.

> How does this feature interact with virtual environments?

Outstanding question, I've added a section for it.

> Why not explicitly deprecate these

+1. I was trying to be not too ambitious here.

> Do you have any concerns that this feature will be overused?

I could see some more people starting to use it, but I think it is a niche
case. I expect system administrators and packaging tools (like venv) to use
it (and with a better experience).

> Will the runtime have any access to the list of __sitecustomize__ modules
being executed?  I.e. will you collect their paths in a new sys module
attribute?

Nope, the PEP explains how to find them programmatically though and for
users we expect to add a CLI option to site to list them.

> We think io.open_code() should be used so that reading the files can be
audited.

Sure thing!

> We think io.open_code() should be used so that reading the files can be
audited.

I've added a section focused on security. Not sure if you were looking for
anything further in terms of security analysis.

Regards,
Mario

On Fri, 2 Apr 2021 at 17:22, Nick Coghlan  wrote:

> On Wed, 31 Mar 2021 at 11:01, Barry Warsaw  wrote:
> >
> > Kind of :)
> >
> > PEP 648 would definitely allow us to deprecate the executable part of
> pth files.  I let my own biases leak in to my response because I would like
> to find a way to replace the sys.path feature of pth with something much
> more auditable and discoverable.  To me that means deprecating pth files
> and finding something better, but maybe not.
>
> Adding pth file auditing to the output of "python -m site" should be
> entirely feasible, it just hasn't been done yet.
>
> Even if it just listed the files found, it would make them easier to
> audit than they are today.
>
> Declaring the feature impossible to audit when we haven't even really
> tried to make it auditable seems premature (the existing site output
> doesn't even indicate which paths in sys.path will be considered when
> looking for pth files, let alone indicate which of those directories
> actually contain any).
>
> Cheers,
> Nick.
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/775VQR46ESG435OYHCRRE4B4MGMCEPPT/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Larry Hastings]

On 4/30/21 4:51 AM, Victor Stinner wrote:

On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings  wrote:

Function and class names should not be followed by parentheses, unless 
demonstrating an example call.

Oh, I love putting parentheses when mentionning a function: "foo() now
does thigs new thing". Also, I like to use :func:`foo` Sphinx markup
to add a link in the changelog, and Sphinx adds parentheses for me
*but* I don't add parentheses :-)


I do too, and I definitely do that when I write emails, .txt files, and 
so on.  But--as you point out--Sphinx adds them for you.  NEWS blurbs 
should be written in CPython-docs-compatible ReST, and that includes 
using :func:`foo` to refer to a function called foo.  Sphinx will turn 
this into a hyperlink to the definition of foo in the docs if it knows 
where it is; :func:`inspect.signature` and :func:`getattr` both work great.


I'm still not sure what markup (if any) to use for Git checkins. On 
Github I know to use Markdown, and they provide a Markdown edit box.  
But should I use Markdown when I use "git commit" at the command-line?  
And why am I bringing this up now?  Surely this will only serve to 
fragment the conversation and confuse the larger issue.



Cheers,


//arry/

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/EPTB5KK6NXKHGHVB4HXAGBWTIKNBCJML/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Steven D'Aprano]

On Thu, Apr 29, 2021 at 09:52:14PM -0700, Larry Hastings wrote:
> 
> 
> D'oh!  I have a second draft already.
> 
>Your NEWS entry should be written in the /present tense,/ and should
>start with a verb:

Without a subject of the sentence, that's not present tense, it is the 
imperative mood.


"Fix buffalo.spam ..."

is a command or suggestion. The imperative is suitable for a list of 
things which should be done, a TODO list, not a list of things which 
have already been done.

https://grammar.collinsdictionary.com/easy-learning/the-imperative

When it comes to "the" present tense, there are (at least?) four, and 
one looks superficially like the imperative, but they need a subject:


# present simple tense
"Larry fixes buffalo.spam ..."

# present continuous tense
"Larry is fixing buffalo.spam ..."

# present perfect tense
"Larry has fixed buffalo.spam ..."

# present perfect continuous tense
"Larry has been fixing buffalo.spam ..."


https://grammar.collinsdictionary.com/easy-learning/the-present-simple-tense


One might get away with an implicit "I" in the present simple tense:


[I] fix buffalo.spam ...


and readers with a good understanding of English will probably be able 
to infer the intention (tasks which have already been done, not tasks 
still to be done) but those whose English skills are not as good will 
probably struggle.

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BEED5L4Y72YJF5Z3HG7VY55AF5T6NYWQ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Victor Stinner]

On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings  wrote:
> Your NEWS entry should be written in the present tense, and should start with 
> a verb:
>
> Add foo [...]
> Change bar [...]
> Remove bat [...]
> Fix buffalo.spam [...]

You might suggest using "now" when describing a behavior change: "foo
now does this new thing [...]"

> Function and class names should not be followed by parentheses, unless 
> demonstrating an example call.

Oh, I love putting parentheses when mentionning a function: "foo() now
does thigs new thing". Also, I like to use :func:`foo` Sphinx markup
to add a link in the changelog, and Sphinx adds parentheses for me
*but* I don't add parentheses :-)

By the way, I recently discovered that :data:, :func:, :option:, etc.
accept references written as . Examples:

* :option:`-X utf8 <-X>`
* :data:`sys.flags.dev_mode `
* :c:func:`Py_TYPE(self) `
* :func:`map(f, iterA, iterB, ...) `

I like it! It's convenient to document a function call with
arguements, so the arguments can be named in the sentence (like "self"
in "Py_TYPE(self)").

Victor
-- 
Night gathers, and now my watch begins. It shall not end until my death.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/QO6IDVU2ZHPHSPJA7GLIFNEKDTGDPWMQ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Victor Stinner]

On Fri, Apr 30, 2021 at 6:22 AM Guido van Rossum  wrote:
> There’s something in the dev guide, but not about tense. Worth adding. (My 
> pet peeve is not to write “The foo module resets the bar state when spam 
> happens,” because that isn’t clear about whether that’s the before or after 
> behavior.)

In the past, different people told me that my phrasing was confusing
and suggested me to add "now". It kept this habbit:

"The foo module *now* resets the bar state when spam happens"

Victor
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/AWH3BEAHTNGLGYFSPB4EQRAYC7DTAPO5/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Antoine Pitrou]

On Thu, 29 Apr 2021 21:52:14 -0700
Larry Hastings  wrote:
> D'oh!  I have a second draft already.
> 
> Your NEWS entry should be written in the /present tense,/ and should
> start with a verb:
> 
>   * Add foo [...]
>   * Change bar [...]
>   * Remove bat [...]
>   * Fix buffalo.spam [...]
> 
> Function and class names should not be followed by parentheses,
> unless demonstrating an example call.
> 
> 
> Slapping my forehead,

You probably mean "Slap my forehead".

Regards

Antoine.


___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/R57FF2LB7FSC7FQVA5DYJNS6XRXWTGOW/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Oleg Broytman]

On Fri, Apr 30, 2021 at 09:43:44AM +0300, Serhiy Storchaka 
 wrote:
> 30.04.21 05:57, Larry Hastings пише:
> > When one writes one's "blurb" for the changelog, in what tense should it
> > be?
> 
> See the previous discussion on this topic:
> https://mail.python.org/archives/list/python-dev@python.org/thread/C342Y73LALVFLI2ACFB3SH6ZDT2YTGPC/
> .
> 
> I always use "fixed", "removed", "added" when describe changes following
> the rule formulated by Oleg Broytman:
> 
> > I use past tense to describe what I did on the code, and present
> > simple to describe what the new code does when running.

   Thanks, Serhiy, for reminding! I said this about git commit messages,
not NEWS items. And even for commit messages I changed my style to be
imperative.
   The widely known advice about git commit messages is: the subject
should be a continuation of "When applied this commit will..."
   So I now use "Implement a feature", "Fix a bug", "Update docs".

Oleg.
-- 
Oleg Broytmanhttps://phdru.name/p...@phdru.name
   Programmers don't die, they just GOSUB without RETURN.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/6BBFXPC6O6XBCYCN2ZBLHPF2NGR4UEGJ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: In what tense should the changelog be written?

[Serhiy Storchaka]

30.04.21 05:57, Larry Hastings пише:
> When one writes one's "blurb" for the changelog, in what tense should it
> be?

See the previous discussion on this topic:
https://mail.python.org/archives/list/python-dev@python.org/thread/C342Y73LALVFLI2ACFB3SH6ZDT2YTGPC/
.

I always use "fixed", "removed", "added" when describe changes following
the rule formulated by Oleg Broytman:

> I use past tense to describe what I did on the code, and present
> simple to describe what the new code does when running.

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/6SXYOA73FGFRP4HND6UM6SXGT23ZH7PS/
Code of Conduct: http://python.org/psf/codeofconduct/