Skip to content

Improve read me #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Improve read me #24

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1ac5c00
Improved README.rst to be more welcome to new visitors.
Mar 13, 2017
494de3c
Further improved README.rst with additional links.
Mar 14, 2017
c1bb558
Updated Hyperlinks.
Mar 14, 2017
efc5a18
Fixed hyperlinks.
clozinski Mar 14, 2017
3c4e2cf
Now I fixed hyperlinks.
clozinski Mar 14, 2017
7b652ad
Finally fixed hyperlinks.
clozinski Mar 14, 2017
99347ef
Fixed One More Link.
clozinski Mar 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 40 additions & 3 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,44 @@
Byterun
-------

This is a pure-Python implementation of a Python bytecode execution virtual
machine. I started it to get a better understanding of bytecodes so I could
fix branch coverage bugs in coverage.py.


Byterun is a python interpreter written in just 1451 lines of Python.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the original phrasing around "interpreter" vs "bytecode execution vm" was more clear. While this is technically correct more people will assume this means it is a complete interpreter for Python like PyPy or Jython which is not true and not a goal of this project.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably avoid giving a concrete line count in the README, it will just become out of date if we make changes later.

Byterun's goal is to clearly explain Python's design.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Byterun is more targeted at the CPython bytecode scheme than Python as a language.

If you want to better understand Python, or you are not quite sure how something in cPYthon works, then Byterun is a great place to start.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CPython is spelled with a capital C and P.

Byterun has proven very useful to a number of different projects, `including one by Google <https://github.com/nedbat/byterun/pull/12>`_.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this may promote the wrong mindset about Byterun. Byterun is a great teaching and learning tool but is not great for actually executing CPython bytecode because performance is not a key concern.


By interpreter we mean a code execution virtual
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This confusion would probably be avoided by keeping the original wording as I commented above.

machine. The Python compiler converts python source code into Python bytecode. The code execution virtual machine then executes that bytecode.

There are a number of python virtual machines. Most Python developers use cPython. cPython includes a virtual machine written in C. Yes it runs Python very fast, but it is a large code base, and difficult to understand. Much better to start by studying Byterun. Then you can move onto cPython.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems strange to compare Byterun and CPython in this way. CPython aims to be a production interpreter for Python while Byterun aims to be a tool used to debug a subset of CPython execution.


If you are interested in Byterun, the first step is to read the
excellent introductory article on Byterun written by Alison
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are two ls in Allison Kaptur's name.

I am very sensitive to properly counting l characters.

Kaptur. `A Python Interpreter written in Python <http://www.aosabook.org/en/500L/a-python-interpreter-written-in-python.html>`_

If you are not sure what a stack machine is, you might even start
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to write a small explanation of a stack machine in our own docs. I find that with CS concepts on wikipedia it can be hard to tease apart abstract concepts and things that are particular to some runtime/language that the author knows.

with `the Wikipedia article on stack machines. <https://en.wikipedia.org/wiki/Stack_machine>`_

After understanding Alison's Byterun article, you should be able to make sense of
`the source code for this repository </byterun>`_
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to self-link in the README. If you are reading it you either have the code or are at a place that has the code.

And from there you can move onto studying cPython, or PyPy, or Jython.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

byterun will not be much help for PyPy or Jython. Those projects to not use CPython's bytecode.


In the process, you
will certainly need to refer to `the list of Python bytecodes <https://docs.python.org/2.4/lib/bytecodes.html>`_
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to move this to an appendix in documentation outside of the README. As a note, I would use the same version here as the execution model docs. Also 2.4 is very out of date and may not actually work with byterun. You should probably use 2.7.


And as you get deeper into the code, you will need to refer to the `Python Execution Model <https://docs.python.org/3/reference/executionmodel.html>`_

We invite you to join this community. What do you want to do with Byterun? Do you have any questions?


History
-------

`Ned Batchelder <https://nedbatchelder.com/>`_,
`started Byterun <https://nedbatchelder.com/blog/201301/byterun_and_making_cells.html>`_ so that he could get a better understanding of bytecodes so that he could fix branch coverage bugs in `coverage.py <https://github.com/nedbat/coveragepy>`_.

Byterun is based on pyvm2 written by Paul Swartz (z3p).