From a622afa235d77488e35b0262a2d1635db10b75c7 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Mon, 17 Dec 2018 18:19:53 -0500 Subject: [PATCH] More typo, grammar, and style fixes --- CONTRIBUTING.md | 2 +- docs/dev/env.rst | 2 +- docs/intro/documentation.rst | 4 +-- docs/intro/learning.rst | 46 +++++++++++++++++--------------- docs/intro/news.rst | 4 +-- docs/notes/styleguide.rst | 5 ++-- docs/scenarios/admin.rst | 30 ++++++++++----------- docs/scenarios/ci.rst | 19 +++++++------ docs/scenarios/cli.rst | 29 ++++++++++---------- docs/scenarios/clibs.rst | 8 +++--- docs/scenarios/crypto.rst | 14 +++++----- docs/scenarios/db.rst | 18 ++++++------- docs/scenarios/gui.rst | 18 ++++++------- docs/scenarios/imaging.rst | 14 +++++----- docs/scenarios/json.rst | 4 +-- docs/scenarios/ml.rst | 20 +++++++------- docs/scenarios/network.rst | 8 +++--- docs/scenarios/scientific.rst | 24 ++++++++--------- docs/scenarios/scrape.rst | 8 +++--- docs/scenarios/serialization.rst | 2 +- docs/scenarios/speed.rst | 18 ++++++------- docs/scenarios/web.rst | 38 +++++++++++++------------- docs/scenarios/xml.rst | 10 +++---- docs/shipping/freezing.rst | 28 +++++++++---------- docs/shipping/packaging.rst | 30 ++++++++++----------- 25 files changed, 201 insertions(+), 202 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d9f03aa1..fb3abe19b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ pip install --user sphinx Then navigate to the directory of the Makefile and ```make build``` or ```make html```. Sphinx will then generate the HTML in a folder called `_build/html/` -After navigating to this folder, you can then use Python's built in webserver to view your changes locally: +After navigating to this folder, you can then use Python's built in web server to view your changes locally: ``` bash python3 -m http.server diff --git a/docs/dev/env.rst b/docs/dev/env.rst index de67a9ae9..2264a83bd 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -188,7 +188,7 @@ Spyder `Spyder `_ is an IDE specifically geared toward working with scientific Python libraries (namely -`Scipy `_). It includes integration with pyflakes_, +`SciPy `_). It includes integration with pyflakes_, `pylint `_ and `rope `_. diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst index 03e56e3fe..887d0982b 100644 --- a/docs/intro/documentation.rst +++ b/docs/intro/documentation.rst @@ -35,14 +35,14 @@ pydoc :program:`pydoc` is a utility that is installed when you install Python. It allows you to quickly retrieve and search for documentation from your shell. For example, if you needed a quick refresher on the -:mod:`time` module, pulling up documentation would be as simple as +:mod:`time` module, pulling up documentation would be as simple as: .. code-block:: console $ pydoc time The above command is essentially equivalent to opening the Python REPL -and running +and running: .. code-block:: pycon diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 2c1f19c01..3b1a5781c 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -37,24 +37,26 @@ pythonbasics.org is an introductiory tutorial for beginners. The tutorial includ Python for Beginners ~~~~~~~~~~~~~~~~~~~~ -thepythonguru.com is a tutorial focuses on beginner programmers. It covers many python concepts -in depth. It also teaches you some advance constructs of python like lambda expression, regular expression. -At last it finishes off with tutorial "How to access MySQL db using python" +thepythonguru.com is a tutorial focused on beginner programmers. It covers many Python concepts +in depth. It also teaches you some advanced constructs of Python like lambda expressions and regular expressions. +And last it finishes off with the tutorial "How to access MySQL db using Python" - - `Python for beginners `_ + `Python for Beginners `_ Learn Python Interactive Tutorial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Learnpython.org is an easy non-intimidating way to get introduced to Python. The website takes the same approach used on the popular -`Try Ruby `_ website, it has an interactive Python +`Try Ruby `_ website. It has an interactive Python interpreter built into the site that allows you to go through the lessons without having to install Python locally. `Learn Python `_ +Python for You and Me +~~~~~~~~~~~~~~~~~~~~~ + If you want a more traditional book, *Python For You and Me* is an excellent resource for learning all aspects of the language. @@ -71,7 +73,7 @@ Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial i Online Python Tutor ~~~~~~~~~~~~~~~~~~~ -Online Python Tutor gives you a visual step by step +Online Python Tutor gives you a visual step-by-step representation of how your program runs. Python Tutor helps people overcome a fundamental barrier to learning programming by understanding what happens as the computer @@ -133,7 +135,7 @@ Think Python: How to Think Like a Computer Scientist Think Python attempts to give an introduction to basic concepts in computer science through the use of the Python language. The focus was to create a book -with plenty of exercises, minimal jargon and a section in each chapter devoted +with plenty of exercises, minimal jargon, and a section in each chapter devoted to the subject of debugging. While exploring the various features available in the Python language the @@ -141,7 +143,7 @@ author weaves in various design patterns and best practices. The book also includes several case studies which have the reader explore the topics discussed in the book in greater detail by applying those topics to -real-world examples. Case studies include assignments in GUI and Markov +real-world examples. Case studies include assignments in GUI programming and Markov Analysis. `Think Python `_ @@ -191,7 +193,7 @@ Code the blocks *Code the blocks* provides free and interactive Python tutorials for beginners. It combines Python programming with a 3D environment where you "place blocks" and construct structures. The tutorials teach you -how to use Python to create progressively elaborate 3D structures, +how to use Python to create progressively more elaborate 3D structures, making the process of learning Python fun and engaging. `Code the blocks `_ @@ -204,9 +206,9 @@ Intermediate Python Tricks: The Book ~~~~~~~~~~~~~~~~~~~~~~~ -Discover Python's best practices with simple examples and start writing even more beautiful + Pythonic code. "Python Tricks: The Book" shows you exactly how. +Discover Python's best practices with simple examples and start writing even more beautiful + Pythonic code. *Python Tricks: The Book* shows you exactly how. -You’ll master intermediate and advanced-level features in Python with practical examples and a clear narrative: +You’ll master intermediate and advanced-level features in Python with practical examples and a clear narrative. `Python Tricks: The Book `_ @@ -214,7 +216,7 @@ Effective Python ~~~~~~~~~~~~~~~~ This book contains 59 specific ways to improve writing Pythonic code. At 227 -pages, it is a very brief overview of some of the most commons adapations +pages, it is a very brief overview of some of the most common adapations programmers need to make to become efficient intermediate level Python programmers. @@ -241,13 +243,13 @@ Expert Python Programming deals with best practices in programming Python and is focused on the more advanced crowd. It starts with topics like decorators (with caching, proxy, and context manager -case-studies), method resolution order, using super() and meta-programming, and +case studies), method resolution order, using super() and meta-programming, and 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 such as writing documentation, test-driven -development, version control, optimization and profiling. +development, version control, optimization, and profiling. `Expert Python Programming `_ @@ -261,7 +263,7 @@ and can make classes and objects behave in different and magical ways. `A Guide to Python's Magic Methods `_ -.. note:: The Rafekettler.com is currently down, you can go to their Github version directly. Here you can find a PDF version: +.. note:: Rafekettler.com is currently down; you can go to their GitHub version directly. Here you can find a PDF version: `A Guide to Python's Magic Methods (repo on GitHub) `_ @@ -317,7 +319,7 @@ Transforming Code into Beautiful, Idiomatic Python Transforming Code into Beautiful, Idiomatic Python is a video by Raymond Hettinger. Learn to take better advantage of Python's best features and improve existing code -through a series of code transformations, "When you see this, do that instead." +through a series of code transformations: "When you see this, do that instead." `Transforming Code into Beautiful, Idiomatic Python `_ @@ -328,7 +330,7 @@ Fullstack Python Fullstack Python offers a complete top-to-bottom resource for web development using Python. -From setting up the webserver, to designing the front-end, choosing a database, +From setting up the web server, to designing the front-end, choosing a database, optimizing/scaling, etc. As the name suggests, it covers everything you need to build and run a complete @@ -353,7 +355,7 @@ Python in a Nutshell ~~~~~~~~~~~~~~~~~~~~ Python in a Nutshell, written by Alex Martelli, covers most cross-platform -Python's usage, from its syntax to built-in libraries to advanced topics such +Python usage, from its syntax to built-in libraries to advanced topics such as writing C extensions. `Python in a Nutshell `_ @@ -361,7 +363,7 @@ as writing C extensions. The Python Language Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is Python's reference manual, it covers the syntax and the core semantics +This is Python's reference manual. It covers the syntax and the core semantics of the language. `The Python Language Reference `_ @@ -388,7 +390,7 @@ Python Cookbook ~~~~~~~~~~~~~~~ Python Cookbook, written by David Beazley and Brian K. Jones, is packed with -practical recipes. This book covers the core python language as well as tasks +practical recipes. This book covers the core Python language as well as tasks common to a wide variety of application domains. `Python Cookbook `_ @@ -396,7 +398,7 @@ common to a wide variety of application domains. Writing Idiomatic Python ~~~~~~~~~~~~~~~~~~~~~~~~ -"Writing Idiomatic Python", written by Jeff Knupp, contains the most common and +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 of a way to write some commonly used piece of code, followed by an explanation of why the idiom diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 1dd89aae1..9f8e9232b 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -87,7 +87,7 @@ Python News is the news section in the official Python web site Import Python Weekly ******************** -Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets +Weekly Python Newsletter containing Python Articles, Projects, Videos, and Tweets delivered in your inbox. Keep Your Python Programming Skills Updated. `Import Python Weekly Newsletter `_ @@ -97,6 +97,6 @@ delivered in your inbox. Keep Your Python Programming Skills Updated. Awesome Python Newsletter ************************* -A weekly overview of the most popular Python news, articles and packages. +A weekly overview of the most popular Python news, articles, and packages. `Awesome Python Newsletter `_ diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 2d036b3be..2d4d7055b 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -135,7 +135,7 @@ Python examples: Externally Linking ****************** -* Prefer labels for well known subjects (ex: proper nouns) when linking: +* Prefer labels for well known subjects (e.g. proper nouns) when linking: .. code-block:: rest @@ -150,7 +150,7 @@ Externally Linking Read the `Sphinx Tutorial `_ -* Avoid using labels such as "click here", "this", etc. preferring +* Avoid using labels such as "click here", "this", etc., preferring descriptive labels (SEO worthy) instead. @@ -209,4 +209,3 @@ documents or large incomplete sections. .. todo:: Learn the Ultimate Answer to the Ultimate Question of Life, The Universe, and Everything - diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 42d29425f..e275018ae 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -23,7 +23,7 @@ Install Fabric: The following code will create two tasks that we can use: ``memory_usage`` and ``deploy``. The former will output the memory usage on each machine. The -latter will ssh into each server, cd to our project directory, activate the +latter will SSH into each server, cd to our project directory, activate the virtual environment, pull the newest codebase, and restart the application server. @@ -101,7 +101,7 @@ The following command lists all available minion hosts, using the ping module. $ salt '*' test.ping -The host filtering is accomplished by matching the minion id, +The host filtering is accomplished by matching the minion id or using the grains system. The `grains `_ system uses static host information like the operating system version or the @@ -131,7 +131,7 @@ it will install and start the Apache server: - require: - pkg: apache -State files can be written using YAML, the Jinja2 template system or pure Python. +State files can be written using YAML, the Jinja2 template system, or pure Python. `Salt Documentation `_ @@ -141,7 +141,7 @@ Psutil ****** `Psutil `_ is an interface to different -system information (e.g. CPU, memory, disks, network, users and processes). +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. @@ -263,9 +263,9 @@ configures itself and this distributed approach makes Chef a scalable automation Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically packages for infrastructure choices, are usually stored in your Chef server. -Read the `Digital Ocean tutorial series +Read the `DigitalOcean tutorial series `_ -on chef to learn how to create a simple Chef Server. +on Chef to learn how to create a simple Chef Server. To create a simple cookbook the `knife `_ command is used: @@ -299,8 +299,8 @@ Puppet Agents are installed on nodes whose state needs to be monitored or changed. A designated server known as the Puppet Master is responsible for orchestrating the agent nodes. -Agent nodes send basic facts about the system such as to the operating system, -kernel, architecture, ip address, hostname etc. to the Puppet Master. +Agent nodes send basic facts about the system such as the operating system, +kernel, architecture, IP address, hostname, etc. to the Puppet Master. The Puppet Master then compiles a catalog with information provided by the agents on how each node should be configured and sends it to the agent. The agent enforces the change as prescribed in the catalog and sends a report back @@ -320,7 +320,7 @@ your Puppet modules. Ubuntu Writing Modules in Puppet is pretty straight forward. Puppet Manifests together -form Puppet Modules. Puppet manifest end with an extension of ``.pp``. +form Puppet Modules. Puppet manifests end with an extension of ``.pp``. Here is an example of 'Hello World' in Puppet. .. code-block:: puppet @@ -334,7 +334,7 @@ Here is an example of 'Hello World' in Puppet. Here is another example with system based logic. Note how the operating system fact is being used as a variable prepended with the ``$`` sign. Similarly, this holds true for other facts such as hostname which can be referenced by -``$hostname`` +``$hostname``. .. code-block:: puppet @@ -346,10 +346,10 @@ holds true for other facts such as hostname which can be referenced by } There are several resource types for Puppet but the package-file-service -paradigm is all you need for undertaking majority of the configuration +paradigm is all you need for undertaking the majority of the configuration management. The following Puppet code makes sure that the OpenSSH-Server package is installed in a system and the sshd service is notified to restart -everytime the sshd configuration file is changed. +every time the sshd configuration file is changed. .. code-block:: puppet @@ -407,6 +407,6 @@ monitoring framework written in Python. Its main goal is to give users a flexibl architecture for their monitoring system that is designed to scale to large environments. -Shinken is backwards-compatible with the Nagios configuration standard, and -plugins.It works on any operating system, and architecture that supports Python -which includes Windows, GNU/Linux, and FreeBSD. +Shinken is backwards-compatible with the Nagios configuration standard and +plugins. It works on any operating system and architecture that supports Python, +which includes Windows, Linux, and FreeBSD. diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 19f18b37b..ade9148c4 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -14,7 +14,7 @@ Why? **** Martin Fowler, who first wrote about `Continuous Integration `_ -(short: CI) together with Kent Beck, describes the CI as follows: +(short: CI) together with Kent Beck, describes CI as follows: Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at @@ -29,8 +29,7 @@ Martin Fowler, who first wrote about `Continuous Integration `_ is an extensible continuous integration -engine. Use it. +`Jenkins CI `_ is an extensible Continuous Integration engine. Use it. ******** @@ -46,7 +45,7 @@ Tox *** `tox `_ is an automation tool providing -packaging, testing and deployment of Python software right from the console or +packaging, testing, and deployment of Python software right from the console or CI server. It is a generic virtualenv management and test command line tool which provides the following features: @@ -55,7 +54,7 @@ which provides the following features: * Running tests in each of the environments, configuring your test tool of choice * Acting as a front-end to Continuous Integration servers, reducing boilerplate - and merging CI and shell-based testing. + and merging CI and shell-based testing ********* @@ -66,7 +65,7 @@ Travis-CI 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 Requests whether this particular changeset breaks the -build or not. So if you are hosting your code on GitHub, travis-ci is a great +build or not. So if you are hosting your code on GitHub, Travis-CI is a great and easy way to get started with Continuous Integration. In order to get started, add a :file:`.travis.yml` file to your repository with @@ -86,12 +85,12 @@ this example content:: 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 `_ +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 `_ +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 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 ab2e11925..266223734 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -15,12 +15,12 @@ switches. Some popular command-line applications include: -* `Grep `_ - A plain-text data search utility +* `grep `_ - A plain-text data search utility * `curl `_ - A tool for data transfer with URL syntax -* `httpie `_ - A command line HTTP +* `httpie `_ - A command-line HTTP client, a user-friendly cURL replacement -* `git `_ - A distributed version control system -* `mercurial `_ - A distributed version control +* `Git `_ - A distributed version control system +* `Mercurial `_ - A distributed version control system primarily written in Python @@ -30,8 +30,8 @@ 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 bars 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. ***** @@ -40,7 +40,7 @@ Click `click `_ is a Python package for creating command-line interfaces in a composable way with as little code as -possible. This “Command-line Interface Creation Kit” is highly +possible. This “Command-Line Interface Creation Kit” is highly configurable but comes with good defaults out of the box. @@ -61,8 +61,8 @@ Plac 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, +module targets especially unsophisticated users, programmers, sysadmins, +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. @@ -73,7 +73,7 @@ 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 +to be used to create multi-level commands such as ``svn`` and ``git``, where the main program handles some basic argument parsing and then invokes a sub-command to do the work. @@ -83,11 +83,11 @@ Cement ****** `Cement `_ is an advanced CLI Application Framework. -Its goal is to introduce a standard, and feature-full platform +Its goal is to introduce a standard and feature-full platform for both simple and complex command line applications as well as support rapid development needs without sacrificing quality. -Cement is flexible, and it's use cases span from the simplicity of a micro-framework -to the complexity of a meg-framework. +Cement is flexible, and its use cases span from the simplicity of a micro-framework +to the complexity of a mega-framework. *********** @@ -95,9 +95,8 @@ Python Fire *********** `Python Fire `_ is a library for -automatically generating command line interfaces from absolutely any Python +automatically generating command-line interfaces from absolutely any Python object. It can help debug Python code more easily from the command line, create CLI interfaces to existing code, allow you to interactively explore code in a REPL, and simplify transitioning between Python and Bash (or any other shell). - diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 661cddafd..5470576b0 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -36,11 +36,11 @@ ABI Interaction ctypes ****** -`ctypes `_ is the de facto +`ctypes `_ is the de facto standard library for interfacing with C/C++ from CPython, and it provides not only full access to the native C interface of most major operating systems (e.g., kernel32 on Windows, or libc on \*nix), but also provides support for loading -and interfacing with dynamic libraries, such as DLLs or shared objects at +and interfacing with dynamic libraries, such as DLLs or shared objects, at runtime. It does bring along with it a whole host of types for interacting with system APIs, and allows you to rather easily define your own complex types, such as structs and unions, and allows you to modify things such as @@ -82,7 +82,7 @@ large number of scripting languages), is a tool for generating bindings for interpreted languages from C/C++ header files. It is extremely simple to use: the consumer simply needs to define an interface file (detailed in the tutorial and documentations), include the requisite C/C++ headers, and run -the build tool against them. While it does have some limits, (it currently +the build tool against them. While it does have some limits (it currently seems to have issues with a small subset of newer C++ features, and getting template-heavy code to work can be a bit verbose), it provides a great deal of power and exposes lots of features to Python with little effort. @@ -137,5 +137,5 @@ Boost.Python `Boost.Python `_ requires a bit more manual work to expose C++ object functionality, but it is capable of providing all the same features SWIG does and then some, -to include providing wrappers to access PyObjects in C++, extracting SWIG- +to include providing wrappers to access PyObjects in C++, extracting SWIG wrapper objects, and even embedding bits of Python into your C++ code. diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst index e6956d75b..39cf8a3a4 100644 --- a/docs/scenarios/crypto.rst +++ b/docs/scenarios/crypto.rst @@ -7,16 +7,16 @@ Cryptography ************ -Cryptography +cryptography ************ -`Cryptography `_ is an actively developed +`cryptography `_ is an actively developed library that provides cryptographic recipes and primitives. It supports -Python 2.6-2.7, Python 3.3+ and PyPy. +Python 2.6-2.7, Python 3.3+, and PyPy. -Cryptography is divided into two layers of recipes and hazardous materials -(hazmat). The recipes layer provides simple API for proper symmetric +cryptography is divided into two layers of recipes and hazardous materials +(hazmat). The recipes layer provides a simple API for proper symmetric encryption and the hazmat layer provides low-level cryptographic primitives. @@ -46,9 +46,9 @@ Example code using high level symmetric encryption recipe: GPGME bindings ************** -The `GPGME Python bindings `_ provide pythonic access to `GPG Made Easy `_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4 and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries. +The `GPGME Python bindings `_ provide Pythonic access to `GPG Made Easy `_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt, and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4, and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries. -A more comprehensive `GPGME Python Bindings HOWTO `_ is available with the source and a HTML version is available `here `_. Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `here `_. +A more comprehensive `GPGME Python Bindings HOWTO `_ is available with the source, and an HTML version is available `here `_. Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `here `_. Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause. diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index fc34fbb34..58211e26b 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -12,7 +12,7 @@ DB-API The Python Database API (DB-API) defines a standard interface for Python database access modules. It's documented in :pep:`249`. -Nearly all Python database modules such as `sqlite3`, `psycopg` and +Nearly all Python database modules such as `sqlite3`, `psycopg`, and `mysql-python` conform to this interface. Tutorials that explain how to work with modules that conform to this interface can be found @@ -39,7 +39,7 @@ Records `Records `_ is minimalist SQL library, designed for sending raw SQL queries to various databases. Data can be used -programmatically, or exported to a number of useful data formats. +programmatically or exported to a number of useful data formats. .. code-block:: console @@ -73,11 +73,11 @@ peewee `peewee `_ is another ORM with a focus on being lightweight with support for Python 2.6+ and 3.2+ which supports -SQLite, MySQL and Postgres by default. The +SQLite, MySQL, and PostgreSQL by default. The `model layer `_ is similar to that of the Django ORM and it has `SQL-like methods `_ -to query data. While SQLite, MySQL and Postgres are supported out-of-the-box, +to query data. While SQLite, MySQL, and PostgreSQL are supported out-of-the-box, there is a `collection of add-ons `_ available. @@ -88,9 +88,9 @@ PonyORM `PonyORM `_ is an ORM that takes a different approach to querying the database. Instead of writing an SQL-like language or boolean -expressions, Python's generator syntax is used. There's also an graphical +expressions, Python's generator syntax is used. There's also a graphical schema editor that can generate PonyORM entities for you. It supports Python -2.6+ and Python 3.3+ and can connect to SQLite, MySQL, Postgres & Oracle +2.6+ and Python 3.3+ and can connect to SQLite, MySQL, PostgreSQL, and Oracle. ********* @@ -98,8 +98,8 @@ SQLObject ********* `SQLObject `_ is yet another ORM. It supports a wide -variety of databases: Common database systems MySQL, Postgres and SQLite and -more exotic systems like SAP DB, SyBase and MSSQL. It only supports Python 2 +variety of databases: common database systems like MySQL, PostgreSQL, and SQLite and +more exotic systems like SAP DB, SyBase, and Microsoft SQL Server. It only supports Python 2 from Python 2.6 upwards. -.. There's no official information on this on their page, this information was gathered by looking at their source code +.. There's no official information on this on their page; this information was gathered by looking at their source code. diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 6825a91ae..e012048bc 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -14,12 +14,12 @@ Camelot ******* `Camelot `_ provides components for building -applications on top of Python, SQLAlchemy and Qt. It is inspired by +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 mailing list https://groups.google.com/forum/#!forum/project-camelot +and the mailing list https://groups.google.com/forum/#!forum/project-camelot. ***** @@ -44,7 +44,7 @@ applications be ported from PyGTK to PyGObject. PyGObject aka (PyGi) ******************** -`PyGObject `_ provides Python bindings, which gives access to the entire GNOME software platform. +`PyGObject `_ provides Python bindings which gives access to the entire GNOME software platform. It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial `_. `API Reference `_ @@ -59,8 +59,8 @@ enabled media rich applications. The aim is to allow for quick and easy interaction design and rapid prototyping, while making your code reusable 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 +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 is free to use. It operates @@ -111,7 +111,7 @@ application source code to be executed as a standalone desktop application. `Python Wiki for PyjamasDesktop `_. -The main website; `pyjs Desktop `_. +The main website: `pyjs Desktop `_. ** @@ -127,13 +127,13 @@ non-GUI applications. PySimpleGUI *********** -`PySimpleGUI `_ is a wrapper for Tkinter and Qt (others on the way). The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using tkinter or Qt. PySimpleGUI code can be "ported" between GUI frameworks by changing import statement. +`PySimpleGUI `_ is a wrapper for Tkinter and Qt (others on the way). The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using Tkinter or Qt. PySimpleGUI code can be "ported" between GUI frameworks by changing import statements. .. code-block:: console $ pip install pysimplegui -PySimpleGUI is contained in a single PySimpleGUI.py file. Should pip installation be impossible, pasting the PySimpleGUI.py file into a project's folder is all that's required to import and begin using. +PySimpleGUI is contained in a single PySimpleGUI.py file. Should pip installation be impossible, copying the PySimpleGUI.py file into a project's folder is all that's required to import and begin using. **** @@ -145,7 +145,7 @@ native, cross platform GUI toolkit. Toga consists of a library of base components with a shared interface to simplify platform-agnostic GUI development. -Toga is available on Mac OS, Windows, Linux (GTK), and mobile platforms such +Toga is available on mOS, Windows, Linux (GTK), and mobile platforms such as Android and iOS. diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst index a6ba48fde..7b0e71935 100644 --- a/docs/scenarios/imaging.rst +++ b/docs/scenarios/imaging.rst @@ -6,7 +6,7 @@ Image Manipulation .. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg Most image processing and manipulation techniques can be carried out -effectively using two libraries: Python Imaging Library (PIL) and OpenSource +effectively using two libraries: Python Imaging Library (PIL) and Open Source Computer Vision (OpenCV). A brief description of both is given below. @@ -21,8 +21,8 @@ for short, is one of the core libraries for image manipulation in Python. Unfort its development has stagnated, with its last release in 2009. Luckily for you, there's an actively-developed fork of PIL called -`Pillow `_ - it's easier to install, runs on -all operating systems, and supports Python 3. +`Pillow `_ -- it's easier to install, runs on +all major operating systems, and supports Python 3. Installation ~~~~~~~~~~~~ @@ -65,11 +65,11 @@ There are more examples of the Pillow library in the `Pillow tutorial `_. -************************** -OpenSource Computer Vision -************************** +*************************** +Open Source Computer Vision +*************************** -OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced +Open Source Computer Vision, more commonly known as OpenCV, is a more advanced image manipulation and processing software than PIL. It has been implemented in several languages and is widely used. diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst index 6495724af..130ad3031 100644 --- a/docs/scenarios/json.rst +++ b/docs/scenarios/json.rst @@ -52,7 +52,7 @@ You can also convert the following to JSON: simplejson ********** -The JSON library was added to Python in version 2.6. +The json library was added to Python in version 2.6. If you're using an earlier version of Python, the `simplejson `_ library is available via PyPI. @@ -68,5 +68,5 @@ importing simplejson under a different name: import simplejson as json -After importing simplejson as json, the above examples will all work as if you +After importing simplejson as `json`, the above examples will all work as if you were using the standard json library. diff --git a/docs/scenarios/ml.rst b/docs/scenarios/ml.rst index baa0777de..71bdceb2d 100644 --- a/docs/scenarios/ml.rst +++ b/docs/scenarios/ml.rst @@ -6,16 +6,16 @@ Machine Learning .. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg -Python has a vast number of libraries for data analysis, statistics and Machine Learning itself, making it a language of choice for many data scientists. +Python has a vast number of libraries for data analysis, statistics, and Machine Learning itself, making it a language of choice for many data scientists. -Some widely used packages for Machine Learning and other Data Science applications are enlisted below. +Some widely used packages for Machine Learning and other data science applications are listed below. *********** -Scipy Stack +SciPy Stack *********** -The Scipy stack consists of a bunch of core helper packages used in data science, for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications. +The SciPy stack consists of a bunch of core helper packages used in data science for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications. The Stack consists of the following packages (link to documentation given): @@ -41,9 +41,9 @@ For installing the full stack, or individual packages, you can refer to the inst scikit-learn ************ -Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing. +Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks, etc. It also has a few sample datasets which can be directly used for training and testing. -Because of its speed, robustness and easiness to use, it's one of the most widely-used libraries for many Machine Learning applications. +Because of its speed, robustness, and ease of, it's one of the most widely-used libraries for many Machine Learning applications. Installation ~~~~~~~~~~~~ @@ -60,16 +60,16 @@ Through conda: conda install scikit-learn -scikit-learn also comes in shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link `_. +scikit-learn also comes shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link `_. Example ~~~~~~~ For this example, we train a simple classifier on the `Iris dataset `_, which comes bundled in with scikit-learn. -The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica). +The dataset takes four features of flowers: sepal length, sepal width, petal length, and petal width, and classifies them into three flower species (labels): setosa, versicolor, or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor), and 2 (virginica). -We shuffle the Iris dataset, and divide it into separate training and testing sets: keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set, and predict on the testing set. +We shuffle the Iris dataset and divide it into separate training and testing sets, keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set and predict on the testing set. .. code-block:: python @@ -120,6 +120,6 @@ Since we're splitting randomly and the classifier trains on every iteration, the [0 1 1 1 0 2 0 2 2 2] 100.0 -The first line contains the labels (i.e flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time. +The first line contains the labels (i.e. flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time. More on scikit-learn can be read in the `documentation `_. diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index d17eea824..f8306c70a 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -12,8 +12,8 @@ Twisted `Twisted `_ is an event-driven networking engine. It can be used to build applications around many different networking -protocols, including http servers and clients, applications using SMTP, POP3, -IMAP or SSH protocols, instant messaging +protocols, including HTTP servers and clients, applications using SMTP, POP3, +IMAP, or SSH protocols, instant messaging, and `much more `_. @@ -30,8 +30,8 @@ message queuing without a message broker. The basic patterns for this are: 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 +- 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 `_. diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 6bdb1c9db..6051e4586 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -16,11 +16,11 @@ and performs well. 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`_ +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 Python ecosystem can be found in the `Python Scientific Lecture Notes -`_ +`_. ***** @@ -35,7 +35,7 @@ which provides features of great interest to scientists. The `inline mode` 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 +store chunks of Python code alongside the results and additional comments (HTML, LaTeX, Markdown). The notebook can then be shared and exported in various file formats. @@ -48,7 +48,7 @@ NumPy ----- `NumPy `_ is a low level library written in C (and -FORTRAN) for high level mathematical functions. NumPy cleverly overcomes the +Fortran) for high level mathematical functions. NumPy cleverly overcomes the 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. @@ -57,7 +57,7 @@ NumPy is part of the SciPy project, and is released as a separate library so 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+. +NumPy is compatible with Python versions 2.4 through 2.7.2 and 3.1+. Numba ----- @@ -75,7 +75,7 @@ SciPy 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. +solving, and signal processing. Matplotlib ---------- @@ -84,7 +84,7 @@ Matplotlib 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 `_, easing transition of MATLAB -users to Python. Many examples, along with the source code to re-create them, +users to Python. Many examples, along with the source code to recreate them, are available in the `matplotlib gallery `_. @@ -92,10 +92,10 @@ Pandas ------ `Pandas `_ is data manipulation library -based on Numpy which provides many useful functions for accessing, -indexing, merging and grouping data easily. The main data structure (DataFrame) +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, -heterogeneous data tables with name indexing, time series operations and +heterogeneous data tables with name indexing, time series operations, and auto-alignment of data. Rpy2 @@ -112,7 +112,7 @@ PsychoPy `PsychoPy `_ is a library for cognitive scientists allowing the creation of cognitive psychology and neuroscience experiments. -The library handles presentation of stimuli, scripting of experimental design +The library handles presentation of stimuli, scripting of experimental design, and data collection. @@ -131,7 +131,7 @@ Unofficial Windows Binaries for Python Extension Packages 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 `_ +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 diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index bf61b29a7..3c7493f42 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -13,7 +13,7 @@ Web Scraping Web sites are written using HTML, which means that each web page is a structured document. Sometimes it would be great to obtain some data from them and preserve the structure while we're at it. Web sites don't always -provide their data in comfortable formats such as ``csv`` or ``json``. +provide their data in comfortable formats such as CSV or JSON. This is where web scraping comes in. Web scraping is the practice of using a computer program to sift through a web page and gather the data that you need @@ -41,7 +41,7 @@ Let's start with the imports: import requests 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``: +parse it using the ``html`` module, and save the results in ``tree``: .. code-block:: python @@ -62,10 +62,10 @@ HTML or XML documents. A good introduction to XPath is on There are also various tools for obtaining the XPath of elements such as FireBug for Firefox or the Chrome Inspector. If you're using Chrome, you can right click an element, choose 'Inspect element', highlight the code, -right click again and choose 'Copy XPath'. +right click again, and choose 'Copy XPath'. After a quick analysis, we see that in our page the data is contained in -two elements - one is a div with title 'buyer-name' and the other is a +two elements -- one is a div with title 'buyer-name' and the other is a span with class 'item-price': .. code-block:: html diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index 559ad3651..fefd88372 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -12,7 +12,7 @@ What is data serialization? Data serialization is the concept of converting structured data into a format that allows it to be shared or stored in such a way that its original -structure to be recovered. In some cases, the secondary intention of data +structure can be recovered. In some cases, the secondary intention of data serialization is to minimize the size of the serialized data which then minimizes disk space or bandwidth requirements. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 5d087e94c..485872360 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -200,8 +200,8 @@ These lines both need a remark: 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 +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 @@ -214,7 +214,7 @@ 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 is the output of an embedded `ARM beaglebone `_ machine: .. code-block:: console @@ -253,7 +253,7 @@ available. The ProcessPoolExecutor works in the same way, except instead of using multiple threads for its workers, it will use multiple processes. This makes it possible -to side-step the GIL, however because of the way things are passed to worker +to side-step the GIL; however, because of the way things are passed to worker processes, only picklable objects can be executed and returned. Because of the way the GIL works, a good rule of thumb is to use a @@ -264,7 +264,7 @@ executor when the task is computationally expensive. There are two main ways of executing things in parallel using the two Executors. One way is with the `map(func, iterables)` method. This works almost exactly like the builtin `map()` function, except it will execute -everything in parallel. : +everything in parallel. .. code-block:: python @@ -304,7 +304,7 @@ result() the scheduled callable returns by default. exception() Return the exception raised by the call. If no exception was raised then - this returns `None`. Note that this will block just like `result()`. + this returns None. Note that this will block just like `result()`. add_done_callback(fn) Attach a callback function that will be executed (as `fn(future)`) when the scheduled callable returns. @@ -357,14 +357,14 @@ futures provided have completed. For more information, on using the `concurrent.futures`_ module, consult the official documentation. -Threading +threading --------- The standard library comes with a `threading`_ module that allows a user to work with multiple threads manually. Running a function in another thread is as simple as passing a callable and -it's arguments to `Thread`'s constructor and then calling `start()`: +its arguments to `Thread`'s constructor and then calling `start()`: .. code-block:: python @@ -399,7 +399,7 @@ there might be situations where two or more threads are trying to write to the same resource at the same time or where the output is dependent on the sequence or timing of certain events. This is called a `data race`_ or race condition. When this happens, the output will be garbled or you may encounter problems -which are difficult to debug. A good example is this `stackoverflow post`_. +which are difficult to debug. A good example is this `Stack Overflow post`_. The way this can be avoided is by using a `Lock`_ that each thread needs to acquire before writing to a shared resource. Locks can be acquired and released diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 40b6656ce..bf5f1864a 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -41,7 +41,7 @@ URL Routing be invoked Request and Response Objects - Encapsulate the information received from or sent to a user's browser + Encapsulates the information received from or sent to a user's browser Template Engine Allows for separating Python code implementing an application's logic from @@ -105,14 +105,14 @@ It is a reliable, high-performance Python web framework for building large-scale app backends and microservices. Falcon encourages the REST architectural style of mapping URIs to resources, trying to do as little as possible while remaining highly effective. -Falcon highlights four main focuses: speed, reliability, flexibility and debuggability. +Falcon highlights four main focuses: speed, reliability, flexibility, and debuggability. It implements HTTP through "responders" such as ``on_get()``, ``on_put()``, etc. These responders receive intuitive request and response objects. Tornado -------- -`Tornado `_ is an asyncronous web framework +`Tornado `_ is an asynchronous web framework for Python that has its own event loop. This allows it to natively support WebSockets, for example. Well-written Tornado applications are known to have excellent performance characteristics. @@ -126,7 +126,7 @@ Pyramid focus on modularity. It comes with a small number of libraries ("batteries") built-in, and encourages users to extend its base functionality. A set of provided cookiecutter templates helps making new project decisions for users. -It poweres one of the most important parts of python infrastucture +It powers one of the most important parts of python infrastucture `PyPI `_. Pyramid does not have a large user base, unlike Django and Flask. It's a @@ -136,11 +136,11 @@ applications today. Masonite -------- -`Masonite `_ is a modern and developer centric, "batteries included", web framework. +`Masonite `_ is a modern and developer centric, "batteries included", web framework. The Masonite framework follows the MVC (Model-View-Controller) architecture pattern and is heavily inspired by frameworks such as Rails and Laravel, so if you are coming to Python from a Ruby or PHP background then you will feel right at home! -Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools and the Orator active record style ORM. +Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools, and the Orator active record style ORM. Masonite is perfect for beginners or experienced developers alike and works hard to be fast and easy from install through to deployment. Try it once and you’ll fall in love. @@ -155,7 +155,7 @@ Nginx ----- `Nginx `_ (pronounced "engine-x") is a web server and -reverse-proxy for HTTP, SMTP and other protocols. It is known for its +reverse-proxy for HTTP, SMTP, and other protocols. It is known for its high performance, relative simplicity, and compatibility with many application servers (like WSGI servers). It also includes handy features like load-balancing, basic authentication, streaming, and others. Designed @@ -177,9 +177,9 @@ servers and provide top performance [3]_. Gunicorn -------- -`Gunicorn `_ (Green Unicorn) is a pure-python WSGI +`Gunicorn `_ (Green Unicorn) is a pure-Python WSGI server used to serve Python applications. Unlike other Python web servers, -it has a thoughtful user-interface, and is extremely easy to use and +it has a thoughtful user interface, and is extremely easy to use and configure. Gunicorn has sane and reasonable defaults for configurations. However, some @@ -192,7 +192,7 @@ Gunicorn is the recommended choice for new Python web applications today. Waitress -------- -`Waitress `_ is a pure-python WSGI server +`Waitress `_ is a pure-Python WSGI server that claims "very acceptable performance". Its documentation is not very detailed, but it does offer some nice functionality that Gunicorn doesn't have (e.g. HTTP request buffering). @@ -207,13 +207,13 @@ uWSGI `uWSGI `_ is a full stack for building hosting services. In addition to process management, process monitoring, and other functionality, uWSGI acts as an application server for various -programming languages and protocols - including Python and WSGI. uWSGI can +programming languages and protocols -- including Python and WSGI. uWSGI can either be run as a stand-alone web router, or be run behind a full web server (such as Nginx or Apache). In the latter case, a web server can configure uWSGI and an application's operation over the `uwsgi protocol `_. uWSGI's web server support allows for dynamically configuring -Python, passing environment variables and further tuning. For full details, +Python, passing environment variables, and further tuning. For full details, see `uWSGI magic variables `_. @@ -275,7 +275,7 @@ Templating ********** Most WSGI applications are responding to HTTP requests to serve content in HTML -or other markup languages. Instead of generating directly textual content from +or other markup languages. Instead of directly generating textual content from Python, the concept of separation of concerns advises us to use templates. A template engine manages a suite of template files, with a system of hierarchy and inclusion to avoid unnecessary repetition, and is in charge of rendering @@ -313,10 +313,10 @@ Jinja2 `Jinja2 `_ is a very well-regarded template engine. It uses a text-based template language and can thus be used to generate any -type markup, not just HTML. It allows customization of filters, tags, tests +type of markup, not just HTML. It allows customization of filters, tags, tests, and globals. It features many improvements over Django's templating system. -Here some important html tags in Jinja2: +Here some important HTML tags in Jinja2: .. code-block:: html @@ -336,7 +336,7 @@ Here some important html tags in Jinja2: {% endfor %} -The next listings is an example of a web site in combination with the Tornado +The next listings are an example of a web site in combination with the Tornado web server. Tornado is not very complicated to use. .. code-block:: python @@ -434,12 +434,12 @@ engine implementation of the `Template Attribute Language (TAL) `_, and `Macro Expansion TAL (Metal) `_ syntaxes. -Chameleon is available for Python 2.5 and up (including 3.x and pypy), and +Chameleon is available for Python 2.5 and up (including 3.x and PyPy), and is commonly used by the `Pyramid Framework `_. Page Templates add within your document structure special element attributes and text markup. Using a set of simple language constructs, you control the -document flow, element repetition, text replacement and translation. Because +document flow, element repetition, text replacement, and translation. Because of the attribute-based syntax, unrendered page templates are valid HTML and can be viewed in a browser and even edited in WYSIWYG editors. This can make round-trip collaboration with designers and prototyping with static files in a @@ -493,7 +493,7 @@ Mako ---- `Mako `_ is a template language that compiles to Python -for maximum performance. Its syntax and api is borrowed from the best parts of other +for maximum performance. Its syntax and API are borrowed from the best parts of other templating languages like Django and Jinja2 templates. It is the default template language included with the `Pylons and Pyramid `_ web frameworks. diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index f9840cf92..91cafc5c4 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -30,13 +30,13 @@ can be loaded like this: import untangle obj = untangle.parse('path/to/file.xml') -and then you can get the child elements name like this: +and then you can get the child element's name attribute like this: .. code-block:: python obj.root.child['name'] -untangle also supports loading XML from a string or an URL. +untangle also supports loading XML from a string or a URL. ********* @@ -69,7 +69,7 @@ can be loaded into a Python dict like this: with open('path/to/file.xml') as fd: doc = xmltodict.parse(fd.read()) -and then you can access elements, attributes and values like this: +and then you can access elements, attributes, and values like this: .. code-block:: python @@ -79,5 +79,5 @@ and then you can access elements, attributes and values like this: doc['mydocument']['plus']['#text'] # == u'element as well' xmltodict also lets you roundtrip back to XML with the unparse function, -has a streaming mode suitable for handling files that don't fit in memory -and supports namespaces. +has a streaming mode suitable for handling files that don't fit in memory, +and supports XML namespaces. diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 5860cb5d4..99dcba293 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -23,7 +23,7 @@ Besides, end-user software should always be in an executable format. Files ending in ``.py`` are for software engineers and system administrators. One disadvantage of freezing is that it will increase the size of your -distribution by about 2–12MB. Also, you will be responsible for shipping +distribution by about 2–12 MB. Also, you will be responsible for shipping updated versions of your application when security vulnerabilities to Python are patched. @@ -60,12 +60,12 @@ py2app no no yes yes MIT no yes yes .. note:: Freezing Python code on Linux into a Windows executable was only once - supported in PyInstaller `and later dropped. + supported in PyInstaller `and later dropped `_. .. note:: - All solutions need MS Visual C++ dll to be installed on target machine, except py2app. - Only Pyinstaller makes self-executable exe that bundles the dll when + All solutions need a Microsoft Visual C++ to be installed on the target machine, except py2app. + Only PyInstaller makes a self-executable exe that bundles the appropriate DLL when passing ``--onefile`` to :file:`Configure.py`. @@ -97,7 +97,7 @@ Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Wi .. note:: This will work for the most basic one file scripts. For more advanced freezing you will have to provide - include and exclude paths like so + include and exclude paths like so: .. code-block:: python @@ -109,8 +109,8 @@ Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Wi freezer.setIcon('my_awesome_icon.ico') -4. Provide the Microsoft Visual C runtime DLL for the freezer. It might be possible to append your :code:`sys.path` -with Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script +4. Provide the Microsoft Visual C++ runtime DLL for the freezer. It might be possible to append your :code:`sys.path` +with the Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script resides. 5. Freeze! @@ -122,7 +122,7 @@ resides. py2exe ~~~~~~ -Prerequisite is to install :ref:`Python on Windows `. The last release of py2exe is from the year 2014. There is not active development. +Prerequisite is to install :ref:`Python on Windows `. The last release of py2exe is from the year 2014. There is not active development. 1. Download and install http://sourceforge.net/projects/py2exe/files/py2exe/ @@ -147,7 +147,7 @@ Prerequisite is to install :ref:`Python on Windows `. The last $ python setup.py py2exe -6. Provide the Microsoft Visual C runtime DLL. Two options: `globally install dll on target machine `_ or `distribute dll alongside with .exe `_. +6. Provide the Microsoft Visual C++ runtime DLL. Two options: `globally install dll on target machine `_ or `distribute dll alongside with .exe `_. PyInstaller ~~~~~~~~~~~ @@ -183,19 +183,19 @@ To create a standard Unix executable, from say :code:`script.py`, use: $ pyinstaller script.py -This creates, +This creates: - a :code:`script.spec` file, analogous to a :code:`make` file - a :code:`build` folder, that holds some log files -- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries, +- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder. -The :code:`script.spec` file can be edited to `customise the build `_, with options such as +The :code:`script.spec` file can be edited to `customise the build `_, with options such as: - bundling data files with the executable - including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically -- adding Python run-time options to the executable, +- adding Python run-time options to the executable Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again): @@ -203,7 +203,7 @@ Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :c $ pyinstaller script.spec -To create a standalone windowed OS X application, use the :code:`--windowed` option +To create a standalone windowed OS X application, use the :code:`--windowed` option: .. code-block:: console diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 9239184d4..0f0ff04d1 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -7,7 +7,7 @@ Packaging Your Code .. image:: /_static/photos/36137234682_be6898bf57_k_d.jpg -Package your code to share it with other developers. For example +Package your code to share it with other developers. For example, to share a library for other developers to use in their application, or for development tools like 'py.test'. @@ -18,7 +18,7 @@ large, professional systems. It is a well-established convention for Python code to be shared this way. If your code isn't packaged on PyPI, then it will be harder -for other developers to find it, and to use it as part of their existing +for other developers to find it and to use it as part of their existing process. They will regard such projects with substantial suspicion of being either badly managed or abandoned. @@ -57,14 +57,14 @@ Pip vs. easy_install -------------------- Use `pip `_. More details -`here `_ +`here `_. Personal PyPI ------------- -If you want to install packages from a source other than PyPI, (say, if -your packages are *proprietary*), you can do it by hosting a simple http +If you want to install packages from a source other than PyPI (say, if +your packages are *proprietary*), you can do it by hosting a simple HTTP server, running from the directory which holds those packages which need to be installed. @@ -85,9 +85,9 @@ Go to your command prompt and type: $ cd archive $ python -m SimpleHTTPServer 9000 -This runs a simple http server running on port 9000 and will list all packages +This runs a simple HTTP server running on port 9000 and will list all packages (like **MyPackage**). Now you can install **MyPackage** using any Python -package installer. Using Pip, you would do it like: +package installer. Using pip, you would do it like: .. code-block:: console @@ -95,7 +95,7 @@ package installer. Using Pip, you would do it like: Having a folder with the same name as the package name is **crucial** here. I got fooled by that, one time. But if you feel that creating a folder called -:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that, is +:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that is *redundant*, you can still install MyPackage using: .. code-block:: console @@ -105,7 +105,7 @@ I got fooled by that, one time. But if you feel that creating a folder called pypiserver ++++++++++ -`Pypiserver `_ is a minimal PyPI +`pypiserver `_ is a minimal PyPI compatible server. It can be used to serve a set of packages to easy_install or pip. It includes helpful features like an administrative command (``-U``) which will update all its packages to their latest versions @@ -115,7 +115,7 @@ found on PyPI. S3-Hosted PyPi ++++++++++++++ -One simple option for a personal PyPi server is to use Amazon S3. A +One simple option for a personal PyPI server is to use Amazon S3. A prerequisite for this is that you have an Amazon AWS account with an S3 bucket. 1. **Install all your requirements from PyPi or another source** @@ -130,8 +130,8 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket. 4. **Upload the new files** -* Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket -* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories +* Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket. +* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories. 5. **Fix new file permissions** @@ -141,7 +141,7 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket. 6. **All done** -* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage` +* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`. .. _packaging-for-linux-distributions-ref: @@ -154,7 +154,7 @@ Creating a Linux distro package is arguably the "right way" to distribute code on Linux. Because a distribution package doesn't include the Python interpreter, it -makes the download and install about 2MB smaller than +makes the download and install about 2-12 MB smaller than :ref:`freezing your application `. Also, if a distribution releases a new security update for Python, then your @@ -165,7 +165,7 @@ for use by distributions like Red Hat or SuSE trivially easy. However, creating and maintaining the different configurations required for each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red -Hat/Fedora, etc) is a fair amount of work. If your code is an application that +Hat/Fedora, etc.) is a fair amount of work. If your code is an application that you plan to distribute on other platforms, then you'll also have to create and maintain the separate config required to freeze your application for Windows and OS X. It would be much less work to simply create and maintain a single