Merge branch 'master' of github.com:kennethreitz/python-guide

Author: kennethreitz

docs/shipping/freezing.rst

@@ -202,7 +202,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/starting/install/osx.rst

@@ -77,6 +77,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
 ----------------
@@ -93,6 +102,12 @@ 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
 --------------------

docs/starting/install3/osx.rst

@@ -70,8 +70,7 @@ Pip
 
 Homebrew installs ``pip3`` for you.
 
-``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both
-the Homebrew'd Python 2 and 3 installed.
+``pip3`` is the alias to ``pip`` pointing to the Homebrew'd Python 3.
 
 Working with Python 3
 ---------------------
@@ -84,18 +83,22 @@ version of Python 3 as well.
 
     $ python
 
-will launch the Python 2 interpreter.
+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 Python 3 interpreter.
+will launch the homebrew-installed Python 3 interpreter.
 
-``pip3`` and ``pip`` will both be available.  If the Homebrew version of Python
-2 is not installed, they will be the same.  If the Homebrew version of Python 2
-is installed then ``pip`` will point to Python 2 and ``pip3`` will point to
-Python 3.
+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.
 
 
 Virtual Environments

docs/starting/install3/win.rst

@@ -1,7 +1,7 @@
 .. _install3-windows:
 
 Installing Python 3 on Windows
-============================
+==============================
 
 First, download the `latest version <https://www.python.org/ftp/python/3.6.0/python-3.6.0.exe>`_
 of Python 3.6 from the official website. If you want to be sure you are installing a fully

docs/writing/documentation.rst

@@ -205,8 +205,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

@@ -230,13 +230,27 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~
 
+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/structure.rst

@@ -391,7 +391,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