classification
Title: devguide: compiler - wording
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Elena.Oat, berker.peksag, eric.araujo, ezio.melotti, matrixise, nitika, numerodix, python-dev, terry.reedy, willingc
Priority: normal Keywords: patch

Created on 2013-10-20 12:28 by numerodix, last changed 2016-01-12 08:35 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
wording_compiler.diff numerodix, 2013-10-20 12:28
wording_compiler2.diff numerodix, 2013-10-20 12:31
wording_compiler3.diff numerodix, 2013-10-20 12:51
wording_compiler_oldpackage.diff numerodix, 2013-10-20 13:32
wording_compiler4.diff numerodix, 2013-10-20 13:46
wording_typo.diff numerodix, 2013-10-20 13:55
wording_compiler_oldpackage2.diff numerodix, 2013-10-20 14:02
issue19316.diff ezio.melotti, 2013-10-21 00:44
doc19316.patch nitika, 2014-03-18 19:35
issue19316.diff Elena.Oat, 2016-01-10 12:54
Messages (28)
msg200572 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 12:28
-  All code relating to the arena is in either Include/pyarena.h or Python/pyarena.c .

I propose: All code relating to the arena is either in Include/pyarena.h or in Python/pyarena.c .
msg200573 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 12:31
- This needs to only be called in strategic areas where the compiler exits.

I propose: This only needs to be called in strategic areas where the compiler exits.
msg200576 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 12:49
- The functions called to generate AST nodes from the parse tree all have the name ast_for_xx where xx is what the grammar rule that the function handles (alias_for_import_name is the exception to this). 

I'm not sure if this ought to be "where xx is the grammar rule that the function handles" or "where xx is the name of the grammar rule that the function handles".
msg200578 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 12:51
- Function and macros for creating and using asdl_seq * types as found in Python/asdl.c and Include/asdl.h:

I propose: The following are functions and macros for creating and using asdl_seq * types as found in Python/asdl.c and Include/asdl.h:
msg200579 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 13:12
- As for handling the line number on which a statement is defined, is handled by compiler_visit_stmt() and thus is not a worry.

I don't understand the final clause here. What is not a worry and why would it be a worry?

The grammar is awkward as well.
msg200580 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 13:32
- But you will also need to change the ‘compiler’ package. The key files to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .

"compiler" was removed in 2.6 or 2.7 iirc. I think it's safe to remove these two sentences.
msg200583 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 13:46
- If you wish to make changes that affect the output of bytecode without having to update the magic number each time (while testing your changes) you can just delete your old .py(c|o) files! Even though you will end up changing the magic number if you change the bytecode, while you are debugging your work you will be changing the bytecode output without constantly bumping up the magic number. This means you end up with stale .pyc files that will not be recreated. Running find . -name '*.py[co]' -exec rm -f {} ';' should delete all .pyc files you have, forcing new ones to be created and thus allow you test out your new bytecode properly.

I propose: 
Any time you make changes that affect the output of bytecode you will need to update the magic number as well, otherwise Python will reuse your old .pyc files and you will not be able to test your new bytecode properly. If you do not wish to constantly bump the magic number you can just delete the old .pyc files each time by running find . -name '*.py[co]' -exec rm -f {} ';'
msg200584 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 13:55
- marshaling

marshalling
msg200586 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 13:59
- import.c
- Home of the magic number (named MAGIC) for bytecode versioning


Probably out of date. I cannot find MAGIC being defined in this file.
msg200587 - (view) Author: Martin Matusiak (numerodix) * Date: 2013-10-20 14:02
- Lib/
- compiler/
- pyassem.py
- One of the files that must be modified if Include/opcode.h is changed.
- pycodegen.py
- One of the files that must be modified if Include/opcode.h is changed.

More mentions of the compiler package.
msg200676 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-21 00:44
Here is a single diff that combines all these patches and a few more things from #19315.
msg200686 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2013-10-21 02:35
> - import.c
> - Home of the magic number (named MAGIC) for bytecode versioning
>
> Probably out of date. I cannot find MAGIC being defined in this file.

It's in importlib._bootstrap:

http://hg.python.org/cpython/file/5dc65f8d29a2/Lib/importlib/_bootstrap.py#l379

Related changeset: http://hg.python.org/cpython/rev/efb5e6ab10f4/
msg201303 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-10-25 23:57
Proposes changes could have been put in one (or just a few) messages with numbered suggestions. This would make it easier to refer to them. Each could have had a link to the file involved in order to make it easy to look at context. My opinions: 

msg200572 disagree
msg200573 agree
msg200576 agree that one of the two is better
msg200578 disagree, I think, though I might change after seeing context 
msg200579 agree that sentence is bad; 'is' has no subject.
msg200580 compiler is present in 2.7, gone in 3.3, 3.4

msg200583 the original is awkward; the replacement is wrong in that it says 'you must do xyz' and then 'if you do not want to do xyz'. Perhaps something like
"When testing changes that affect bytecode output, remove old .pyc files. On unix, use "find . -name '*.py[co]' -exec rm -f {} ';'". When committing such a change, update the magic number."

For running the test suite, that just needs to be run in /lib of the version being tested.  Or now, just delete __pycache__ directories. The Windows equivalent should be given. Or give a python equivalent using shutil.

msg200584 both are 'correct' on Merriam-Webster and wiktionary sites. Firefox only likes the first. I would go with whichever is used most in our docs.

No comment on last two.
msg213995 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-18 17:55
Hi,
http://docs.python.org/devguide/compiler.html
Is this the link of the devguide that needs to be updated?
msg213996 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-18 17:58
Yes, it’s that file.  The source is compiler.rst in this repository: http://hg.python.org/devguide
msg213999 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-18 18:16
I am able to find some errors in the link i just gave in the previous message, so should i submit a patch highlighting those errors ?
msg214000 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-18 18:21
The task here is to work from Ezio’s patch* and edit it to take into account Terry’s replies and your own opinions about what wording is best.

* http://docs.python.org/devguide/faq.html#how-do-i-apply-a-patch
msg214009 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-18 19:35
-This document does not touch on how parsing works beyond what is needed to explain what is needed for compilation. It is also not exhaustive in terms of the how the entire system works. You will most likely need to read some source to have an exact understanding of all details.

+This document does not touch on how parsing works beyond what is needed to explain about the requirements of compilation. It is also not exhaustive in terms of how the entire system works. You will most likely be needed to read some source to have an exact understanding of all details.

I have also attached a patch with some corrections.Please review my patch.
msg215617 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-04-05 14:16
Hi,
I have attached the patch.Please review the patch attached.
msg216569 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-04-16 19:51
Hi,
anyone please review my patch attached.
msg216590 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-04-16 21:01
I will try to take a look, but anyone else is welcome to also.
msg247511 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-07-28 09:27
I've reviewed doc19316.patch. Unfortunately, the patch does not apply cleanly to the up-to-date codebase; it emits this error:

```
patching file compiler.rst
Hunk #1 succeeded at 41 with fuzz 2.
Hunk #3 succeeded at 175 (offset 6 lines).
patch: **** malformed patch at line 58: @@ -386,19 +386,12 @@
```

nikita, Thanks for the initial patch. Would you like to update it?
msg255153 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2015-11-23 13:16
Hi everybody,

Here is a new version of the script for the last version of the devguide.
198554fa82c2

Please review and apply.
msg257265 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-01 02:31
Stéphane, did you forget to attach the patch?
msg257909 - (view) Author: Elena Oat (Elena.Oat) * Date: 2016-01-10 12:54
Here's the patch regenerated for the latest devguide.
msg257931 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2016-01-10 20:16
maybe :/

I have reinstalled my laptop, will try to find the patch asap
msg258074 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-12 08:33
New changeset 43d842419188 by Ezio Melotti in branch 'default':
#19316: fix wording in the compiler.rst page.
https://hg.python.org/devguide/rev/43d842419188
msg258075 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-12 08:35
Fixed, thanks everyone for the patches and the reviews!
History
Date User Action Args
2016-01-12 08:35:26ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg258075

stage: needs patch -> resolved
2016-01-12 08:33:50python-devsetnosy: + python-dev
messages: + msg258074
2016-01-10 20:16:27matrixisesetmessages: + msg257931
2016-01-10 12:54:18Elena.Oatsetfiles: + issue19316.diff
nosy: + Elena.Oat
messages: + msg257909

2016-01-01 02:31:17ezio.melottisetmessages: + msg257265
2015-11-23 13:16:33matrixisesetnosy: + matrixise
messages: + msg255153
2015-07-28 09:27:55willingcsetnosy: + willingc

messages: + msg247511
stage: patch review -> needs patch
2014-04-16 21:01:46terry.reedysetmessages: + msg216590
2014-04-16 19:51:27nitikasetmessages: + msg216569
2014-04-05 14:16:39nitikasetmessages: + msg215617
2014-03-18 19:35:57nitikasetfiles: + doc19316.patch

messages: + msg214009
2014-03-18 18:21:11eric.araujosetmessages: + msg214000
2014-03-18 18:16:30nitikasetmessages: + msg213999
2014-03-18 17:58:34eric.araujosetnosy: + eric.araujo
messages: + msg213996
2014-03-18 17:55:45nitikasetnosy: + nitika
messages: + msg213995
2013-10-25 23:57:28terry.reedysetnosy: + terry.reedy
messages: + msg201303
2013-10-21 02:35:18berker.peksagsetnosy: + berker.peksag
messages: + msg200686
2013-10-21 00:45:11ezio.melottilinkissue19315 superseder
2013-10-21 00:44:30ezio.melottisetfiles: + issue19316.diff
messages: + msg200676

assignee: ezio.melotti
type: enhancement
stage: patch review
2013-10-20 14:02:23numerodixsetfiles: + wording_compiler_oldpackage2.diff

messages: + msg200587
2013-10-20 13:59:39numerodixsetmessages: + msg200586
2013-10-20 13:55:51numerodixsetfiles: + wording_typo.diff

messages: + msg200584
2013-10-20 13:46:21numerodixsetfiles: + wording_compiler4.diff

messages: + msg200583
2013-10-20 13:32:47numerodixsetfiles: + wording_compiler_oldpackage.diff

messages: + msg200580
2013-10-20 13:12:19numerodixsetmessages: + msg200579
2013-10-20 12:51:11numerodixsetfiles: + wording_compiler3.diff

messages: + msg200578
2013-10-20 12:49:00numerodixsetmessages: + msg200576
2013-10-20 12:31:35numerodixsetfiles: + wording_compiler2.diff

messages: + msg200573
2013-10-20 12:28:46numerodixcreate