kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 06:46:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #867 from kennethreitz/master

Browse Source 
Added in speed section
This commit is contained in:
Kenneth Reitz
2018-01-08 09:58:00 -05:00
committed by GitHub
parent 4a7336f8ff d626196d63
commit 6092a1a533
56 changed files with 1106 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODE_OF_CONDUCT.md
+3
View File
@@ -0,0 +1,3 @@
Be cordial or be on your way.
https://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way
Readme.rst
+3 -1
View File
@@ -3,6 +3,8 @@ Hitchhiker's Guide to Python
**Python Best Practices Guidebook**
.. image:: https://farm1.staticflickr.com/628/33173824932_58add34581_k_d.jpg
-----------
**Work in progress. If you'd like to help, please do. There's a lot of work to
@@ -16,7 +18,7 @@ basis.
Topics include:
- Platform- and version-specific installations
- Platform and version-specific installations
- Py2app, Py2exe, bbfreeze, pyInstaller
- Pip
- Numpy, scipy, statpy, pyplot, matplotlib
docs/_static/ad.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 83 KiB

docs/_templates/hacks.html
Vendored
+31
View File
@@ -1,3 +1,34 @@
<!-- Alabaster (krTheme++) Hacks -->
<aside id="python27">
Python 3, the new best practice, is here to stay.
Python 2 will retire in only <time></time> months!
</aside>
<!-- Python 2 Death Clock™ -->
<style type="text/css">
body { margin-top: 4em; }
#python27 {
position: fixed;
top: 0;
left: 0; right: 0;
height: auto;
text-align: center;
color: white;
background-color: black;
font-size: larger;
line-height: 3;
}
</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
<script>
var death = new Date('2020-04-12');
var diff = moment.duration(death - moment());
document.querySelector('#python27 time').innerText = (diff.years() * 12) + diff.months();
</script>
<script type="text/javascript">
var _gauges = _gauges || [];
(function() {
docs/_templates/sidebarintro.html
Vendored
+13 -2
View File
@@ -19,6 +19,13 @@
<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow @kennethreitz</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script></p>
<p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
<p><a href="https://saythanks.io/to/kennethreitz">Say Thanks!</a></p>
<a href="http://www.dataquest.io/?utm_source=hitchhikersguide&utm_medium=ad">
<img src="{{ pathto('_static/ad.png', 1) }}" alt="">
</a>
<hr>
<h3>O'Reilly Book</h3>
@@ -32,12 +39,15 @@
<p>More <a href="http://kennethreitz.org/">Kenneth Reitz</a> projects:</p>
<ul>
<li><a href="http://wsl-guide.org/">wsl-guide.org</a></li>
<li><a href="http://edmsynths.com/">edmsynths.com</a></li>
<li><a href="http://pipenv.org/">pipenv</a></li>
<li><a href="http://pep8.org/">pep8.org</a></li>
<li><a href="http://python-requests.org">Requests: HTTP for Humans</a></li>
<li><a href="https://github.com/kennethreitz/maya">Maya: Datetimes for Humans</a></li>
<li><a href="https://github.com/kennethreitz/records">Records: SQL for Humans</a></li>
<li><a href="http://www.git-legit.org">Legit: Git for Humans</a></li>
<li><a href="http://docs.python-tablib.org/en/latest/">Tablib: Tabular Datasets</a></li>
<li><a href="http://markdownplease.com">Markdown, Please!</a></li>
</ul>
<h3>Contributors</h3>
@@ -62,6 +72,7 @@
<li><a href="http://docs.python-guide.org/en/latest/">English</a></li>
<li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
<li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
<li><a href="https://python-guide-ja.readthedocs.io/en/latest/">Japanese</a></li>
<li><a href="http://python-guideja.readthedocs.io/ja/latest/">Japanese</a></li>
<li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
<li><a href="http://python-guide-pt-br.readthedocs.io/pt_BR/latest/">Brazilian Portuguese</a></li>
</ul>
docs/_templates/sidebarlogo.html
Vendored
+15 -3
View File
@@ -16,9 +16,15 @@
allowtransparency="true" frameborder="0" scrolling="0" width="200" height="20"></iframe></p>
<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow @kennethreitz</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script></p>
<p><a href="https://saythanks.io/to/kennethreitz">Say Thanks!</a></p>
<p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
<a href="http://www.dataquest.io/?utm_source=hitchhikersguide&utm_medium=ad">
<img src="{{ pathto('_static/ad.png', 1) }}" alt="">
</a>
<hr>
<h3>O'Reilly Book</h3>
<p>This guide is now available in tangible book form!</p>
@@ -27,16 +33,21 @@
<p>All proceeds are being directly donated to the <a href="https://djangogirls.org">DjangoGirls</a> organization.</p>
<h3>Other Projects</h3>
<p>More <a href="http://kennethreitz.org/">Kenneth Reitz</a> projects:</p>
<ul>
<li><a href="http://wsl-guide.org/">wsl-guide.org</a></li>
<li><a href="http://edmsynths.com/">edmsynths.com</a></li>
<li><a href="http://pipenv.org/">pipenv</a></li>
<li><a href="http://pep8.org/">pep8.org</a></li>
<li><a href="http://python-requests.org">Requests: HTTP for Humans</a></li>
<li><a href="https://github.com/kennethreitz/maya">Maya: Datetimes for Humans</a></li>
<li><a href="https://github.com/kennethreitz/records">Records: SQL for Humans</a></li>
<li><a href="http://www.git-legit.org">Legit: Git for Humans</a></li>
<li><a href="http://docs.python-tablib.org/en/latest/">Tablib: Tabular Datasets</a></li>
<li><a href="http://markdownplease.com">Markdown, Please!</a></li>
</ul>
<h3>Translations</h3>
@@ -44,6 +55,7 @@
<li><a href="http://docs.python-guide.org/en/latest/">English</a></li>
<li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
<li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
<li><a href="https://python-guide-ja.readthedocs.io/en/latest/">Japanese</a></li>
<li><a href="http://python-guideja.readthedocs.io/ja/latest/">Japanese</a></li>
<li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
<li><a href="http://python-guide-pt-br.readthedocs.io/pt_BR/latest/">Brazilian Portuguese</a></li>
</ul>
docs/conf.py
+2 -1
View File
@@ -109,7 +109,8 @@ html_theme_options = {
'github_user': 'kennethreitz',
'github_repo': 'python-guide',
'github_banner': True,
'show_related': False
'show_related': False,
'note_bg': '#FFF59C'
}
# Add any paths that contain custom themes here, relative to this directory.
docs/contents.rst.inc
+28 -18
View File
@@ -1,24 +1,50 @@
Getting Started with Python
---------------------------
New to Python? Let's properly setup up your Python environment.
New to Python? Let's properly setup up your Python environment:
.. toctree::
:maxdepth: 2
starting/which-python
- Properly Install Python
- Properly Install Python on your system:
.. toctree::
:maxdepth: 1
starting/installation
starting/install3/osx
starting/install3/win
starting/install3/linux
starting/install/osx
starting/install/win
starting/install/linux
- Using Virtualenvs with Pipenv:
.. toctree::
:maxdepth: 2
dev/virtualenvs
Python Development Environments
-------------------------------
This part of the guide focus on the Python development environment,
and the best-practice tools that are available for writing Python code.
.. toctree::
:maxdepth: 2
dev/env
dev/virtualenvs
dev/pip-virtualenv
Writing Great Python Code
-------------------------
@@ -80,22 +106,6 @@ This part of the guide focuses on deploying your Python code.
shipping/freezing
Python Development Environments
-------------------------------
This part of the guide focus on the Python development environment,
and the best-practice tools that are available for writing Python code.
.. toctree::
:maxdepth: 2
dev/env
dev/virtualenvs
dev/pip-virtualenv
Additional Notes
----------------
docs/dev/env.rst
+11 -9
View File
@@ -1,6 +1,8 @@
Your Development Environment
============================
.. image:: https://farm3.staticflickr.com/2930/33175624924_7febc46cc4_k_d.jpg
Text Editors
::::::::::::
@@ -35,11 +37,11 @@ source files.
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 plugins to do these checks from within the editor.
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 pycodestyle_ and Pyflakes_ will do this
for you. If your Vim is compiled with ``+python`` you can also utilize some
very handy plugins to do these checks from within the editor.
For PEP8 checking and pyflakes, you can install vim-flake8_. Now you can map the
function ``Flake8`` to any hotkey or action you want in Vim. The plugin will
@@ -68,12 +70,12 @@ Python-mode
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
- Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pycodestyle``, ``mccabe``) in any combination
- Code refactoring and autocompletion with Rope
- Fast Python folding
- Virtualenv support
- Search through Python documentation and run Python code
- Auto PEP8_ error fixes
- Auto pycodestyle_ error fixes
And more.
@@ -86,7 +88,7 @@ using ``<Tab>`` key or any other customized keys.
.. _indent: http://www.vim.org/scripts/script.php?script_id=974
.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
.. _PEP8: http://pypi.python.org/pypi/pep8/
.. _pycodestyle: https://pypi.python.org/pypi/pycodestyle/
.. _syntastic: https://github.com/scrooloose/syntastic
.. _Python-mode: https://github.com/klen/python-mode
.. _SuperTab: http://www.vim.org/scripts/script.php?script_id=1643
@@ -151,7 +153,7 @@ versions of PyCharm: Professional Edition (Free 30-day trial) and Community
Edition (Apache 2.0 License) with fewer features.
Python (on Visual Studio Code)
-----------------------------
------------------------------
`Python for Visual Studio <https://marketplace.visualstudio.com/items?itemName=donjayamanne.python>`_ is an extension for the `Visual Studio Code IDE <https://code.visualstudio.com>`_.
This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux.
docs/dev/pip-virtualenv.rst
+4 -2
View File
@@ -3,6 +3,8 @@
Further Configuration of Pip and Virtualenv
===========================================
.. image:: https://farm4.staticflickr.com/3934/34018732105_f0e6758859_k_d.jpg
Requiring an active virtual environment for ``pip``
---------------------------------------------------
@@ -18,8 +20,8 @@ environment of the project. Over time this can result in a messy global package
list.
In order to make sure that you install packages to your active virtual
environment when you use ``pip install``, consider adding the following two
lines to your :file:`~/.bashrc` file:
environment when you use ``pip install``, consider adding the following
line to your :file:`~/.bashrc` file:
.. code-block:: console
docs/dev/virtualenvs.rst
+221 -26
View File
@@ -1,29 +1,219 @@
.. _virtualenvironments-ref:
Virtual Environments
====================
Pipenv & Virtual Environments
=============================
A Virtual Environment is a tool to keep the dependencies required by different
projects in separate places, by creating virtual Python environments for them.
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.
.. image:: https://farm5.staticflickr.com/4290/35294660055_42c02b2316_k_d.jpg
For example, you can work on a project which requires Django 1.10 while also
maintaining a project which requires Django 1.8.
This tutorial walks you through installing and using Python packages.
virtualenv
It will show you how to install and use the necessary tools and make strong
recommendations on best practices. Keep in mind that Python is used for a great
many different purposes, and precisely how you want to manage your dependencies
may change based on how you decide to publish your software. The guidance
presented here is most directly applicable to the development and deployment of
network services (including web applications), but is also very well suited to
managing development and testing environments for any kind of project.
.. Note:: This guide is written for Python 3, however, these instructions
should work fine on Python 2.7—if you are still using it, for some reason.
Make sure you've got Python & pip
---------------------------------
Before you go any further, make sure you have Python and that it's available
from your command line. You can check this by simply running:
.. code-block:: bash
$ python --version
You should get some output like ``3.6.2``. If you do not have Python, please
install the latest 3.x version from `python.org`_ or refer to the
`Installing Python`_ section of this guide.
.. Note:: If you're newcomer and you get an error like this:
.. code-block:: python
>>> python
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined
It's because this command is intended to be run in a *shell* (also called
a *terminal* or *console*). See the Python for Beginners
`getting started tutorial`_ for an introduction to using your operating
system's shell and interacting with Python.
Additionally, you'll need to make sure you have :ref:`pip` available. You can
check this by running:
.. code-block:: bash
$ pip --version
If you installed Python from source, with an installer from `python.org`_, or
via `Homebrew`_ you should already have pip. If you're on Linux and installed
using your OS package manager, you may have to `install pip <https://pip.pypa.io/en/stable/installing/>`_ separately.
.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
.. _python.org: https://python.org
.. _Homebrew: https://brew.sh
.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
Installing Pipenv
-----------------
:ref:`Pipenv` is a dependency manager for Python projects. If you're familiar
with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
tools. While :ref:`pip` can install Python packages, Pipenv is recommended as
it's a higher-level tool that simplifies dependency management for common use
cases.
Use ``pip`` to install Pipenv:
.. code-block:: python
$ pip install --user pipenv
.. Note:: This does a `user installation`_ to prevent breaking any system-wide
packages. If ``pipenv`` isn't available in your shell after installation,
you'll need to add the `user base`_'s binary directory to your ``PATH``.
On Linux and macOS you can find the user base binary directory by running
``python -m site --user-base`` and adding ``bin`` to the end. For example,
this will typically print ``~/.local`` (with ``~`` expanded to the
absolute path to your home directory) so you'll need to add
``~/.local/bin`` to your ``PATH``. You can set your ``PATH`` permanently by
`modifying ~/.profile`_.
On Windows you can find the user base binary directory by running
``py -m site --user-site`` and replacing ``site-packages`` with
``Scripts``. For example, this could return
``C:\Users\Username\AppData\Roaming\Python36\site-packages`` so you would
need to set your ``PATH`` to include
``C:\Users\Username\AppData\Roaming\Python36\Scripts``. You can set your
user ``PATH`` permanently in the `Control Panel`_. You may need to log
out for the ``PATH`` changes to take effect.
.. _npm: https://www.npmjs.com/
.. _bundler: http://bundler.io/
.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
Installing packages for your project
------------------------------------
Pipenv manages dependencies on a per-project basis. To install packages,
change into your project's directory (or just an empty directory for this
tutorial) and run:
.. code-block:: bash
$ cd myproject
$ pipenv install requests
Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
for you in your project's directory. The :ref:`Pipfile` is used to track which
dependencies your project needs in case you need to re-install them, such as
when you share your project with others. You should get output similar to this
(although the exact paths shown will vary):
.. code-block:: text
Creating a Pipfile for this project...
Creating a virtualenv for this project...
Using base prefix '/usr/local/Cellar/python3/3.6.2/Frameworks/Python.framework/Versions/3.6'
New python executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python3.6
Also creating executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python
Installing setuptools, pip, wheel...done.
Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
Installing requests...
Collecting requests
Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
Using cached idna-2.6-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Installing collected packages: idna, urllib3, chardet, certifi, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
Adding requests to Pipfile's [packages]...
P.S. You have excellent taste! ✨ 🍰 ✨
.. _Requests: https://python-requests.org
Using installed packages
------------------------
Now that Requests is installed you can create a simple ``main.py`` file to
use it:
.. code-block:: python
import requests
response = requests.get('https://httpbin.org/ip')
print('Your IP is {0}'.format(response.json()['origin']))
Then you can run this script using ``pipenv run``:
.. code-block:: bash
$ pipenv run python main.py
You should get output similar to this:
.. code-block:: text
Your IP is 8.8.8.8
Using ``$ pipenv run`` ensures that your installed packages are available to
your script. It's also possible to spawn a new shell that ensures all commands
have access to your installed packages with ``$ pipenv shell``.
Next steps
----------
Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨
Lower level: virtualenv
=======================
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
isolated Python environments. virtualenv creates a folder which contains all the
necessary executables to use the packages that a Python project would need.
It can be used standalone, in place of Pipenv.
Install virtualenv via pip:
.. code-block:: console
$ pip install virtualenv
Test your installation
.. code-block:: console
$ virtualenv --version
Basic Usage
~~~~~~~~~~~
@@ -32,35 +222,40 @@ Basic Usage
.. code-block:: console
$ cd my_project_folder
$ virtualenv venv
$ virtualenv my_project
``virtualenv venv`` will create a folder in the current directory which will
``virtualenv my_project`` will create a folder in the current directory which will
contain the Python executable files, and a copy of the ``pip`` library which you
can use to install other packages. The name of the virtual environment (in this
case, it was ``venv``) can be anything; omitting the name will place the files
case, it was ``my_project``) can be anything; omitting the name will place the files
in the current directory instead.
This creates a copy of Python in whichever directory you ran the command in,
placing it in a folder named :file:`venv`.
placing it in a folder named :file:`my_project`.
You can also use a Python interpreter of your choice.
You can also use the Python interpreter of your choice (like
``python2.7``).
.. code-block:: console
$ virtualenv -p /usr/bin/python2.7 venv
$ virtualenv -p /usr/bin/python2.7 my_project
This will use the Python interpreter in :file:`/usr/bin/python2.7`
or change the interpreter globally with an env variable in ``~/.bashrc``:
.. code-block:: console
$ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
2. To begin using the virtual environment, it needs to be activated:
.. code-block:: console
$ source venv/bin/activate
$ source my_project/bin/activate
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
the prompt (e.g. ``(my_project)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.
placed in the ``my_project`` folder, isolated from the global Python installation.
Install packages as usual, for example:
@@ -79,7 +274,7 @@ This puts you back to the system's default Python interpreter with all its
installed libraries.
To delete a virtual environment, just delete its folder. (In this case,
it would be ``rm -rf venv``.)
it would be ``rm -rf my_project``.)
After a while, though, you might end up with a lot of virtual environments
littered across your system, and its possible you'll forget their names or
@@ -88,7 +283,7 @@ where they were placed.
Other Notes
~~~~~~~~~~~
Running ``virtualenv`` with the option :option:`--no-site-packages` will not
Running ``virtualenv`` with the option ``--no-site-packages`` will not
include the packages that are installed globally. This can be useful
for keeping the package list clean in case it needs to be accessed later.
[This is the default behavior for ``virtualenv`` 1.7 and later.]
@@ -115,7 +310,7 @@ This can help ensure consistency across installations, across deployments,
and across developers.
Lastly, remember to exclude the virtual environment folder from source
control by adding it to the ignore list.
control by adding it to the ignore list (see :ref:`Version Control Ignores<version_control_ignores>`).
.. _virtualenvwrapper-ref:
@@ -153,18 +348,18 @@ Basic Usage
.. code-block:: console
$ mkvirtualenv venv
$ mkvirtualenv my_project
This creates the :file:`venv` folder inside :file:`~/Envs`.
This creates the :file:`my_project` folder inside :file:`~/Envs`.
2. Work on a virtual environment:
.. code-block:: console
$ workon venv
$ workon my_project
Alternatively, you can make a project, which creates the virtual environment,
and also a project directory inside ``$PROJECT_HOME``, which is ``cd`` -ed into
and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into
when you ``workon myproject``.
.. code-block:: console
docs/index.rst
+2
View File
@@ -20,6 +20,8 @@ This guide is **opinionated** in a way that is almost, but not quite, entirely
available here. Rather, you'll find a nice concise list of highly recommended
options.
.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
—*Kenneth Reitz*
Let's get started! But first, let's make sure you know where your towel is.
docs/intro/community.rst
+2
View File
@@ -3,6 +3,8 @@
The Community
=============
.. image:: https://farm5.staticflickr.com/4225/34689432801_78d97ecec9_k_d.jpg
BDFL
----
docs/intro/documentation.rst
+2
View File
@@ -1,6 +1,8 @@
Documentation
=============
.. image:: https://farm5.staticflickr.com/4178/33928823133_2f3d32cf32_k_d.jpg
Official Documentation
----------------------
docs/intro/duction.rst
+2
View File
@@ -1,6 +1,8 @@
Introduction
============
.. image:: https://farm5.staticflickr.com/4180/34725946825_0f85497e60_k_d.jpg
From the `official Python website <http://python.org/about/>`_:
Python is a general-purpose, high-level programming language similar
docs/intro/learning.rst
+25 -2
View File
@@ -1,6 +1,8 @@
Learning Python
===============
.. image:: https://farm3.staticflickr.com/2840/32800783863_11a00db52c_k_d.jpg
Beginner
--------
@@ -23,6 +25,14 @@ At last it finishes off with tutorial "How to access MySQL db using python"
`Python for beginners <http://thepythonguru.com/>`_
Learn Python for Data Science Interactively
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you prefer an online interactive environment to learn Python for Data Science, `this free python tutorial by DataCamp <https://www.datacamp.com/courses/intro-to-python-for-data-science?tap_a=5644-dce66f&tap_s=116411-750171>`_ is a great way to get started. If you're already somewhat advanced and interested in machine learning, check out this `course on Supervised Learning with scikit-learn <https://www.datacamp.com/courses/supervised-learning-with-scikit-learn?tap_a=5644-dce66f&tap_s=116411-750171>`_, by one the core developers of scikit-learn.
`Python for data science <http://datacamp.com/?tap_a=5644-dce66f&tap_s=116411-750171>`_
Learn Python Interactive Tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -39,6 +49,15 @@ If you want a more traditional book, *Python For You and Me* is an excellent
resource for learning all aspects of the language.
`Python for You and Me <https://pymbook.readthedocs.io/>`_
`Learn Python Interactively with DataCamp! <https://www.datacamp.com/>`_
Learn Python Step by Step
~~~~~~~~~~~~~~~~~~~~~~~~~
Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial is supplemented with logically added coding snippets and equips with a follow-up quiz on the subject learned. There is a section for `Python interview questions <http://www.techbeamers.com/python-interview-questions-programmers>`_ to help job seekers. You can also read essential `Python tips <http://www.techbeamers.com/essential-python-tips-tricks-programmers>`_ and learn `best coding practices <http://www.techbeamers.com/python-code-optimization-tips-tricks>`_ for writing quality code. Here, you'll get the right platform to learn Python quickly.
`Learn Python Basic to Advanced <http://www.techbeamers.com/python-tutorial-step-by-step>`_
Online Python Tutor
~~~~~~~~~~~~~~~~~~~
@@ -97,7 +116,7 @@ Dive Into Python 3 is a good book for those ready to jump in to Python 3. It's
a good read if you are moving from Python 2 to 3 or if you already have some
experience programming in another language.
`Dive Into Python 3 <http://www.diveinto.org/python3/>`_
`Dive Into Python 3 <http://www.diveintopython3.net/>`_
Think Python: How to Think Like a Computer Scientist
@@ -145,7 +164,7 @@ A free introductory book that teaches Python at the beginner level, it assumes
no previous programming experience.
`A Byte of Python for Python 2.x <http://www.ibiblio.org/swaroopch/byteofpython/read/>`_
`A Byte of Python for Python 3.x <http://swaroopch.com/notes/Python_en-Preface/>`_
`A Byte of Python for Python 3.x <https://python.swaroopch.com/>`_
Learn to Program in Python with Codeacademy
@@ -210,6 +229,10 @@ and can make classes and objects behave in different and magical ways.
`A Guide to Python's Magic Methods <http://www.rafekettler.com/magicmethods.html>`_
.. note:: The 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) <https://github.com/RafeKettler/magicmethods/blob/master/magicmethods.pdf>`_
For Engineers and Scientists
----------------------------
docs/intro/news.rst
+17 -1
View File
@@ -1,6 +1,8 @@
News
====
.. image:: https://farm4.staticflickr.com/3804/33573767786_eececc5d27_k_d.jpg
Planet Python
~~~~~~~~~~~~~
@@ -16,6 +18,20 @@ Python-related news.
`/r/python <http://reddit.com/r/python>`_
Talk Python Podcast
~~~~~~~~~~~~~~~~~~~
The #1 Python-focused podcast covering the people and ideas in Python.
`Talk Python To Me <https://talkpython.fm>`_
Python Bytes Podcast
~~~~~~~~~~~~~~~~~~~~
A short-form Python podcast covering recent developer headlines.
`Python Bytes <https://pythonbytes.fm>`_
Pycoder's Weekly
~~~~~~~~~~~~~~~~
@@ -49,7 +65,7 @@ delivered in your inbox. Keep Your Python Programming Skills Updated.
`Import Python Weekly Newsletter <http://www.importpython.com/newsletter/>`_
Awesome Python Newsletter
~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
A weekly overview of the most popular Python news, articles and packages.
docs/notes/contribute.rst
+2
View File
@@ -1,6 +1,8 @@
Contribute
~~~~~~~~~~
.. image:: https://farm3.staticflickr.com/2858/33573769116_49c1ef51e7_k_d.jpg
Python-guide is under active development, and contributors are welcome.
If you have a feature request, suggestion, or bug report, please open a new
docs/notes/license.rst
+2
View File
@@ -2,4 +2,6 @@
License
=======
.. image:: https://farm4.staticflickr.com/3762/32800805573_568d6b72fd_k_d.jpg
The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license <https://creativecommons.org/licenses/by-nc-sa/3.0/>`_.
docs/notes/styleguide.rst
+2
View File
@@ -4,6 +4,8 @@
The Guide Style Guide
=====================
.. image:: https://farm4.staticflickr.com/3684/33573755856_7f43d43adf_k_d.jpg
As with all documentation, having a consistent format helps make the
document more understandable. In order to make The Guide easier to digest,
all contributions should fit within the rules of this style guide where
docs/scenarios/admin.rst
+3 -1
View File
@@ -1,6 +1,8 @@
Systems Administration
======================
.. image:: https://farm5.staticflickr.com/4179/34435690580_3afec7d4cd_k_d.jpg
Fabric
------
@@ -131,7 +133,7 @@ State files can be written using YAML, the Jinja2 template system or pure Python
Psutil
------
`Psutil <https://code.google.com/p/psutil/>`_ is an interface to different
`Psutil <https://github.com/giampaolo/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
docs/scenarios/ci.rst
+5 -1
View File
@@ -1,6 +1,10 @@
Continuous Integration
======================
.. image:: https://farm5.staticflickr.com/4173/33907150594_9abba7ad0a_k_d.jpg
.. note::
For advice on writing your tests, see :doc:`/writing/tests`.
Why?
----
@@ -77,7 +81,7 @@ 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 <http://about.travis-ci.org/docs/>`_
and much more. The `travis-ci docs <https://docs.travis-ci.com/user/languages/python/>`_
explain all of these options, and are very thorough.
In order to activate testing for your project, go to `the travis-ci site <https://travis-ci.org/>`_
docs/scenarios/cli.rst
+3 -1
View File
@@ -1,6 +1,8 @@
Command-line Applications
=========================
.. image:: https://farm5.staticflickr.com/4272/34435690330_11930b5987_k_d.jpg
Command-line applications, also referred to as
`Console Applications <http://en.wikipedia.org/wiki/Console_application>`_,
are computer programs designed to be used from a text interface, such as a
@@ -30,7 +32,7 @@ column printer, iterator based progress bars and implicit argument handling.
Click
-----
`click <http://click.pocoo.org/>`_ is an upcoming Python package for creating
`click <http://click.pocoo.org/>`_ 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
configurable but comes with good defaults out of the box.
docs/scenarios/clibs.rst
+4 -1
View File
@@ -1,6 +1,8 @@
Interfacing with C/C++ Libraries
================================
.. image:: https://farm5.staticflickr.com/4173/34725951345_c8f5959a2e_k_d.jpg
C Foreign Function Interface
----------------------------
@@ -96,9 +98,10 @@ Example: Overloading __repr__
std::string getName();
};
:file:`myclass.i`
.. code-block:: c++
.. code-block:: idl
:linenos:
%include "string.i"
docs/scenarios/client.rst
+1 -1
View File
@@ -1,7 +1,7 @@
Network Applications
====================
.. image:: https://farm5.staticflickr.com/4251/34364815780_bea6614025_k_d.jpg
HTTP
::::
docs/scenarios/crypto.rst
+2
View File
@@ -1,6 +1,8 @@
Cryptography
============
.. image:: https://farm5.staticflickr.com/4220/33907152824_bf91078cc1_k_d.jpg
Cryptography
------------
docs/scenarios/db.rst
+2
View File
@@ -1,6 +1,8 @@
Databases
=========
.. image:: https://farm5.staticflickr.com/4225/33907152464_a99fdcc8de_k_d.jpg
DB-API
------
docs/scenarios/gui.rst
+13
View File
@@ -1,6 +1,9 @@
GUI Applications
================
.. image:: https://farm5.staticflickr.com/4250/33907143624_cd621b535c_k_d.jpg
Alphabetical list of GUI Applications.
Camelot
@@ -85,6 +88,16 @@ Qt
is widely used for developing software with a GUI but can also be used for
non-GUI applications.
Toga
----
`Toga <https://toga.readthedocs.io/en/latest/>`_ is a Python native, OS
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
as Android and iOS.
Tk
--
Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
docs/scenarios/imaging.rst
+2
View File
@@ -2,6 +2,8 @@
Image Manipulation
==================
.. image:: https://farm5.staticflickr.com/4157/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
Computer Vision (OpenCV).
docs/scenarios/json.rst
+2
View File
@@ -1,6 +1,8 @@
JSON
====
.. image:: https://farm5.staticflickr.com/4174/33928819683_97b5c6a184_k_d.jpg
The `json <https://docs.python.org/2/library/json.html>`_ library can parse
JSON from strings or files. The library parses JSON into a Python dictionary
or list. It can also convert Python dictionaries or lists into JSON strings.
docs/scenarios/ml.rst
+2
View File
@@ -2,6 +2,8 @@
Machine Learning
================
.. image:: https://farm4.staticflickr.com/3954/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.
Some widely used packages for Machine Learning and other Data Science applications are enlisted below.
docs/scenarios/network.rst
+2
View File
@@ -1,6 +1,8 @@
Networking
==========
.. image:: https://farm3.staticflickr.com/2892/34151833832_6bdfd930af_k_d.jpg
Twisted
-------
docs/scenarios/scientific.rst
+2
View File
@@ -2,6 +2,8 @@
Scientific Applications
=======================
.. image:: https://farm3.staticflickr.com/2890/33925223870_97e44f5629_k_d.jpg
Context
:::::::
docs/scenarios/scrape.rst
+5 -1
View File
@@ -1,6 +1,8 @@
HTML Scraping
=============
.. image:: https://farm3.staticflickr.com/2900/34268661876_442428e122_k_d.jpg
Web Scraping
------------
@@ -49,7 +51,7 @@ will focus on the former.
XPath is a way of locating information in structured documents such as
HTML or XML documents. A good introduction to XPath is on
`W3Schools <http://www.w3schools.com/xsl/xpath_intro.asp>`_ .
`W3Schools <http://www.w3schools.com/xml/xpath_intro.asp>`_ .
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
@@ -103,3 +105,5 @@ using Python or we can save it to a file and share it with the world.
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.
If you want to learn how to import data using python - this `DataCamp course on Importing Data <https://www.datacamp.com/courses/importing-data-in-r-part-1?tap_a=5644-dce66f&tap_s=116411-750171>`_ is a great place to start.
docs/scenarios/serialization.rst
+2
View File
@@ -2,6 +2,8 @@
Data Serialization
==================
.. image:: https://farm3.staticflickr.com/2927/33467946364_3e59bd376a_k_d.jpg
What is data serialization?
---------------------------
docs/scenarios/speed.rst
+3
View File
@@ -1,6 +1,8 @@
Speed
=====
.. image:: https://farm3.staticflickr.com/2826/33175625804_e225b90f3e_k_d.jpg
CPython, the most commonly used implementation of Python, is slow for CPU bound
tasks. `PyPy`_ is fast.
@@ -448,3 +450,4 @@ Multiprocessing
.. _`threading`: https://docs.python.org/3/library/threading.html
.. _`stackoverflow post`: http://stackoverflow.com/questions/26688424/python-threads-are-printing-at-the-same-time-messing-up-the-text-output
.. _`data race`: https://en.wikipedia.org/wiki/Race_condition
.. _`Lock`: https://docs.python.org/3/library/threading.html#lock-objects
docs/scenarios/web.rst
+14 -18
View File
@@ -1,6 +1,8 @@
================
Web Applications
================
=============================
Web Applications & Frameworks
=============================
.. image:: https://farm3.staticflickr.com/2891/34309496175_b82d104282_k_d.jpg
As a powerful scripting language adapted to both fast prototyping
and bigger projects, Python is widely used in web application
@@ -10,6 +12,7 @@ Context
:::::::
WSGI
----
@@ -59,7 +62,7 @@ modules <http://djangopackages.com/>`_ that can be incorporated into a new
project as-is, or customized to fit your needs.
There are annual Django conferences `in the United States
<http://djangocon.us>`_ and `in Europe <http://djangocon.eu>`_.
<http://djangocon.us>`_, `Europe <http://djangocon.eu>`_, and `Australia <http://djangocon.com.au>`_.
The majority of new Python web applications today are built with Django.
@@ -221,19 +224,12 @@ how to set up your first application.
Heroku is the recommended PaaS for deploying Python web applications today.
Gondor
------
Eldarion
--------
`Gondor <https://gondor.io/>`_ is a PaaS specialized for deploying Django
and Pinax applications. Gondor recommends Django version 1.6 and supports any
WSGI application on Python version 2.7. Gondor can automatically configure your
Django site if you use :file:`local_settings.py` for site-specific configuration
information.
Gondor has a guide on deploying `Django projects <https://gondor.io/support/django/setup/>`_.
Gondor is run by a small company and focuses on helping businesses find success with
Python and Django.
`Eldarion <http://eldarion.cloud/>`_ (formely known as Gondor) is a PaaS powered
by Kubernetes, CoreOS, and Docker. They support any WSGI application and have a
guide on deploying `Django projects <https://eldarion-gondor.github.io/docs/how-to/setup-deploy-first-django-project/>`_.
Templating
::::::::::
@@ -372,7 +368,7 @@ into the corresponding block in the :file:`base.html` page.
.. code-block:: html
<!{% extends "base.html" %}
{% extends "base.html" %}
{% block content %}
<p class="important">
<div id="content">
@@ -464,7 +460,7 @@ frameworks.
An example template in Mako looks like:
.. code-block:: html
.. code-block:: mako
<%inherit file="base.html"/>
<%
docs/scenarios/xml.rst
+2
View File
@@ -1,6 +1,8 @@
XML parsing
===========
.. image:: https://farm3.staticflickr.com/2808/33888714601_a1f7d020a2_k_d.jpg
untangle
--------
docs/shipping/freezing.rst
+46 -5
View File
@@ -4,11 +4,13 @@
Freezing Your Code
==================
.. image:: https://farm5.staticflickr.com/4227/33907151034_e0a9e53402_k_d.jpg
"Freezing" your code is creating a single-file executable file to distribute
to end-users, that contains all of your application code as well as the
Python interpreter.
Applications such as 'Dropbox', 'Eve Online', 'Civilisation IV', and
Applications such as 'Dropbox', 'Eve Online', 'Civilization IV', and
BitTorrent clients do this.
The advantage of distributing this way is that your application will "just work",
@@ -60,7 +62,7 @@ py2app no no yes yes MIT no yes yes
.. 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
passing :option:`--onefile` to :file:`Configure.py`.
passing ``--onefile`` to :file:`Configure.py`.
Windows
-------
@@ -70,7 +72,46 @@ bbFreeze
Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Windows <install-windows>`.
.. todo:: Write steps for most basic .exe
1. Install :code:`bbfreeze`:
.. code-block:: console
$ pip install bbfreeze
2. Write most basic :file:`bb_setup.py`
.. code-block:: python
from bbfreeze import Freezer
freezer = Freezer(distdir='dist')
freezer.addScript('foobar.py', gui_only=True)
freezer()
.. 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
.. code-block:: python
freezer = Freezer(distdir='dist', includes=['my_code'], excludes=['docs'])
3. (Optionally) include icon
.. code-block:: python
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
resides.
5. Freeze!
.. code-block:: console
$ python bb_setup.py
py2exe
~~~~~~
@@ -108,7 +149,7 @@ PyInstaller
Prerequisite is to have installed :ref:`Python, Setuptools and pywin32 dependency on Windows <install-windows>`.
- `Most basic tutorial <http://bojan-komazec.blogspot.com/2011/08/how-to-create-windows-executable-from.html>`_
- `Manual <http://www.pyinstaller.org/export/d3398dd79b68901ae1edd761f3fe0f4ff19cfb1a/project/doc/Manual.html?format=raw>`_
- `Manual <https://pyinstaller.readthedocs.io/en/stable/>`_
OS X
@@ -163,7 +204,7 @@ To create a standalone windowed OS X application, use the :code:`--windowed` opt
This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt <https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide <http://wiki.qt.io/About-PySide>`_, to control the graphical parts of the app.
There are several options in :code:`script.spec` related to Mac OS X app bundles `here <http://pythonhosted.org/PyInstaller/#spec-file-options-for-a-mac-os-x-bundle>`_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.
There are several options in :code:`script.spec` related to Mac OS X app bundles `here <http://pythonhosted.org/PyInstaller/spec-files.html#spec-file-options-for-a-mac-os-x-bundle>`_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.
Linux
docs/shipping/packaging.rst
+4 -2
View File
@@ -4,6 +4,8 @@
Packaging Your Code
===================
.. image:: https://farm5.staticflickr.com/4325/36137234682_be6898bf57_k_d.jpg
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'.
@@ -101,7 +103,7 @@ pypiserver
`Pypiserver <https://pypi.python.org/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
(:option:`-U`) which will update all its packages to their latest versions
(``-U``) which will update all its packages to their latest versions
found on PyPI.
@@ -152,7 +154,7 @@ Also, if a distribution releases a new security update for Python, then your
application will automatically start using that new version of Python.
The bdist_rpm command makes `producing an RPM file <https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages>`_
for use by distributions like Red Hat or SuSE is trivially easy.
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
docs/starting/install/linux.rst
+15 -11
View File
@@ -1,25 +1,29 @@
.. _install-linux:
Installing Python on Linux
==========================
Installing Python 2 on Linux
=============================
The latest versions of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu
.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg
.. note::
Check out our :ref:`guide for installing Python 3 on Linux<install3-linux>`.
The latest versions of CentOS, Red Hat Enterprise Linux (RHEL) and Ubuntu
**come with Python 2.7 out of the box**.
To see which version of Python you have installed, open a command prompt and run
.. code-block:: console
$ python --version
$ python2 --version
Some older versions of RHEL and CentOS come with Python 2.4 which is
unacceptable for modern Python development. Fortunately, there are
`Extra Packages for Enterprise Linux`_ which include high
quality additional packages based on their Fedora counterparts. This
repository contains a Python 2.6 package specifically designed to install
side-by-side with the system's Python 2.4 installation.
However, with the growing popularity of Python 3, some distributions, such as
Fedora, don't come with Python 2 pre-installed. You can install the ``python2``
package with your distribution package manager:
.. _Extra Packages for Enterprise Linux: http://fedoraproject.org/wiki/EPEL
.. code-block:: console
$ sudo dnf install python2
You do not need to install or configure anything else to use Python. Having
said that, I would strongly recommend that you install the tools and libraries
docs/starting/install/osx.rst
+40 -15
View File
@@ -1,17 +1,22 @@
.. _install-osx:
Installing Python on Mac OS X
=============================
Installing Python 2 on Mac OS X
===============================
The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg
You do not need to install or configure anything else to use Python. Having
said that, I would strongly recommend that you install the tools and libraries
described in the next section before you start building Python applications
for real-world use. In particular, you should always install Setuptools, as it
makes it much easier for you to use other third-party Python libraries.
.. note::
Check out our :ref:`guide for installing Python 3 on OS X<install3-osx>`.
The version of Python that ships with OS X is great for learning but it's not
The latest version of Mac OS X, High Sierra, **comes with Python 2.7 out of the box**.
You do not need to install or configure anything else to use Python. Having said
that, I would strongly recommend that you install the tools and libraries
described in the next section before you start building Python applications for
real-world use. In particular, you should always install Setuptools, as it makes
it much easier for you to install and manage other third-party Python libraries.
The version of Python that ships with OS X is great for learning, but it's not
good for development. The version shipped with OS X may be out of date from the
`official current Python release <https://www.python.org/downloads/mac-osx/>`_,
which is considered the stable production version.
@@ -30,9 +35,14 @@ minimal but unofficial
package.
.. note::
If you already have Xcode installed or plan to use Homebrew, do not install
OSX-GCC-Installer. In combination, the software can cause issues that are
difficult to diagnose.
If you already have XCode installed, do not install OSX-GCC-Installer.
In combination, the software can cause issues that are difficult to
diagnose.
.. note::
If you perform a fresh install of XCode, you will also need to add the
commandline tools by running ``xcode-select --install`` on the terminal.
While OS X comes with a large number of UNIX utilities, those familiar with
Linux systems will notice one key component missing: a decent package manager.
@@ -69,6 +79,15 @@ or Python 3:
This will take a minute or two.
Homebrew names the executable ``python2`` so that you can still run the system Python via the executable ``python``.
.. code-block:: console
$ python -V # system Python interpreter
$ python2 -V # Homebrew installed Python 2 interpreter
$ python3 -V # Homebrew installed Python 3 interpreter (if installed)
Setuptools & Pip
----------------
@@ -81,14 +100,21 @@ software over a network (usually the Internet) with a single command
capability to your own Python software with very little work.
``pip`` is a tool for easily installing and managing Python packages,
that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways <https://python-packaging-user-guide.readthedocs.io/pip_easy_install/#pip-vs-easy-install>`_,
that is recommended over ``easy_install``. It is superior to ``easy_install``
in `several ways <https://python-packaging-user-guide.readthedocs.io/pip_easy_install/#pip-vs-easy-install>`_,
and is actively maintained.
.. code-block:: console
$ pip2 -V # pip pointing to the Homebrew installed Python 2 interpreter
$ pip3 -V # pip pointing to the Homebrew installed Python 3 interpreter (if installed)
Virtual Environments
--------------------
A Virtual Environment is a tool to keep the dependencies required by different projects
A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep the dependencies required by different projects
in separate places, by creating virtual Python environments for them. 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.
@@ -98,7 +124,6 @@ maintaining a project which requires Django 1.8.
To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
--------------------------------
This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
docs/starting/install/win.rst
+23 -18
View File
@@ -1,10 +1,15 @@
.. _install-windows:
Installing Python on Windows
============================
Installing Python 2 on Windows
==============================
First, download the `latest version <https://www.python.org/ftp/python/2.7.12/python-2.7.12.msi>`_
of Python 2.7 from the official Website. If you want to be sure you are installing a fully
.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg
.. note::
Check out our :ref:`guide for installing Python 3 on Windows<install3-windows>`.
First, download the `latest version <https://www.python.org/ftp/python/2.7.14/python-2.7.14.msi>`_
of Python 2.7 from the official website. If you want to be sure you are installing a fully
up-to-date version, click the Downloads > Windows link from the home page of the
`Python.org web site <http://python.org>`_ .
@@ -35,6 +40,8 @@ You can do this easily by running the following in ``powershell``:
[Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User")
This is also an option during the installation process.
The second (:file:`Scripts`) directory receives command files when certain
packages are installed, so it is a very useful addition.
You do not need to install or configure anything else to use Python. Having
@@ -46,24 +53,22 @@ makes it much easier for you to use other third-party Python libraries.
Setuptools + Pip
----------------
The most crucial third-party Python software of all is Setuptools, which
extends the packaging and installation facilities provided by the distutils in
the standard library. Once you add Setuptools to your Python system you can
download and install any compliant Python software product with a single
command. It also enables you to add this network installation capability to
your own Python software with very little work.
The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
To obtain the latest version of Setuptools for Windows, run the Python script
available here: `ez_setup.py <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
Once installed, you can download, install and uninstall any compliant Python software
product with a single command. It also enables you to add this network installation
capability to your own Python software with very little work.
Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
pip by default.
You'll now have a new command available to you: **easy_install**. It is
considered by many to be deprecated, so we will install its replacement:
**pip**. Pip allows for uninstallation of packages, and is actively maintained,
unlike easy_install.
To see if pip is installed, open a command prompt and run
To install pip, run the Python script available here:
`get-pip.py <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_
.. code-block:: console
$ command -v pip
To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
Virtual Environments
docs/starting/install3/linux.rst
+112
View File
@@ -0,0 +1,112 @@
.. _install3-linux:
Installing Python 3 on Linux
============================
.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg
This document describes how to install Python 3.6 on Ubuntu Linux machines.
To see which version of Python 3 you have installed, open a command prompt and run
.. code-block:: console
$ python3 --version
If you are using Ubuntu 16.10 or newer, then you can easily install Python 3.6 with the following commands::
$ sudo apt-get update
$ sudo apt-get install python3.6
If you're using another version of Ubuntu (e.g. the latest LTS release), we recommend using the `deadsnakes PPA <https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa>`_ to install Python 3.6::
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt-get update
$ sudo apt-get install python3.6
If you are using other Linux distribution, chances are you already have Python 3
pre-installed as well. If not, use your distribution's package manager.
For example on Fedora, you would use `dnf`:
.. code-block:: console
$ sudo dnf install python3
Note that if the version of the ``python3`` package is not recent enough
for you, there may be ways of installing more recent versions as well,
depending on you distribution. For example installing the ``python36`` package
on Fedora 25 to get Python 3.6. If you are a Fedora user, you might want
to read about `multiple Python versions available in Fedora`_.
.. _multiple Python versions available in Fedora: https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html
Working with Python 3
---------------------
At this point, you may have system Python 2.7 available as well.
.. code-block:: console
$ python
This will launch the Python 2 interpreter.
.. code-block:: console
$ python3
This will launch the Python 3 interpreter.
Setuptools & Pip
----------------
The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
Once installed, you can download, install and uninstall any compliant Python software
product with a single command. It also enables you to add this network installation
capability to your own Python software with very little work.
Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
pip by default.
To see if pip is installed, open a command prompt and run
.. code-block:: console
$ command -v pip
To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
Note that on some Linux distributions including Ubuntu and Fedora the ``pip``
command is meant for Python 2, while the ``pip3`` command is meant for Python 3.
.. code-block:: console
$ command -v pip3
However, when using virtual environments (described below), you don't need to
care about that.
Pipenv & Virtual Environments
-----------------------------
The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
A Virtual Environment is a tool to keep the dependencies required by different projects
in separate places, by creating virtual Python environments for them. 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.
For example, you can work on a project which requires Django 1.10 while also
maintaining a project which requires Django 1.8.
So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
--------------------------------
This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
which is available under the same license.
docs/starting/install3/osx.rst
+124
View File
@@ -0,0 +1,124 @@
:orphan: This article should not be added to a toctree for now
.. _install3-osx:
Installing Python 3 on Mac OS X
===============================
.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg
The latest version of Mac OS X, High Sierra, **comes with Python 2.7 out of the box**.
You do not need to install or configure anything else to use Python 2. These
instructions document the installation of Python 3.
The version of Python that ships with OS X is great for learning, but it's not
good for development. The version shipped with OS X may be out of date from the
`official current Python release <https://www.python.org/downloads/mac-osx/>`_,
which is considered the stable production version.
Doing it Right
--------------
Let's install a real version of Python.
Before installing Python, you'll need to install GCC. GCC can be obtained
by downloading `XCode <http://developer.apple.com/xcode/>`_, the smaller
`Command Line Tools <https://developer.apple.com/downloads/>`_ (must have an
Apple account) or the even smaller `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
package.
.. note::
If you already have XCode installed, do not install OSX-GCC-Installer.
In combination, the software can cause issues that are difficult to
diagnose.
.. note::
If you perform a fresh install of XCode, you will also need to add the
commandline tools by running ``xcode-select --install`` on the terminal.
While OS X comes with a large number of UNIX utilities, those familiar with
Linux systems will notice one key component missing: a package manager.
`Homebrew <http://brew.sh>`_ fills this void.
To `install Homebrew <http://brew.sh/#install>`_, open :file:`Terminal` or
your favorite OSX terminal emulator and run
.. code-block:: console
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
The script will explain what changes it will make and prompt you before the
installation begins.
Once you've installed Homebrew, insert the Homebrew directory at the top
of your :envvar:`PATH` environment variable. You can do this by adding the following
line at the bottom of your :file:`~/.profile` file
.. code-block:: console
export PATH=/usr/local/bin:/usr/local/sbin:$PATH
Now, we can install Python 3:
.. code-block:: console
$ brew install python3
This will take a minute or two.
Pip
---
Homebrew installs ``pip3`` for you.
``pip3`` is the alias to ``pip`` pointing to the Homebrew'd Python 3.
Working with Python 3
---------------------
At this point, you have the system Python 2.7 available, potentially the
:ref:`Homebrew version of Python 2 <install-osx>` installed, and the Homebrew
version of Python 3 as well.
.. code-block:: console
$ python
will launch the system Python interpreter.
.. code-block:: console
$ python2
will launch the homebrew-installed Python 2 interpreter (if any).
.. code-block:: console
$ python3
will launch the homebrew-installed Python 3 interpreter.
If the Homebrew version of Python 2 is installed then ``pip2`` will point to Python 2.
If the Homebrew version of Python 3 is installed then ``pip3`` will point to Python 3.
Pipenv & Virtual Environments
-----------------------------
The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
A Virtual Environment is a tool to keep the dependencies required by different projects
in separate places, by creating virtual Python environments for them. 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.
For example, you can work on a project which requires Django 1.10 while also
maintaining a project which requires Django 1.8.
So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
--------------------------------
This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
which is available under the same license.
docs/starting/install3/win.rst
+95
View File
@@ -0,0 +1,95 @@
.. _install3-windows:
Installing Python 3 on Windows
==============================
.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg
First, download the `latest version <https://www.python.org/ftp/python/3.6.3/python-3.6.3.exe>`_
of Python 3.6 from the official website. If you want to be sure you are installing a fully
up-to-date version, click the Downloads > Windows link from the home page of the
`Python.org web site <http://python.org>`_ .
By design, Python installs to a directory with the version number embedded,
e.g. Python version 3.6 will install at :file:`C:\\Python36\\`, so that you can
have multiple versions of Python on the
same system without conflicts. Of course, only one interpreter can be the
default application for Python file types. It also does not automatically
modify the :envvar:`PATH` environment variable, so that you always have control over
which copy of Python is run.
Typing the full path name for a Python interpreter each time quickly gets
tedious, so add the directories for your default Python version to the :envvar:`PATH`.
Assuming that your Python installation is in :file:`C:\\Python36\\`, add this to your
:envvar:`PATH`:
.. code-block:: console
C:\Python36\;C:\Python36\Scripts\
You can do this easily by running the following in ``powershell``:
.. code-block:: console
[Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python36\;C:\Python36\Scripts\", "User")
This is also an option during the installation process.
The second (:file:`Scripts`) directory receives command files when certain
packages are installed, so it is a very useful addition.
You do not need to install or configure anything else to use Python. Having
said that, I would strongly recommend that you install the tools and libraries
described in the next section before you start building Python applications for
real-world use. In particular, you should always install Setuptools, as it
makes it much easier for you to use other third-party Python libraries.
Working with Python 3
---------------------
At this point, you may also have Python 2.7 installed.
.. code-block:: console
$ python
This will launch the Python 2 interpreter.
.. code-block:: console
$ python3
This will launch the Python 3 interpreter.
Setuptools + Pip
----------------
The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_,
which let you download, install and uninstall any compliant Python software
product with a single command. It also enables you to add this network installation
capability to your own Python software with very little work.
All supported versions of Python 3 include pip, so just make sure it's up to date::
python -m pip install -U pip
Pipenv & Virtual Environments
-----------------------------
The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
A Virtual Environment is a tool to keep the dependencies required by different projects
in separate places, by creating virtual Python environments for them. 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.
For example, you can work on a project which requires Django 1.10 while also
maintaining a project which requires Django 1.8.
So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
--------------------------------
This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
which is available under the same license.
docs/starting/installation.rst
+23 -5
View File
@@ -1,6 +1,10 @@
.. _installation:
Properly Installing Python
==========================
.. image:: https://farm5.staticflickr.com/4303/36137232412_fdcb0f84eb_k_d.jpg
There's a good chance that you already have Python on your operating system.
If so, you do not need to install or configure anything else to use Python.
@@ -10,12 +14,26 @@ applications for real-world use. In particular, you should always install
Setuptools, Pip, and Virtualenv — they make it much easier for you to use
other third-party Python libraries.
.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
—*Kenneth Reitz*
Installation Guides
-------------------
These guides go over the proper installation of :ref:`Python 2.7 <which-python>`
for development purposes, as well as setuptools, pip, and virtualenv setup.
These guides go over the proper installation of :ref:`Python <which-python>`
for development purposes, as well as setuptools, pip and virtualenv.
- :ref:`Mac OS X <install-osx>`.
- :ref:`Microsoft Windows <install-windows>`.
- :ref:`Linux <install-linux>`.
Python 3 Installation Guides
////////////////////////////
- :ref:`Python 3 on MacOS <install3-osx>`.
- :ref:`Python 3 on Windows <install3-windows>`.
- :ref:`Python 3 on Linux <install3-linux>`.
Legacy Python 2 Installation Guides
///////////////////////////////////
- :ref:`Python 2 on MacOS <install-osx>`.
- :ref:`Python 2 on Microsoft Windows <install-windows>`.
- :ref:`Python 2 on Linux <install-linux>`.
docs/starting/which-python.rst
+31 -33
View File
@@ -1,57 +1,53 @@
Picking an Interpreter
======================
Picking an Python Interpreter (3 vs. 2)
=======================================
.. image:: https://farm5.staticflickr.com/4265/34484834733_5b80f65ab1_k_d.jpg
.. _which-python:
The State of Python (2 vs 3)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The State of Python (3 & 2)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When choosing a Python interpreter, one looming question is always present:
"Should I choose Python 2 or Python 3"? The answer is not as obvious as
"Should I choose Python 2 or Python 3"? The answer is a bit more subtle than
one might think.
The basic gist of the state of things is as follows:
1. Python 2.7 has been the standard for a *long* time.
2. Python 3 introduced major changes to the language, which many developers are unhappy with.
3. Python 2.7 will receive necessary security updates until 2020 [#pep373_eol]_.
4. Python 3 is continually evolving, like Python 2 did in years past.
So, you can now see why this is not such an easy decision.
1. Most production applications today use Python 2.7.
2. Python 3 is ready for the production deployment of applications today.
3. Python 2.7 will only receive necessary security updates until 2020 [#pep373_eol]_.
4. The brand name "Python" encapsulates both Python 3 and Python 2.
Recommendations
~~~~~~~~~~~~~~~
.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
—*Kenneth Reitz*
I'll be blunt:
**Use Python 3 if...**
- You don't care.
- You love Python 3.
- You are indifferent towards 2 vs 3.
- You don't know which one to use.
- You embrace change.
**Use Python 2 if...**
- You love Python 2 and are saddened by the future being Python 3.
- The stability requirements of your software would be improved by a language and runtime that never changes.
- Software that you depend on requires it.
- Use Python 3 for new Python applications.
- If you're learning Python for the first time, familiarizing yourself with Python 2.7 will be very
useful, but not more useful than learning Python 3.
- Learn both. They are both "Python".
- Software that is already built often depends on Python 2.7.
- If you are writing a new open source Python library, it's best to write it for both Python 2 and 3
simultaneously. Only supporting Python 3 for a new library you want to be widely adopted is a
political statement and will alienate many of your users. This is not a problem — slowly, over the next three years, this will become less the case.
So.... 3?
~~~~~~~~~
If you're choosing a Python interpreter to use, and aren't opinionated, then I
If you're choosing a Python interpreter to use, I
recommend you use the newest Python 3.x, since every version brings new and
improved standard library modules, security and bug fixes. Progress is progress.
improved standard library modules, security and bug fixes.
Given such, only use Python 2 if you have a strong reason to, such as a Python 2
exclusive library which has no adequate Python 3 ready alternative, or you
(like me) absolutely love and are inspired by Python 2.
Given such, only use Python 2 if you have a strong reason to, such as a
pre-existing code-base, a Python 2 exclusive library, simplicity/familiarity,
or, of course, you absolutely love and are inspired by Python 2. No harm in that.
Check out `Can I Use Python 3? <https://caniusepython3.com/>`_ to see if any
software you're depending on will block your adoption of Python 3.
@@ -62,7 +58,9 @@ It is possible to `write code that works on Python 2.6, 2.7, and Python 3
<https://docs.python.org/3/howto/pyporting.html>`_. This
ranges from trivial to hard depending upon the kind of software
you are writing; if you're a beginner there are far more important things to
worry about.
worry about. Note that Python 2.6 is end-of-life upstream, so you shouldn't
try to write 2.6-compatible code unless you're being paid specifically to
do that.
Implementations
~~~~~~~~~~~~~~~
docs/writing/documentation.rst
+4 -2
View File
@@ -1,6 +1,8 @@
Documentation
=============
.. image:: https://farm5.staticflickr.com/4279/35620636012_f66aa88f93_k_d.jpg
Readability is a primary focus for Python developers, in both project
and code documentation. Following some simple best practices can save
both you and others a lot of time.
@@ -205,8 +207,8 @@ more information about a function, what it does, any exceptions it may raise,
what it returns, or relevant details about the parameters.
For more detailed documentation of code a popular style is the one used for the
Numpy project, often called `Numpy style`_ docstrings. While it can take up a
few more lines the previous example, it allows the developer to include a lot
Numpy project, often called `Numpy style`_ docstrings. While it can take up more
lines than the previous example, it allows the developer to include a lot
more information about a method, function, or class. ::
def random_number_generator(arg1, arg2):
docs/writing/gotchas.rst
+21 -2
View File
@@ -1,6 +1,8 @@
Common Gotchas
==============
.. image:: https://farm5.staticflickr.com/4163/34435688380_b5a740762b_k_d.jpg
For the most part, Python aims to be a clean and consistent language that
avoids surprises. However, there are a few cases that can be confusing to
newcomers.
@@ -76,6 +78,7 @@ signal that no argument was provided (:py:data:`None` is often a good choice).
to.append(element)
return to
Do not forget, you are passing a *list* object as the second argument.
When the Gotcha Isn't a Gotcha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -229,13 +232,29 @@ Here's nice trick for removing all of these files, if they already exist::
Run that from the root directory of your project, and all ``.pyc`` files
will suddenly vanish. Much better.
.. _version_control_ignores:
Version Control Ignores
~~~~~~~~~~~~~~~~~~~~~~~
If you still need the ``.pyc`` files for performance reasons, you can always add them
to the ignore files of your version control repositories. Popular version control
systems have the ability to use wildcards defined in a file to apply special
rules.
An ignore file will make sure the matching files don't get checked into the repository.
Git_ uses ``.gitignore`` while Mercurial_ uses ``.hgignore``.
.. _Git: https://git-scm.com/
.. _Mercurial: https://www.mercurial-scm.org/
At the minimum your ignore files should look like this.
::
syntax:glob # This line is not needed for .gitignore files.
*.py[cod] # Will match .pyc, .pyo and .pyd files.
__pycache__/ # Exclude the whole folder
You may wish to include more files and directories depending on your needs.
The next time you commit to the repository, these files will not be included.
docs/writing/license.rst
+2
View File
@@ -1,6 +1,8 @@
Choosing a License
==================
.. image:: https://farm5.staticflickr.com/4228/33907149294_82d7535a6c_k_d.jpg
Your source publication *needs* a license. In the US, if no license is
specified, users have no legal right to download, modify, or distribute.
Furthermore, people can't contribute to your code unless you tell them what
docs/writing/logging.rst
+3 -10
View File
@@ -1,6 +1,8 @@
Logging
=======
.. image:: https://farm5.staticflickr.com/4246/35254379756_c9fe23f843_k_d.jpg
The :mod:`logging` module has been a part of Python's Standard Library since
version 2.3. It is succinctly described in :pep:`282`. The documentation
is notoriously hard to read, except for the `basic logging tutorial`_.
@@ -55,17 +57,8 @@ this in your ``__init__.py``
.. code-block:: python
# Set default logging handler to avoid "No handler found" warnings.
import logging
try: # Python 2.7+
from logging import NullHandler
except ImportError:
class NullHandler(logging.Handler):
def emit(self, record):
pass
logging.getLogger(__name__).addHandler(NullHandler())
logging.getLogger(__name__).addHandler(logging.NullHandler())
Logging in an Application
docs/writing/reading.rst
+2
View File
@@ -1,6 +1,8 @@
Reading Great Code
==================
.. image:: https://farm5.staticflickr.com/4221/34689452831_93d7fd0571_k_d.jpg
One of the core tenets behind the design of Python is creating
readable code. The motivation behind this design is simple: The number
one thing that Python programmers do is read code.
docs/writing/structure.rst
+32 -5
View File
@@ -1,6 +1,8 @@
Structuring Your Project
========================
.. image:: https://farm5.staticflickr.com/4203/33907151224_0574e7dfc2_k_d.jpg
By "structure" we mean the decisions you make concerning
how your project best meets its objective. We need to consider how to
best leverage Python's features to create clean, effective code.
@@ -172,6 +174,8 @@ Test Suite
::::::::::
*For advice on writing your tests, see :doc:`writing/tests`.*
.. csv-table::
:widths: 20, 40
@@ -200,7 +204,7 @@ it. You can do this a few ways:
package properly.
I highly recommend the latter. Requiring a developer to run
`setup.py <http://setup.py>`__ develop to test an actively changing
``setup.py develop`` to test an actively changing
codebase also requires them to have an isolated environment setup for
each instance of the codebase.
@@ -211,7 +215,7 @@ file:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
import sample
@@ -391,7 +395,17 @@ folder named :file:`my` which is not the case. There is an
dot notation should be used in the Python docs.
If you'd like you could name your module :file:`my_spam.py`, but even our
friend the underscore should not be seen often in module names.
friend the underscore should not be seen often in module names. However, using other
characters (spaces or hyphens) in module names will prevent importing
(- is the subtract operator), so try to keep module names short so there is
no need to separate words. And, most of all, don't namespace with underscores, use submodules instead.
.. code-block:: python
# OK
import library.plugin.foo
# not OK
import library.foo_plugin
Aside from some naming restrictions, nothing special is required for a Python
file to be a module, but you need to understand the import mechanism in order
@@ -762,7 +776,7 @@ compute x + 1, you have to create another integer and give it a name.
my_list = [1, 2, 3]
my_list[0] = 4
print my_list # [4, 2, 3] <- The same list as changed
print my_list # [4, 2, 3] <- The same list has changed
x = 6
x = x + 1 # The new x is another object
@@ -787,6 +801,11 @@ full string is needed. One thing to notice, however, is that list
comprehensions are better and faster than constructing a list in a loop
with calls to ``append()``.
One other option is using the map function, which can 'map' a function
('str') to an iterable ('range(20)'). This results in a map object,
which you can then ('join') together just like the other examples.
The map function can be even faster than a list comprehension in some cases.
**Bad**
.. code-block:: python
@@ -807,7 +826,7 @@ with calls to ``append()``.
nums.append(str(n))
print "".join(nums) # much more efficient
**Best**
**Better**
.. code-block:: python
@@ -815,6 +834,14 @@ with calls to ``append()``.
nums = [str(n) for n in range(20)]
print "".join(nums)
**Best**
.. code-block:: python
# create a concatenated string from 0 to 19 (e.g. "012..1819")
nums = map(str, range(20))
print "".join(nums)
One final thing to mention about strings is that using ``join()`` is not always
best. In the instances where you are creating a new string from a pre-determined
number of strings, using the addition operator is actually faster, but in cases
docs/writing/style.rst
+9 -7
View File
@@ -3,6 +3,8 @@
Code Style
==========
.. image:: https://farm5.staticflickr.com/4223/33907150054_5ee79e8940_k_d.jpg
If you ask Python programmers what they like most about Python, they will
often cite its high readability. Indeed, a high level of readability
is at the heart of the design of the Python language, following the
@@ -459,23 +461,23 @@ best to adhere to the guidelines laid out within this document. Some project
may sway from it from time to time, while others may
`amend its recommendations <http://docs.python-requests.org/en/master/dev/contributing/#kenneth-reitz-s-code-style>`_.
That being said, conforming your Python code to PEP 8 is generally a good
idea and helps make code more consistent when working on projects with other
developers. There is a command-line program, `pep8 <https://github.com/jcrocholl/pep8>`_,
that can check your code for conformance. Install it by running the following
command in your terminal:
That being said, conforming your Python code to PEP 8 is generally a good idea
and helps make code more consistent when working on projects with other
developers. There is a command-line program, `pycodestyle <https://github.com/PyCQA/pycodestyle>`_
(previously known as ``pep8``), that can check your code for conformance.
Install it by running the following command in your terminal:
.. code-block:: console
$ pip install pep8
$ pip install pycodestyle
Then run it on a file or series of files to get a report of any violations.
.. code-block:: console
$ pep8 optparse.py
$ pycodestyle optparse.py
optparse.py:69:11: E401 multiple imports on one line
optparse.py:77:1: E302 expected 2 blank lines, found 1
optparse.py:88:5: E301 expected 1 blank line, found 0
docs/writing/tests.rst
+31 -11
View File
@@ -1,6 +1,8 @@
Testing Your Code
=================
.. image:: https://farm5.staticflickr.com/4166/34435687940_8f73fc1fa6_k_d.jpg
Testing your code is very important.
Getting used to writing testing code and running this code in parallel is now
@@ -185,24 +187,41 @@ and then running the `py.test` command
is far less work than would be required for the equivalent functionality with
the unittest module!
`py.test <http://pytest.org/latest/>`_
`py.test <https://docs.pytest.org/en/latest/>`_
Nose
----
nose extends unittest to make testing easier.
Hypothesis
----------
Hypothesis is a library which lets you write tests that are parametrized by
a source of examples. It then generates simple and comprehensible examples
that make your tests fail, letting you find more bugs with less work.
.. code-block:: console
$ pip install nose
$ pip install hypothesis
nose provides automatic test discovery to save you the hassle of manually
creating test suites. It also provides numerous plugins for features such as
xUnit-compatible test output, coverage reporting, and test selection.
For example, testing lists of floats will try many examples, but report the
minimal example of each bug (distinguished exception type and location):
`nose <https://nose.readthedocs.io/en/latest/>`_
.. code-block:: python
@given(lists(floats(allow_nan=False, allow_infinity=False), min_size=1))
def test_mean(xs):
mean = sum(xs) / len(xs)
assert min(xs) <= mean(xs) <= max(xs)
.. code-block:: none
Falsifying example: test_mean(
xs=[1.7976321109618856e+308, 6.102390043022755e+303]
)
Hypothesis is practical as well as very powerful, and will often find bugs
that escaped all other forms of testing. It integrates well with py.test,
and has a strong focus on usability in both simple and advanced scenarios.
`hypothesis <https://hypothesis.readthedocs.io/en/latest/>`_
tox
@@ -218,7 +237,8 @@ multiple interpreter configurations
tox allows you to configure complicated multi-parameter test matrices via a
simple ini-style configuration file.
`tox <http://testrun.org/tox/latest/>`_
`tox <https://tox.readthedocs.io/en/latest/>`_
Unittest2
---------