From 4432d8202018dba838063b157a810e4668a8f478 Mon Sep 17 00:00:00 2001 From: Sharlak Date: Sun, 30 Jul 2017 21:23:32 +0100 Subject: [PATCH 1/8] lengthened title underline appropriately --- docs/starting/install3/win.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install3/win.rst b/docs/starting/install3/win.rst index 6010b0b..bb6c38f 100644 --- a/docs/starting/install3/win.rst +++ b/docs/starting/install3/win.rst @@ -1,7 +1,7 @@ .. _install3-windows: Installing Python 3 on Windows -============================ +============================== First, download the `latest version `_ of Python 3.6 from the official website. If you want to be sure you are installing a fully From d39c485d167cc4cf37813ca89ac6a2fdcd9972f3 Mon Sep 17 00:00:00 2001 From: Sharlak Date: Sun, 30 Jul 2017 21:57:19 +0100 Subject: [PATCH 2/8] clarified module naming re: underscores --- docs/writing/structure.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b33d6f6..486004c 100644 --- a/docs/writing/structure.rst +++ b/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 From e0f8d9166c5c843e89894feb560d0128278bd2a4 Mon Sep 17 00:00:00 2001 From: wangbx Date: Mon, 31 Jul 2017 23:31:26 +0800 Subject: [PATCH 3/8] correct wrong Mac OS X app bundles link --- docs/shipping/freezing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 41c2344..aaf4cc9 100644 --- a/docs/shipping/freezing.rst +++ b/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 `_ or `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 `_. 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 `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option. Linux From 6776b2ff22987580ee59e655c64808e6ad5c4434 Mon Sep 17 00:00:00 2001 From: Harry Moreno Date: Mon, 31 Jul 2017 17:01:06 -0400 Subject: [PATCH 4/8] Fix grammar --- docs/writing/documentation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index bdd39e1..a91b86b 100644 --- a/docs/writing/documentation.rst +++ b/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): From 7be51790e493a9836095705bcbb29ff9687d77c4 Mon Sep 17 00:00:00 2001 From: daegontaven Date: Fri, 11 Aug 2017 01:46:24 -0400 Subject: [PATCH 5/8] Add version control ignores to gotchas --- docs/writing/gotchas.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index fcf1439..4c901d0 100644 --- a/docs/writing/gotchas.rst +++ b/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 looks 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. From ec5f791c695a5c205069f9c6c0fde6fe5e921ccd Mon Sep 17 00:00:00 2001 From: Vivek Joshy Date: Fri, 11 Aug 2017 06:01:03 -0400 Subject: [PATCH 6/8] Correct typo Change looks to look --- docs/writing/gotchas.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 4c901d0..4a28085 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -244,7 +244,7 @@ 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 looks like this. +At the minimum your ignore files should look like this. :: From af75a6aad6bd7655662cabd6f8da35d30b7fd1a9 Mon Sep 17 00:00:00 2001 From: cclauss Date: Thu, 17 Aug 2017 13:33:16 +0200 Subject: [PATCH 7/8] Changes in how homebrew installs Python on Mac OSX MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Homebrew no longer sets `pip`. See 5 executable names in https://docs.brew.sh/Homebrew-and-Python.html * `python` points to the macOS system Python (with no manual PATH modification) * `python2` points to Homebrew’s Python 2.7.x (if installed) * `python3` points to Homebrew’s Python 3.x (if installed) * `pip2` points to Homebrew’s Python 2.7.x’s pip (if installed) * `pip3` points to Homebrew’s Python 3.x’s pip (if installed) --- docs/starting/install3/osx.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst index 8844f2e..14adc77 100644 --- a/docs/starting/install3/osx.rst +++ b/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 From 2d1b231c4d61813ec28a2ea546cb76862f5ba40d Mon Sep 17 00:00:00 2001 From: cclauss Date: Thu, 17 Aug 2017 13:44:46 +0200 Subject: [PATCH 8/8] Changes in how homebrew installs Python on Mac OSX MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Homebrew no longer sets pip. See 5 executable names in https://docs.brew.sh/Homebrew-and-Python.html python points to the macOS system Python (with no manual PATH modification) python2 points to Homebrew’s Python 2.7.x (if installed) python3 points to Homebrew’s Python 3.x (if installed) pip2 points to Homebrew’s Python 2.7.x’s pip (if installed) pip3 points to Homebrew’s Python 3.x’s pip (if installed) --- docs/starting/install/osx.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 24eb274..bd7733b 100644 --- a/docs/starting/install/osx.rst +++ b/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 `_, 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 --------------------