diff --git a/docs/dev/env.rst b/docs/dev/env.rst index bdee11c..37673e4 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -149,7 +149,7 @@ PyCharm / IntelliJ IDEA known for IntelliJ IDEA. Both share the same code base and most of PyCharm's features can be brought to IntelliJ with the free `Python Plug-In `_. There are two versions of PyCharm: Professional Edition (Free 30-day trial) -and Community Edition(Apache 2.0 License) with less features. +and Community Edition(Apache 2.0 License) with fewer features. Eclipse @@ -210,7 +210,7 @@ offering sourcecode autocompletion, syntax highlighting, support for version control systems, python 3 support, integrated web browser, python shell, integrated debugger and a flexible plug-in system. Written in python, it is based on the Qt gui toolkit, integrating the Scintilla editor control. Eric -is an open-source software (GPLv3 licence) with more than ten years of active +is an open-source software project (GPLv3 licence) with more than ten years of active development. diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index b163a76..4b9c4dc 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -148,8 +148,8 @@ general :pep:`8` best practices. It has a detailed, multi-chapter case study on writing and releasing a package and eventually an application, including a chapter on using zc.buildout. Later -chapters detail best practices with writing documentation, test-driven -development, version control, and optimization/profiling. +chapters detail best practices such as writing documentation, test-driven +development, version control, optimization and profiling. `Expert Python Programming `_ @@ -171,7 +171,7 @@ A Primer on Scientific Programming with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A Primer on Scientific Programming with Python, written by Hans Petter Langtangen, -mainly covers Python's usage in scientific field. In the book, examples are +mainly covers Python's usage in the scientific field. In the book, examples are chosen from mathematics and the natural sciences. `A Primer on Scientific Programming with Python `_ @@ -179,7 +179,7 @@ chosen from mathematics and the natural sciences. Numerical Methods in Engineering with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, attempts to +Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, puts the emphasis on numerical methods and how to implement them in Python. `Numerical Methods in Engineering with Python `_ diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 5ccf6dc..32c44d4 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -35,7 +35,7 @@ new releases, jobs, etc. related to Python. Python News ~~~~~~~~~~~~~ -News section in the official Python web site (www.python.org). It briefly -highlights the news from Python community. +Python News is the news section in the official Python web site (www.python.org). It briefly +highlights the news from the Python community. `Python News `_ diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 461c2a9..af11cdf 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -240,13 +240,13 @@ Chef Puppet ------ -`Puppet `_ is an IT Automation and configuration management +`Puppet `_ is IT Automation and configuration management software from Puppet Labs that allows System Administrators to define the state of their IT Infrastructure, thereby providing an elegant way to manage their fleet of physical and virtual machines. Puppet is available both as an Open Source and an Enterprise variant. Modules are -small,shareable units of code written to automate or define the state of a system. +small, shareable units of code written to automate or define the state of a system. `Puppet Forge `_ is a repository for modules written by the community for Open Source and Enterprise Puppet. @@ -261,7 +261,7 @@ how each node should be configured and sends it to the agent. The agent enforces change as prescribed in the catalog and sends a report back to the Puppet Master. Facter is an interesting tool that ships with Puppet that pulls basic facts about -the System. These facts can be referenced as a variable while writing your +the system. These facts can be referenced as a variable while writing your Puppet modules. .. code-block:: console @@ -328,7 +328,7 @@ everytime the sshd configuration file is changed. hasrestart=> true, } -For more information checkout `Puppet Labs Documentation `_ +For more information, refer to the `Puppet Labs Documentation `_ Blueprint --------- diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index e2219b3..7c3c634 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -35,7 +35,7 @@ and deployable. Kivy is written in Python, based on OpenGL and supports different input devices such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on. -Kivy is actively being developed by a community and free to use. It operates +Kivy is actively being developed by a community and is free to use. It operates on all major platforms (Linux, OSX, Windows, Android). The main resource for information is the website: http://kivy.org diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 64fe18e..86f6409 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -26,7 +26,7 @@ IPython `IPython `_ is an enhanced version of Python interpreter, which provides features of great interest to scientists. The `inline mode` -allow graphics and plots to be displayed in the terminal (Qt based version). +allows graphics and plots to be displayed in the terminal (Qt based version). Moreover, the `notebook` mode supports literate programming and reproducible science generating a web-based Python notebook. This notebook allows you to store chunks of Python code along side the results and additional comments @@ -55,9 +55,9 @@ NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+. Numba ----- -`Numba `_ is an Numpy aware Python compiler +`Numba `_ is a NumPy aware Python compiler (just-in-time (JIT) specializing compiler) which compiles annotated Python (and -Numpy) code to LLVM (Low Level Virtual Machine) through special decorators. +NumPy) code to LLVM (Low Level Virtual Machine) through special decorators. Briefly, Numba uses a system that compiles Python code with LLVM to code which can be natively executed at runtime. diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 4d7551e..026ac71 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -3,7 +3,7 @@ Web Applications ================ As a powerful scripting language adapted to both fast prototyping -and bigger projects, Python is widely used in Web applications +and bigger projects, Python is widely used in web application development. Context @@ -84,8 +84,8 @@ Werkzeug `Werkzeug `_ is not actually a real framework, but rather a very powerful set of tools for building web applications. It provides URL routing utilities, request and response objects and a basic development -server. It is mostly used where users need bigger flexibility for their -application that is not commonly found in other web frameworks. +server. It is mostly used where users need more flexibility for their +application than is commonly found in other web frameworks. Support can be found on its `mailing list `_. @@ -179,7 +179,7 @@ variables `_. Server Best Practices ::::::::::::::::::::: -The majority of self hosted Python applications today are hosted with a WSGI +The majority of self-hosted Python applications today are hosted with a WSGI server such as :ref:`Gunicorn `, either directly or behind a lightweight web server such as :ref:`nginx `. @@ -195,7 +195,7 @@ Platform-as-a-Service Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure which abstracts and manages infrastructure, routing, and scaling of web -applications. When using PaaS, application developers can focus on writing +applications. When using a PaaS, application developers can focus on writing application code rather than needing to be concerned with deployment details. @@ -327,8 +327,8 @@ Here some important html tags in Jinja2: -The next listings is an example of a web site in combination with the tornado -web server. Tornado is not very complicate to use. +The next listings is an example of a web site in combination with the Tornado +web server. Tornado is not very complicated to use. .. code-block:: python diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 8fe7e6b..88820f6 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -24,13 +24,13 @@ Use `pip `_. More details `here `_, which is considered the stable production version. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 37764c9..2c9b163 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -266,10 +266,10 @@ logic (called pure functions) allow the following benefits: - Pure functions are easier to test with unit-tests: There is less need for complex context setup and data cleaning afterwards. -- Pure functions are easier to manipulate, decorate, and pass-around. +- Pure functions are easier to manipulate, decorate, and pass around. -In summary, pure functions, without any context or side-effects, are more -efficient building blocks than classes and objects for some architectures. +In summary, pure functions are more efficient building blocks than classes +and objects for some architectures because they have no context or side-effects. Obviously, object-orientation is useful and even necessary in many cases, for example when developing graphical desktop applications or games, where the @@ -314,7 +314,7 @@ of the function logic. Dynamic typing -------------- -Python is said to be dynamically typed, which means that variables +Python is dynamically typed, which means that variables do not have a fixed type. In fact, in Python, variables are very different from what they are in many other languages, specifically statically-typed languages. Variables are not a segment of the computer's diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 42c76b8..3f4cfa8 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -88,7 +88,7 @@ Arguments can be passed to functions in four different ways. 1. **Positional arguments** are mandatory and have no default values. They are the 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 +that are fully part of the function's meaning and their order is natural. For instance, in ``send(message, recipient)`` or ``point(x, y)`` the user of the function has no difficulty remembering that those two functions require two arguments, and in which order. @@ -102,7 +102,7 @@ calls to ``send('Hello', 'World')`` and ``point(1, 2)``. 2. **Keyword arguments** are not mandatory and have default values. They are often used for optional parameters sent to the function. When a function has more than two or three positional parameters, its signature is more difficult to remember -and using keyword argument with default values is helpful. For instance, a more +and using keyword arguments 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 they are not passed another value. @@ -165,7 +165,7 @@ Avoid the magical wand ~~~~~~~~~~~~~~~~~~~~~~ A powerful tool for hackers, Python comes with a very rich set of hooks and -tools allowing to do almost any kind of tricky tricks. For instance, it is +tools allowing you to do almost any kind of tricky tricks. For instance, it is possible to do each of the following: * change how objects are created and instantiated @@ -212,7 +212,7 @@ Using this convention generously is encouraged: any method or property that is not intended to be used by client code should be prefixed with an underscore. This will guarantee a better separation of duties and easier modification of existing code; it will always be possible to publicize a private property, -while privatising a public property might be a much harder operation. +but making a public property private might be a much harder operation. Returning values ~~~~~~~~~~~~~~~~ @@ -374,7 +374,7 @@ 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. +the hash of the dictionary, finding keys in the dictionary can be done very quickly. For more information see this `StackOverflow `_ page. @@ -422,7 +422,7 @@ Conforming your Python code to PEP 8 is generally a good idea and helps make code more consistent when working on projects with other developers. There is a command-line program, `pep8 `_, that can check your code for conformance. Install it by running the following -command in your Terminal: +command in your terminal: .. code-block:: console @@ -639,6 +639,6 @@ and square braces. from some.deep.module.inside.a.module import ( a_nice_function, another_nice_function, yet_another_nice_function) -However, more often than not having to split long logical line is a sign that +However, more often than not, having to split a long logical line is a sign that you are trying to do too many things at the same time, which may hinder readability. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index f4ca54b..f416944 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -19,8 +19,8 @@ Some general rules of testing: usually handled by :meth:`setUp()` and :meth:`tearDown()` methods. - Try hard to make tests that run fast. If one single test needs more than a - few millisecond to run, development will be slowed down or the tests will - not be run as often as desirable. In some cases, tests can't be fast because + few milliseconds to run, development will be slowed down or the tests will + not be run as often as is desirable. In some cases, tests can't be fast because they need a complex data structure to work on, and this data structure must be loaded every time the test runs. Keep these heavier tests in a separate test suite that is run by some scheduled task, and run all other tests as