From 205ffc7dd6495ff92c217c7f0dbe80f21d7d3a73 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 05:31:40 -0700 Subject: [PATCH 01/60] use correct URL for Pyramid wrap to 79 columns --- docs/scenarios/web.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 9dd3928..601e880 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -102,10 +102,9 @@ I do not recommend using Tornado unless you think you need it. Pyramid -------- -`Pyramid `_ is a very flexible -framework with a heavy focus on modularity. It comes with a small number -of libraries ("batteries") built-in, and encourages users to extend its -base functionality. +`Pyramid `_ is a very flexible framework with a heavy +focus on modularity. It comes with a small number of libraries ("batteries") +built-in, and encourages users to extend its base functionality. Pyramid does not have a large user base, unlike Django and Flask. It's a capable framework, but not a very popular choice for new Python web From 9c703e6c702f65b5031fe741d5c184e35a0e5cf3 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Fri, 1 Apr 2016 16:56:21 +0800 Subject: [PATCH 02/60] Update crypto.rst Python 3.2 support has been dropped from pyca/cryptography as of April 2015. https://github.com/pyca/cryptography/pull/1846 --- docs/scenarios/crypto.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst index 94bd58d..e4b103a 100644 --- a/docs/scenarios/crypto.rst +++ b/docs/scenarios/crypto.rst @@ -6,7 +6,7 @@ Cryptography `Cryptography `_ is an actively developed library that provides cryptographic recipes and primitives. It supports -Python 2.6-2.7, Python 3.2+ and PyPy. +Python 2.6-2.7, Python 3.3+ and PyPy. Cryptography is divided into two layers of recipes and hazardous materials From 1a5d942353783ec1231756450138e35c6ffe91ce Mon Sep 17 00:00:00 2001 From: Nathaniel Irons Date: Sun, 3 Apr 2016 11:53:21 -0700 Subject: [PATCH 03/60] Fix Xcode typo --- docs/starting/install/osx.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index b401c55..03426c5 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -22,18 +22,18 @@ 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 `_, the smaller +by downloading `Xcode `_, the smaller `Command Line Tools `_ (must have an Apple account) or the even smaller `OSX-GCC-Installer `_ package. .. note:: - If you already have XCode installed, do not install OSX-GCC-Installer. + 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 + 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 From f7f472883324db521eff10948d4ff7605510f15c Mon Sep 17 00:00:00 2001 From: gruzovator Date: Tue, 19 Apr 2016 11:55:48 +0300 Subject: [PATCH 04/60] more simple rm pyc files command --- 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 62704c5..3a4c335 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -224,7 +224,7 @@ Removing Bytecode (.pyc) Files Here's nice trick for removing all of these files, if they already exist:: - $ find . -name "*.pyc" -exec rm -rf {} \; + $ find . -name "*.pyc" -delete Run that from the root directory of your project, and all ``.pyc`` files will suddenly vanish. Much better. From 44e72cd2e363551af589ef10987061a0a4e2fb04 Mon Sep 17 00:00:00 2001 From: Grant Regimbal Date: Thu, 21 Apr 2016 19:44:26 -0500 Subject: [PATCH 05/60] link to pep 257 --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c6905e3..bd59437 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -108,7 +108,7 @@ In Python, *docstrings* describe modules, classes, and functions: ... In general, follow the comment section of :pep:`8#comments` (the "Python Style -Guide"). +Guide"). More information about docstrings can be found at :pep:`0257#specification` (The Docstring Conventions Guide). Commenting Sections of Code ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From bdf3e1ea92dfac8c2b5266f5926ed632e70bfc86 Mon Sep 17 00:00:00 2001 From: Tom Date: Tue, 10 May 2016 17:05:23 -0600 Subject: [PATCH 06/60] Fix incorrect dictConfig example dictConfig expects a special `root` key outside of the `loggers` subdictionary in order to configure the root logger. I've tried the existing example code on python 2.7.5 and 3.5.1, and in neither case does the final log line produce any output (because the root logger remains set to `looging.WARN` by default). Changing the example to use the `root` key causes the log message to appear properly. The `root` key is explained in PEP391: https://www.python.org/dev/peps/pep-0391/#dictionary-schema-detail --- docs/writing/logging.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst index 8763e8d..9b41aba 100644 --- a/docs/writing/logging.rst +++ b/docs/writing/logging.rst @@ -163,10 +163,10 @@ the configuration dictionary. 'formatter': 'f', 'level': logging.DEBUG} }, - loggers = { - 'root': {'handlers': ['h'], - 'level': logging.DEBUG} - } + root = { + 'handlers': ['h'], + 'level': logging.DEBUG, + }, ) dictConfig(logging_config) From 6eee93bb68d7a20f057cd712d87fbf78f3723e62 Mon Sep 17 00:00:00 2001 From: Stan Bright Date: Fri, 27 May 2016 12:50:42 +0300 Subject: [PATCH 07/60] Add 'Awesome Python Newsletter' from LibHunt --- docs/intro/news.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 4297490..54f8ff7 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -47,3 +47,10 @@ Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets delivered in your inbox. Keep Your Python Programming Skills Updated. `Import Python Weekly Newsletter `_ + +Awesome Python Newsletter +~~~~~~~~~~~~~~~~~~~~ + +A weekly overview of the most popular Python news, articles and packages. + + `Awesome Python Newsletter `_ From 1d25e8bffe5bada0f188b56215ef21e9bb2ca482 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Fri, 3 Jun 2016 15:24:21 +0800 Subject: [PATCH 08/60] Added a bit about concurrent.futures --- docs/scenarios/speed.rst | 127 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 125 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 6050c98..9cba3e2 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -226,10 +226,131 @@ Numba ----- .. todo:: Write about Numba and the autojit compiler for NumPy -Threading -::::::::: +Concurrency +::::::::::: +Concurrent.futures +------------------ + +The `concurrent.futures`_ module is a module in the standard library that +provides a "high-level interface for asynchronously executing callables". It +abstracts away a lot of the more complicated details about using multiple +threads or processes for concurrency, and allows the user to focus on +accomplishing the task at hand. + +The `concurrent.futures`_ module exposes two main classes, the +`ThreadPoolExecutor` and the `ProcessPoolExecutor`. The ThreadPoolExecutor +will create a pool of worker threads that a user can submit jobs to. These jobs +will then be executed in another thread when the next worker thread becomes +available. + +The ProcessPoolExecutor works in the same way, except instead of using multiple +threads for its workers, it will use multiple processes. This makes it possible +to side-step the GIL, however because of the way things are passed to worker +processes, only picklable objects can be executed and returned. + +Because of the way the GIL works, a good rule of thumb is to use a +ThreadPoolExecutor when the task being executed involves a lot of blocking +(i.e. making requests over the network) and to use a ProcessPoolExecutor +executor when the task is computationally expensive. + +There are two main ways of executing things in parallel using the two +Executors. One way is with the `map(func, iterables)` method. This works +almost exactly like the builtin `map()` function, except it will execute +everything in parallel. :: + + from concurrent.futures import ThreadPoolExecutor + import requests + + def get_webpage(url): + """ + Some blocking function. + """ + page = requests.get(url) + return page + + pool = ThreadPoolExecutor(max_workers=5) + + my_urls = ['http://google.com/']*10 # Create a list of urls + + for page in pool.map(get_webpage, my_urls): + # Do something with the result + print(page.text) + +For even more control, the `submit(func, *args, **kwargs)` method will schedule +a callable to be executed ( as `func(*args, **kwargs)`) and returns a `Future`_ +object that represents the execution of the callable. + +The Future object provides various methods that can be used to check on the +progress of the scheduled callable. These include: + +cancel() + Attempt to cancel the call. +cancelled() + Return True if the call was successfully cancelled. +running() + Return True if the call is currently being executed and cannot be + cancelled. +done() + Return True if the call was successfully cancelled or finished running. +result() + Return the value returned by the call. Note that this call will block until + the scheduled callable returns by default. +exception() + Return the exception raised by the call. If no exception was raised then + this returns `None`. Note that this will block just like `result()`. +add_done_callback(fn) + Attach a callback function that will be executed (as `fn(future)`) when the + scheduled callable returns. + +:: + + from concurrent.futures import ProcessPoolExecutor, as_completed + + def is_prime(n): + if n % 2 == 0: + return n, False + + sqrt_n = int(n**0.5) + for i in range(3, sqrt_n + 1, 2): + if n % i == 0: + return n, False + return n, True + + PRIMES = [ + 112272535095293, + 112582705942171, + 112272535095293, + 115280095190773, + 115797848077099, + 1099726899285419] + + futures = [] + with ProcessPoolExecutor(max_workers=4) as pool: + # Schedule the ProcessPoolExecutor to check if a number is prime + # and add the returned Future to our list of futures + for p in PRIMES: + fut = pool.submit(is_prime, p) + futures.append(fut) + + # As the jobs are completed, print out the results + for number, result in as_completed(futures): + if result: + print("{} is prime".format(number)) + else: + print("{} is not prime".format(number)) + +The `concurrent.futures`_ module contains two helper functions for working with +Futures. The `as_completed(futures)` function returns an iterator over the list +of futures, yielding the futures as they complete. + +The `wait(futures)` function will simply block until all futures in the list of +futures provided have completed. + +For more information, on using the `concurrent.futures`_ module, consult the +official documentation. + Threading --------- @@ -248,3 +369,5 @@ Multiprocessing .. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf .. _`Special care`: http://docs.python.org/c-api/init.html#threads .. _`David Beazley's`: http://www.dabeaz.com/GIL/gilvis/measure2.py +.. _`concurrent.futures`: https://docs.python.org/3/library/concurrent.futures.html +.. _`Future`: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future From 75e957e89e83da75ff7c50a1d5e79e6e7e50e10d Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Fri, 3 Jun 2016 16:06:11 +0800 Subject: [PATCH 09/60] Wrote a bit about threading --- docs/scenarios/speed.rst | 74 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 3 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 9cba3e2..16f5d53 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -264,9 +264,6 @@ everything in parallel. :: import requests def get_webpage(url): - """ - Some blocking function. - """ page = requests.get(url) return page @@ -354,6 +351,74 @@ official documentation. Threading --------- +The standard library comes with a `threading`_ module that allows a user to +work with multiple threads manually. + +Running a function in another thread is as simple as passing a callable and +it's arguments to `Thread`'s constructor and then calling `start()`:: + + from threading import Thread + import requests + + def get_webpage(url): + page = requests.get(url) + return page + + some_thread = Thread(get_webpage, 'http://google.com/') + some_thread.start() + +To wait until the thread has terminated, call `join()`:: + + some_thread.join() + +After calling `join()`, it is always a good idea to check whether the thread is +still alive (because the join call timed out):: + + if some_thread.is_alive(): + print("join() must have timed out.") + else: + print("Our thread has terminated.") + +Because multiple threads have access to the same section of memory, sometimes +there might be situations where two or more threads are trying to write to the +same resource at the same time or where the output is dependent on the sequence +or timing of certain events. This is called a `data race`_ or race condition. +When this happens, the output will be garbled or you may encounter problems +which are difficult to debug. A good example is this `stackoverflow post`_. + +The way this can be avoided is by using a `Lock`_ that each thread needs to +acquire before writing to a shared resource. Locks can be acquired and released +through either the contextmanager protocol (`with` statement), or by using +`acquire()` and `release()` directly. Here is a (rather contrived) example:: + + from threading import Lock, Thread + + file_lock = Lock() + + def log(msg): + with file_lock: + open('website_changes.log', 'w') as f: + f.write(changes) + + def monitor_website(some_website): + """ + Monitor a website and then if there are any changes, log them to disk. + """ + while True: + changes = check_for_changes(some_website) + if changes: + log(changes) + + websites = ['http://google.com/', ... ] + for website in websites: + t = Thread(monitor_website, website) + t.start() + +Here, we have a bunch of threads checking for changes on a list of sites and +whenever there are any changes, they attempt to write those changes to a file +by calling `log(changes)`. When `log()` is called, it will wait to acquire +the lock with `with file_lock:`. This ensures that at any one time, only one +thread is writing to the file. Spawning Processes ------------------ @@ -371,3 +436,6 @@ Multiprocessing .. _`David Beazley's`: http://www.dabeaz.com/GIL/gilvis/measure2.py .. _`concurrent.futures`: https://docs.python.org/3/library/concurrent.futures.html .. _`Future`: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future +.. _`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 From dde23c230e84b92e436b4657a80708ba2decad3f Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Fri, 3 Jun 2016 16:15:00 +0800 Subject: [PATCH 10/60] Converted "::" to proper python code-block directives --- docs/scenarios/speed.rst | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 16f5d53..21166b2 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -258,7 +258,9 @@ executor when the task is computationally expensive. There are two main ways of executing things in parallel using the two Executors. One way is with the `map(func, iterables)` method. This works almost exactly like the builtin `map()` function, except it will execute -everything in parallel. :: +everything in parallel. : + +.. code-block:: python from concurrent.futures import ThreadPoolExecutor import requests @@ -301,7 +303,8 @@ add_done_callback(fn) Attach a callback function that will be executed (as `fn(future)`) when the scheduled callable returns. -:: + +.. code-block:: python from concurrent.futures import ProcessPoolExecutor, as_completed @@ -355,7 +358,9 @@ The standard library comes with a `threading`_ module that allows a user to work with multiple threads manually. Running a function in another thread is as simple as passing a callable and -it's arguments to `Thread`'s constructor and then calling `start()`:: +it's arguments to `Thread`'s constructor and then calling `start()`: + +.. code-block:: python from threading import Thread import requests @@ -367,12 +372,16 @@ it's arguments to `Thread`'s constructor and then calling `start()`:: some_thread = Thread(get_webpage, 'http://google.com/') some_thread.start() -To wait until the thread has terminated, call `join()`:: +To wait until the thread has terminated, call `join()`: + +.. code-block:: python some_thread.join() After calling `join()`, it is always a good idea to check whether the thread is -still alive (because the join call timed out):: +still alive (because the join call timed out): + +.. code-block:: python if some_thread.is_alive(): print("join() must have timed out.") @@ -389,7 +398,10 @@ which are difficult to debug. A good example is this `stackoverflow post`_. The way this can be avoided is by using a `Lock`_ that each thread needs to acquire before writing to a shared resource. Locks can be acquired and released through either the contextmanager protocol (`with` statement), or by using -`acquire()` and `release()` directly. Here is a (rather contrived) example:: +`acquire()` and `release()` directly. Here is a (rather contrived) example: + + +.. code-block:: python from threading import Lock, Thread @@ -402,7 +414,8 @@ through either the contextmanager protocol (`with` statement), or by using def monitor_website(some_website): """ - Monitor a website and then if there are any changes, log them to disk. + Monitor a website and then if there are any changes, + log them to disk. """ while True: changes = check_for_changes(some_website) From 5888db734d010fa329bbe5cbfbf4d69926fb4e95 Mon Sep 17 00:00:00 2001 From: dfowler Date: Fri, 3 Jun 2016 17:57:03 -0400 Subject: [PATCH 11/60] Fix a few typos --- docs/scenarios/db.rst | 2 +- docs/writing/structure.rst | 2 +- docs/writing/style.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index a2de7fe..3ed1191 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -29,7 +29,7 @@ Records `Records `_ is minimalist SQL library, designed for sending raw SQL queries to various databases. Data can be used -programatically, or exported to a number of useful data formats. +programmatically, or exported to a number of useful data formats. .. code-block:: console diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 6448dba..4f8bb37 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -600,7 +600,7 @@ clearer and thus preferred. This mechanism is useful for separating concerns and avoiding external un-related logic 'polluting' the core logic of the function or method. A good example of a piece of functionality that is better handled -with decoration is memoization or caching: you want to store the results of an +with decoration is memorization or caching: you want to store the results of an expensive function in a table and use them directly instead of recomputing them when they have already been computed. This is clearly not part of the function logic. diff --git a/docs/writing/style.rst b/docs/writing/style.rst index b916569..2b2c7c8 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -455,9 +455,9 @@ PEP 8 easy-to-read version of PEP 8 is also available at `pep8.org `_. This is highly recommended reading. The entire Python community does their -best to adhere to the guidelines laidout within this document. Some project +best to adhere to the guidelines laid out within this document. Some project may sway from it from time to time, while others may -`ammend its recommendations `_. +`amend its recommendations `_. 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 From 8b674a5b3089ef9033566bf50434d66e557b8b36 Mon Sep 17 00:00:00 2001 From: Zev Averbach Date: Fri, 3 Jun 2016 16:06:45 -0700 Subject: [PATCH 12/60] changed "tenants" to "tenets" Tenants are people who pay rent; tenets are principles or beliefs. --- docs/writing/reading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst index 39b0888..9734225 100644 --- a/docs/writing/reading.rst +++ b/docs/writing/reading.rst @@ -1,7 +1,7 @@ Reading Great Code ================== -One of the core tenants behind the design of Python is creating +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. From 4fb3bf7b4a9638ce7d69cb4bde6bcfaf543710c2 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Sun, 12 Jun 2016 19:51:46 +0800 Subject: [PATCH 13/60] Wrote a bit about docstrings --- docs/writing/documentation.rst | 120 +++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index bd59437..cb541e1 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -65,6 +65,11 @@ There is also **great**, **free** hosting for your Sphinx_ docs: your source repository so that rebuilding your documentation will happen automatically. +When run, Sphinx_ will import your code and using Python's introspection +features it will extract all function, method and class signatures. It will +also extract the accompanying docstrings, and compile it all into well +structured and easily readable documentation for your project. + .. note:: Sphinx is famous for its API generation, but it also works well @@ -127,6 +132,30 @@ Some tools use docstrings to embed more-than-documentation behavior, such as unit test logic. Those can be nice, but you won't ever go wrong with vanilla "here's what this does." +Tools like Sphinx_ will parse your docstrings as reStructuredText and render it +correctly as HTML. This makes it very easy to embed snippets of example code in +a project's documentation. + +Additionally, Doctest_ will read all embedded docstrings that look like input +from the Python commandline (prefixed with ">>>") and run them, checking to see +if the output of the command matches the text on the following line. This +allows developers to embed real examples and usage of functions alongside +their source code, and as a side effect, it also ensures that their code is +tested and works. + +:: + + def my_function(a, b): + """ + >>> my_function(2, 3) + 6 + >>> my_function('a', 3) + 'aaa' + """ + return a * b + +.. _Doctest: https://docs.python.org/3/library/doctest.html + Docstrings versus Block comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,8 +170,99 @@ comment block is a programmer's note. The docstring describes the """Returns the square root of self times self.""" ... +Unlike block comments, docstrings are built into the Python language itself. +This means you can use all of Python's powerful introspection capabilities to +access docstrings at runtime, compared with comments which are optimised out. +Docstrings are accessible from both the `__doc__` dunder attribute for almost +every Python object, as well as with the built in `help()` function. + +While block comments are usually used to explain *what* a section of code is +doing, or the specifics of an algorithm, docstrings are more intended for +explaining to other users of your code (or you in 6 months time) *how* a +particular function can be used and the general purpose of a function, class, +or module. + +Writing Docstrings +~~~~~~~~~~~~~~~~~~ + +Depending on the complexity of the function, method, or class being written, a +one-line docstring may be perfectly appropriate. These are generally used for +really obvious cases, such as:: + + def add(a, b): + """Add two numbers and return the result.""" + return a + b + +The docstring should describe the function in a way that is easy to understand. +Embedding the function's signature in the docstring is unnecessary because it +can easily be obtained using the `inspect` module, and doesn't provide much +additional information. + +For more complex cases, there are a couple generally accepted styles used +when writing documentation. The first of these uses reStructuredText syntax +to format arguments and other elements of the docstring appropriately:: + + def function1(self, arg1, arg2, arg3): + """A short, one line summary of the function. + + This is a longer explanation, which may include math with + latex syntax :math:`\\alpha`. + + :param arg1: the first value + :param arg2: the first value + :param arg3: the first value + :type arg1: int, float,... + :type arg2: int, float,... + :type arg3: int, float,... + :returns: arg1/arg2 +arg3 + :rtype: int, float + """ + return arg1/arg2 + arg3 + +`thomas-cokelaer.info`_ has a fairly complete article showing more examples for +this style. + +While the end result is parsed by Sphinx and renders correctly in a browser, it +isn't the easiest of formats to read. The `NumPy style`_ is a lot nicer to read, +however it consumes a lot more real estate than the previous style:: + + def random_number_generator(arg1, arg2): + """ + Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + int + Description of return value + + """ + return 42 + +The `sphinx.ext.napoleon`_ plugin allows Sphinx to parse this style of +docstrings, making it easy to incorporate NumPy style docstrings into your +project. + +At the end of the day, it doesn't really matter what style is used for writing +docstrings, their purpose is to serve as documentation for anyone who may need +to read or make changes to your code. As long as it is correct, understandable +and gets the relevant points across then it has done the job it was designed to +do. + + .. see also:: Further reading on docstrings: :pep:`257` +.. _thomas-cokelaer.info: http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html +.. _sphinx.ext.napoleon: https://sphinxcontrib-napoleon.readthedocs.io/ +.. _`NumPy style`: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html Other Tools ----------- From fb388b8f7bffabc728b1a90178eed16515f61585 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Sun, 12 Jun 2016 19:53:40 +0800 Subject: [PATCH 14/60] changed the pep 257 line from a see also to a normal line --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index cb541e1..0368681 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -258,7 +258,7 @@ and gets the relevant points across then it has done the job it was designed to do. -.. see also:: Further reading on docstrings: :pep:`257` +For further reading on docstrings, feel free to consult :pep:`257` .. _thomas-cokelaer.info: http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html .. _sphinx.ext.napoleon: https://sphinxcontrib-napoleon.readthedocs.io/ From 3c0b0270baad77a813bf1dedb5674ba159f966d1 Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Mon, 13 Jun 2016 09:49:18 +0800 Subject: [PATCH 15/60] Removed the rst/sphinx-style docstring example --- docs/writing/documentation.rst | 31 ++++--------------------------- 1 file changed, 4 insertions(+), 27 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 0368681..c5f8221 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -198,33 +198,10 @@ Embedding the function's signature in the docstring is unnecessary because it can easily be obtained using the `inspect` module, and doesn't provide much additional information. -For more complex cases, there are a couple generally accepted styles used -when writing documentation. The first of these uses reStructuredText syntax -to format arguments and other elements of the docstring appropriately:: - - def function1(self, arg1, arg2, arg3): - """A short, one line summary of the function. - - This is a longer explanation, which may include math with - latex syntax :math:`\\alpha`. - - :param arg1: the first value - :param arg2: the first value - :param arg3: the first value - :type arg1: int, float,... - :type arg2: int, float,... - :type arg3: int, float,... - :returns: arg1/arg2 +arg3 - :rtype: int, float - """ - return arg1/arg2 + arg3 - -`thomas-cokelaer.info`_ has a fairly complete article showing more examples for -this style. - -While the end result is parsed by Sphinx and renders correctly in a browser, it -isn't the easiest of formats to read. The `NumPy style`_ is a lot nicer to read, -however it consumes a lot more real estate than the previous style:: +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 than usual, it allows the developer to include a lot more +information about a method, function, or class. :: def random_number_generator(arg1, arg2): """ From 10defd73a2f1cb34887f178dc119c32c2dbbba8d Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Mon, 13 Jun 2016 10:07:29 +0800 Subject: [PATCH 16/60] Added a bit so the transition from short to long docstrings flows better --- docs/writing/documentation.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c5f8221..b159351 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -194,14 +194,20 @@ really obvious cases, such as:: return a + b The docstring should describe the function in a way that is easy to understand. -Embedding the function's signature in the docstring is unnecessary because it -can easily be obtained using the `inspect` module, and doesn't provide much -additional information. +For simple cases like trivial functions and classes, simply embedding the +function's signature (i.e. `add(a, b) -> result`) in the docstring is +unnecessary. This is because with Python's `inspect` module, it is already +quite easy to find this information if needed, and it is also readily available +by reading the source code. + +In larger or more complex projects however, it is often a good idea to give +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 than usual, it allows the developer to include a lot more -information about a method, function, or class. :: +few more lines 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 fc8788b2300f6674764d20bf2f0835a0cc38b544 Mon Sep 17 00:00:00 2001 From: Rahiel Kasim Date: Tue, 14 Jun 2016 14:04:43 +0200 Subject: [PATCH 17/60] speed.rst: PEP8 in examples PEP8 --- docs/scenarios/speed.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 21166b2..fc038c1 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -108,7 +108,7 @@ keywords compared to the next one, which is implemented in pure Python: def primes(kmax): """Calculation of prime numbers in standard Python syntax""" - p= range(1000) + p = range(1000) result = [] if kmax > 1000: kmax = 1000 @@ -145,7 +145,7 @@ to be compiled into C types while also creating a Python list: def primes(kmax): """Calculation of prime numbers in standard Python syntax""" - p= range(1000) + p = range(1000) result = [] What is the difference? In the upper Cython version you can see the From 7c7fe74dab50e5ee722ad0ca434398cee505dd4a Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Singh Date: Mon, 20 Jun 2016 18:06:58 +0530 Subject: [PATCH 18/60] Update admin.rst with monitoring tool shinken. --- docs/scenarios/admin.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index f0b56a6..55926fd 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -380,3 +380,13 @@ environment can be created, and many are already available. Buidout is written in Python. +Shinken +------- + +`Shinken `_ is a modern, Nagios compatible monitoring framework, written in Python. +Its main goal is to give users a flexible architecture for their monitoring +system that is designed to scale to large environments. + +Shinken is backwards-compatible with the Nagios configuration standard and plugins. +It works on any operating system and architecture that supports Python, which includes +Windows, GNU/Linux and FreeBSD. From 2ed32ebe0d9b683f48dab70c4a5600669ecfbb03 Mon Sep 17 00:00:00 2001 From: kikisdeliveryservice Date: Mon, 20 Jun 2016 13:38:23 -0700 Subject: [PATCH 19/60] Clean up of intro paragraphs for clarity. --- docs/writing/style.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 2b2c7c8..0c60372 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -3,17 +3,17 @@ Code Style ========== -If you ask Python programmers what they like most in Python, they will -often say its high readability. Indeed, a high level of readability +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 recognized fact that code is read much more often than it is written. -One reason for Python code to be easily read and understood is its relatively +One reason for the high readability of Python code is its relatively complete set of Code Style guidelines and "Pythonic" idioms. -Moreover, when a veteran Python developer (a Pythonista) points to portions of -code and says they are not "Pythonic", it usually means that these lines -of code do not follow the common guidelines and fail to express the intent in +When a veteran Python developer (a Pythonista) calls portions of +code not "Pythonic", they usually mean that these lines +of code do not follow the common guidelines and fail to express its intent in what is considered the best (hear: most readable) way. On some border cases, no best way has been agreed upon on how to express @@ -53,7 +53,7 @@ One statement per line While some compound statements such as list comprehensions are allowed and appreciated for their brevity and their expressiveness, -it is bad practice to have two disjoint statements on the same line of code. +it is bad practice to have two disjointed statements on the same line of code. **Bad** From 673ed9a74218fbdb3d14e923e21e9be8bbce4d5c Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Mon, 20 Jun 2016 23:16:50 -0400 Subject: [PATCH 20/60] oreilly book --- docs/_templates/sidebarintro.html | 7 +++++++ docs/_templates/sidebarlogo.html | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index b52228c..400b66a 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -20,6 +20,13 @@

Join Mailing List.

+

O'Reilly Book

+ +

This guide is now available for pre-order in tangible book form!

+ + + +

All proceeds are being directly donated to the DjangoGirls organization.

Other Projects

diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index 9ef1f0a..b11b551 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -19,7 +19,13 @@

Join Mailing List.

+

O'Reilly Book

+

This guide is now available for pre-order in tangible book form!

+ + + +

All proceeds are being directly donated to the DjangoGirls organization.

Other Projects

From 30f19999fd5823f85bd6f535504188b49c9d4baf Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Singh Date: Tue, 21 Jun 2016 12:54:55 +0530 Subject: [PATCH 21/60] Corrected Oxford comma. Close #238 Signed-off-by: Abhishek Kumar Singh --- docs/scenarios/admin.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 55926fd..69e66d4 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -383,10 +383,11 @@ Buidout is written in Python. Shinken ------- -`Shinken `_ is a modern, Nagios compatible monitoring framework, written in Python. -Its main goal is to give users a flexible architecture for their monitoring -system that is designed to scale to large environments. +`Shinken `_ is a modern, Nagios compatible +monitoring framework written in Python.Its main goal is to give users a flexible +architecture for their monitoring system that is designed to scale to large +environments. -Shinken is backwards-compatible with the Nagios configuration standard and plugins. -It works on any operating system and architecture that supports Python, which includes -Windows, GNU/Linux and FreeBSD. +Shinken is backwards-compatible with the Nagios configuration standard and +plugins.It works on any operating system and architecture that supports Python +which includes Windows, GNU/Linux and FreeBSD. From a64d47166c198f3161b8c3d25121e97da4d59cfa Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Singh Date: Tue, 21 Jun 2016 13:00:42 +0530 Subject: [PATCH 22/60] Added Oxford Comma! Signed-off-by: Abhishek Kumar Singh --- docs/scenarios/admin.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 69e66d4..7fbc9b5 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -384,10 +384,10 @@ Shinken ------- `Shinken `_ is a modern, Nagios compatible -monitoring framework written in Python.Its main goal is to give users a flexible +monitoring framework written in Python. Its main goal is to give users a flexible architecture for their monitoring system that is designed to scale to large environments. -Shinken is backwards-compatible with the Nagios configuration standard and -plugins.It works on any operating system and architecture that supports Python -which includes Windows, GNU/Linux and FreeBSD. +Shinken is backwards-compatible with the Nagios configuration standard, and +plugins.It works on any operating system, and architecture that supports Python +which includes Windows, GNU/Linux, and FreeBSD. From 081c47511f6f7357154b9738ac5c3df6ffac0b6b Mon Sep 17 00:00:00 2001 From: nhumrich Date: Tue, 21 Jun 2016 12:28:06 -0600 Subject: [PATCH 23/60] Update cli.rst Add cement to cli frameworks --- docs/scenarios/cli.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index c8cdcec..ccd9681 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -62,3 +62,13 @@ subcommands, output formatters, and other extensions. The framework is meant to be used to create multi-level commands such as subversion and git, where the main program handles some basic argument parsing and then invokes a sub-command to do the work. + +Cement +------ + +`Cement `_ is an advanced CLI Application Framework. +Its goal is to introduce a standard, and feature-full platform +for both simple and complex command line applications as well +as support rapid development needs without sacrificing quality. +Cement is flexible, and it's use cases span from the simplicity of a micro-framework +to the complexity of a meg-framework. From 122f67bf050d35530aee4fc6d8886b4ba73f6cdd Mon Sep 17 00:00:00 2001 From: kikisdeliveryservice Date: Tue, 21 Jun 2016 13:06:58 -0700 Subject: [PATCH 24/60] Clean up of tests.rst --- docs/writing/tests.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 84e5d27..0849530 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -3,8 +3,8 @@ Testing Your Code Testing your code is very important. -Getting used to writing the testing code and the running code in parallel is -now considered a good habit. Used wisely, this method helps you define more +Getting used to writing testing code and running this code in parallel is now +considered a good habit. Used wisely, this method helps you define more precisely your code's intent and have a more decoupled architecture. Some general rules of testing: @@ -12,8 +12,8 @@ Some general rules of testing: - A testing unit should focus on one tiny bit of functionality and prove it correct. -- Each test unit must be fully independent. Each of them must be able to run - alone, and also within the test suite, regardless of the order they are +- Each test unit must be fully independent. Each test must be able to run + alone, and also within the test suite, regardless of the order that they are called. The implication of this rule is that each test must be loaded with a fresh dataset and may have to do some cleanup afterwards. This is usually handled by :meth:`setUp()` and :meth:`tearDown()` methods. @@ -27,8 +27,8 @@ Some general rules of testing: tests as often as needed. - Learn your tools and learn how to run a single test or a test case. Then, - when developing a function inside a module, run this function's tests very - often, ideally automatically when you save the code. + when developing a function inside a module, run this function's tests + frequently, ideally automatically when you save the code. - Always run the full test suite before a coding session, and run it again after. This will give you more confidence that you did not break anything @@ -63,11 +63,11 @@ Some general rules of testing: - Another use of the testing code is as an introduction to new developers. When someone will have to work on the code base, running and reading the related - testing code is often the best they can do. They will or should discover the - hot spots, where most difficulties arise, and the corner cases. If they have - to add some functionality, the first step should be to add a test and, by this - means, ensure the new functionality is not already a working path that has not - been plugged into the interface. + testing code is often the best thing that they can do to start. They will + or should discover the hot spots, where most difficulties arise, and the + corner cases. If they have to add some functionality, the first step should + be to add a test to ensure that the new functionality is not already a + working path that has not been plugged into the interface. The Basics :::::::::: From 82a89026b9300322443a135e962b7784fdd00d1a Mon Sep 17 00:00:00 2001 From: Aaron Peschel Date: Tue, 28 Jun 2016 15:53:53 -0700 Subject: [PATCH 25/60] Don't treat targets as files Currently, this sample Makefile has problems if there are any files/directories named init or test in the same directory as the makefile. This commit adds a phony to the sample Makefile so that these targets are not treated as files. --- docs/writing/structure.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 4f8bb37..31f387e 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -254,6 +254,8 @@ your project. test: py.test tests + .PHONY init test + Other generic management scripts (e.g. ``manage.py`` or ``fabfile.py``) belong at the root of the repository as well. From a603b95c8746f0a6333ec7fa31e4536a47a0868c Mon Sep 17 00:00:00 2001 From: Don Jayamanne Date: Wed, 6 Jul 2016 17:17:28 +1000 Subject: [PATCH 26/60] updated to include a reference to VS Code --- docs/dev/env.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 41ec2d7..3e03253 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -150,6 +150,14 @@ features can be brought to IntelliJ with the free 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 `_ is an extension for the `Visual Studio Code IDE `_. +This is a free, light weight and open source IDE, with support for Mac, Windows and Linux. +Built using open source technologies such as NodeJs and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. +MIT licensed. + Enthought Canopy ---------------- `Enthought Canopy `_ is a Python From 46ca5e9323b250d9d3addff93b066c49bc1edbe5 Mon Sep 17 00:00:00 2001 From: Don Jayamanne Date: Thu, 7 Jul 2016 00:23:31 +1000 Subject: [PATCH 27/60] fixed review issues --- docs/dev/env.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 3e03253..d587027 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -154,8 +154,9 @@ Python (on Visual Studio Code) ----------------------------- `Python for Visual Studio `_ is an extension for the `Visual Studio Code IDE `_. -This is a free, light weight and open source IDE, with support for Mac, Windows and Linux. -Built using open source technologies such as NodeJs and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. +This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux. +Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. + MIT licensed. Enthought Canopy From d0d6f664edbf2ea2b3d34aaaebbaf6959b74fe24 Mon Sep 17 00:00:00 2001 From: Thomas Gratier Date: Sat, 9 Jul 2016 10:33:07 +0200 Subject: [PATCH 28/60] Duplicated word --- docs/scenarios/clibs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 290638e..bae907b 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -39,7 +39,7 @@ types, such as structs and unions, and allows you to modify things such as padding and alignment, if needed. It can be a bit crufty to use, but in conjunction with the `struct `_ module, you are essentially provided full control over how your data types get -translated into something something usable by a pure C(++) method. +translated into something usable by a pure C(++) method. Struct Equivalents ~~~~~~~~~~~~~~~~~~ From 82ef7f39ba6fc1570e29707eb0a332bca9e82232 Mon Sep 17 00:00:00 2001 From: Thomas Gratier Date: Sat, 9 Jul 2016 22:46:17 +0200 Subject: [PATCH 29/60] Remove duplicated "in" word --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 7fbc9b5..8356223 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -190,7 +190,7 @@ Ansible `Ansible `_ is an open source system automation tool. The biggest advantage over Puppet or Chef is it does not require an agent on the client machine. Playbooks are Ansible’s configuration, deployment, and -orchestration language and are written in in YAML with Jinja2 for templating. +orchestration language and are written in YAML with Jinja2 for templating. Ansible supports Python versions 2.6 and 2.7 and can be installed via pip: From 730c97f4afcaf9c5348e23c8358e48fc2a37c32b Mon Sep 17 00:00:00 2001 From: Thomas Gratier Date: Sun, 10 Jul 2016 00:12:12 +0200 Subject: [PATCH 30/60] Fix typo: infrustructure to infrastructure --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 8356223..0bd928d 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -262,7 +262,7 @@ To create a simple cookbook the `knife `_ comma `Getting started with Chef `_ is a good starting point for Chef Beginners and many community maintained cookbooks that can -serve as a good reference or tweaked to serve your infrustructure configuration needs can be +serve as a good reference or tweaked to serve your infrastructure configuration needs can be found on the `Chef Supermarket `_. - `Chef Documentation `_ From ecb39fcf6a8f3b80abfab3aeef7af5c977c2a5be Mon Sep 17 00:00:00 2001 From: Thomas Gratier Date: Sat, 16 Jul 2016 21:48:36 +0200 Subject: [PATCH 31/60] Indent unindented content in numbered list --- docs/writing/style.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 0c60372..7454e94 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -124,13 +124,13 @@ inside the function) that was added "just in case" and is seemingly never used, than to add a new optional argument and its logic when needed. 3. The **arbitrary argument list** is the third way to pass arguments to a -function. If the function intention is better expressed by a signature with an -extensible number of positional arguments, it can be defined with the ``*args`` -constructs. In the function body, ``args`` will be a tuple of all the -remaining positional arguments. For example, ``send(message, *args)`` can be -called with each recipient as an argument: ``send('Hello', 'God', 'Mom', -'Cthulhu')``, and in the function body ``args`` will be equal to ``('God', -'Mom', 'Cthulhu')``. + function. If the function intention is better expressed by a signature with + an extensible number of positional arguments, it can be defined with the + ``*args`` constructs. In the function body, ``args`` will be a tuple of all + the remaining positional arguments. For example, ``send(message, *args)`` + can be called with each recipient as an argument:``send('Hello', 'God', + 'Mom', 'Cthulhu')``, and in the function body ``args`` will be equal to + ``('God', 'Mom', 'Cthulhu')``. However, this construct has some drawbacks and should be used with caution. If a function receives a list of arguments of the same nature, it is often more From f31ca0a5fbdb7531d752f668816b7aa8108dcac4 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Mon, 18 Jul 2016 14:07:09 -0400 Subject: [PATCH 32/60] french! --- docs/_templates/sidebarintro.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 400b66a..e916269 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -60,7 +60,8 @@

Translations

\ No newline at end of file + From 5d4b76ca37ce0758380d939b306a78d6f9adaf8c Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Mon, 18 Jul 2016 14:07:22 -0400 Subject: [PATCH 33/60] Update sidebarlogo.html --- docs/_templates/sidebarlogo.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index b11b551..f5e634c 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -42,7 +42,8 @@

Translations

\ No newline at end of file + From c31000c6b8c1c520086af755645a21876bb6bacc Mon Sep 17 00:00:00 2001 From: Manas Date: Wed, 27 Jul 2016 12:28:41 +0530 Subject: [PATCH 34/60] Update startproject in example start-project should be startproject https://docs.djangoproject.com/en/1.9/ref/django-admin/#django-admin-startproject --- docs/writing/structure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 31f387e..7879d17 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -271,7 +271,7 @@ following, as they always have: :: - $ django-admin.py start-project samplesite + $ django-admin.py startproject samplesite The resulting repository structure looks like this: @@ -293,7 +293,7 @@ Let's do it properly: :: - $ django-admin.py start-project samplesite . + $ django-admin.py startproject samplesite . Note the "``.``". From ca64c6f722c00226bdfd30a58a6efc9f0bd45c3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Hermann?= Date: Wed, 27 Jul 2016 23:05:53 +0200 Subject: [PATCH 35/60] Mention dh-virtualenv in the Tools list --- docs/shipping/packaging.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 1c65961..596ebaf 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -184,3 +184,4 @@ Useful Tools - `fpm `_ - `alien `_ +- `dh-virtualenv `_ (for APT/DEB omnibus packaging) From f86e9cc096174967105c76954055e27dd92e25cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Konrad=20F=C3=B6rstner?= Date: Fri, 29 Jul 2016 08:29:18 +0200 Subject: [PATCH 36/60] Update link for rpy2 --- docs/scenarios/scientific.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 8600bc9..92c8c80 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -94,7 +94,7 @@ auto-alignment of data. Rpy2 ---- -`Rpy2 `_ is a Python binding for the R +`Rpy2 `_ is a Python binding for the R statistical package allowing the execution of R functions from Python and passing data back and forth between the two environments. Rpy2 is the object oriented implementation of the `Rpy `_ From 1bcc6d5cc84b5de6c2c5fccda45b0529556a7924 Mon Sep 17 00:00:00 2001 From: Robson Roberto Souza Peixoto Date: Mon, 1 Aug 2016 00:43:48 -0300 Subject: [PATCH 37/60] Cleaning up *.py[co] and __pycache__ tip --- 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 3a4c335..f8e2e23 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -224,7 +224,7 @@ Removing Bytecode (.pyc) Files Here's nice trick for removing all of these files, if they already exist:: - $ find . -name "*.pyc" -delete + $ find . -type f -name "*.py[co]" -delete -or -type d -name "__pycache__" -delete Run that from the root directory of your project, and all ``.pyc`` files will suddenly vanish. Much better. From 91df42f1708875a095561965a2816774ea41fbb2 Mon Sep 17 00:00:00 2001 From: Kevin Ndung'u Date: Wed, 10 Aug 2016 16:58:21 +0300 Subject: [PATCH 38/60] Fix .PHONY target rule .PHONY should be followed by a colon --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 7879d17..ef0184e 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -254,7 +254,7 @@ your project. test: py.test tests - .PHONY init test + .PHONY: init test Other generic management scripts (e.g. ``manage.py`` or ``fabfile.py``) belong at the root of the repository as well. From 7adc9c0d030622b6896c5aa82ef4cb48828851a0 Mon Sep 17 00:00:00 2001 From: Ahmad Jarara Date: Sun, 28 Aug 2016 17:35:52 -0400 Subject: [PATCH 39/60] fix memoization typo, link to wikipedia's overview --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index ef0184e..87395c4 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -602,7 +602,7 @@ clearer and thus preferred. This mechanism is useful for separating concerns and avoiding external un-related logic 'polluting' the core logic of the function or method. A good example of a piece of functionality that is better handled -with decoration is memorization or caching: you want to store the results of an +with decoration is `memoization ` or caching: you want to store the results of an expensive function in a table and use them directly instead of recomputing them when they have already been computed. This is clearly not part of the function logic. From 71257bed9e3c06c0e962712026791d855c7c14f8 Mon Sep 17 00:00:00 2001 From: Ahmad Jarara Date: Mon, 29 Aug 2016 20:49:31 -0400 Subject: [PATCH 40/60] fixing markup on memoization link hint --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 87395c4..a156fba 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -602,7 +602,7 @@ clearer and thus preferred. This mechanism is useful for separating concerns and avoiding external un-related logic 'polluting' the core logic of the function or method. A good example of a piece of functionality that is better handled -with decoration is `memoization ` or caching: you want to store the results of an +with decoration is `memoization `__ or caching: you want to store the results of an expensive function in a table and use them directly instead of recomputing them when they have already been computed. This is clearly not part of the function logic. From f0867fe4d68b681de130973c692801858f1dcc2d Mon Sep 17 00:00:00 2001 From: Ahmad Jarara Date: Wed, 31 Aug 2016 14:45:35 -0400 Subject: [PATCH 41/60] include instructions to preview changes in CONTRIB --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 481f3f6..83a9cd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,28 @@ see: http://docs.python-guide.org/en/latest/notes/contribute/ +How to test your changes +------------------------ + +The html version of this guide is built with [sphinx](http://www.sphinx-doc.org/en/stable/). You may test your revisions locally by having sphinx installed. You can do this easily with pip (as described in the link). + +``` bash +pip install --user sphinx +``` + +Then navigate to the directory of the makefile and ```make build``` or ```make html```. Sphinx will then generate the html in a folder called _build/html + +After navigating to this folder, you can then use python's built in webserver to view your changes locally: + +``` bash +python3 -m http.server +``` + +By default, http.server listens on every ip address bound on your host on port 8000. To bind to a specific one, say, localhost on port 8005: + +``` bash +python3 -m http.server 8005 --bind 127.0.0.1 +``` Style Guide ----------- From 15396a5403a1563ecab439415ed7631fd6ea6cee Mon Sep 17 00:00:00 2001 From: denfromufa Date: Thu, 1 Sep 2016 15:31:20 -0500 Subject: [PATCH 42/60] Update which-python.rst Pythonnet supports from Python 2.6 up to Python 3.5 --- docs/starting/which-python.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index b07b634..26732e3 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -137,12 +137,12 @@ installation with the .NET Common Language Runtime (CLR). This is the inverse approach to that taken by IronPython (see above), to which it is more complementary than competing with. -In conjunction with Mono, PythonNet enables native Python +In conjunction with Mono, pythonnet enables native Python installations on non-Windows operating systems, such as OS X and Linux, to operate within the .NET framework. It can be run in addition to IronPython without conflict. -PythonNet supports from Python 2.3 up to Python 2.7. [#pythonnet_ver]_ +Pythonnet supports from Python 2.6 up to Python 3.5. [#pythonnet_ver1]_ [#pythonnet_ver2]_ .. [#pypy_ver] http://pypy.org/compat.html @@ -150,6 +150,8 @@ PythonNet supports from Python 2.3 up to Python 2.7. [#pythonnet_ver]_ .. [#iron_ver] http://ironpython.codeplex.com/releases/view/81726 -.. [#pythonnet_ver] http://pythonnet.github.io/readme.html +.. [#pythonnet_ver1] https://travis-ci.org/pythonnet/pythonnet + +.. [#pythonnet_ver2] https://ci.appveyor.com/project/TonyRoberts/pythonnet-480xs .. [#pep373_eol] https://www.python.org/dev/peps/pep-0373/#id2 From cfb46b56ae8735fbd5d269e9df57b1349cc3472c Mon Sep 17 00:00:00 2001 From: Ruben Roy Date: Wed, 14 Sep 2016 04:49:03 +0530 Subject: [PATCH 43/60] Update contents.rst.inc Fixes layout issue in subsection 1.2.1 with latex --- docs/contents.rst.inc | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index c2c603d..f84b3f0 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -7,16 +7,10 @@ New to Python? Let's properly setup up your Python environment. :maxdepth: 2 starting/which-python - -- Properly Install Python - - .. toctree:: - :maxdepth: 1 - - starting/installation - starting/install/osx - starting/install/win - starting/install/linux + starting/installation + starting/install/osx + starting/install/win + starting/install/linux From af7d603e977efc2156d8c9e3c51b5ccb0ce4f91c Mon Sep 17 00:00:00 2001 From: Adam Chainz Date: Wed, 21 Sep 2016 08:31:09 +0100 Subject: [PATCH 44/60] Convert readthedocs links for their .org -> .io migration for hosted projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per [their blog post of the 27th April](https://blog.readthedocs.com/securing-subdomains/) ‘Securing subdomains’: > Starting today, Read the Docs will start hosting projects from subdomains on the domain readthedocs.io, instead of on readthedocs.org. This change addresses some security concerns around site cookies while hosting user generated data on the same domain as our dashboard. Test Plan: Manually visited all the links I’ve modified. --- docs/_templates/sidebarintro.html | 8 ++++---- docs/_templates/sidebarlogo.html | 8 ++++---- docs/dev/virtualenvs.rst | 6 +++--- docs/intro/learning.rst | 2 +- docs/scenarios/ci.rst | 2 +- docs/scenarios/clibs.rst | 2 +- docs/scenarios/db.rst | 6 +++--- docs/scenarios/gui.rst | 2 +- docs/scenarios/imaging.rst | 6 +++--- docs/scenarios/json.rst | 2 +- docs/scenarios/web.rst | 14 +++++++------- docs/shipping/packaging.rst | 4 ++-- docs/starting/install/osx.rst | 2 +- docs/writing/tests.rst | 2 +- 14 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index e916269..2c085fc 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -60,8 +60,8 @@

Translations

diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index f5e634c..605909b 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -42,8 +42,8 @@

Translations

diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index bb3f948..848d7ae 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -122,7 +122,7 @@ control by adding it to the ignore list. virtualenvwrapper ----------------- -`virtualenvwrapper `_ +`virtualenvwrapper `_ provides a set of commands which makes working with virtual environments much more pleasant. It also places all your virtual environments in one place. @@ -134,7 +134,7 @@ To install (make sure **virtualenv** is already installed): $ export WORKON_HOME=~/Envs $ source /usr/local/bin/virtualenvwrapper.sh -(`Full virtualenvwrapper install instructions `_.) +(`Full virtualenvwrapper install instructions `_.) For Windows, you can use the `virtualenvwrapper-win `_. @@ -206,7 +206,7 @@ Other useful commands ``lssitepackages`` Shows contents of :file:`site-packages` directory. -`Full list of virtualenvwrapper commands `_. +`Full list of virtualenvwrapper commands `_. virtualenv-burrito ------------------ diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 8ab6608..823da5b 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -38,7 +38,7 @@ without having to install Python locally. 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 `_ + `Python for You and Me `_ Online Python Tutor ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index aa8d196..16e0ea0 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -35,7 +35,7 @@ automate the compile/test cycle to validate code changes. Tox --- -`tox `_ is an automation tool providing +`tox `_ is an automation tool providing packaging, testing and deployment of Python software right from the console or CI server. It is a generic virtualenv management and test command line tool which provides the following features: diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index bae907b..82e041f 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -4,7 +4,7 @@ Interfacing with C/C++ Libraries C Foreign Function Interface ---------------------------- -`CFFI `_ provides a simple to use +`CFFI `_ provides a simple to use mechanism for interfacing with C from both CPython and PyPy. It supports two modes: an inline ABI compatibility mode (example provided below), which allows you to dynamically load and run functions from executable modules (essentially diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 3ed1191..58d9cd2 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -60,11 +60,11 @@ peewee `peewee `_ is another ORM with a focus on being lightweight with support for Python 2.6+ and 3.2+ which supports SQLite, MySQL and Postgres by default. The -`model layer `_ +`model layer `_ is similar to that of the Django ORM and it has -`SQL-like methods `_ +`SQL-like methods `_ to query data. While SQLite, MySQL and Postgres are supported out-of-the-box, -there is a `collection of add-ons `_ +there is a `collection of add-ons `_ available. PonyORM diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 854fb82..f56b212 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -28,7 +28,7 @@ applications be ported from PyGTK to PyGObject. PyGObject aka (PyGi) -------------------- `PyGObject `_ provides Python bindings, which gives access to the entire GNOME software platform. -It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial `_. +It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial `_. `API Reference `_ diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst index 23ecece..49d3af1 100644 --- a/docs/scenarios/imaging.rst +++ b/docs/scenarios/imaging.rst @@ -24,7 +24,7 @@ Installation Before installing Pillow, you'll have to install Pillow's prerequisites. Find the instructions for your platform in the -`Pillow installation instructions `_. +`Pillow installation instructions `_. After that, it's straightforward: @@ -57,7 +57,7 @@ Example exif_data There are more examples of the Pillow library in the -`Pillow tutorial `_. +`Pillow tutorial `_. OpenSource Computer Vision @@ -104,4 +104,4 @@ Example There are more Python-implemented examples of OpenCV in this `collection of tutorials -`_. +`_. diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst index b5145fc..860e794 100644 --- a/docs/scenarios/json.rst +++ b/docs/scenarios/json.rst @@ -47,7 +47,7 @@ simplejson The JSON library was added to Python in version 2.6. If you're using an earlier version of Python, the -`simplejson `_ library is +`simplejson `_ library is available via PyPI. simplejson mimics the json standard library. It is available so that developers diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 601e880..9e07a59 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -154,7 +154,7 @@ Gunicorn is the recommended choice for new Python web applications today. Waitress -------- -`Waitress `_ is a pure-python WSGI server +`Waitress `_ is a pure-python WSGI server that claims "very acceptable performance". Its documentation is not very detailed, but it does offer some nice functionality that Gunicorn doesn't have (e.g. HTTP request buffering). @@ -166,18 +166,18 @@ Waitress is gaining popularity within the Python web development community. uWSGI ----- -`uWSGI `_ is a full stack for building +`uWSGI `_ is a full stack for building hosting services. In addition to process management, process monitoring, and other functionality, uWSGI acts as an application server for various programming languages and protocols - including Python and WSGI. uWSGI can either be run as a stand-alone web router, or be run behind a full web server (such as Nginx or Apache). In the latter case, a web server can configure uWSGI and an application's operation over the -`uwsgi protocol `_. +`uwsgi protocol `_. uWSGI's web server support allows for dynamically configuring Python, passing environment variables and further tuning. For full details, see `uWSGI magic -variables `_. +variables `_. I do not recommend using uWSGI unless you know why you need it. @@ -393,10 +393,10 @@ Jinja2 is the recommended templating library for new Python web applications. Chameleon --------- -`Chameleon `_ Page Templates are an HTML/XML template +`Chameleon `_ Page Templates are an HTML/XML template engine implementation of the `Template Attribute Language (TAL) `_, -`TAL Expression Syntax (TALES) `_, -and `Macro Expansion TAL (Metal) `_ syntaxes. +`TAL Expression Syntax (TALES) `_, +and `Macro Expansion TAL (Metal) `_ syntaxes. Chameleon is available for Python 2.5 and up (including 3.x and pypy), and is commonly used by the `Pyramid Framework `_. diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 596ebaf..c679575 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -25,7 +25,7 @@ and being able and willing to use tools such as pip to install your code's other dependencies. This is fine when distributing to other developers, but makes this method unsuitable for distributing applications to end-users. -The `Python Packaging Guide `_ +The `Python Packaging Guide `_ provides an extensive guide on creating and maintaining Python packages. Alternatives to Packaging @@ -184,4 +184,4 @@ Useful Tools - `fpm `_ - `alien `_ -- `dh-virtualenv `_ (for APT/DEB omnibus packaging) +- `dh-virtualenv `_ (for APT/DEB omnibus packaging) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 03426c5..4222485 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -77,7 +77,7 @@ 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 `_, +that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, and is actively maintained. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 0849530..b8b7ca0 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -202,7 +202,7 @@ 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. - `nose `_ + `nose `_ tox From 1caa6c77509c1453fb36dfa498b94358015d6b66 Mon Sep 17 00:00:00 2001 From: "Tim D. Smith" Date: Thu, 22 Sep 2016 12:39:35 -0700 Subject: [PATCH 45/60] CLT are not needed if full Xcode is installed --- docs/starting/install/osx.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 4222485..b6eb135 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -32,10 +32,6 @@ package. 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. `Homebrew `_ fills this void. From 359e4b9e3d066d3f3f9c10dbad2af5bf4e78220a Mon Sep 17 00:00:00 2001 From: "Tim D. Smith" Date: Thu, 22 Sep 2016 12:40:43 -0700 Subject: [PATCH 46/60] Don't specifically need gcc --- docs/starting/install/osx.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index b6eb135..3d14254 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -21,10 +21,10 @@ 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 `_, the smaller -`Command Line Tools `_ (must have an -Apple account) or the even smaller `OSX-GCC-Installer `_ +Before installing Python, you'll need to install a C compiler. A compiler can be +obtained by downloading `Xcode `_, the +smaller `Command Line Tools `_ (must +have an Apple account) or the even smaller `OSX-GCC-Installer `_ package. .. note:: From 1d516898b3f6872b8cda1b823797781f64cfb87d Mon Sep 17 00:00:00 2001 From: "Tim D. Smith" Date: Thu, 22 Sep 2016 12:45:16 -0700 Subject: [PATCH 47/60] Update guidance on C toolchains --- docs/starting/install/osx.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 3d14254..e8aa1df 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -21,16 +21,18 @@ Doing it Right Let's install a real version of Python. -Before installing Python, you'll need to install a C compiler. A compiler can be -obtained by downloading `Xcode `_, the -smaller `Command Line Tools `_ (must -have an Apple account) or the even smaller `OSX-GCC-Installer `_ +Before installing Python, you'll need to install a C compiler. The fastest way +is to install the Xcode Command Line Tools by running +``xcode-select --install``. You can also download the full version of +`Xcode `_ from the Mac App Store, or the +minimal but unofficial +`OSX-GCC-Installer `_ 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. + 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. 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. From 2423a9da64181d8a55be72fc269e7f6ac3d011f1 Mon Sep 17 00:00:00 2001 From: "Tim D. Smith" Date: Thu, 22 Sep 2016 12:45:24 -0700 Subject: [PATCH 48/60] Offer guidance on Python 3 --- docs/starting/install/osx.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index e8aa1df..5c73d69 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -61,6 +61,12 @@ Now, we can install Python 2.7: $ brew install python +or Python 3: + +.. code-block:: console + + $ brew install python3 + This will take a minute or two. From ab3332e42c0ba4694e171090d564aa5a0af5d53f Mon Sep 17 00:00:00 2001 From: Kishor Bhat Date: Thu, 29 Sep 2016 11:36:11 +0530 Subject: [PATCH 49/60] Remove redundant statement --- docs/scenarios/admin.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 0bd928d..8e738d9 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -378,8 +378,6 @@ Buildout is primarily used to download and set up dependencies in Python eggs format of the software being developed or deployed. Recipes for build tasks in any environment can be created, and many are already available. -Buidout is written in Python. - Shinken ------- From 5ad43199debdd2d33eab35190c8c3a9d4f60ca42 Mon Sep 17 00:00:00 2001 From: Sidney Pham Date: Fri, 7 Oct 2016 15:53:05 +1100 Subject: [PATCH 50/60] Fixed example docstring --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index bd59437..7e10ab4 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -104,7 +104,7 @@ In Python, *docstrings* describe modules, classes, and functions: .. code-block:: python def square_and_rooter(x): - """Returns the square root of self times self.""" + """Return the square root of self times self.""" ... In general, follow the comment section of :pep:`8#comments` (the "Python Style From 25dc76e5365ba6a9833163dbf3450da227c71d21 Mon Sep 17 00:00:00 2001 From: Kishor Bhat Date: Fri, 7 Oct 2016 15:36:14 +0530 Subject: [PATCH 51/60] Remove numba todo; already taken care of under scenarios/scientific.rst --- docs/scenarios/speed.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index fc038c1..2c775b8 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -222,10 +222,6 @@ Pyrex Shedskin? --------- -Numba ------ -.. todo:: Write about Numba and the autojit compiler for NumPy - Concurrency ::::::::::: From 473f4c77a7aee526f3658188d036e2db58b67b89 Mon Sep 17 00:00:00 2001 From: Austin Date: Sun, 16 Oct 2016 09:00:42 -0400 Subject: [PATCH 52/60] Remove Ubuntu specification The linked page is general to linux, and specifically mentions CentOS, Fedora, RHEL and Ubuntu. It does not contain any information that is specific to Ubuntu only. --- docs/starting/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 04aaaa0..5df0035 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -18,4 +18,4 @@ for development purposes, as well as setuptools, pip, and virtualenv setup. - :ref:`Mac OS X `. - :ref:`Microsoft Windows `. -- :ref:`Ubuntu Linux `. +- :ref:`Linux `. From 111c5d67698604526de994d222665a0bab536561 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 20 Oct 2016 02:24:28 -0400 Subject: [PATCH 53/60] available now! --- docs/_templates/sidebarintro.html | 2 +- docs/_templates/sidebarlogo.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 2c085fc..5a49dc0 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -22,7 +22,7 @@

O'Reilly Book

-

This guide is now available for pre-order in tangible book form!

+

This guide is now available in tangible book form!

diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index 605909b..bea79f7 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -21,7 +21,7 @@

O'Reilly Book

-

This guide is now available for pre-order in tangible book form!

+

This guide is now available in tangible book form!

From d67923cf94d20db423cee2b841415ba4a4b36535 Mon Sep 17 00:00:00 2001 From: Aditya Date: Wed, 26 Oct 2016 19:12:11 +0530 Subject: [PATCH 54/60] Update the link for latest available Python 2.7 release for Windows --- docs/starting/install/win.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index a34566e..674bb68 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -3,7 +3,7 @@ Installing Python on Windows ============================ -First, download the `latest version `_ +First, download the `latest version `_ 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 `_ . From be8ce2704df28a3279ee1d6f5809ee776dcf327d Mon Sep 17 00:00:00 2001 From: Aditya Date: Wed, 26 Oct 2016 20:37:54 +0530 Subject: [PATCH 55/60] Update to recent versions of Django for virtualenv example --- docs/dev/virtualenvs.rst | 4 ++-- docs/starting/install/linux.rst | 4 ++-- docs/starting/install/osx.rst | 4 ++-- docs/starting/install/win.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 848d7ae..e6be87f 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -8,8 +8,8 @@ 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.3 while also -maintaining a project which requires Django 1.0. +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. virtualenv ---------- diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index e68c5d0..aa56ec0 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -55,8 +55,8 @@ in separate places, by creating virtual Python environments for them. It solves "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.3 while also -maintaining a project which requires Django 1.0. +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. To start using this and see more information: :ref:`Virtual Environments ` docs. diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 4222485..a4fa0cf 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -89,8 +89,8 @@ in separate places, by creating virtual Python environments for them. It solves "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.3 while also -maintaining a project which requires Django 1.0. +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. To start using this and see more information: :ref:`Virtual Environments ` docs. diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 674bb68..131ace6 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -74,8 +74,8 @@ in separate places, by creating virtual Python environments for them. It solves "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.3 while also -maintaining a project which requires Django 1.0. +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. To start using this and see more information: :ref:`Virtual Environments ` docs. From fe7467bcc426bada462c77087085ca1389341e5e Mon Sep 17 00:00:00 2001 From: Adam Zapletal Date: Sat, 29 Oct 2016 18:24:14 -0500 Subject: [PATCH 56/60] Update link to Mercurial site --- docs/scenarios/cli.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index c8cdcec..8999792 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -16,7 +16,7 @@ Some popular command-line applications include: * `httpie `_ - A command line HTTP client, a user-friendly cURL replacement * `git `_ - A distributed version control system -* `mercurial `_ - A distributed version control +* `mercurial `_ - A distributed version control system primarily written in Python Clint From 27c1567df56125359f96dad9d31e2664a025ddde Mon Sep 17 00:00:00 2001 From: Shiven Mian Date: Mon, 31 Oct 2016 14:50:30 +0530 Subject: [PATCH 57/60] added machine learning docs --- docs/scenarios/ml.rst | 117 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/scenarios/ml.rst diff --git a/docs/scenarios/ml.rst b/docs/scenarios/ml.rst new file mode 100644 index 0000000..25cab80 --- /dev/null +++ b/docs/scenarios/ml.rst @@ -0,0 +1,117 @@ +================ +Machine Learning +================ + +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. + +Scipy Stack +----------- + +The Scipy stack consists of a bunch of core helper packages used in data science, for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications. + +The Stack consists of the following packages (link to documentation given): + +1. `NumPy `_ +2. `SciPy library `_ +3. `Matplotlib `_ +4. `IPython `_ +5. `pandas `_ +6. `Sympy `_ +7. `nose `_ + +The stack also comes with Python bundled in, but has been excluded from the above list. + +Installation +~~~~~~~~~~~~ + +For installing the full stack, or individual packages, you can refer to the instructions given `here `_. + +**NB:** `Anaconda `_ is highly preferred and recommended for installing and maintaining data science packages seamlessly. + +scikit-learn +------------ + +Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing. + +Because of its speed, robustness and easiness to use, it's one of the most widely-used libraries for many Machine Learning applications. + +Installation +~~~~~~~~~~~~ + +Through PyPI: + +.. code-block:: python + + pip install -U scikit-learn + +Through conda: + +.. code-block:: python + + conda install scikit-learn + +scikit-learn also comes in shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link `_. + +Example +~~~~~~~ + +For this example, we train a simple classifier on the `Iris dataset `_, which comes bundled in with scikit-learn. + +The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica). + +We shuffle the Iris dataset, and divide it into separate training and testing sets: keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set, and predict on the testing set. + +.. code-block:: python + + from sklearn.datasets import load_iris + from sklearn import tree + from sklearn.metrics import accuracy_score + import numpy as np + + #loading the iris dataset + iris = load_iris() + + x = iris.data #array of the data + y = iris.target #array of labels (i.e answers) of each data entry + + #getting label names i.e the three flower species + y_names = iris.target_names + + #taking random indices to split the dataset into train and test + test_ids = np.random.permutation(len(x)) + + #splitting data and labels into train and test + #keeping last 10 entries for testing, rest for training + + x_train = x[test_ids[:-10]] + x_test = x[test_ids[-10:]] + + y_train = y[test_ids[:-10]] + y_test = y[test_ids[-10:]] + + #classifying using decision tree + clf = tree.DecisionTreeClassifier() + + #training (fitting) the classifier with the training set + clf.fit(x_train, y_train) + + #predictions on the test dataset + pred = clf.predict(x_test) + + print pred #predicted labels i.e flower species + print y_test #actual labels + print (accuracy_score(pred, y_test))*100 #prediction accuracy + +Since we're splitting randomly and the classifier trains on every iteration, the accuracy may vary. Running the above code gives: + +.. code-block:: python + + [0 1 1 1 0 2 0 2 2 2] + [0 1 1 1 0 2 0 2 2 2] + 100.0 + +The first line contains the labels (i.e flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time. + +More on scikit-learn can be read in the `documentation `_. \ No newline at end of file From 3a353c64f41bc530c65be199eb4e8c85e9ddc9d1 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Wed, 2 Nov 2016 11:23:21 -0400 Subject: [PATCH 58/60] ml --- docs/contents.rst.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index f84b3f0..f2cad22 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -58,6 +58,7 @@ different scenarios. scenarios/xml scenarios/json scenarios/crypto + scenarios/ml scenarios/clibs From 4a7336f8ffbb9002adf6703609406147e7e6c266 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Wed, 2 Nov 2016 11:35:47 -0400 Subject: [PATCH 59/60] Revert "Update contents.rst.inc" --- docs/contents.rst.inc | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index f2cad22..22cbdc9 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -7,10 +7,16 @@ New to Python? Let's properly setup up your Python environment. :maxdepth: 2 starting/which-python - starting/installation - starting/install/osx - starting/install/win - starting/install/linux + +- Properly Install Python + + .. toctree:: + :maxdepth: 1 + + starting/installation + starting/install/osx + starting/install/win + starting/install/linux From 7c8dfd0d3e8f4cafe874d293c2ed647cf8d91844 Mon Sep 17 00:00:00 2001 From: Chocobo1 Date: Sun, 6 Nov 2016 19:57:59 +0800 Subject: [PATCH 60/60] Correct name for the game "Civilization IV" --- 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 d42f2d6..4e2de50 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -8,7 +8,7 @@ Freezing Your Code 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",