diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 1d3068dd6..50ddbb0b9 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -5,15 +5,15 @@ Your Development Environment Text Editors :::::::::::: -Just about anything which can edit plain text will work for writing Python code, +Just about anything that can edit plain text will work for writing Python code, however, using a more powerful editor may make your life a bit easier. -VIM +Vim --- Vim is a text editor which uses keyboard shortcuts for editing instead of menus -or icons. There exist a couple of plugins and settings for the VIM editor to +or icons. There are a couple of plugins and settings for the Vim editor to aid Python development. If you only develop in Python, a good start is to set the default settings for indentation and line-wrapping to values compliant with :pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the @@ -21,24 +21,24 @@ following lines:: set textwidth=79 " lines longer than 79 columns will be broken set shiftwidth=4 " operation >> indents 4 columns; << unindents 4 columns - set tabstop=4 " an hard TAB displays as 4 columns + set tabstop=4 " a hard TAB displays as 4 columns set expandtab " insert spaces when hitting TABs set softtabstop=4 " insert/delete 4 spaces when hitting a TAB/BACKSPACE set shiftround " round indent to multiple of 'shiftwidth' set autoindent " align the new line indent with the previous line With these settings, newlines are inserted after 79 characters and indentation -is set to 4 spaces per tab. If you also use VIM for other languages, there is a -handy plugin at indent_, which handles indentation settings for Python source +is set to 4 spaces per tab. If you also use Vim for other languages, there is a +handy plugin called indent_, which handles indentation settings for Python source files. -There is also a handy syntax plugin at syntax_ featuring some improvements over -the syntax file included in VIM 6.1. +There is also a handy syntax plugin called syntax_ featuring some improvements over +the syntax file included in Vim 6.1. These plugins supply you with a basic environment for developing in Python. To get the most out of Vim, you should continually check your code for syntax errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you. -If your VIM is compiled with :option:`+python` you can also utilize some very handy +If your Vim is compiled with :option:`+python` you can also utilize some very handy plugins to do these checks from within the editor. For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can @@ -51,7 +51,7 @@ order to do this, add the following lines to your :file:`.vimrc`:: autocmd BufWritePost *.py call Pyflakes() autocmd BufWritePost *.py call Pep8() -If you are already using syntastic_ you can enable it to run Pyflakes on write +If you are already using syntastic_, you can set it to run Pyflakes on write and show errors and warnings in the quickfix window. An example configuration to do that which also shows status and warning messages in the statusbar would be:: @@ -61,24 +61,26 @@ to do that which also shows status and warning messages in the statusbar would b let g:syntastic_auto_loc_list=1 let g:syntastic_loc_list_height=5 + Python-mode ^^^^^^^^^^^ -Python-mode_ is a complex solution in VIM for working with Python code. +Python-mode_ is a complex solution for working with Python code in Vim. It has: - Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pep8``, ``mccabe``) in any combination - Code refactoring and autocompletion with Rope - Fast Python folding - Virtualenv support -- Search by Python documentation and run Python code +- Search through Python documentation and run Python code - Auto PEP8_ error fixes And more. SuperTab ^^^^^^^^ -SuperTab_ is a small VIM plugin that makes code completion more convenient by + +SuperTab_ is a small Vim plugin that makes code completion more convenient by using ```` key or any other customized keys. .. _indent: http://www.vim.org/scripts/script.php?script_id=974 @@ -94,9 +96,9 @@ using ```` key or any other customized keys. Emacs ----- -Emacs is a powerful text editor. It's fully programmable (lisp), but -it can be some work to wire up correctly. A good start if you're -already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki. +Emacs is another powerful text editor. It is fully programmable (lisp), but +it can be some work to wire up correctly. A good start if you're already an +Emacs user is `Python Programming in Emacs`_ at EmacsWiki. 1. Emacs itself comes with a Python mode. 2. Python ships with an alternate version: @@ -155,18 +157,18 @@ Spyder `Spyder `_ is an IDE specifically geared toward working with scientific Python libraries (namely `Scipy `_). -It includes integration with pyflakes_, `pylint `_, +It includes integration with pyflakes_, `pylint `_ and `rope `_. Spyder is open-source (free), offers code completion, syntax highlighting, -class and function browser, and object inspection. +a class and function browser, and object inspection. WingIDE ------- `WingIDE `_ is a Python specific IDE. It runs on Linux, -Windows, and Mac (as an X11 application, which frustrates some Mac users). +Windows and Mac (as an X11 application, which frustrates some Mac users). WingIDE offers code completion, syntax highlighting, source browser, graphical debugger and support for version control systems. @@ -196,8 +198,9 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps your global site-packages directory clean and manageable. `virtualenv `_ creates -a folder which contains all the necessary executables to contain the -packages that a Python project would need. An example workflow is given. +a folder which contains all the necessary executables to use the +packages that a Python project would need. An example workflow is given +below. Install virtualenv: @@ -230,7 +233,7 @@ The name of the current virtual environment will now appear on the left of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to let you know that it's active. From now on, any package that you install using ``pip`` will be placed in the ``venv`` folder, isolated from the global -Python installation. +Python installation. Install packages as usual: @@ -259,9 +262,9 @@ the current state of the environment packages. To do this, run This will create a :file:`requirements.txt` file, which contains a simple list of all the packages in the current environment, and their respective -versions. Later, when a different developer (or you, if you need to re- -create the environment) can install the same packages, with the same -versions by running +versions. Later it will be easier for a different developer (or you, if you +need to re-create the environment) to install the same packages using the +same versions: .. code-block:: console @@ -291,8 +294,8 @@ Put this into your :file:`~/.bash_profile` (Linux/Mac) file: $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages' This will prevent your virtualenvs from relying on your (global) site packages -directory, so that they are completely separate.. -[note: This is the default behavior for ``virtualenv`` 1.7 and later] +directory, so that they are completely separate. +[Note: This is the default behavior for ``virtualenv`` 1.7 and later] Other Tools ::::::::::: diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 23d9240f1..935839055 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -11,13 +11,13 @@ include: Python's philosophy focuses on readability, from code blocks delineated with significant whitespace to intuitive keywords in - place of inscrutable punctuation + place of inscrutable punctuation. * **extensive standard libraries and third party modules for virtually any task** Python is sometimes described with the words "batteries included" - for its extensive + because of its extensive `standard library `_, which includes modules for regular expressions, file IO, fraction handling, object serialization, and much more. @@ -77,13 +77,11 @@ For the Community All contributions to the Guide are welcome, from Pythonistas of all levels. If you think there's a gap in what the Guide covers, fork the Guide on -GitHub and submit a pull request. +GitHub and submit a pull request. -Contributions are welcome from everyone, whether they're an old hand or a -first-time Pythonista, and the authors to the Guide will gladly help if you -have any questions about the appropriateness, completeness, or accuracy of +Contributions are welcome from everyone, whether they're an old hand or a +first-time Pythonista, and the authors to the Guide will gladly help if you +have any questions about the appropriateness, completeness, or accuracy of a contribution. To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page. - - diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 31641f7b2..2436cea61 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -7,8 +7,8 @@ Beginner The Python Tutorial ~~~~~~~~~~~~~~~~~~~~ -This is the official tutorial, it covers all the basics, and offers a tour of the -language and the standard library, recommended for those who need a quickstart +This is the official tutorial. It covers all the basics, and offers a tour of the +language and the standard library. Recommended for those who need a quickstart guide to the language. `The Python Tutorial `_ @@ -189,6 +189,7 @@ Miscellaneous topics Problem Solving with Algorithms and Data Structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Problem Solving with Algorithms and Data Structures covers a range of data structures and algorithms. All concepts are illustrated with Python code along with interactive samples that can be run directly in the browser. @@ -198,8 +199,9 @@ that can be run directly in the browser. Programming Collective Intelligence ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Programming Collective Intelligence introduces a wide array of basic machine learning and -data mining methods. The exposition is not very mathematically formal, but rather focuses +data mining methods. The exposition is not very mathematically formal, but rather focuses on explaining the underlying intuition and shows how to implement the algorithms in Python. `Programming Collective Intelligence `_ @@ -223,7 +225,7 @@ This is Python's reference manual, it covers the syntax and the core semantics o language. `The Python Language Reference `_ - + Python Pocket Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,13 +239,12 @@ Writing Idiomatic Python ~~~~~~~~~~~~~~~~~~~~~~~~ "Writing Idiomatic Python", written by Jeff Knupp, contains the most common and -important Python idioms in a format that maximizes identification and understanding. -Each idiom is presented as a recommendation to write some commonly used piece of code. -It is followed by an explanation of why the idiom is important. It also contains two -code samples: the "Harmful" way to write it and the "Idiomatic" way +important Python idioms in a format that maximizes identification and understanding. +Each idiom is presented as a recommendation of a way to write some commonly +used piece of code, followed by an explanation of why the idiom is important. +It also contains two code samples for each idiom: the "Harmful" way to write it +and the "Idiomatic" way. `For Python 2.7.3+ `_ `For Python 3.3+ `_ - - diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 0dafa0be7..2a82b03df 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -126,9 +126,12 @@ State files can be written using YAML, the Jinja2 template system or pure Python Psutil ------ -`Psutil `_ is an interface to different system information (e.g. CPU, memory, disks, network, users and processes). -Here is an example to be aware of some server overload. In case of some failed test (net, CPU) it send an email. +`Psutil `_ is an interface to different +system information (e.g. CPU, memory, disks, network, users and processes). + +Here is an example to be aware of some server overload. If any of the +tests (net, CPU) fail, it will send an email. .. code-block:: python @@ -162,7 +165,7 @@ Here is an example to be aware of some server overload. In case of some failed t if counter > 25: attack = 0 counter = 0 - # Write a very important email if attack is higher then 4 + # Write a very important email if attack is higher than 4 TO = "you@your_email.com" FROM = "webmaster@your_domain.com" SUBJECT = "Your domain is out of system resources!" @@ -173,12 +176,17 @@ Here is an example to be aware of some server overload. In case of some failed t server.quit() -A full terminal application like a widely extended top which is based on psutil and with the ability of a client-server -monitoring is `glance `_. +A full terminal application like a widely extended top which is based on +psutil and with the ability of a client-server monitoring is +`glance `_. Ansible ------- -`Ansible `_ is a open source system automation tool. The biggest advantage over Puppet or Chef is it does not require an agent on the client machine. Playbooks are Ansible’s configuration, deployment, and orchestration language and are written in in yaml with jinja2 for templating. + +`Ansible `_ is an open source system automation tool. +The biggest advantage over Puppet or Chef is it does not require an agent on +the client machine. Playbooks are Ansible’s configuration, deployment, and +orchestration language and are written in in YAML with Jinja2 for templating. Ansible supports Python versions 2.6 and 2.7 and can be installed via pip: @@ -186,11 +194,12 @@ Ansible supports Python versions 2.6 and 2.7 and can be installed via pip: $ pip install ansible -Ansible requires a inventory file that describes the hosts it has access to. Here is an example of a host and -playbook that will ping all the hosts in the inventory file: +Ansible requires an inventory file that describes the hosts to which it has +access. Below is an example of a host and playbook that will ping all the +hosts in the inventory file. Here is an example inventory file: -hosts.yml +:file:`hosts.yml` .. code-block:: yaml @@ -198,7 +207,7 @@ hosts.yml 127.0.0.1 Here is an example playbook: -ping.yml +:file:`ping.yml` .. code-block:: yaml @@ -207,7 +216,7 @@ ping.yml tasks: - name: ping - action: ping + action: ping To run the playbook: @@ -215,9 +224,9 @@ To run the playbook: $ ansible-playbook ping.yml -i hosts.yml --ask-pass -That Ansible playbook will ping all of the servers in the hosts.yml file. You can also select groups of servers using Ansible. For more information about Ansible read the docs. - -`Ansible Docs `_ +The Ansible playbook will ping all of the servers in the :file:`hosts.yml` file. +You can also select groups of servers using Ansible. For more information +about Ansible, read the `Ansible Docs `_. Chef diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 4e4a80ece..7923c8ebf 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -26,6 +26,7 @@ engine. Use it. Buildbot -------- + `Buildbot `_ is a Python system to automate the compile/test cycle to validate code changes. @@ -33,9 +34,13 @@ automate the compile/test cycle to validate code changes. Mule ----- -`Mule `_ is a lightweight integration platform that enables you to connect anything, anywhere. -You can use Mule to intelligently manage message routing, data mapping, orchestration, reliability, security, and scalability between nodes. -Plug other systems and applications into Mule and let it handle all the communication between systems, enabling you to track and monitor everything that happens. +`Mule `_ +is a lightweight integration platform that enables you to connect anything, +anywhere. You can use Mule to intelligently manage message routing, data +mapping, orchestration, reliability, security and scalability between nodes. +Plug other systems and applications into Mule and let it handle all the +communication between systems, enabling you to track and monitor everything +that happens. Tox @@ -56,6 +61,7 @@ which provides the following features: Travis-CI --------- + `Travis-CI `_ is a distributed CI server which builds tests for open source projects for free. It provides multiple workers to run Python tests on and seamlessly integrates with GitHub. You can even have it comment on your Pull @@ -79,12 +85,13 @@ example content:: - master -This will get your project tested on all the listed Python versions by running the given -script and only build the master branch. There are a lot more options you can enable, like -notifications, before and after steps and much more. The -`travis-ci docs `_ explain all of those and are very -thorough. +This will get your project tested on all the listed Python versions by +running the given script, and will only build the master branch. There are a +lot more options you can enable, like notifications, before and after steps +and much more. The `travis-ci docs `_ +explain all of these options, and are very thorough. In order to activate testing for your project, go to `the travis-ci site `_ -and login with your GitHub account. Then activate your project in your profile settings and that's -it. From now on, your project's tests will be run on every push to GitHub. +and login with your GitHub account. Then activate your project in your +profile settings and you're ready to go. From now on, your project's tests +will be run on every push to GitHub. diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 461dda593..7268b0518 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -8,15 +8,15 @@ Clint `clint `_ is a Python module which is filled with very useful tools for developing command-line applications. -It supports features such as; CLI Colors and Indents, Simple and Powerful -Column Printer, Iterator based progress bar and Implicit argument handling. +It supports features such as; CLI colors and indents, simple and powerful +column printer, iterator based progress bars and implicit argument handling. Click ----- `click `_ is an upcoming Python package for creating -command-line interfaces in a composable way with as little amount of code as -necessary. It’s the “Command-line Interface Creation Kit”. It’s highly +command-line interfaces in a composable way with as little code as +possible. This “Command-line Interface Creation Kit” is highly configurable but comes with good defaults out of the box. docopt @@ -29,18 +29,20 @@ POSIX-style usage instructions. Plac ------ -`Plac `_ is a Python module that allows developing command-line applications. In fact -plac is a simple wrapper over the Python standard library `argparse `_, it hides most of its -complexity by using a declarative interface: the argument parser is inferred -rather than written down by imperatively. It is targetting especially unsophisticated -users, programmers, sys-admins, scientists and in general people writing throw-away -scripts for themselves, choosing the command-line interface because it is quick -and simple. +`Plac `_ is a simple wrapper +over the Python standard library `argparse `_, +which hides most of its complexity by using a declarative interface: the +argument parser is inferred rather than written down by imperatively. This +module targets especially unsophisticated users, programmers, sys-admins, +scientists and in general people writing throw-away scripts for themselves, +who choose to create a command-line interface because it is quick and simple. Cliff ------ -`Cliff `_ is a framework for building command-line programs. -It uses setuptools entry points to provide subcommands, output formatters, and other extensions. The framework -is meant to be used to create multi-level commands such as subversion and git, where the main program handles -some basic argument parsing and then invokes a sub-command to do the work. +`Cliff `_ is a framework for +building command-line programs. It uses setuptools entry points to provide +subcommands, output formatters, and other extensions. The framework is meant +to be used to create multi-level commands such as subversion and git, where +the main program handles some basic argument parsing and then invokes a +sub-command to do the work. diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst index b7494b080..d589a47c9 100644 --- a/docs/scenarios/client.rst +++ b/docs/scenarios/client.rst @@ -45,10 +45,10 @@ library is designed to have a familiar socket-style API. RabbitMQ -------- -RabbitMQ is an open source message broker software that implements the Advanced Message Queuing Protocol (AMQP). -The RabbitMQ server is written in the Erlang programming language and is built on the Open Telecom Platform -framework for clustering and failover. Client libraries to interface with the broker are available +RabbitMQ is an open source message broker software that implements the Advanced Message Queuing Protocol (AMQP). +The RabbitMQ server is written in the Erlang programming language and is built on the Open Telecom Platform +framework for clustering and failover. Client libraries to interface with the broker are available for all major programming languages. -- `Homepage `_ +- `Homepage `_ - `GitHub Organization `_ diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 252d9d7b1..0d30c3ee2 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -30,14 +30,11 @@ Django ORM The Django ORM is the interface used by `Django `_ to provide database access. -It's based on the idea of `models `_, an abstraction that makes it easier to -manipulate data in Python. +It's based on the idea of `models `_, +an abstraction that makes it easier to manipulate data in Python. The basics: - Each model is a Python class that subclasses django.db.models.Model. - Each attribute of the model represents a database field. - Django gives you an automatically-generated database-access API; see `Making queries `__. -to provide database access. - - diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 2a5d3619a..e2219b371 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -9,9 +9,9 @@ Camelot applications on top of Python, SQLAlchemy and Qt. It is inspired by the Django admin interface. -The main resource for information is the website: -http://www.python-camelot.com -and the mailinglist https://groups.google.com/forum/#!forum/project-camelot +The main resource for information is the website: +http://www.python-camelot.com +and the mailing list https://groups.google.com/forum/#!forum/project-camelot Cocoa ----- @@ -22,7 +22,7 @@ GTk PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library itself, it is currently licensed under the GNU LGPL. It is worth noting that PyGTK only currently supports the Gtk-2.X API (NOT Gtk-3.0). It is currently -recommended that PyGTK not be used for new projects and existing applications +recommended that PyGTK not be used for new projects and that existing applications be ported from PyGTK to PyGObject. Kivy @@ -54,11 +54,13 @@ PyQt ~~~~ .. note:: If your software does not fully comply with the GPL you will need a commercial license! +PyQt provides Python bindings for the Qt Framework (see below). + http://www.riverbankcomputing.co.uk/software/pyqt/download PyjamasDesktop (pyjs Desktop) ----------------------------- -PyjamasDesktop is a port of PyJamas. PyjamasDesktop is application widget set +PyjamasDesktop is a port of Pyjamas. PyjamasDesktop is application widget set for desktop and a cross-platform framework. (After release v0.6 PyjamasDesktop is a part of Pyjamas (Pyjs)). Briefly, it allows the exact same Python web application source code to be executed as a standalone desktop application. @@ -69,8 +71,9 @@ The main website; `pyjs Desktop `_. Qt -- -`Qt `_ is a cross-platform application framework that is widely used for developing -software with a GUI but can also be used for non-GUI applications. +`Qt `_ is a cross-platform application framework that +is widely used for developing software with a GUI but can also be used for +non-GUI applications. Tk -- diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index 56031aa9d..9834be819 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -12,21 +12,23 @@ IMAP or SSH protocols, instant messaging and `much more `_ is the Python binding for `ZeroMQ `_, -which is a high-performance asynchronous messaging library. One great advantage is that ZeroMQ -can be used for message queuing without a message broker. The basic patterns for this are: - -- request-reply: connects a set of clients to a set of services. This is a remote procedure call - and task distribution pattern. -- publish-subscribe: connects a set of publishers to a set of subscribers. This is a data - distribution pattern. -- push-pull (or pipeline): connects nodes in a fan-out / fan-in pattern that can have multiple - steps, and loops. This is a parallel task distribution and collection pattern. +`PyZMQ `_ is the Python binding for +`ZeroMQ `_, which is a high-performance asynchronous +messaging library. One great advantage of ZeroMQ is that it can be used for +message queuing without a message broker. The basic patterns for this are: + +- request-reply: connects a set of clients to a set of services. This is a + remote procedure call and task distribution pattern. +- publish-subscribe: connects a set of publishers to a set of subscribers. + This is a data distribution pattern. +- push-pull (or pipeline): connects nodes in a fan-out / fan-in pattern that + can have multiple steps, and loops. This is a parallel task distribution + and collection pattern. For a quick start, read the `ZeroMQ guide `_. gevent ------ -`gevent `_ is a coroutine-based Python networking library -that uses greenlets and libevent event loop. +`gevent `_ is a coroutine-based Python networking library +that uses greenlets and libevent event loops. diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index a8dc59e70..64fe18e2d 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -5,12 +5,12 @@ Scientific Applications Context ::::::: -Python is frequently used for high-performance scientific applications. Python -is widely used in academia and scientific projects because it is easy to write, -and it performs really well. +Python is frequently used for high-performance scientific applications. It +is widely used in academia and scientific projects because it is easy to write +and performs well. -Due to its high performance nature, scientific computing in Python often refers -to external libraries, typically written in faster languages (like C, or +Due to its high performance nature, scientific computing in Python often +utilizes external libraries, typically written in faster languages (like C, or FORTRAN for matrix operations). The main libraries used are `NumPy`_, `SciPy`_ and `Matplotlib`_. Going into detail about these libraries is beyond the scope of the Python guide. However, a comprehensive introduction to the scientific @@ -24,13 +24,14 @@ Tools IPython ------- -`IPython `_ is an enhanced version of Python interpreter. -The features it provides are of great interest for the scientists. The `inline mode` +`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). -Moreover the `notebook` mode supports literate programming and reproducible science -generating a web-based Python notebook. This notebook allowing to store chunk of -Python code along side to the results and additional comments (HTML, LaTeX, Markdown). -The notebook could be shared and exported in various file formats. +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 +(HTML, LaTeX, Markdown). The notebook can then be shared and exported in various +file formats. Libraries @@ -45,9 +46,9 @@ problem of running slower algorithms on Python by using multidimensional arrays and functions that operate on arrays. Any algorithm can then be expressed as a function on arrays, allowing the algorithms to be run quickly. - NumPy is part of the SciPy project, and is released as a separate library so -people who only need the basic requirements can just use NumPy. +people who only need the basic requirements can use it without installing the +rest of SciPy. NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+. @@ -56,60 +57,62 @@ Numba `Numba `_ is an 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). -Briefly, Numba using system that compiles Python code with LLVM to code which +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. SciPy ----- -`SciPy `_ is a library that uses Numpy for more mathematical -functions. SciPy uses NumPy arrays as the basic data structure. SciPy comes -with modules for various commonly used tasks in scientific programming, for -example: linear algebra, integration (calculus), ordinary differential equation -solvers and signal processing. +`SciPy `_ is a library that uses NumPy for more mathematical +functions. SciPy uses NumPy arrays as the basic data structure, and comes +with modules for various commonly used tasks in scientific programming, +including linear algebra, integration (calculus), ordinary differential equation +solving and signal processing. Matplotlib ---------- `Matplotlib `_ is a flexible plotting library for creating interactive 2D and 3D plots that can also be saved as -manuscript-quality figures. The API in many ways reflects that of `MATLAB +manuscript-quality figures. The API in many ways reflects that of `MATLAB `_, easing transition of MATLAB -users to Python. Many examples, along with the source code to re-create them, -can be browsed at the `matplotlib gallery +users to Python. Many examples, along with the source code to re-create them, +are available in the `matplotlib gallery `_. Pandas ------ + `Pandas `_ is data manipulation library -based on Numpy and which provides many useful functions for accessing, +based on Numpy which provides many useful functions for accessing, indexing, merging and grouping data easily. The main data structure (DataFrame) -is close to what could be found in the R statistical package, that is -an heterogeneous data tables with name indexing, time series operations -and auto-alignment of data. +is close to what could be found in the R statistical package; that is, +heterogeneous data tables with name indexing, time series operations and +auto-alignment of data. Rpy2 ---- + `Rpy2 `_ is a Python binding for the R -statistical package allowing to execute R functions from Python and passing -data back and forth the two environments. Rpy2 is the object oriented -implementation of the binding based on `Rpy `_. +statistical package allowing the execution of R functions from Python and passing +data back and forth between the two environments. Rpy2 is the object oriented +implementation of the `Rpy `_ bindings. PsychoPy -------- `PsychoPy `_ is a library for cognitive scientists -allowing to create cognitive psychology and neuroscience experiments. The library -handles both presentation of stimuli, scripting of experimental design and -data collection. +allowing the creation of cognitive psychology and neuroscience experiments. +The library handles presentation of stimuli, scripting of experimental design +and data collection. Resources ::::::::: -Installation of scientific Python packages can be troublesome. Many of these -packages are implemented as Python C extensions which need to be compiled. +Installation of scientific Python packages can be troublesome, as many of +these packages are implemented as Python C extensions which need to be compiled. This section lists various so-called scientific Python distributions which provide precompiled and easy-to-install collections of scientific Python packages. @@ -117,27 +120,27 @@ packages. Unofficial Windows Binaries for Python Extension Packages --------------------------------------------------------- -Many people who do scientific computing are on Windows. And yet many of the -scientific computing packages are notoriously difficult to build and install. -`Christoph Gohlke `_ however, has -compiled a list of Windows binaries for many useful Python packages. The list -of packages has grown from a mainly scientific Python resource to a more -general list. It might be a good idea to check it out if you're on Windows. +Many people who do scientific computing are on Windows, yet many of the +scientific computing packages are notoriously difficult to build and install +on this platform. `Christoph Gohlke `_ +however, has compiled a list of Windows binaries for many useful Python packages. +The list of packages has grown from a mainly scientific Python resource to a more +general list. If you're on Windows, you may want to check it out. Anaconda -------- `Continuum Analytics `_ offers the `Anaconda Python Distribution `_ which -includes all the common scientific Python packages and additionally many -packages related to data analytics and big data. Anaconda itself is free, and -Continuum sells a number of proprietary add-ons. Free -licenses for the add-ons are available for academics and researchers. +includes all the common scientific Python packages as well as many packages +related to data analytics and big data. Anaconda itself is free, and +Continuum sells a number of proprietary add-ons. Free licenses for the +add-ons are available for academics and researchers. Canopy ------ -`Canopy '_ is another scientific Python -distribution, produced by `Enthought `_. A limited -'Canopy Express' variant is available for free, and Enthought charge for the -full distribution. Free licenses are available for academics. +`Canopy `_ is another scientific +Python distribution, produced by `Enthought `_. +A limited 'Canopy Express' variant is available for free, but Enthought +charges for the full distribution. Free licenses are available for academics. diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 8533919d8..8e1a6fc03 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -18,8 +18,8 @@ lxml and Requests ----------------- `lxml `_ is a pretty extensive library written for parsing -XML and HTML documents really fast. It even handles messed up tags. We will -also be using the `Requests `_ +XML and HTML documents very quickly, even handling messed up tags in the +process. We will also be using the `Requests `_ module instead of the already built-in urllib2 module due to improvements in speed and readability. You can easily install both using ``pip install lxml`` and ``pip install requests``. @@ -31,8 +31,8 @@ Let's start with the imports: from lxml import html import requests -Next we will use ``requests.get`` to retrieve the web page with our data -and parse it using the ``html`` module and save the results in ``tree``: +Next we will use ``requests.get`` to retrieve the web page with our data, +parse it using the ``html`` module and save the results in ``tree``: .. code-block:: python @@ -40,7 +40,7 @@ and parse it using the ``html`` module and save the results in ``tree``: tree = html.fromstring(page.text) ``tree`` now contains the whole HTML file in a nice tree structure which -we can go over two different ways: XPath and CSSSelect. In this example, I +we can go over two different ways: XPath and CSSSelect. In this example, we will focus on the former. XPath is a way of locating information in structured documents such as @@ -96,6 +96,6 @@ a web page using lxml and Requests. We have it stored in memory as two lists. Now we can do all sorts of cool stuff with it: we can analyze it using Python or we can save it to a file and share it with the world. -A cool idea to think about is modifying this script to iterate through -the rest of the pages of this example dataset or rewriting this +Some more cool ideas to think about are modifying this script to iterate +through the rest of the pages of this example dataset, or rewriting this application to use threads for improved speed. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 61cf80b6c..8bd4cb5b8 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -68,10 +68,10 @@ C Extensions Cython ------ -`Cython `_ implements a superset of the Python language -with which you are able to write C and C++ modules for Python. Cython also -allows you to call functions from compiled C libraries. Using Cython allows -you to take advantage of Python's strong typing of variables and operations. +`Cython `_ implements a superset of the Python language +with which you are able to write C and C++ modules for Python. Cython also +allows you to call functions from compiled C libraries. Using Cython allows +you to take advantage of Python's strong typing of variables and operations. Here's an example of strong typing with Cython: @@ -100,11 +100,11 @@ Here's an example of strong typing with Cython: return result -This implementation of an algorithm to find prime numbers has some additional keywords instead of the next one, which is implemented in pure Python: +This implementation of an algorithm to find prime numbers has some additional +keywords compared to the next one, which is implemented in pure Python: .. code-block:: python - def primes(kmax): """Calculation of prime numbers in standard Python syntax""" @@ -125,7 +125,7 @@ This implementation of an algorithm to find prime numbers has some additional ke n = n + 1 return result -Notice that in the Cython version you declare integers and integer arrays for +Notice that in the Cython version you declare integers and integer arrays to be compiled into C types while also creating a Python list: @@ -148,12 +148,14 @@ to be compiled into C types while also creating a Python list: p= range(1000) result = [] -What is the difference? In the upper Cython version you can see the declaration of the variable types and the integer array -in a similar way like in standard C. For example `cdef int n,k,i` in line 3. This additional type declaration (e.g. integer) -allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in :file:`*.py` files, -Cython code is saved in :file:`*.pyx` files. +What is the difference? In the upper Cython version you can see the +declaration of the variable types and the integer array in a similar way as +in standard C. For example `cdef int n,k,i` in line 3. This additional type +declaration (i.e. integer) allows the Cython compiler to generate more +efficient C code from the second version. While standard Python code is saved +in :file:`*.py` files, Cython code is saved in :file:`*.pyx` files. -And what is with the speed? So let's try it! +What's the difference in speed? Let's try it! .. code-block:: python @@ -179,7 +181,7 @@ And what is with the speed? So let's try it! print "Python time: %s" %(t2-t1) -These both lines need a remark: +These lines both need a remark: .. code-block:: python @@ -187,11 +189,15 @@ These both lines need a remark: pyximport.install() -The `pyximport` module allows you to import :file:`*.pyx` files (e.g., :file:`primesCy.pyx`) with the Cython-compiled version of the `primes` function. -The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, -which is automatically compiled to a :file:`*.so` C-library. Cython is able to import this library for you in your Python-code. -Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. -On a standard notebook (dual core AMD E-450 1.6 GHz), the measured values are: +The `pyximport` module allows you to import :file:`*.pyx` files (e.g., +:file:`primesCy.pyx`) with the Cython-compiled version of the `primes` +function. The `pyximport.install()` command allows the Python interpreter to +start the Cython compiler directly to generate C-code, which is automatically +compiled to a :file:`*.so` C-library. Cython is then able to import this +library for you in your Python code, easily and efficiently. With the +`time.time()` function you are able to compare the time between these 2 +different calls to find 500 prime numbers. On a standard notebook (dual core +AMD E-450 1.6 GHz), the measured values are: .. code-block:: console @@ -200,14 +206,15 @@ On a standard notebook (dual core AMD E-450 1.6 GHz), the measured values are: Python time: 0.0566 seconds +And here the output of an embedded `ARM beaglebone `_ machine: -And here the output of an embedded `ARM beaglebone `_ machine: .. code-block:: console Cython time: 0.0196 seconds Python time: 0.3302 seconds + Pyrex ----- diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 4fcedf070..4d7551edc 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -24,7 +24,7 @@ WSGI is documented in :pep:`3333`. Frameworks :::::::::: -Broadly speaking, a web framework consist of a set of libraries and a main +Broadly speaking, a web framework consists of a set of libraries and a main handler within which you can build custom code to implement a web application (i.e. an interactive web site). Most web frameworks include patterns and utilities to accomplish at least the following: @@ -280,7 +280,7 @@ and to the templates themselves. - Template files should be passed only the dynamic content that is needed for rendering the template. Avoid - to be tempted to pass additional content "just in case": + the temptation to pass additional content "just in case": it is easier to add some missing variable when needed than to remove a likely unused variable later. @@ -288,7 +288,7 @@ and to the templates themselves. or assignments in the template itself, and many allow some Python code to be evaluated in the templates. This convenience can lead to uncontrolled - increase in complexity, and often harder to find bugs. + increase in complexity, and often make it harder to find bugs. - It is often necessary to mix JavaScript templates with HTML templates. A sane approach to this design is to isolate @@ -299,9 +299,12 @@ and to the templates themselves. Jinja2 ------ -`Jinja2 `_ is a template engine which is similar to the Django template system with some extra features. It is a text-based template -language and thus can be used to generate any markup. It allows customization of filters, tags, tests and globals. -Unlike the template system implemented in the Django Framework it allows to call functions. The Code is staying under the BSD license. +`Jinja2 `_ is a template engine which is similar to +the Django template system with some extra features. It is a text-based +template language and thus can be used to generate any markup. It allows +customization of filters, tags, tests and globals, and unlike the template +system implemented in the Django Framework, also allows calling functions. +Jinja2 is released under the BSD license. Here some important html tags in Jinja2: @@ -324,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 complicate to use. .. code-block:: python @@ -365,7 +368,8 @@ to use. application.listen(PORT) tornado.ioloop.IOLoop.instance().start() -The :file:`base.html` file can be used as base for all site pages which are for example implemented in the content block. +The :file:`base.html` file can be used as base for all site pages which are +for example implemented in the content block. .. code-block:: html @@ -389,8 +393,9 @@ The :file:`base.html` file can be used as base for all site pages which are for -The next listing is our site page (:file:`site.html`) loaded in the Python app which extends :file:`base.html`. The content block is -automatically set into the corresponding block in the :file:`base.html` page. +The next listing is our site page (:file:`site.html`) loaded in the Python +app which extends :file:`base.html`. The content block is automatically set +into the corresponding block in the :file:`base.html` page. .. code-block:: html diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index e5600c7df..0aeb77b86 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -93,13 +93,13 @@ Reference`_ should help you familiarize yourself with its syntax. Code Documentation Advice ------------------------- -Comments clarify the code and they are added with purpose of making the -code easier to understand. In Python, comments begin with a hash +Comments clarify the code and they are added with purpose of making the +code easier to understand. In Python, comments begin with a hash (number sign) (``#``). .. _docstring-ref: -In Python, *docstrings* describe modules, classes, and functions: +In Python, *docstrings* describe modules, classes, and functions: .. code-block:: python @@ -168,7 +168,7 @@ Epydoc_ .. _Epydoc: http://epydoc.sourceforge.net MkDocs_ - MkDocs is a fast and simple static site generator that's geared towards + MkDocs is a fast and simple static site generator that's geared towards building project documentation with Markdown. .. _MkDocs: http://www.mkdocs.org/ diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 5ed5669c1..a59eb9b2e 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -172,7 +172,7 @@ Alternatively, you can use the functools.partial function: from functools import partial from operator import mul - + def create_multipliers(): return [partial(mul, i) for i in range(5)]