From 50ccd6b6a91718035b51d9ebbabc0279d7636fad Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 18:22:05 -0300 Subject: [PATCH 1/6] Grammar fix: s/it's current/it's currently --- docs/starting/which-python.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index ab5d9b97e..3a39b6634 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -69,7 +69,7 @@ PyPy aims for maximum compatibility with the reference CPython implementation while improving performance. If you are looking to squeeze more performance out of your Python code, it's -worth giving PyPy a try. On a suite of benchmarks, it's current `over 5 times +worth giving PyPy a try. On a suite of benchmarks, it's currently `over 5 times faster than CPython `_. Currently PyPy supports Python 2.7. [#pypy_ver]_ From 8ed7588716d3a83b9799dff65d5feb2731922d78 Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 18:23:45 -0300 Subject: [PATCH 2/6] Grammar fixes --- docs/starting/which-python.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 3a39b6634..2486528df 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -90,11 +90,11 @@ Currently Jython supports up to Python 2.5. [#jython_ver]_ IronPython ---------- -`IronPython `_ is an implementation of Python for .NET +`IronPython `_ is an implementation of Python for the .NET framework. It can use both Python and .NET framework libraries, and can also expose Python code to other .NET languages. -`Python Tools for Visual Studio `_ integrate +`Python Tools for Visual Studio `_ integrates IronPython directly in to the Visual Studio development environment, making it an ideal choice for Windows developers. From 1fb50a3999f62dc84b6989588a56cd3becc9e76a Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 18:30:05 -0300 Subject: [PATCH 3/6] Made more direct and concise The guide is opinionated, and that's ok. --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 456fd43af..cd647633a 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -91,7 +91,7 @@ environment, or your project's internal modules. To keep in line with the style guide, keep module names short, lowercase, and be sure to avoid using special symbols like the dot (.) or question mark (?). -So a file name like `my.spam.py` is one you should try to avoid! Naming this way +So a file name like `my.spam.py` is one you should avoid! Naming this way will interfere with the way python looks for modules. In this example python expects to find a "spam.py" file in a folder named "my" From b9b50213bb84896f7f6300a3d50efaf3516294af Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 18:46:08 -0300 Subject: [PATCH 4/6] Quick grammar fix --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index cd647633a..001413948 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -281,7 +281,7 @@ Decorators ---------- The Python language provides a simple yet powerful syntax called 'decorators'. -A decorator is a function or a class that wraps (or decorate) a function +A decorator is a function or a class that wraps (or decorates) a function or a method. The 'decorated' function or method will replace the original 'undecorated' function or method. Because functions are first-class objects in Python, it can be done 'manually', but using the @decorator syntax is From bc7799d1fad0ddc241ee021bd738197b9646d724 Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 18:48:45 -0300 Subject: [PATCH 5/6] Separate join and list comprehension --- docs/writing/structure.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 001413948..af388bc79 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -445,7 +445,8 @@ with calls to append(). .. code-block:: python # create a concatenated string from 0 to 19 (e.g. "012..1819") - print "".join([str(n) for n in range(20)]) + nums = [str(n) for n in range(20)] + print "".join(nums) One final thing to mention about strings is that using join() is not always best. In the instances where you are creating a new string from a pre-determined From 810956c56b0266722433b935ca208f9bc4ce5847 Mon Sep 17 00:00:00 2001 From: Kyle Kelley Date: Mon, 18 Mar 2013 19:06:50 -0300 Subject: [PATCH 6/6] Grammar: plurality fixes, tense fix, typos --- docs/writing/style.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 285d8ca6c..dcfd145fe 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -10,8 +10,8 @@ recognised fact that code is read much more often than it is written. One reason for Python code to be easily read and understood is its relatively complete set of Code Style guidelines and "Pythonic" idioms. -Moreover, when a veteran Python developer (a Pythonista) point to some -parts of a code and say it is not "Pythonic", it usually means that these lines +Moreover, when a veteran Python developer (a Pythonista) points to portions of code +and says they are not "Pythonic", it usually means that these lines of code do not follow the common guidelines and fail to express the intent in what is considered the best (hear: most readable) way. @@ -89,7 +89,7 @@ Arguments can be passed to functions in four different ways. simplest form of arguments and they can be used for the few function arguments that are fully part of the functions meaning and their order is natural. For instance, in ``send(message, recipient)`` or ``point(x, y)`` the user of the -function has no difficulty to remember that those two function require two +function has no difficulty remembering that those two functions require two arguments, and in which order. In those two cases, it is possible to use argument names when calling the functions @@ -103,7 +103,7 @@ used for optional parameters sent to the function. When a function has more than two or three positional parameters, its signature will be more difficult to remember and using keyword argument with default values is helpful. For instance, a more complete ``send`` function could be defined as ``send(message, to, cc=None, bcc=None)``. -Here ``cc`` and ``bcc`` are optional, and evaluate to ``None`` when the are not +Here ``cc`` and ``bcc`` are optional, and evaluate to ``None`` when they are not passed another value. Calling a function with keyword arguments can be done in multiple ways in Python, @@ -189,18 +189,18 @@ As seen above, Python allows many tricks, and some of them are potentially dangerous. A good example is that any client code can override an object's properties and methods: there is no "private" keyword in Python. This philosophy, very different from highly defensive languages like Java, which -give a lot of mechanism to prevent any misuse, is expressed by the saying: "We +give a lot of mechanisms to prevent any misuse, is expressed by the saying: "We are consenting adults". This doesn't mean that, for example, no properties are considered private, and that no proper encapsulation is possible in Python. But, instead of relying on concrete walls erected by the developers between their code and other's, the -Python community prefers to rely on a set of convention indicating that these +Python community prefers to rely on a set of conventions indicating that these elements should not be accessed directly. The main convention for private properties and implementation details is to prefix all "internals" with an underscore. If the client code breaks this rule -and access to these marked elements, any misbehavior or problems encountered if +and accesses these marked elements, any misbehavior or problems encountered if the code is modified is the responsibility of the client code. Using this convention generously is encouraged: any method or property that is @@ -215,7 +215,7 @@ Returning values When a function grows in complexity is not uncommon to use multiple return statements inside the function's body. However, in order to keep a clear intent and a sustainable readability level, it is preferable to avoid returning meaningful values from many -output point in the body. +output points in the body. There are two main cases for returning values in a function: The result of the function return when it has been processed normally, and the error cases that indicate a wrong @@ -227,12 +227,12 @@ as None or False, indicating that the function could not perform correctly might case, it is better to return as early as the incorrect context has been detected. It will help to flatten the structure of the function: all the code after the return-because-of-error statement can assume the condition is met to further compute the function's main result. -Having multiple such return statement is often necessary. +Having multiple such return statements is often necessary. However, when a function has multiple main exit points for its normal course, it becomes difficult to debug the returned result, and it may be preferable to keep a single exit -point. This will also help factoring out some code paths, and the multiple exit point -is a probable indication that such a refactoring is needed. +point. This will also help factoring out some code paths, and the multiple exit points +are a probable indication that such a refactoring is needed. .. code-block:: python @@ -351,7 +351,7 @@ Take the following code for example:: return 's' in l Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in python are hashtables, the lookup performance between the two is very different. -Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary finding keys in the dict can be done very quickly. +Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary, finding keys in the dict can be done very quickly. For more information see this `StackOverflow `_ page. Zen of Python @@ -589,9 +589,9 @@ sometimes but is preferably avoided, because of its fragility: a white space added to the end of the line, after the backslash, will break the code and may have unexpected results. -A preferred solution is to use parenthesis around your elements. Left with an +A preferred solution is to use parentheses around your elements. Left with an unclosed parenthesis on an end-of-line the Python interpreter will join the -next line until the parenthesis is closed. The same behavior holds for curly +next line until the parentheses are closed. The same behavior holds for curly and square braces. **Bad**: