diff --git a/.gitignore b/.gitignore
index 331e463fc..76ac05298 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,14 @@
docs/_build
.idea
+
+# Ignore irrelevant files from the Sublime Text editor
+*.sublime-workspace
+*.sublime-project
+
+# Ignore .hgignore for contributors using Mercurial.
+.hgignore
+
+# Ignore files generated during build
+build/
+
+venv/
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 000000000..d3375de72
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,8 @@
+sudo: false
+language: python
+python:
+ - "3.6"
+install: pip install sphinx
+script:
+ - make doctest
+ - make html
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 000000000..9b170d2fb
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,3 @@
+Be cordial or be on your way.
+
+https://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..fb3abe19b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+How to contribute
+-----------------
+
+This guide is under heavy development. If you would like to contribute, please
+see:
+
+https://docs.python-guide.org/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 web server 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
+-----------
+
+For all contributions, please follow the `Guide Style Guide`:
+
+https://docs.python-guide.org/notes/styleguide/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 000000000..a632f3e73
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,360 @@
+Creative Commons Legal Code
+
+Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+ LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+ REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR
+ DAMAGES RESULTING FROM ITS USE.
+
+License
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
+COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
+COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
+AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
+TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
+BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
+CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
+CONDITIONS.
+
+1. Definitions
+
+ a. "Adaptation" means a work based upon the Work, or upon the Work and
+ other pre-existing works, such as a translation, adaptation,
+ derivative work, arrangement of music or other alterations of a
+ literary or artistic work, or phonogram or performance and includes
+ cinematographic adaptations or any other form in which the Work may be
+ recast, transformed, or adapted including in any form recognizably
+ derived from the original, except that a work that constitutes a
+ Collection will not be considered an Adaptation for the purpose of
+ this License. For the avoidance of doubt, where the Work is a musical
+ work, performance or phonogram, the synchronization of the Work in
+ timed-relation with a moving image ("synching") will be considered an
+ Adaptation for the purpose of this License.
+ b. "Collection" means a collection of literary or artistic works, such as
+ encyclopedias and anthologies, or performances, phonograms or
+ broadcasts, or other works or subject matter other than works listed
+ in Section 1(g) below, which, by reason of the selection and
+ arrangement of their contents, constitute intellectual creations, in
+ which the Work is included in its entirety in unmodified form along
+ with one or more other contributions, each constituting separate and
+ independent works in themselves, which together are assembled into a
+ collective whole. A work that constitutes a Collection will not be
+ considered an Adaptation (as defined above) for the purposes of this
+ License.
+ c. "Distribute" means to make available to the public the original and
+ copies of the Work or Adaptation, as appropriate, through sale or
+ other transfer of ownership.
+ d. "License Elements" means the following high-level license attributes
+ as selected by Licensor and indicated in the title of this License:
+ Attribution, Noncommercial, ShareAlike.
+ e. "Licensor" means the individual, individuals, entity or entities that
+ offer(s) the Work under the terms of this License.
+ f. "Original Author" means, in the case of a literary or artistic work,
+ the individual, individuals, entity or entities who created the Work
+ or if no individual or entity can be identified, the publisher; and in
+ addition (i) in the case of a performance the actors, singers,
+ musicians, dancers, and other persons who act, sing, deliver, declaim,
+ play in, interpret or otherwise perform literary or artistic works or
+ expressions of folklore; (ii) in the case of a phonogram the producer
+ being the person or legal entity who first fixes the sounds of a
+ performance or other sounds; and, (iii) in the case of broadcasts, the
+ organization that transmits the broadcast.
+ g. "Work" means the literary and/or artistic work offered under the terms
+ of this License including without limitation any production in the
+ literary, scientific and artistic domain, whatever may be the mode or
+ form of its expression including digital form, such as a book,
+ pamphlet and other writing; a lecture, address, sermon or other work
+ of the same nature; a dramatic or dramatico-musical work; a
+ choreographic work or entertainment in dumb show; a musical
+ composition with or without words; a cinematographic work to which are
+ assimilated works expressed by a process analogous to cinematography;
+ a work of drawing, painting, architecture, sculpture, engraving or
+ lithography; a photographic work to which are assimilated works
+ expressed by a process analogous to photography; a work of applied
+ art; an illustration, map, plan, sketch or three-dimensional work
+ relative to geography, topography, architecture or science; a
+ performance; a broadcast; a phonogram; a compilation of data to the
+ extent it is protected as a copyrightable work; or a work performed by
+ a variety or circus performer to the extent it is not otherwise
+ considered a literary or artistic work.
+ h. "You" means an individual or entity exercising rights under this
+ License who has not previously violated the terms of this License with
+ respect to the Work, or who has received express permission from the
+ Licensor to exercise rights under this License despite a previous
+ violation.
+ i. "Publicly Perform" means to perform public recitations of the Work and
+ to communicate to the public those public recitations, by any means or
+ process, including by wire or wireless means or public digital
+ performances; to make available to the public Works in such a way that
+ members of the public may access these Works from a place and at a
+ place individually chosen by them; to perform the Work to the public
+ by any means or process and the communication to the public of the
+ performances of the Work, including by public digital performance; to
+ broadcast and rebroadcast the Work by any means including signs,
+ sounds or images.
+ j. "Reproduce" means to make copies of the Work by any means including
+ without limitation by sound or visual recordings and the right of
+ fixation and reproducing fixations of the Work, including storage of a
+ protected performance or phonogram in digital form or other electronic
+ medium.
+
+2. Fair Dealing Rights. Nothing in this License is intended to reduce,
+limit, or restrict any uses free from copyright or rights arising from
+limitations or exceptions that are provided for in connection with the
+copyright protection under copyright law or other applicable laws.
+
+3. License Grant. Subject to the terms and conditions of this License,
+Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+perpetual (for the duration of the applicable copyright) license to
+exercise the rights in the Work as stated below:
+
+ a. to Reproduce the Work, to incorporate the Work into one or more
+ Collections, and to Reproduce the Work as incorporated in the
+ Collections;
+ b. to create and Reproduce Adaptations provided that any such Adaptation,
+ including any translation in any medium, takes reasonable steps to
+ clearly label, demarcate or otherwise identify that changes were made
+ to the original Work. For example, a translation could be marked "The
+ original work was translated from English to Spanish," or a
+ modification could indicate "The original work has been modified.";
+ c. to Distribute and Publicly Perform the Work including as incorporated
+ in Collections; and,
+ d. to Distribute and Publicly Perform Adaptations.
+
+The above rights may be exercised in all media and formats whether now
+known or hereafter devised. The above rights include the right to make
+such modifications as are technically necessary to exercise the rights in
+other media and formats. Subject to Section 8(f), all rights not expressly
+granted by Licensor are hereby reserved, including but not limited to the
+rights described in Section 4(e).
+
+4. Restrictions. The license granted in Section 3 above is expressly made
+subject to and limited by the following restrictions:
+
+ a. You may Distribute or Publicly Perform the Work only under the terms
+ of this License. You must include a copy of, or the Uniform Resource
+ Identifier (URI) for, this License with every copy of the Work You
+ Distribute or Publicly Perform. You may not offer or impose any terms
+ on the Work that restrict the terms of this License or the ability of
+ the recipient of the Work to exercise the rights granted to that
+ recipient under the terms of the License. You may not sublicense the
+ Work. You must keep intact all notices that refer to this License and
+ to the disclaimer of warranties with every copy of the Work You
+ Distribute or Publicly Perform. When You Distribute or Publicly
+ Perform the Work, You may not impose any effective technological
+ measures on the Work that restrict the ability of a recipient of the
+ Work from You to exercise the rights granted to that recipient under
+ the terms of the License. This Section 4(a) applies to the Work as
+ incorporated in a Collection, but this does not require the Collection
+ apart from the Work itself to be made subject to the terms of this
+ License. If You create a Collection, upon notice from any Licensor You
+ must, to the extent practicable, remove from the Collection any credit
+ as required by Section 4(d), as requested. If You create an
+ Adaptation, upon notice from any Licensor You must, to the extent
+ practicable, remove from the Adaptation any credit as required by
+ Section 4(d), as requested.
+ b. You may Distribute or Publicly Perform an Adaptation only under: (i)
+ the terms of this License; (ii) a later version of this License with
+ the same License Elements as this License; (iii) a Creative Commons
+ jurisdiction license (either this or a later license version) that
+ contains the same License Elements as this License (e.g.,
+ Attribution-NonCommercial-ShareAlike 3.0 US) ("Applicable License").
+ You must include a copy of, or the URI, for Applicable License with
+ every copy of each Adaptation You Distribute or Publicly Perform. You
+ may not offer or impose any terms on the Adaptation that restrict the
+ terms of the Applicable License or the ability of the recipient of the
+ Adaptation to exercise the rights granted to that recipient under the
+ terms of the Applicable License. You must keep intact all notices that
+ refer to the Applicable License and to the disclaimer of warranties
+ with every copy of the Work as included in the Adaptation You
+ Distribute or Publicly Perform. When You Distribute or Publicly
+ Perform the Adaptation, You may not impose any effective technological
+ measures on the Adaptation that restrict the ability of a recipient of
+ the Adaptation from You to exercise the rights granted to that
+ recipient under the terms of the Applicable License. This Section 4(b)
+ applies to the Adaptation as incorporated in a Collection, but this
+ does not require the Collection apart from the Adaptation itself to be
+ made subject to the terms of the Applicable License.
+ c. You may not exercise any of the rights granted to You in Section 3
+ above in any manner that is primarily intended for or directed toward
+ commercial advantage or private monetary compensation. The exchange of
+ the Work for other copyrighted works by means of digital file-sharing
+ or otherwise shall not be considered to be intended for or directed
+ toward commercial advantage or private monetary compensation, provided
+ there is no payment of any monetary compensation in con-nection with
+ the exchange of copyrighted works.
+ d. If You Distribute, or Publicly Perform the Work or any Adaptations or
+ Collections, You must, unless a request has been made pursuant to
+ Section 4(a), keep intact all copyright notices for the Work and
+ provide, reasonable to the medium or means You are utilizing: (i) the
+ name of the Original Author (or pseudonym, if applicable) if supplied,
+ and/or if the Original Author and/or Licensor designate another party
+ or parties (e.g., a sponsor institute, publishing entity, journal) for
+ attribution ("Attribution Parties") in Licensor's copyright notice,
+ terms of service or by other reasonable means, the name of such party
+ or parties; (ii) the title of the Work if supplied; (iii) to the
+ extent reasonably practicable, the URI, if any, that Licensor
+ specifies to be associated with the Work, unless such URI does not
+ refer to the copyright notice or licensing information for the Work;
+ and, (iv) consistent with Section 3(b), in the case of an Adaptation,
+ a credit identifying the use of the Work in the Adaptation (e.g.,
+ "French translation of the Work by Original Author," or "Screenplay
+ based on original Work by Original Author"). The credit required by
+ this Section 4(d) may be implemented in any reasonable manner;
+ provided, however, that in the case of a Adaptation or Collection, at
+ a minimum such credit will appear, if a credit for all contributing
+ authors of the Adaptation or Collection appears, then as part of these
+ credits and in a manner at least as prominent as the credits for the
+ other contributing authors. For the avoidance of doubt, You may only
+ use the credit required by this Section for the purpose of attribution
+ in the manner set out above and, by exercising Your rights under this
+ License, You may not implicitly or explicitly assert or imply any
+ connection with, sponsorship or endorsement by the Original Author,
+ Licensor and/or Attribution Parties, as appropriate, of You or Your
+ use of the Work, without the separate, express prior written
+ permission of the Original Author, Licensor and/or Attribution
+ Parties.
+ e. For the avoidance of doubt:
+
+ i. Non-waivable Compulsory License Schemes. In those jurisdictions in
+ which the right to collect royalties through any statutory or
+ compulsory licensing scheme cannot be waived, the Licensor
+ reserves the exclusive right to collect such royalties for any
+ exercise by You of the rights granted under this License;
+ ii. Waivable Compulsory License Schemes. In those jurisdictions in
+ which the right to collect royalties through any statutory or
+ compulsory licensing scheme can be waived, the Licensor reserves
+ the exclusive right to collect such royalties for any exercise by
+ You of the rights granted under this License if Your exercise of
+ such rights is for a purpose or use which is otherwise than
+ noncommercial as permitted under Section 4(c) and otherwise waives
+ the right to collect royalties through any statutory or compulsory
+ licensing scheme; and,
+ iii. Voluntary License Schemes. The Licensor reserves the right to
+ collect royalties, whether individually or, in the event that the
+ Licensor is a member of a collecting society that administers
+ voluntary licensing schemes, via that society, from any exercise
+ by You of the rights granted under this License that is for a
+ purpose or use which is otherwise than noncommercial as permitted
+ under Section 4(c).
+ f. Except as otherwise agreed in writing by the Licensor or as may be
+ otherwise permitted by applicable law, if You Reproduce, Distribute or
+ Publicly Perform the Work either by itself or as part of any
+ Adaptations or Collections, You must not distort, mutilate, modify or
+ take other derogatory action in relation to the Work which would be
+ prejudicial to the Original Author's honor or reputation. Licensor
+ agrees that in those jurisdictions (e.g. Japan), in which any exercise
+ of the right granted in Section 3(b) of this License (the right to
+ make Adaptations) would be deemed to be a distortion, mutilation,
+ modification or other derogatory action prejudicial to the Original
+ Author's honor and reputation, the Licensor will waive or not assert,
+ as appropriate, this Section, to the fullest extent permitted by the
+ applicable national law, to enable You to reasonably exercise Your
+ right under Section 3(b) of this License (right to make Adaptations)
+ but not otherwise.
+
+5. Representations, Warranties and Disclaimer
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING AND TO THE
+FULLEST EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR OFFERS THE WORK AS-IS
+AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE
+WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT
+LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS,
+ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT
+DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED
+WARRANTIES, SO THIS EXCLUSION MAY NOT APPLY TO YOU.
+
+6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
+LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
+ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
+ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+
+ a. This License and the rights granted hereunder will terminate
+ automatically upon any breach by You of the terms of this License.
+ Individuals or entities who have received Adaptations or Collections
+ from You under this License, however, will not have their licenses
+ terminated provided such individuals or entities remain in full
+ compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
+ survive any termination of this License.
+ b. Subject to the above terms and conditions, the license granted here is
+ perpetual (for the duration of the applicable copyright in the Work).
+ Notwithstanding the above, Licensor reserves the right to release the
+ Work under different license terms or to stop distributing the Work at
+ any time; provided, however that any such election will not serve to
+ withdraw this License (or any other license that has been, or is
+ required to be, granted under the terms of this License), and this
+ License will continue in full force and effect unless terminated as
+ stated above.
+
+8. Miscellaneous
+
+ a. Each time You Distribute or Publicly Perform the Work or a Collection,
+ the Licensor offers to the recipient a license to the Work on the same
+ terms and conditions as the license granted to You under this License.
+ b. Each time You Distribute or Publicly Perform an Adaptation, Licensor
+ offers to the recipient a license to the original Work on the same
+ terms and conditions as the license granted to You under this License.
+ c. If any provision of this License is invalid or unenforceable under
+ applicable law, it shall not affect the validity or enforceability of
+ the remainder of the terms of this License, and without further action
+ by the parties to this agreement, such provision shall be reformed to
+ the minimum extent necessary to make such provision valid and
+ enforceable.
+ d. No term or provision of this License shall be deemed waived and no
+ breach consented to unless such waiver or consent shall be in writing
+ and signed by the party to be charged with such waiver or consent.
+ e. This License constitutes the entire agreement between the parties with
+ respect to the Work licensed here. There are no understandings,
+ agreements or representations with respect to the Work not specified
+ here. Licensor shall not be bound by any additional provisions that
+ may appear in any communication from You. This License may not be
+ modified without the mutual written agreement of the Licensor and You.
+ f. The rights granted under, and the subject matter referenced, in this
+ License were drafted utilizing the terminology of the Berne Convention
+ for the Protection of Literary and Artistic Works (as amended on
+ September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
+ Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996
+ and the Universal Copyright Convention (as revised on July 24, 1971).
+ These rights and subject matter take effect in the relevant
+ jurisdiction in which the License terms are sought to be enforced
+ according to the corresponding provisions of the implementation of
+ those treaty provisions in the applicable national law. If the
+ standard suite of rights granted under applicable copyright law
+ includes additional rights not granted under this License, such
+ additional rights are deemed to be included in the License; this
+ License is not intended to restrict the license of any rights under
+ applicable law.
+
+
+Creative Commons Notice
+
+ Creative Commons is not a party to this License, and makes no warranty
+ whatsoever in connection with the Work. Creative Commons will not be
+ liable to You or any party on any legal theory for any damages
+ whatsoever, including without limitation any general, special,
+ incidental or consequential damages arising in connection to this
+ license. Notwithstanding the foregoing two (2) sentences, if Creative
+ Commons has expressly identified itself as the Licensor hereunder, it
+ shall have all rights and obligations of Licensor.
+
+ Except for the limited purpose of indicating to the public that the
+ Work is licensed under the CCPL, Creative Commons does not authorize
+ the use by either party of the trademark "Creative Commons" or any
+ related trademark or logo of Creative Commons without the prior
+ written consent of Creative Commons. Any permitted use will be in
+ compliance with Creative Commons' then-current trademark usage
+ guidelines, as may be published on its website or otherwise made
+ available upon request from time to time. For the avoidance of doubt,
+ this trademark restriction does not form part of this License.
+
+ Creative Commons may be contacted at http://creativecommons.org/.
diff --git a/Makefile b/Makefile
index 4c2b0cf39..e702e7819 100644
--- a/Makefile
+++ b/Makefile
@@ -1,2 +1,7 @@
-build:
- cd docs && make html
\ No newline at end of file
+.PHONY: build
+build: html
+
+# this pattern rule lets you run "make build" (or any other target
+# in docs/Makefile) in this directory as though you were in docs/
+%:
+ cd docs && make $@
diff --git a/Readme.rst b/Readme.rst
index 7d3237804..f35c71225 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -3,24 +3,36 @@ Hitchhiker's Guide to Python
**Python Best Practices Guidebook**
+→ Read the free guide at: `docs.python-guide.org `_
+
+.. image:: https://farm1.staticflickr.com/628/33173824932_58add34581_k_d.jpg
+
-----------
-**Work in progress. If you'd like to help, please do. There's a lot of work to be done.**
+**Work in progress. If you'd like to help, please do. There's a lot of work to
+be done.**
-This guide is currently under heavy development. This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
+This guide is currently under heavy development. This opinionated guide
+exists to provide both novice and expert Python developers a best practice
+handbook to the installation, configuration, and usage of Python on a daily
+basis.
Topics include:
-- Platform/version specific installations
+- Platform and version-specific installations
- Py2app, Py2exe, bbfreeze, pyInstaller
-- Pip / virtualenv
-- Documentation. Writing it.
-- server configurations / tools for various web frameworks
-- fabric
-- exhaustive module recommendations, grouped by topic/purpose
-- Testing. Jenkins + tox guides.
-- How to interface w/ hg from git easily
-- what libraries to use for what
-
-
+- Pip
+- Numpy, scipy, statpy, pyplot, matplotlib
+- Virtualenv
+- Fabric
+- Exhaustive module recommendations, grouped by topic/purpose
+- Which libraries to use for what
+- Server configurations & tools for various web frameworks
+- Documentation: writing it
+- Testing: Jenkins & tox guides
+- How to easily interface ``hg`` from ``git``
+
+If you aren't fond of reading reStructuredText, there is an
+almost up-to-date `HTML version at docs.python-guide.org
+`_.
diff --git a/TODO.rst b/TODO.rst
index e50140bb2..af9093b7f 100644
--- a/TODO.rst
+++ b/TODO.rst
@@ -1,11 +1,3 @@
-* Build out TODO.rst
-* Get some rhyme and reason into the project
-* Setup basic skeleton
- - installation
- - codingstyle
- - module distribution
- - applications distribution
- - virtualenv
- - webdev
-
-
\ No newline at end of file
+* Establish "use this" vs "alternatives are...." recommendations
+
+.. todolist::
\ No newline at end of file
diff --git a/docs/404.rst b/docs/404.rst
new file mode 100644
index 000000000..f4fc9fcc1
--- /dev/null
+++ b/docs/404.rst
@@ -0,0 +1,28 @@
+:orphan:
+
+#################
+404 — Not Found
+#################
+
+**Sorry, but we couldn't find the page you requested.**
+
+It looks like this was the result of either:
+
+- a mistyped address
+- an out-of-date link
+
+`Click here to go back to the homepage. `_
+
+Or, try `searching `_.
+
+.. raw:: html
+
+
diff --git a/docs/Makefile b/docs/Makefile
index d8dd1f433..963704aff 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,12 +7,19 @@ SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man changes linkcheck doctest gettext
help:
@echo "Please use \`make ' where is one of"
@@ -27,14 +34,20 @@ help:
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
- -rm -rf $(BUILDDIR)/*
+ rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -46,6 +59,12 @@ dirhtml:
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+netlify: dirhtml
+ @cp $(BUILDDIR)/dirhtml/404/index.html $(BUILDDIR)/dirhtml/404.html
+ @sed -i -e 's/src="http://github.com///src="\//g' $(BUILDDIR)/dirhtml/404.html
+ @sed -i -e 's/href="http://github.com///href="\//g' $(BUILDDIR)/dirhtml/404.html
+ @cp _extra/* $(BUILDDIR)/dirhtml/
+
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@@ -72,17 +91,17 @@ qthelp:
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/osxpython.qhcp"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pythonguide.qhcp"
@echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/osxpython.qhc"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pythonguide.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
- @echo "# mkdir -p $$HOME/.local/share/devhelp/osxpython"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/osxpython"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/pythonguide"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pythonguide"
@echo "# devhelp"
epub:
@@ -100,7 +119,13 @@ latex:
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
- make -C $(BUILDDIR)/latex all-pdf
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
@@ -113,6 +138,24 @@ man:
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@@ -128,3 +171,16 @@ doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+serve:
+ cd $(BUILDDIR)/dirhtml && python3 -m http.server 8005
diff --git a/docs/_extra/_redirects b/docs/_extra/_redirects
new file mode 100644
index 000000000..2cb986392
--- /dev/null
+++ b/docs/_extra/_redirects
@@ -0,0 +1,18 @@
+# Redirect rules
+# Docs: https://www.netlify.com/docs/redirects/
+
+# Redirect http to https (avoid one extra hop with an explicit rule for /en/latest/)
+http://docs.python-guide.org/en/latest/* https://docs.python-guide.org/:splat 301!
+http://docs.python-guide.org/* https://docs.python-guide.org/:splat 301!
+
+# Redirect RTD prefix to /
+/en/latest/* /:splat 301!
+
+# Redirect domain aliases to primary domain
+http://python-guide.org/* http://docs.python-guide.org/:splat 301!
+https://python-guide.org/* https://docs.python-guide.org/:splat 301!
+
+# Redirect Netlify version to primary domain
+https://python-guide.netlify.com/* https://docs.python-guide.org/:splat 301!
+
+/guide-book https://www.amazon.com/Hitchhikers-Guide-Python-Practices-Development/dp/1491933178/ref=as_li_ss_il?ie=UTF8&linkCode=li2&tag=bookforkind-20&linkId=804806ebdacaf3b56567347f3afbdbca 302
diff --git a/docs/_extra/ads.txt b/docs/_extra/ads.txt
new file mode 100644
index 000000000..52291a930
--- /dev/null
+++ b/docs/_extra/ads.txt
@@ -0,0 +1,340 @@
+33across.com, 0010b00002Mpn7AAAR, DIRECT, bbea06d9c4d2853c
+33across.com, 0013300001kQj2HAAS, RESELLER, bbea06d9c4d2853c
+33across.com, 0013300001qkdlwAAA, RESELLER
+33across.com, 0013300001r0t9mAAA, RESELLER
+33across.com, 0014000001aXjnGAAS, RESELLER, bbea06d9c4d2853c # 33 Across
+33across.com,0013300001r0t9mAAA,reseller,bbea06d9c4d2853c
+ad-generation.jp,12474,RESELLER,7f4ea9029ac04e53
+adform.com, 183, RESELLER
+adform.com, 2708, DIRECT, 9f5210a2f0999e32
+adtech.com, 10947, DIRECT, e1a5b5b6e3255540
+adtech.com, 11095, RESELLER
+adtech.com, 11119, RESELLER
+adtech.com, 11208, RESELLER
+adtech.com, 11341, DIRECT
+adtech.com, 12094, RESELLER
+adtech.com, 12094, RESELLER # 33 Across
+adtech.com, 9904, RESELLER
+adtech.com,12068,RESELLER,e1a5b5b6e3255540
+advangelists.com, 8d3bba7425e7c98c50f52ca1b52d3735, RESELLER, 60d26397ec060f98
+advangelists.com, 8d3bba7425e7c98c50f52ca1b52d3735, RESELLER, 60d26397ec060f98 # 33 Across
+advertising.com, 11602, RESELLER
+Advertising.com, 16736, RESELLER
+advertising.com, 19623, RESELLER # AOL - One
+advertising.com, 24410, RESELLER
+advertising.com, 28409, DIRECT, e1a5b5b6e3255540
+advertising.com, 28509, DIRECT, e1a5b5b6e3255540
+advertising.com, 28605, RESELLER # RhythmOne
+advertising.com, 7372, RESELLER
+advertising.com, 8603, RESELLER # Taboola
+amxrtb.com, 105199384, DIRECT
+aol.com, 11119, DIRECT
+aol.com, 53392, RESELLER # Taboola
+aolcloud.net, 9904, RESELLER
+appnexus.com, 1001, RESELLER, f5ab79cb980f11d1
+appnexus.com, 10239, RESELLER, f5ab79cb980f11d1
+appnexus.com, 10239, RESELLER, f5ab79cb980f11d1 # 33 Across
+appnexus.com, 11786, RESELLER, f5ab79cb980f11d1
+appnexus.com, 11801, RESELLER
+appnexus.com, 11924, RESELLER, f5ab79cb980f11d1
+appnexus.com, 12061, RESELLER
+appnexus.com, 12263, RESELLER
+appnexus.com, 12290, RESELLER, f5ab79cb980f11d1
+appnexus.com, 12366, RESELLER, f5ab79cb980f11d1
+appnexus.com, 1314, RESELLER
+Appnexus.com, 1356, RESELLER, f5ab79cb980f11d1
+appnexus.com, 1360, RESELLER, f5ab79cb980f11d1
+appnexus.com, 1613, reseller
+appnexus.com, 1908, RESELLER
+appnexus.com, 1908, RESELLER, f5ab79cb980f11d1
+appnexus.com, 1908, RESELLER, f5ab79cb980f11d1 # DistrictM
+appnexus.com, 1942, RESELLER, f5ab79cb980f11d1
+appnexus.com, 2530, RESELLER
+appnexus.com, 2758, RESELLER, f5ab79cb980f11d1
+appnexus.com, 3135, RESELLER, f5ab79cb980f11d1
+appnexus.com, 3153, DIRECT
+appnexus.com, 3153, RESELLER
+appnexus.com, 3153, RESELLER, f5ab79cb980f11d1
+appnexus.com, 3326, reseller
+appnexus.com, 4052, RESELLER
+appnexus.com, 4052, RESELLER, f5ab79cb980f11d1 # Conversant
+appnexus.com, 6849, RESELLER, f5ab79cb980f11d1 # RhythmOne
+appnexus.com, 7118, RESELLER
+appnexus.com, 7556, DIRECT, f5ab79cb980f11d1
+appnexus.com, 7597, RESELLER, f5ab79cb980f11d1
+appnexus.com, 7911, RESELLER #yieldmo
+appnexus.com, 7944, RESELLER
+appnexus.com, 8692, DIRECT, f5ab79cb980f11d1
+appnexus.com, 9316, RESELLER, f5ab79cb980f11d1 # AppNexus
+appnexus.com, 9393, DIRECT
+appnexus.com, 9393, RESELLER #Video #Display, f5ab79cb980f11d1
+appnexus.com,1001,reseller,f5ab79cb980f11d1
+appnexus.com,10239,reseller,f5ab79cb980f11d1
+appnexus.com,1356,reseller,f5ab79cb980f11d1
+appnexus.com,1908,RESELLER,f5ab79cb980f11d1
+appnexus.com,2758,reseller,f5ab79cb980f11d1
+appnexus.com,3663,RESELLER,f5ab79cb980f11d1
+appnexus.com,7597,reseller,f5ab79cb980f11d1
+appnexus.com,9316,reseller,f5ab79cb980f11d1
+aps.amazon.com,094e2c86-72d9-47d6-a647-d95ce39ad4c7,DIRECT
+aps.amazon.com,2840f06c-5d89-4853-a03e-3bfa567dd33c,reseller
+aps.amazon.com,48266a61-b3d9-4cb7-b172-553abc6a42a4,DIRECT
+aralego.com, par-488A3E6BD8D997D0ED8B3BD34D8BA4B, RESELLER # ucFunnel
+audienciad.com, 202922, DIRECT
+bidtellect.com, 1407, RESELLER, 1c34aa2d85d45e93
+bidtellect.com,1407,reseller,1c34aa2d85d45e93
+brightcom.com, 20292, DIRECT
+ccoxmt.com, 2000067997702, RESELLER
+consumable.com, 2000908, DIRECT, aefcd3d2f45b5070
+contextweb.com, 558355, RESELLER
+contextweb.com, 558511, RESELLER
+contextweb.com, 560606, RESELLER
+contextweb.com, 560606, RESELLER, 89ff185a4c4e857
+contextweb.com, 560606, RESELLER, 89ff185a4c4e857c
+contextweb.com, 561118, RESELLER, 89ff185a4c4e857c #yieldmo
+contextweb.com, 561998, RESELLER, 89ff185a4c4e857c
+contextweb.com, 562350, RESELLER, 89ff185a4c4e857c
+contextweb.com,558355,reseller
+conversantmedia.com, 20923, RESELLER # Conversant
+conversantmedia.com, 39882, DIRECT, 03113cd04947736d
+conversantmedia.com, 40790, RESELLER, 03113cd04947736d
+conversantmedia.com, 41812, DIRECT
+coxmt.com, 2000067907202, RESELLER
+criteo.com, 109412, DIRECT, 9fac4a4a87c2a44f
+districtm.io, 100808, DIRECT
+districtm.io, 100835, DIRECT
+districtm.io, 100835, DIRECT, 3fd707be9c4527c3
+districtm.io, 101080, RESELLER
+districtm.io, 101769, RESELLER, 3fd707be9c4527c3 # DistrictM
+districtm.io,100962,RESELLER,3fd707be9c4527c3
+EMXDGT.com, 1133, DIRECT, 1e1d41537f7cad7f
+emxdgt.com, 20, DIRECT, 1e1d41537f7cad7f
+emxdgt.com, 326, RESELLER, 1e1d41537f7cad7f
+emxdgt.com, 326, RESELLER, 1e1d41537f7cad7f # 33 Across
+EMXDGT.com,1284,reseller,1e1d41537f7cad7f
+engagebdr.com, 10417, RESELLER # EngageDBR
+freewheel.tv, 146081, reseller
+freewheel.tv, 19129, RESELLER
+freewheel.tv, 19133, RESELLER
+freewheel.tv, 33081, RESELLER
+freewheel.tv, 33601, RESELLER
+freewheel.tv, 799841, RESELLER # Taboola
+freewheel.tv, 799921, RESELLER # Taboola
+google.com, pub-1320774679920841, RESELLER, f08c47fec0942fa0
+google.com, pub-1409765517756851, reseller
+google.com, pub-2290755540215120, RESELLER, f08c47fec0942fa0
+google.com, pub-2802445174821308, RESELLER, f08c47fec0942fa0
+google.com, pub-3848273848634341, RESELLER, f08c47fec0942fa0
+google.com, pub-4075894099602271, reseller
+google.com, pub-4207323757133151, RESELLER, f08c47fec0942fa0
+google.com, pub-4641608711979091, DIRECT, f08c47fec0942fa0
+google.com, pub-5231479214411897, RESELLER, f08c47fec0942fa0
+Google.com, pub-5995202563537249, RESELLER, f08c47fec0942fa0
+google.com, pub-6314168058065736, RESELLER, f08c47fec0942fa0
+google.com, pub-8172268348509349, RESELLER, f08c47fec0942fa0
+google.com, pub-9557089510405422, RESELLER, f08c47fec0942fa0
+google.com, pub-9557089510405422, RESELLER, f08c47fec0942fa0 # 33 Across
+google.com, pub-9685734445476814, RESELLER, f08c47fec0942fa0
+google.com, pub-9685734445476814, RESELLER, f08c47fec0942fa0 # DistrictM
+google.com,pub-3848273848634341,reseller,f08c47fec0942fa0
+google.com,pub-9557089510405422,reseller,f08c47fec0942fa0
+gumgum.com, 11645, RESELLER, ffdef49475d318a9
+gumgum.com, 13174, DIRECT, ffdef49475d318a9
+gumgum.com, 13318, RESELLER, ffdef49475d318a9
+gumgum.com, 13318, RESELLER, ffdef49475d318a9 # 33 Across
+gumgum.com, 13504, RESELLER, ffdef49475d318a9
+gumgum.com,13174,DIRECT,ffdef49475d318a9
+gumgum.com,14141,RESELLER,ffdef49475d318a9
+improvedigital.com, 1362, RESELLER
+improvedigital.com, 1669, RESELLER # ImproveDigital
+improvedigital.com, 185, RESELLER
+indexexchange.com, 175407, RESELLER
+indexexchange.com, 177754, RESELLER, 50b1c356f2c5c8fc
+indexexchange.com, 182257, RESELLER, 50b1c356f2c5c8fc # RhythmOne
+indexexchange.com, 183965, RESELLER, 50b1c356f2c5c8fc # AOL - One
+indexexchange.com, 184914, DIRECT, 50b1c356f2c5c8fc
+indexexchange.com, 186046, RESELLER
+indexexchange.com, 186248, DIRECT, 50b1c356f2c5c8fc
+indexexchange.com, 187196, DIRECT
+indexexchange.com, 187454, DIRECT, 50b1c356f2c5c8fc
+indexexchange.com, 189744, RESELLER
+indexexchange.com, 189872, RESELLER
+indexexchange.com, 191503, RESELLER, 50b1c356f2c5c8fc
+indexexchange.com, 191740, RESELLER, 50b1c356f2c5c8fc # Index
+indexexchange.com, 191923, RESELLER
+indexexchange.com, 191973, RESELLER, 50b1c356f2c5c8fc
+indexexchange.com, 193351, DIRECT
+lijit.com, 217352, DIRECT, fafdf38b16bf6b2b
+lijit.com, 217352-eb, DIRECT, fafdf38b16bf6b2b
+lijit.com, 248396, DIRECT, fafdf38b16bf6b2b
+lijit.com, 248396-eb, DIRECT, fafdf38b16bf6b2b
+lijit.com, 260380, RESELLER, fafdf38b16bf6b2b
+lijit.com, 270524, RESELLER, fafdf38b16bf6b2b
+lijit.com,217352,DIRECT,fafdf38b16bf6b2b
+lkqd.com, 470, RESELLER, 59c49fa9598a0117
+lkqd.net, 470, RESELLER, 59c49fa9598a0117
+Newormedia.com, 2169, DIRECT
+newormedia.com, 4908, DIRECT
+onetag.com, 572a470226457b8, RESELLER # OneTag
+onetag.com, 664e107d9f2b748, RESELLER #yieldmo
+onomagic.com, 202921, DIRECT
+openx.com, 539824308, RESELLER, 6a698e2ec38604c6
+openx.com, 537120563, RESELLER, 6a698e2ec38604c6
+openx.com, 537120563, RESELLER, 6a698e2ec38604c6 # 33 Across
+openx.com, 537120960, RESELLER
+openx.com, 537127577, RESELLER, 6a698e2ec38604c6
+Openx.com, 537143344, RESELLER
+openx.com, 537149485, RESELLER, 6a698e2ec38604c6
+openx.com, 537150004, DIRECT, 6a698e2ec38604c6
+openx.com, 537153209, RESELLER, 6a698e2ec38604c6
+openx.com, 538959099, RESELLER
+openx.com, 538959099, RESELLER, 6a698e2ec38604c6
+openx.com, 539699341, DIRECT, 6a698e2ec38604c6
+openx.com, 539824308, RESELLER, 6a698e2ec38604c6
+openx.com, 540003333, RESELLER, 6a698e2ec38604c6
+openx.com, 540031703, RESELLER, 6a698e2ec38604c6
+openx.com, 540031703, RESELLER, 6a698e2ec38604c6 # Conversant
+openx.com, 540258065, RESELLER, 6a698e2ec38604c6
+openx.com, 540274407, RESELLER, 6a698e2ec38604c6
+openx.com, 540337213, RESELLER, 6a698e2ec38604c6
+openx.com, 540401713, RESELLER, 6a698e2ec38604c6 # OpenX
+openx.com, 541159484, RESELLER, 6a698e2ec38604c6
+openx.com, 542511596, RESELLER, 6a698e2ec38604c6
+openx.com, 83499, RESELLER
+openx.com,537149485,reseller,6a698e2ec38604c6
+openx.com,540191398,RESELLER,6a698e2ec38604c6
+openx.com,540833447, RESELLER, 6a698e2ec38604c6
+outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, DIRECT
+outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, RESELLER
+outbrain.com,00254374f0c468f3b2732db17fd42cb6e5,reseller
+pubmatic.com, 137711, RESELLER
+pubmatic.com, 137711, RESELLER, 5d62403b186f2ace
+pubmatic.com, 156084, RESELLER, 5d62403b186f2ace # AOL - One
+pubmatic.com, 156212, RESELLER
+pubmatic.com, 156212, RESELLER, 5d62403b186f2ace
+pubmatic.com, 156307, RESELLER, 5d62403b186f2ace # Taboola
+pubmatic.com, 156319, DIRECT, 5d62403b186f2ace
+pubmatic.com, 156325, RESELLER, 5d62403b186f2ace # AOL - One
+pubmatic.com, 156344, RESELLER, 5d62403b186f2ace # Pubmatic
+pubmatic.com, 156423, RESELLER, 5d62403b186f2ace
+pubmatic.com, 156423, RESELLER, 5d62403b186f2ace # 33 Across
+pubmatic.com, 156458, RESELLER, 5d62403b186f2ace # AOL - One
+pubmatic.com, 156557, RESELLER
+pubmatic.com, 156595, RESELLER, 5d62403b186f2ace
+pubmatic.com, 157367, DIRECT, 5d62403b186f2ace
+pubmatic.com, 158100, RESELLER, 5d62403b186f2ace
+pubmatic.com, 158355 , RESELLER, 5d62403b186f2ace
+pubmatic.com, 158723, RESELLER, 5d62403b186f2ace
+pubmatic.com, 159117, DIRECT, 5d62403b186f2ace
+pubmatic.com, 159277, RESELLER, 5d62403b186f2ace # RhythmOne
+pubmatic.com, 159330, RESELLER, 5d62403b186f2ace
+pubmatic.com, 159477,RESELLER,5d62403b186f2ace
+pubmatic.com, 160082 , RESELLER, 5d62403b186f2ace
+pubmatic.com, 160131, RESELLER, 5d62403b186f2ace
+pubmatic.com, 32987, RESELLER, 5d62403b186f2ace
+pubmatic.com, 50758, RESELLER, 5d62403b186f2ace
+pubmatic.com, 62483, RESELLER
+pubmatic.com, 79136 , RESELLER, 5d62403b186f2ace
+pubmatic.com,157150,RESELLER,5d62403b186f2ace
+pubmatic.com,157897,reseller,5d62403b186f2ace
+pubmatic.com,160006,RESELLER,5d62403b186f2ace
+pubmatic.com,160096,RESELLER,5d62403b186f2ace
+pubnative.net, 1007284, RESELLER, d641df8625486a7b #yieldmodisplay
+pubnative.net, 1007285, RESELLER, d641df8625486a7b #yieldmonative
+pubnative.net, 1007286, RESELLER, d641df8625486a7b #yieldmovideo
+pubnx.com, 337-1, RESELLER, 8728b7e97e589da4 # Vertoz
+revcontent.com, 76611, RESELLER
+rhythmone.com, 1059622079, RESELLER
+rhythmone.com, 1059622079, RESELLER, a670c89d4a324e47
+rhythmone.com, 1114124056, RESELLER, a670c89d4a324e47
+rhythmone.com, 1166984029, RESELLER, a670c89d4a324e47 # Taboola
+rhythmone.com, 2241341073, RESELLER, a670c89d4a324e47
+rhythmone.com, 2310154583, DIRECT, a670c89d4a324e47
+rhythmone.com, 2439829435, RESELLER, a670c89d4a324e47
+rhythmone.com, 2439829435, RESELLER, a670c89d4a324e47 # 33 Across
+rhythmone.com, 78519861, RESELLER
+rhythmone.com, 905992537, RESELLER, a670c89d4a324e47 # RhythmOne
+rhythmone.com,1654642120,RESELLER,a670c89d4a324e47
+rhythmone.com,2310154583,DIRECT,a670c89d4a324e47
+rhythmone.com,78519861,reseller,a670c89d4a324e47
+rtk.io, 819, DIRECT
+rubiconproject.com, 13344, RESELLER, 0bfd66d529a55807 # Rubicon
+rubiconproject.com, 15268, RESELLER, 0bfd66d529a55807 # RhythmOne
+rubiconproject.com, 16414, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 16414, RESELLER, 0bfd66d529a55807 # 33 Across
+rubiconproject.com, 17070, RESELLER, 0bfd66d529a55807 #yieldmo
+rubiconproject.com, 17632, DIRECT, 0bfd66d529a55807
+rubiconproject.com, 17790, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 17792, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 17822, DIRECT, 0bfd66d529a55807
+rubiconproject.com, 17822, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 17960, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 18222, RESELLER, 0bfd66d529a55807 # AOL - One
+rubiconproject.com, 18694, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 18890, DIRECT, 0bfd66d529a55807
+rubiconproject.com, 20130, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 20416, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 21310, RESELLER , 0bfd66d529a55807
+rubiconproject.com, 21642, RESELLER, 0bfd66d529a55807
+rubiconproject.com, 8861, reseller, 0bfd66d529a55807
+rubiconproject.com,18020,RESELLER,0bfd66d529a55807
+Sekindo.com, 20749, DIRECT, b6b21d256ef43532
+sharethrough.com, 3a0f657b, DIRECT, d53b998a7bd4ecd2
+sharethrough.com, d09156e5, RESELLER, d53b998a7bd4ecd2
+smaato.com, 1100033117, RESELLER
+smaato.com, 1100047713, RESELLER, 07bcf65f187117b4
+smaato.com,1100044650,RESELLER,07bcf65f187117b4
+smartadserver.com, 3436, RESELLER
+sonobi.com, 337f0e70cc, DIRECT
+sonobi.com, 37dd19ad4a, RESELLER, d1a215d9eb5aee9e
+sonobi.com, 6e5cfb5420, DIRECT, d1a215d9eb5aee9e
+sonobi.com, e55fb5d7c2, DIRECT, d1a215d9eb5aee9e
+sovrn.com, 217352, DIRECT, fafdf38b16bf6b2b
+sovrn.com, 248396, DIRECT, fafdf38b16bf6b2b
+sovrn.com, 260380, RESELLER, fafdf38b16bf6b2b
+sovrn.com, 270524, RESELLER, fafdf38b16bf6b2b
+sovrn.com,217352,DIRECT,fafdf38b16bf6b2b
+sparcmedia.com, 310627, Direct
+spotx.tv, 108933, RESELLER, 7842df1d2fe2db34
+spotx.tv, 147949, RESELLER, 7842df1d2fe2db34
+spotx.tv, 212457, RESELLER
+spotx.tv, 228454, RESELLER, 7842df1d2fe2db34
+spotx.tv, 270977, DIRECT, 7842df1d2fe2db34
+spotx.tv, 285547, RESELLER, 7842df1d2fe2db34 # RhythmOne
+spotx.tv, 71451, RESELLER, 7842df1d2fe2db34 # Taboola
+spotx.tv, 84294, RESELLER, 7842df1d2fe2db34
+spotx.tv, 94794, RESELLER, 7842df1d2fe2db34 # SpotX
+spotxchange.com, 108933, RESELLER, 7842df1d2fe2db34
+spotxchange.com, 147949, RESELLER, 7842df1d2fe2db34
+spotxchange.com, 212457, RESELLER
+spotxchange.com, 228454, RESELLER, 7842df1d2fe2db34
+spotxchange.com, 270977, DIRECT, 7842df1d2fe2db34
+spotxchange.com, 285547, RESELLER, 7842df1d2fe2db34 # RhythmOne
+spotxchange.com, 71451, RESELLER, 7842df1d2fe2db34 # Taboola
+spotxchange.com, 84294, RESELLER, 7842df1d2fe2db34
+spotxchange.com, 94794, RESELLER, 7842df1d2fe2db34 # SpotX
+springserve.com, 686, DIRECT, a24eb641fc82e93d
+synacor.com, 82350, RESELLER, e108f11b2cdf7d5b
+synacor.com,82151,reseller,e108f11b2cdf7d5b
+teads.tv, 19014, DIRECT, 15a9c44f6d26cbe1
+telaria.com, mb9eo-oqsbf, RESELLER, 1a4e959a1b50034a
+telaria.com, vtrdn-wjdav, DIRECT, 1a4e959a1b50034a
+telaria.com, vtrdn-ysjam, DIRECT, 1a4e959a1b50034a
+themediagrid.com, P5JONV, RESELLER, 35d5010d7789b49d # Media Grid (IPONWEB)
+tremorhub.com, mb9eo-oqsbf, RESELLER, 1a4e959a1b50034a
+tremorhub.com, vtrdn-wjdav, DIRECT, 1a4e959a1b50034a
+tremorhub.com, vtrdn-ysjam, DIRECT, 1a4e959a1b50034a
+tremorhub.com, z87wm, RESELLER, 1a4e959a1b50034a # Taboola
+triplelift.com, 7205, DIRECT, 6c33edb13117fd86
+ucfunnel.com, par-488A3E6BD8D997D0ED8B3BD34D8BA4B, RESELLER # ucFunnel
+vertamedia.com, 287605, DIRECT, 7de89dc7742b5b11
+vertamedia.com, 287605, RESELLER, 7de89dc7742b5b11
+video.unrulymedia.com, 2310154583, DIRECT
+video.unrulymedia.com, 905992537, RESELLER, a670c89d4a324e47 # RhythmOne
+yahoo.com, 55771, RESELLER, e1a5b5b6e3255540
+yahoo.com, 55104, DIRECT, e1a5b5b6e3255540
+yahoo.com, 55317, RESELLER # Verizon
+yahoo.com, 57289, RESELLER, e1a5b5b6e3255540
+yahoo.com, 57695, DIRECT, e1a5b5b6e3255540
+yahoo.com,55029,RESELLER,e1a5b5b6e3255540
+yieldmo.com, 2417496099628458357, DIRECT
diff --git a/docs/_extra/robots.txt b/docs/_extra/robots.txt
new file mode 100644
index 000000000..eb0536286
--- /dev/null
+++ b/docs/_extra/robots.txt
@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:
diff --git a/docs/_static/guide-book-cover.jpg b/docs/_static/guide-book-cover.jpg
new file mode 100644
index 000000000..abbbc2871
Binary files /dev/null and b/docs/_static/guide-book-cover.jpg differ
diff --git a/docs/_static/pep-0001-1.png b/docs/_static/pep-0001-1.png
new file mode 100644
index 000000000..51eb2b258
Binary files /dev/null and b/docs/_static/pep-0001-1.png differ
diff --git a/docs/_static/photos/32800783863_11a00db52c_k_d.jpg b/docs/_static/photos/32800783863_11a00db52c_k_d.jpg
new file mode 100644
index 000000000..649272a69
Binary files /dev/null and b/docs/_static/photos/32800783863_11a00db52c_k_d.jpg differ
diff --git a/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg b/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg
new file mode 100644
index 000000000..208bbe8f9
Binary files /dev/null and b/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg differ
diff --git a/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg b/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg
new file mode 100644
index 000000000..040660b87
Binary files /dev/null and b/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg differ
diff --git a/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg b/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg
new file mode 100644
index 000000000..c356d03d3
Binary files /dev/null and b/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg differ
diff --git a/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg b/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg
new file mode 100644
index 000000000..75a02fd7b
Binary files /dev/null and b/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg differ
diff --git a/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg b/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg
new file mode 100644
index 000000000..54781c3ec
Binary files /dev/null and b/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg differ
diff --git a/docs/_static/photos/33573767786_eececc5d27_k_d.jpg b/docs/_static/photos/33573767786_eececc5d27_k_d.jpg
new file mode 100644
index 000000000..1b529faad
Binary files /dev/null and b/docs/_static/photos/33573767786_eececc5d27_k_d.jpg differ
diff --git a/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg b/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg
new file mode 100644
index 000000000..a7734c79d
Binary files /dev/null and b/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg differ
diff --git a/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg b/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg
new file mode 100644
index 000000000..efdbea512
Binary files /dev/null and b/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg differ
diff --git a/docs/_static/photos/33907143624_cd621b535c_k_d.jpg b/docs/_static/photos/33907143624_cd621b535c_k_d.jpg
new file mode 100644
index 000000000..d7604c1a7
Binary files /dev/null and b/docs/_static/photos/33907143624_cd621b535c_k_d.jpg differ
diff --git a/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg b/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg
new file mode 100644
index 000000000..85bb549c8
Binary files /dev/null and b/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg differ
diff --git a/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg b/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg
new file mode 100644
index 000000000..93e98f476
Binary files /dev/null and b/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg differ
diff --git a/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg b/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg
new file mode 100644
index 000000000..480d6e153
Binary files /dev/null and b/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg differ
diff --git a/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg b/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg
new file mode 100644
index 000000000..ae0136d82
Binary files /dev/null and b/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg differ
diff --git a/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg b/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg
new file mode 100644
index 000000000..cf218c710
Binary files /dev/null and b/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg differ
diff --git a/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg b/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg
new file mode 100644
index 000000000..91bfebbb0
Binary files /dev/null and b/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg differ
diff --git a/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg b/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg
new file mode 100644
index 000000000..7b3151fd5
Binary files /dev/null and b/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg differ
diff --git a/docs/_static/photos/33925223870_97e44f5629_k_d.jpg b/docs/_static/photos/33925223870_97e44f5629_k_d.jpg
new file mode 100644
index 000000000..b271f261a
Binary files /dev/null and b/docs/_static/photos/33925223870_97e44f5629_k_d.jpg differ
diff --git a/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg b/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg
new file mode 100644
index 000000000..8bdd9082c
Binary files /dev/null and b/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg differ
diff --git a/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg b/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg
new file mode 100644
index 000000000..995212043
Binary files /dev/null and b/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg differ
diff --git a/docs/_static/photos/34018729885_002ced9b54_k_d.jpg b/docs/_static/photos/34018729885_002ced9b54_k_d.jpg
new file mode 100644
index 000000000..5420bb6a1
Binary files /dev/null and b/docs/_static/photos/34018729885_002ced9b54_k_d.jpg differ
diff --git a/docs/_static/photos/34018732105_f0e6758859_k_d.jpg b/docs/_static/photos/34018732105_f0e6758859_k_d.jpg
new file mode 100644
index 000000000..1a4c3dd03
Binary files /dev/null and b/docs/_static/photos/34018732105_f0e6758859_k_d.jpg differ
diff --git a/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg b/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg
new file mode 100644
index 000000000..21fada7a6
Binary files /dev/null and b/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg differ
diff --git a/docs/_static/photos/34268661876_442428e122_k_d.jpg b/docs/_static/photos/34268661876_442428e122_k_d.jpg
new file mode 100644
index 000000000..f6ce0be5c
Binary files /dev/null and b/docs/_static/photos/34268661876_442428e122_k_d.jpg differ
diff --git a/docs/_static/photos/34309496175_b82d104282_k_d.jpg b/docs/_static/photos/34309496175_b82d104282_k_d.jpg
new file mode 100644
index 000000000..a09fd0a3d
Binary files /dev/null and b/docs/_static/photos/34309496175_b82d104282_k_d.jpg differ
diff --git a/docs/_static/photos/34364815780_bea6614025_k_d.jpg b/docs/_static/photos/34364815780_bea6614025_k_d.jpg
new file mode 100644
index 000000000..ab05248ae
Binary files /dev/null and b/docs/_static/photos/34364815780_bea6614025_k_d.jpg differ
diff --git a/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg b/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg
new file mode 100644
index 000000000..e765c7cf2
Binary files /dev/null and b/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg differ
diff --git a/docs/_static/photos/34435688380_b5a740762b_k_d.jpg b/docs/_static/photos/34435688380_b5a740762b_k_d.jpg
new file mode 100644
index 000000000..baa1f17fc
Binary files /dev/null and b/docs/_static/photos/34435688380_b5a740762b_k_d.jpg differ
diff --git a/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg b/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
new file mode 100644
index 000000000..fe4c1aa40
Binary files /dev/null and b/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg differ
diff --git a/docs/_static/photos/34435689480_2e6f358510_k_d.jpg b/docs/_static/photos/34435689480_2e6f358510_k_d.jpg
new file mode 100644
index 000000000..87e278159
Binary files /dev/null and b/docs/_static/photos/34435689480_2e6f358510_k_d.jpg differ
diff --git a/docs/_static/photos/34435690330_11930b5987_k_d.jpg b/docs/_static/photos/34435690330_11930b5987_k_d.jpg
new file mode 100644
index 000000000..74b44e067
Binary files /dev/null and b/docs/_static/photos/34435690330_11930b5987_k_d.jpg differ
diff --git a/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg b/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg
new file mode 100644
index 000000000..4a00c547e
Binary files /dev/null and b/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg differ
diff --git a/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg b/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg
new file mode 100644
index 000000000..8a667d23a
Binary files /dev/null and b/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg differ
diff --git a/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg b/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg
new file mode 100644
index 000000000..88c760e87
Binary files /dev/null and b/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg differ
diff --git a/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg b/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg
new file mode 100644
index 000000000..50554cfa6
Binary files /dev/null and b/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg differ
diff --git a/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg b/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg
new file mode 100644
index 000000000..ab2ae0735
Binary files /dev/null and b/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg differ
diff --git a/docs/_static/photos/34725946825_0f85497e60_k_d.jpg b/docs/_static/photos/34725946825_0f85497e60_k_d.jpg
new file mode 100644
index 000000000..5d58e91d3
Binary files /dev/null and b/docs/_static/photos/34725946825_0f85497e60_k_d.jpg differ
diff --git a/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg b/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg
new file mode 100644
index 000000000..c982f1fe8
Binary files /dev/null and b/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg differ
diff --git a/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg b/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg
new file mode 100644
index 000000000..c25560701
Binary files /dev/null and b/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg differ
diff --git a/docs/_static/photos/35294660055_42c02b2316_k_d.jpg b/docs/_static/photos/35294660055_42c02b2316_k_d.jpg
new file mode 100644
index 000000000..f7cc6b936
Binary files /dev/null and b/docs/_static/photos/35294660055_42c02b2316_k_d.jpg differ
diff --git a/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg b/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg
new file mode 100644
index 000000000..e3a1b74a9
Binary files /dev/null and b/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg differ
diff --git a/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg b/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg
new file mode 100644
index 000000000..ed1364a28
Binary files /dev/null and b/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg differ
diff --git a/docs/_static/photos/36137234682_be6898bf57_k_d.jpg b/docs/_static/photos/36137234682_be6898bf57_k_d.jpg
new file mode 100644
index 000000000..fed85141d
Binary files /dev/null and b/docs/_static/photos/36137234682_be6898bf57_k_d.jpg differ
diff --git a/docs/_static/python-guide-logo.png b/docs/_static/python-guide-logo.png
new file mode 100644
index 000000000..25e4f82c6
Binary files /dev/null and b/docs/_static/python-guide-logo.png differ
diff --git a/docs/_static/social-card.jpg b/docs/_static/social-card.jpg
new file mode 100644
index 000000000..9f74ef1e4
Binary files /dev/null and b/docs/_static/social-card.jpg differ
diff --git a/docs/_static/test b/docs/_static/test
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html
new file mode 100644
index 000000000..cea323be6
--- /dev/null
+++ b/docs/_templates/hacks.html
@@ -0,0 +1 @@
+
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
new file mode 100644
index 000000000..6a6a22b8a
--- /dev/null
+++ b/docs/_templates/layout.html
@@ -0,0 +1,113 @@
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+ {# No super() because we want to avoid loading an empty custom.css file #}
+
+ {# #}
+
+
+
+
+ {% if pagename == 'index' %}
+
+
+ {% elif pagename == '404' %}
+ {# No canonical on our 404 template. #}
+ {% else %}
+
+
+ {% endif %}
+
+
+
+
+
+
+
+
+
+
+ {%- if metatags is defined %}
+ {# FIXME: For some reason the `meta` dict is always empty. Extract the desc from the `metatags` text. #}
+
+ {%- endif %}
+
+
+
+
+
+
+ {# Alabaster theme native GA integration is outdated (ga.js). #}
+ {# Insert our own GA snippet instead. #}
+
+{% endblock %}
+
+{# From: https://github.com/bitprophet/alabaster/blob/5f249677242be96601e034edb3697b7482a6abcf/alabaster/layout.html #}
+{# Nav should appear before content, not after #}
+{%- block content %}
+{%- if theme_fixed_sidebar|lower == 'true' %}
+
- This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
+
- Feedback is greatly appreciated. If you have any questions, comments,
- random praise, or anonymous threats,
- shoot me an email.
+ This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis.
+
+
+
+
+
+
O'Reilly Book
+
+
This guide is now available in tangible book form!
+
+
+
+
All proceeds are being directly donated to the DjangoGirls organization.
+
+
Contributors
+
+ This guide is the result of the collaboration of
+ hundreds of people
+ around the world, and your contributions
+ are welcome!
+
- This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
-
\ No newline at end of file
+ This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis.
+
+
+
+
+
+
+
+
O'Reilly Book
+
+
This guide is now available in tangible book form!
+
+
+
+
All proceeds are being directly donated to the DjangoGirls organization.
diff --git a/docs/_themes/README.rst b/docs/_themes/README.rst
deleted file mode 100644
index 8648482a3..000000000
--- a/docs/_themes/README.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-krTheme Sphinx Style
-====================
-
-This repository contains sphinx styles Kenneth Reitz uses in most of
-his projects. It is a drivative of Mitsuhiko's themes for Flask and Flask related
-projects. To use this style in your Sphinx documentation, follow
-this guide:
-
-1. put this folder as _themes into your docs folder. Alternatively
- you can also use git submodules to check out the contents there.
-
-2. add this to your conf.py: ::
-
- sys.path.append(os.path.abspath('_themes'))
- html_theme_path = ['_themes']
- html_theme = 'flask'
-
-The following themes exist:
-
-**kr**
- the standard flask documentation theme for large projects
-
-**kr_small**
- small one-page theme. Intended to be used by very small addon libraries.
-
diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html
deleted file mode 100644
index 75e20e6f9..000000000
--- a/docs/_themes/kr/layout.html
+++ /dev/null
@@ -1,51 +0,0 @@
-{%- extends "basic/layout.html" %}
-{%- block extrahead %}
- {{ super() }}
- {% if theme_touch_icon %}
-
- {% endif %}
-
-{% endblock %}
-{%- block relbar2 %}{% endblock %}
-{%- block footer %}
-
-
-
-
-
-
-
-
-
-
-
-{%- endblock %}
diff --git a/docs/_themes/kr/relations.html b/docs/_themes/kr/relations.html
deleted file mode 100644
index 3bbcde85b..000000000
--- a/docs/_themes/kr/relations.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
- {% endif %}
-{% endblock %}
-{# do not display relbars #}
-{% block relbar1 %}{% endblock %}
-{% block relbar2 %}
- {% if theme_github_fork %}
-
- {% endif %}
-{% endblock %}
-{% block sidebar1 %}{% endblock %}
-{% block sidebar2 %}{% endblock %}
diff --git a/docs/_themes/kr_small/static/flasky.css_t b/docs/_themes/kr_small/static/flasky.css_t
deleted file mode 100644
index fe2141c56..000000000
--- a/docs/_themes/kr_small/static/flasky.css_t
+++ /dev/null
@@ -1,287 +0,0 @@
-/*
- * flasky.css_t
- * ~~~~~~~~~~~~
- *
- * Sphinx stylesheet -- flasky theme based on nature theme.
- *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
- */
-
-@import url("http://github.com/basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
- font-family: 'Georgia', serif;
- font-size: 17px;
- color: #000;
- background: white;
- margin: 0;
- padding: 0;
-}
-
-div.documentwrapper {
- float: left;
- width: 100%;
-}
-
-div.bodywrapper {
- margin: 40px auto 0 auto;
- width: 700px;
-}
-
-hr {
- border: 1px solid #B1B4B6;
-}
-
-div.body {
- background-color: #ffffff;
- color: #3E4349;
- padding: 0 30px 30px 30px;
-}
-
-img.floatingflask {
- padding: 0 0 10px 10px;
- float: right;
-}
-
-div.footer {
- text-align: right;
- color: #888;
- padding: 10px;
- font-size: 14px;
- width: 650px;
- margin: 0 auto 40px auto;
-}
-
-div.footer a {
- color: #888;
- text-decoration: underline;
-}
-
-div.related {
- line-height: 32px;
- color: #888;
-}
-
-div.related ul {
- padding: 0 0 0 10px;
-}
-
-div.related a {
- color: #444;
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-a {
- color: #004B6B;
- text-decoration: underline;
-}
-
-a:hover {
- color: #6D4100;
- text-decoration: underline;
-}
-
-div.body {
- padding-bottom: 40px; /* saved for footer */
-}
-
-div.body h1,
-div.body h2,
-div.body h3,
-div.body h4,
-div.body h5,
-div.body h6 {
- font-family: 'Garamond', 'Georgia', serif;
- font-weight: normal;
- margin: 30px 0px 10px 0px;
- padding: 0;
-}
-
-{% if theme_index_logo %}
-div.indexwrapper h1 {
- text-indent: -999999px;
- background: url(http://github.com/%7B%7B%20theme_index_logo%20%7D%7D) no-repeat center center;
- height: {{ theme_index_logo_height }};
-}
-{% endif %}
-
-div.body h2 { font-size: 180%; }
-div.body h3 { font-size: 150%; }
-div.body h4 { font-size: 130%; }
-div.body h5 { font-size: 100%; }
-div.body h6 { font-size: 100%; }
-
-a.headerlink {
- color: white;
- padding: 0 4px;
- text-decoration: none;
-}
-
-a.headerlink:hover {
- color: #444;
- background: #eaeaea;
-}
-
-div.body p, div.body dd, div.body li {
- line-height: 1.4em;
-}
-
-div.admonition {
- background: #fafafa;
- margin: 20px -30px;
- padding: 10px 30px;
- border-top: 1px solid #ccc;
- border-bottom: 1px solid #ccc;
-}
-
-div.admonition p.admonition-title {
- font-family: 'Garamond', 'Georgia', serif;
- font-weight: normal;
- font-size: 24px;
- margin: 0 0 10px 0;
- padding: 0;
- line-height: 1;
-}
-
-div.admonition p.last {
- margin-bottom: 0;
-}
-
-div.highlight{
- background-color: white;
-}
-
-dt:target, .highlight {
- background: #FAF3E8;
-}
-
-div.note {
- background-color: #eee;
- border: 1px solid #ccc;
-}
-
-div.seealso {
- background-color: #ffc;
- border: 1px solid #ff6;
-}
-
-div.topic {
- background-color: #eee;
-}
-
-div.warning {
- background-color: #ffe4e4;
- border: 1px solid #f66;
-}
-
-p.admonition-title {
- display: inline;
-}
-
-p.admonition-title:after {
- content: ":";
-}
-
-pre, tt {
- font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
- font-size: 0.85em;
-}
-
-img.screenshot {
-}
-
-tt.descname, tt.descclassname {
- font-size: 0.95em;
-}
-
-tt.descname {
- padding-right: 0.08em;
-}
-
-img.screenshot {
- -moz-box-shadow: 2px 2px 4px #eee;
- -webkit-box-shadow: 2px 2px 4px #eee;
- box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils {
- border: 1px solid #888;
- -moz-box-shadow: 2px 2px 4px #eee;
- -webkit-box-shadow: 2px 2px 4px #eee;
- box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils td, table.docutils th {
- border: 1px solid #888;
- padding: 0.25em 0.7em;
-}
-
-table.field-list, table.footnote {
- border: none;
- -moz-box-shadow: none;
- -webkit-box-shadow: none;
- box-shadow: none;
-}
-
-table.footnote {
- margin: 15px 0;
- width: 100%;
- border: 1px solid #eee;
-}
-
-table.field-list th {
- padding: 0 0.8em 0 0;
-}
-
-table.field-list td {
- padding: 0;
-}
-
-table.footnote td {
- padding: 0.5em;
-}
-
-dl {
- margin: 0;
- padding: 0;
-}
-
-dl dd {
- margin-left: 30px;
-}
-
-pre {
- padding: 0;
- margin: 15px -30px;
- padding: 8px;
- line-height: 1.3em;
- padding: 7px 30px;
- background: #eee;
- border-radius: 2px;
- -moz-border-radius: 2px;
- -webkit-border-radius: 2px;
-}
-
-dl pre {
- margin-left: -60px;
- padding-left: 60px;
-}
-
-tt {
- background-color: #ecf0f3;
- color: #222;
- /* padding: 1px 2px; */
-}
-
-tt.xref, a tt {
- background-color: #FBFBFB;
-}
-
-a:hover tt {
- background: #EEE;
-}
diff --git a/docs/_themes/kr_small/theme.conf b/docs/_themes/kr_small/theme.conf
deleted file mode 100644
index 542b46251..000000000
--- a/docs/_themes/kr_small/theme.conf
+++ /dev/null
@@ -1,10 +0,0 @@
-[theme]
-inherit = basic
-stylesheet = flasky.css
-nosidebar = true
-pygments_style = flask_theme_support.FlaskyStyle
-
-[options]
-index_logo = ''
-index_logo_height = 120px
-github_fork = ''
diff --git a/docs/conf.py b/docs/conf.py
index bbc7e5eec..d732ac29f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,7 +11,9 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
-import sys, os
+import datetime
+import os
+import sys
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -25,7 +27,12 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.ifconfig']
+extensions = [
+ 'sphinx.ext.ifconfig',
+ 'sphinx.ext.todo',
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.doctest',
+]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -40,8 +47,11 @@
master_doc = 'index'
# General information about the project.
+current_year = datetime.datetime.now().year
project = u'pythonguide'
-copyright = u'2011. A Kenneth Reitz Project'
+copyright = (u'2011-{} Kenneth Reitz'
+ ' & Real Python.'
+ ' CC BY-NC-SA 3.0').format(current_year)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -64,7 +74,10 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = [
+ '_build',
+ '_themes/*.rst', # Excluded due to README.rst in _themes/
+]
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
@@ -91,19 +104,26 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'kr'
+html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ 'show_powered_by': False,
+ 'github_user': 'realpython',
+ 'github_repo': 'python-guide',
+ 'github_banner': True,
+ 'show_related': False,
+ 'note_bg': '#FFF59C',
+}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['_themes']
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
-#html_title = None
+html_title = 'The Hitchhiker\'s Guide to Python'
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
@@ -132,9 +152,9 @@
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
- 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
+ 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html', 'hacks.html'],
'**': ['sidebarlogo.html', 'localtoc.html', 'relations.html',
- 'sourcelink.html', 'searchbox.html']
+ 'sourcelink.html', 'searchbox.html', 'hacks.html']
}
# Additional templates that should be rendered to pages, maps page names to
@@ -151,7 +171,7 @@
#html_split_index = False
# If true, links to the reST sources are added to the pages.
-html_show_sourcelink = True
+html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
@@ -182,7 +202,7 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'pythonguide.tex', u'Pythong Guide Documentation',
+ ('index', 'pythonguide.tex', u'Python Guide Documentation',
u'Kenneth Reitz', 'manual'),
]
@@ -226,7 +246,7 @@
epub_title = u'pythonguide'
epub_author = u'Kenneth Reitz'
epub_publisher = u'Kenneth Reitz'
-epub_copyright = u'2010, Kenneth Reitz'
+epub_copyright = u'2011–{}, Kenneth Reitz & Real Python'.format(current_year)
# The language of the text. It defaults to the language option
# or en if the language is not set.
@@ -246,15 +266,23 @@
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
-# HTML files shat should be inserted after the pages created by sphinx.
+# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
-#epub_exclude_files = []
+epub_exclude_files = [
+ ('search.html', 'Search'),
+]
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
+
+todo_include_todos = True
+
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3', None),
+}
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 515c0a402..29b076197 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -1,87 +1,140 @@
-Introduction
-------------
-
-This part of the guide, which is mostly prose, begins with some
-background information about Python, then focuses on next steps.
-
-.. toctree::
- :maxdepth: 2
-
- intro/duction
- intro/community
- intro/learning
- intro/documentation
- intro/news
-
-
-Getting Started
----------------
-
-This part of the guide focuses on setting up your Python environment.
-
-.. toctree::
- :maxdepth: 2
-
- starting/which-python
- starting/installation
- starting/dev-env
- starting/next
-
-
-Writing Great Code
-------------------
-
-This part of the guide focuses on best practices for writing Python code.
-
-.. toctree::
- :maxdepth: 2
-
- writing/structure
- writing/style
- writing/documentation
- writing/tests
- writing/license
-
-
-
-Shipping Great Code
--------------------
-
-This part of the guide focuses on deploying your Python code.
-
-.. toctree::
- :maxdepth: 2
-
- shipping/packaging
- shipping/freezing
-
-
-Scenario Guide
---------------
-
-This part of the guide focuses on tool and module advice based on
-different scenarios.
-
-.. toctree::
- :maxdepth: 2
-
- scenarios/cli
- scenarios/gui
- scenarios/web
- scenarios/db
- scenarios/admin
- scenarios/ci
- scenarios/speed
-
-
-
-Additional Notes
-----------------
-
-Contibution notes and legal information are here (for those interested).
-
-.. toctree::
- :maxdepth: 2
-
- notes/contribute
- notes/license
+Getting Started with Python
+---------------------------
+
+New to Python? Let's properly setup up your Python environment:
+
+.. toctree::
+ :maxdepth: 2
+
+ starting/which-python
+
+- Properly Install Python on your system:
+
+ .. toctree::
+ :maxdepth: 1
+
+ starting/installation
+ starting/install3/osx
+ starting/install3/win
+ starting/install3/linux
+ starting/install/osx
+ starting/install/win
+ starting/install/linux
+
+
+- Using Virtualenvs with Pipenv:
+
+ .. toctree::
+ :maxdepth: 2
+
+ dev/virtualenvs
+
+
+Python Development Environments
+-------------------------------
+
+This part of the guide focuses on the Python development environment,
+and the best-practice tools that are available for writing Python code.
+
+.. toctree::
+ :maxdepth: 2
+
+ dev/env
+ dev/virtualenvs
+ dev/pip-virtualenv
+
+
+
+
+Writing Great Python Code
+-------------------------
+
+This part of the guide focuses on the best-practices for writing Python code.
+
+.. toctree::
+ :maxdepth: 2
+
+ writing/structure
+ writing/style
+ writing/reading
+ writing/documentation
+ writing/tests
+ writing/logging
+ writing/gotchas
+ writing/license
+
+
+
+Scenario Guide for Python Applications
+--------------------------------------
+
+This part of the guide focuses on tool and module advice based on
+different scenarios.
+
+.. toctree::
+ :maxdepth: 2
+
+ scenarios/client
+ scenarios/web
+ scenarios/scrape
+ scenarios/cli
+ scenarios/gui
+ scenarios/db
+ scenarios/network
+ scenarios/admin
+ scenarios/ci
+ scenarios/speed
+ scenarios/scientific
+ scenarios/imaging
+ scenarios/serialization
+ scenarios/xml
+ scenarios/json
+ scenarios/crypto
+ scenarios/ml
+ scenarios/clibs
+
+
+Shipping Great Python Code
+--------------------------
+
+This part of the guide focuses on sharing and deploying your Python code.
+
+.. toctree::
+ :maxdepth: 2
+
+ shipping/publishing
+ shipping/packaging
+ shipping/freezing
+
+
+Additional Notes
+----------------
+
+This part of the guide, which is mostly prose, begins with some
+background information about Python, and then focuses on next steps.
+
+.. toctree::
+ :maxdepth: 2
+
+ intro/duction
+ intro/community
+ intro/learning
+ intro/documentation
+ intro/news
+
+.. note::
+ Notes defined within all diatonic and chromatic musical scales have been
+ intentionally excluded from this list of additional notes. Additionally,
+ this note.
+
+
+--------------------------------------
+
+Contribution notes and legal information (for those interested).
+
+.. toctree::
+ :maxdepth: 2
+
+ notes/contribute
+ notes/license
+ notes/styleguide
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
new file mode 100644
index 000000000..7da63c0e6
--- /dev/null
+++ b/docs/dev/env.rst
@@ -0,0 +1,365 @@
+Your Development Environment
+============================
+
+.. image:: /_static/photos/33175624924_7febc46cc4_k_d.jpg
+
+
+Text Editors
+::::::::::::
+
+Just about anything that can edit plain text will work for writing Python code;
+however, using a more powerful editor may make your life a bit easier.
+
+
+Vim
+---
+
+Vim is a text editor which uses keyboard shortcuts for editing instead of menus
+or icons. There are a couple of plugins and settings for the Vim editor to
+aid Python development. If you only develop in Python, a good start is to set
+the default settings for indentation and line-wrapping to values compliant with
+:pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the
+following lines::
+
+ set textwidth=79 " lines longer than 79 columns will be broken
+ set shiftwidth=4 " operation >> indents 4 columns; << unindents 4 columns
+ set tabstop=4 " a hard TAB displays as 4 columns
+ set expandtab " insert spaces when hitting TABs
+ set softtabstop=4 " insert/delete 4 spaces when hitting a TAB/BACKSPACE
+ set shiftround " round indent to multiple of 'shiftwidth'
+ set autoindent " align the new line indent with the previous line
+
+With these settings, newlines are inserted after 79 characters and indentation
+is set to 4 spaces per tab. If you also use Vim for other languages, there is a
+handy plugin called indent_, which handles indentation settings for Python
+source files.
+
+There is also a handy syntax plugin called syntax_ featuring some improvements
+over the syntax file included in Vim 6.1.
+
+These plugins supply you with a basic environment for developing in Python. To
+get the most out of Vim, you should continually check your code for syntax
+errors and PEP8 compliance. Luckily pycodestyle_ and Pyflakes_ will do this
+for you. If your Vim is compiled with ``+python`` you can also utilize some
+very handy plugins to do these checks from within the editor.
+
+For PEP8 checking and pyflakes, you can install vim-flake8_. Now you can map the
+function ``Flake8`` to any hotkey or action you want in Vim. The plugin will
+display errors at the bottom of the screen, and provide an easy way to jump to
+the corresponding line. It's very handy to call this function whenever you save
+a file. In order to do this, add the following line to your
+:file:`.vimrc`::
+
+ autocmd BufWritePost *.py call Flake8()
+
+If you are already using syntastic_, you can set it to run Pyflakes on write
+and show errors and warnings in the quickfix window. An example configuration
+to do that which also shows status and warning messages in the statusbar would
+be::
+
+ set statusline+=%#warningmsg#
+ set statusline+=%{SyntasticStatuslineFlag()}
+ set statusline+=%*
+ let g:syntastic_auto_loc_list=1
+ let g:syntastic_loc_list_height=5
+
+
+Python-mode
+^^^^^^^^^^^
+
+Python-mode_ is a complex solution for working with Python code in Vim.
+It has:
+
+- Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pycodestyle``, ``mccabe``) in any combination
+- Code refactoring and autocompletion with Rope
+- Fast Python folding
+- Virtualenv support
+- Search through Python documentation and run Python code
+- Auto pycodestyle_ error fixes
+
+And more.
+
+SuperTab
+^^^^^^^^
+
+SuperTab_ is a small Vim plugin that makes code completion more convenient by
+using ```` key or any other customized keys.
+
+.. _indent: http://www.vim.org/scripts/script.php?script_id=974
+.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
+.. _Pyflakes: http://pypi.org/project/pyflakes/
+.. _pycodestyle: https://pypi.org/project/pycodestyle/
+.. _syntastic: https://github.com/vim-syntastic/syntastic
+.. _Python-mode: https://github.com/python-mode/python-mode
+.. _SuperTab: http://www.vim.org/scripts/script.php?script_id=1643
+.. _vim-flake8: https://github.com/nvie/vim-flake8
+
+Emacs
+-----
+
+Emacs is another powerful text editor. It is fully programmable (Lisp), but
+it can be some work to wire up correctly. A good start if you're already an
+Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
+
+1. Emacs itself comes with a Python mode.
+
+.. _Python Programming in Emacs: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs
+
+TextMate
+--------
+
+ `TextMate `_ brings Apple's approach to operating
+ systems into the world of text editors. By bridging Unix underpinnings and
+ GUI, TextMate cherry-picks the best of both worlds to the benefit of expert
+ scripters and novice users alike.
+
+Sublime Text
+------------
+
+ `Sublime Text `_ is a sophisticated text
+ editor for code, markup, and prose. You'll love the slick user interface,
+ extraordinary features, and amazing performance.
+
+Sublime Text has excellent support for editing Python code and uses Python for
+its plugin API. It also has a diverse variety of plugins,
+`some of which `_ allow for
+in-editor PEP8 checking and code "linting".
+
+Atom
+----
+
+ `Atom `_ is a hackable text editor for the 21st century,
+ built on atom-shell, and based on everything we love about our favorite
+ editors.
+
+Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin
+development. It comes with native package control and a plethora of packages.
+Recommended for Python development is
+`Linter `_ combined with
+`linter-flake8 `_.
+
+Python (on Visual Studio Code)
+------------------------------
+
+`Python for Visual Studio `_ is an extension for the `Visual Studio Code `_.
+This is a free, lightweight, open source code editor, 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.
+
+IDEs
+::::
+
+PyCharm / IntelliJ IDEA
+-----------------------
+
+`PyCharm `_ is developed by JetBrains, also
+known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
+features can be brought to IntelliJ with the free
+`Python Plug-In `_. There are two
+versions of PyCharm: Professional Edition (Free 30-day trial) and Community
+Edition (Apache 2.0 License) with fewer features.
+
+
+Enthought Canopy
+----------------
+`Enthought Canopy `_ is a Python
+IDE which is focused towards Scientists and Engineers as it provides pre
+installed libraries for data analysis.
+
+Eclipse
+-------
+
+The most popular Eclipse plugin for Python development is Aptana's
+`PyDev `_.
+
+
+Komodo IDE
+----------
+
+`Komodo IDE `_ is developed by
+ActiveState and is a commercial IDE for Windows, Mac, and Linux.
+`KomodoEdit `_ is the open source
+alternative.
+
+
+Spyder
+------
+
+`Spyder `_ is an IDE specifically geared
+toward working with scientific Python libraries (namely
+`SciPy `_). It includes integration with pyflakes_,
+`pylint `_ and
+`rope `_.
+
+Spyder is open source (free), offers code completion, syntax highlighting,
+a class and function browser, and object inspection.
+
+
+WingIDE
+-------
+
+`WingIDE `_ is a Python specific IDE. It runs on Linux,
+Windows, and Mac (as an X11 application, which frustrates some Mac users).
+
+WingIDE offers code completion, syntax highlighting, source browser, graphical
+debugger and support for version control systems.
+
+
+NINJA-IDE
+---------
+
+`NINJA-IDE `_ (from the recursive acronym: "Ninja-IDE
+Is Not Just Another IDE") is a cross-platform IDE, specially designed to build
+Python applications, and runs on Linux/X11, Mac OS X, and Windows desktop
+operating systems. Installers for these platforms can be downloaded from the
+website.
+
+NINJA-IDE is open source software (GPLv3 licence) and is developed
+in Python and Qt. The source files can be downloaded from
+`GitHub `_.
+
+
+Eric (The Eric Python IDE)
+--------------------------
+
+`Eric `_ is a full featured Python IDE
+offering source code autocompletion, syntax highlighting, support for version
+control systems, Python 3 support, integrated web browser, python shell,
+integrated debugger, and a flexible plug-in system. Written in Python, it is
+based on the Qt GUI toolkit, integrating the Scintilla editor control. Eric
+is an open source software project (GPLv3 licence) with more than ten years of
+active development.
+
+Mu
+--
+
+`Mu `_ is a minimalist Python IDE which can run Python 3 code
+locally and can also deploy code to the BBC micro:bit and to Adafruit boards running
+CircuitPython.
+
+Intended for beginners, mu includes a Python 3 interpreter, and is easy to install
+on Windows, OS/X and Linux. It runs well on the Raspberry Pi.
+
+There's an active support community on gitter.
+
+
+Interpreter Tools
+:::::::::::::::::
+
+
+Virtual Environments
+--------------------
+
+Virtual Environments provide a powerful way to isolate project package dependencies. This means that you can use packages particular to a Python project without installing them system wide and thus avoiding potential version conflicts.
+
+To start using and see more information:
+`Virtual Environments `_ docs.
+
+
+pyenv
+-----
+
+`pyenv `_ is a tool to allow multiple versions
+of the Python interpreter to be installed at the same time. This solves the
+problem of having different projects requiring different versions of Python.
+For example, it becomes very easy to install Python 2.7 for compatibility in
+one project, while still using Python 3.4 as the default interpreter.
+pyenv isn't just limited to the CPython versions – it will also install PyPy,
+Anaconda, miniconda, stackless, Jython, and IronPython interpreters.
+
+pyenv works by filling a ``shims`` directory with fake versions of the Python
+interpreter (plus other tools like ``pip`` and ``2to3``). When the system
+looks for a program named ``python``, it looks inside the ``shims`` directory
+first, and uses the fake version, which in turn passes the command on to
+pyenv. pyenv then works out which version of Python should be run based on
+environment variables, ``.python-version`` files, and the global default.
+
+pyenv isn't a tool for managing virtual environments, but there is the plugin
+`pyenv-virtualenv `_ which automates
+the creation of different environments, and also makes it possible to use the
+existing pyenv tools to switch to different environments based on environment
+variables or ``.python-version`` files.
+
+Other Tools
+:::::::::::
+
+IDLE
+----
+
+:ref:`IDLE ` is an integrated development environment that is
+part of the Python standard distribution. It is completely written in Python and uses
+the Tkinter GUI toolkit. Though IDLE is not suited for full-blown development
+using Python, it is quite helpful to try out small Python snippets and
+experiment with different features in Python.
+
+It provides the following features:
+
+* Python Shell Window (interpreter)
+* Multi window text editor that colorizes Python code
+* Minimal debugging facility
+
+
+IPython
+-------
+
+`IPython `_ provides a rich toolkit to help you make the
+most out of using Python interactively. Its main components are:
+
+* Powerful Python shells (terminal- and Qt-based)
+* A web-based notebook with the same core features but support for rich media,
+ text, code, mathematical expressions and inline plots
+* Support for interactive data visualization and use of GUI toolkits
+* Flexible, embeddable interpreters to load into your own projects
+* Tools for high level and interactive parallel computing
+
+.. code-block:: console
+
+ $ pip install ipython
+
+To download and install IPython with all its optional dependencies for the notebook, qtconsole, tests, and other functionalities:
+
+.. code-block:: console
+
+ $ pip install ipython[all]
+
+BPython
+-------
+
+`bpython `_ is an alternative interface to the
+Python interpreter for Unix-like operating systems. It has the following
+features:
+
+* In-line syntax highlighting
+* Readline-like autocomplete with suggestions displayed as you type
+* Expected parameter list for any Python function
+* "Rewind" function to pop the last line of code from memory and re-evaluate
+* Send entered code off to a pastebin
+* Save entered code to a file
+* Auto-indentation
+* Python 3 support
+
+.. code-block:: console
+
+ $ pip install bpython
+
+ptpython
+--------
+
+`ptpython `_ is a REPL build
+on top of the `prompt_toolkit `_
+library. It is considered to be an alternative to BPython_. Features include:
+
+* Syntax highlighting
+* Autocompletion
+* Multiline editing
+* Emacs and Vim Modes
+* Embedding REPL inside of your code
+* Syntax validation
+* Tab pages
+* Support for integrating with IPython_'s shell, by installing IPython
+ (``pip install ipython``) and running ``ptipython``.
+
+.. code-block:: console
+
+ $ pip install ptpython
diff --git a/docs/dev/pip-virtualenv.rst b/docs/dev/pip-virtualenv.rst
new file mode 100644
index 000000000..667f30c7a
--- /dev/null
+++ b/docs/dev/pip-virtualenv.rst
@@ -0,0 +1,137 @@
+.. _pip-virtualenv:
+
+Further Configuration of pip and Virtualenv
+===========================================
+
+.. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg
+
+Requiring an active virtual environment for ``pip``
+---------------------------------------------------
+
+By now it should be clear that using virtual environments is a great way to
+keep your development environment clean and keeping different projects'
+requirements separate.
+
+When you start working on many different projects, it can be hard to remember to
+activate the related virtual environment when you come back to a specific
+project. As a result of this, it is very easy to install packages globally
+while thinking that you are actually installing the package for the virtual
+environment of the project. Over time this can result in a messy global package
+list.
+
+In order to make sure that you install packages to your active virtual
+environment when you use ``pip install``, consider adding the following
+line to your :file:`~/.bashrc` file:
+
+.. code-block:: console
+
+ export PIP_REQUIRE_VIRTUALENV=true
+
+After saving this change and sourcing the :file:`~/.bashrc` file with
+``source ~/.bashrc``, pip will no longer let you install packages if you are not
+in a virtual environment. If you try to use ``pip install`` outside of a
+virtual environment pip will gently remind you that an activated virtual
+environment is needed to install packages.
+
+.. code-block:: console
+
+ $ pip install requests
+ Could not find an activated virtualenv (required).
+
+You can also do this configuration by editing your :file:`pip.conf` or
+:file:`pip.ini` file. :file:`pip.conf` is used by Unix and Mac OS X operating
+systems and it can be found at:
+
+.. code-block:: console
+
+ $HOME/.pip/pip.conf
+
+Similarly, the :file:`pip.ini` file is used by Windows operating systems and it
+can be found at:
+
+.. code-block:: console
+
+ %USERPROFILE%\pip\pip.ini
+
+If you don't have a :file:`pip.conf` or :file:`pip.ini` file at these locations,
+you can create a new file with the correct name for your operating system.
+
+If you already have a configuration file, just add the following line under the
+``[global]`` settings to require an active virtual environment:
+
+.. code-block:: console
+
+ require-virtualenv = true
+
+If you did not have a configuration file, you will need to create a new one and
+add the following lines to this new file:
+
+.. code-block:: console
+
+ [global]
+ require-virtualenv = true
+
+
+You will of course need to install some packages globally (usually ones that
+you use across different projects consistently) and this can be accomplished by
+adding the following to your :file:`~/.bashrc` file:
+
+.. code-block:: console
+
+ gpip() {
+ PIP_REQUIRE_VIRTUALENV=false pip "$@"
+ }
+
+After saving the changes and sourcing your :file:`~/.bashrc` file you can now
+install packages globally by running ``gpip install``. You can change the name
+of the function to anything you like, just keep in mind that you will have to
+use that name when trying to install packages globally with pip.
+
+Caching packages for future use
+-------------------------------
+
+Every developer has preferred libraries and when you are working on a lot of
+different projects, you are bound to have some overlap between the libraries
+that you use. For example, you may be using the ``requests`` library in a lot
+of different projects.
+
+It is surely unnecessary to re-download the same packages/libraries each time
+you start working on a new project (and in a new virtual environment as a
+result). Fortunately, starting with version 6.0, pip provides an `on-by-default
+caching mechanism
+`_ that doesn't
+need any configuration.
+
+When using older versions, you can configure pip in such a way that it tries to
+reuse already installed packages, too.
+
+On Unix systems, you can add the following line to your :file:`.bashrc` or
+:file:`.bash_profile` file.
+
+.. code-block:: console
+
+ export PIP_DOWNLOAD_CACHE=$HOME/.pip/cache
+
+You can set the path to anywhere you like (as long as you have write
+access). After adding this line, ``source`` your :file:`.bashrc`
+(or :file:`.bash_profile`) file and you will be all set.
+
+Another way of doing the same configuration is via the :file:`pip.conf` or
+:file:`pip.ini` files, depending on your system. If you are on Windows, you can
+add the following line to your :file:`pip.ini` file under ``[global]`` settings:
+
+.. code-block:: console
+
+ download-cache = %USERPROFILE%\pip\cache
+
+Similarly, on Unix systems you should simply add the following line to your
+:file:`pip.conf` file under ``[global]`` settings:
+
+.. code-block:: console
+
+ download-cache = $HOME/.pip/cache
+
+Even though you can use any path you like to store your cache, it is recommended
+that you create a new folder *in* the folder where your :file:`pip.conf` or
+:file:`pip.ini` file lives. If you don't trust yourself with all of this path
+voodoo, just use the values provided here and you will be fine.
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
new file mode 100644
index 000000000..fe6bd3f9e
--- /dev/null
+++ b/docs/dev/virtualenvs.rst
@@ -0,0 +1,441 @@
+.. _virtualenvironments-ref:
+
+Pipenv & Virtual Environments
+=============================
+
+.. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg
+
+This tutorial walks you through installing and using Python packages.
+
+It will show you how to install and use the necessary tools and make strong
+recommendations on best practices. Keep in mind that Python is used for a great
+many different purposes, and precisely how you want to manage your dependencies
+may change based on how you decide to publish your software. The guidance
+presented here is most directly applicable to the development and deployment of
+network services (including web applications), but is also very well suited to
+managing development and testing environments for any kind of project.
+
+.. Note:: This guide is written for Python 3, however, these instructions
+ should work fine on Python 2.7—if you are still using it, for some reason.
+
+
+Make sure you've got Python & pip
+---------------------------------
+
+Before you go any further, make sure you have Python and that it's available
+from your command line. You can check this by simply running:
+
+.. code-block:: console
+
+ $ python --version
+
+You should get some output like ``3.6.2``. If you do not have Python, please
+install the latest 3.x version from `python.org`_ or refer to the
+`Installing Python`_ section of this guide.
+
+.. Note:: If you're newcomer and you get an error like this:
+
+ .. code-block:: python
+
+ >>> python
+ Traceback (most recent call last):
+ File "", line 1, in
+ NameError: name 'python' is not defined
+
+ It's because this command is intended to be run in a *shell* (also called
+ a *terminal* or *console*). See the Python for Beginners
+ `getting started tutorial`_ for an introduction to using your operating
+ system's shell and interacting with Python.
+
+Additionally, you'll need to make sure you have `pip`_ available. You can
+check this by running:
+
+.. code-block:: console
+
+ $ pip --version
+
+If you installed Python from source, with an installer from `python.org`_, or
+via `Homebrew`_ you should already have pip. If you're on Linux and installed
+using your OS package manager, you may have to `install pip `_ separately.
+
+.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
+.. _python.org: https://python.org
+.. _pip: https://pypi.org/project/pip/
+.. _Homebrew: https://brew.sh
+.. _Installing Python: https://docs.python-guide.org/starting/installation/
+
+
+Installing Pipenv
+-----------------
+
+`Pipenv`_ is a dependency manager for Python projects. If you're familiar
+with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
+tools. While `pip`_ can install Python packages, Pipenv is recommended as
+it's a higher-level tool that simplifies dependency management for common use
+cases.
+
+Use ``pip`` to install Pipenv:
+
+.. code-block:: console
+
+ $ pip install --user pipenv
+
+
+.. Note:: This does a `user installation`_ to prevent breaking any system-wide
+ packages. If ``pipenv`` isn't available in your shell after installation,
+ you'll need to add the `user base`_'s binary directory to your ``PATH``.
+
+ On Linux and macOS you can find the user base binary directory by running
+ ``python -m site --user-base`` and adding ``bin`` to the end. For example,
+ this will typically print ``~/.local`` (with ``~`` expanded to the
+ absolute path to your home directory) so you'll need to add
+ ``~/.local/bin`` to your ``PATH``. You can set your ``PATH`` permanently by
+ `modifying ~/.profile`_.
+
+ On Windows you can find the user base binary directory by running
+ ``py -m site --user-site`` and replacing ``site-packages`` with
+ ``Scripts``. For example, this could return
+ ``C:\Users\Username\AppData\Roaming\Python36\site-packages`` so you would
+ need to set your ``PATH`` to include
+ ``C:\Users\Username\AppData\Roaming\Python36\Scripts``. You can set your
+ user ``PATH`` permanently in the `Control Panel`_. You may need to log
+ out for the ``PATH`` changes to take effect.
+
+.. _Pipenv: https://pipenv.kennethreitz.org/
+.. _npm: https://www.npmjs.com/
+.. _bundler: http://bundler.io/
+.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
+.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
+.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
+.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
+
+Installing packages for your project
+------------------------------------
+
+Pipenv manages dependencies on a per-project basis. To install packages,
+change into your project's directory (or just an empty directory for this
+tutorial) and run:
+
+.. code-block:: console
+
+ $ cd project_folder
+ $ pipenv install requests
+
+Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
+for you in your project's directory. The `Pipfile`_ is used to track which
+dependencies your project needs in case you need to re-install them, such as
+when you share your project with others. You should get output similar to this
+(although the exact paths shown will vary):
+
+.. _Pipfile: https://github.com/pypa/pipfile
+
+.. code-block:: text
+
+ Creating a Pipfile for this project...
+ Creating a virtualenv for this project...
+ Using base prefix '/usr/local/Cellar/python3/3.6.2/Frameworks/Python.framework/Versions/3.6'
+ New python executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python3.6
+ Also creating executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python
+ Installing setuptools, pip, wheel...done.
+
+ Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
+ Installing requests...
+ Collecting requests
+ Using cached requests-2.18.4-py2.py3-none-any.whl
+ Collecting idna<2.7,>=2.5 (from requests)
+ Using cached idna-2.6-py2.py3-none-any.whl
+ Collecting urllib3<1.23,>=1.21.1 (from requests)
+ Using cached urllib3-1.22-py2.py3-none-any.whl
+ Collecting chardet<3.1.0,>=3.0.2 (from requests)
+ Using cached chardet-3.0.4-py2.py3-none-any.whl
+ Collecting certifi>=2017.4.17 (from requests)
+ Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
+ Installing collected packages: idna, urllib3, chardet, certifi, requests
+ Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
+
+ Adding requests to Pipfile's [packages]...
+ P.S. You have excellent taste! ✨ 🍰 ✨
+
+.. _Requests: https://requests.readthedocs.io/en/latest/
+
+
+Using installed packages
+------------------------
+
+Now that Requests is installed you can create a simple ``main.py`` file to
+use it:
+
+.. code-block:: python
+
+ import requests
+
+ response = requests.get('https://httpbin.org/ip')
+
+ print('Your IP is {0}'.format(response.json()['origin']))
+
+Then you can run this script using ``pipenv run``:
+
+.. code-block:: console
+
+ $ pipenv run python main.py
+
+You should get output similar to this:
+
+.. code-block:: text
+
+ Your IP is 8.8.8.8
+
+Using ``$ pipenv run`` ensures that your installed packages are available to
+your script. It's also possible to spawn a new shell that ensures all commands
+have access to your installed packages with ``$ pipenv shell``.
+
+
+Next steps
+----------
+
+Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨
+
+
+
+Lower level: virtualenv
+=======================
+
+`virtualenv `_ is a tool to create
+isolated Python environments. virtualenv creates a folder which contains all the
+necessary executables to use the packages that a Python project would need.
+
+It can be used standalone, in place of Pipenv.
+
+Install virtualenv via pip:
+
+.. code-block:: console
+
+ $ pip install virtualenv
+
+Test your installation:
+
+.. code-block:: console
+
+ $ virtualenv --version
+
+Basic Usage
+-----------
+
+1. Create a virtual environment for a project:
+
+.. code-block:: console
+
+ $ cd project_folder
+ $ virtualenv venv
+
+``virtualenv venv`` will create a folder in the current directory which will
+contain the Python executable files, and a copy of the ``pip`` library which you
+can use to install other packages. The name of the virtual environment (in this
+case, it was ``venv``) can be anything; omitting the name will place the files
+in the current directory instead.
+
+.. note::
+ 'venv' is the general convention used globally. As it is readily available in ignore files (eg: .gitignore')
+
+This creates a copy of Python in whichever directory you ran the command in,
+placing it in a folder named :file:`venv`.
+
+You can also use the Python interpreter of your choice (like
+``python2.7``).
+
+.. code-block:: console
+
+ $ virtualenv -p /usr/bin/python2.7 venv
+
+or change the interpreter globally with an env variable in ``~/.bashrc``:
+
+.. code-block:: console
+
+ $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
+
+2. To begin using the virtual environment, it needs to be activated:
+
+.. code-block:: console
+
+ $ source venv/bin/activate
+
+The name of the current virtual environment will now appear on the left of
+the prompt (e.g. ``(venv)Your-Computer:project_folder UserName$``) to let you know
+that it's active. From now on, any package that you install using pip will be
+placed in the ``venv`` folder, isolated from the global Python installation.
+
+For Windows, the same command mentioned in step 1 can be used to create a virtual environment. However, activating the environment requires a slightly different command.
+
+Assuming that you are in your project directory:
+
+.. code-block:: console
+
+ C:\Users\SomeUser\project_folder> venv\Scripts\activate
+
+Install packages using the ``pip`` command:
+
+.. code-block:: console
+
+ $ pip install requests
+
+3. If you are done working in the virtual environment for the moment, you can
+ deactivate it:
+
+.. code-block:: console
+
+ $ deactivate
+
+This puts you back to the system's default Python interpreter with all its
+installed libraries.
+
+To delete a virtual environment, just delete its folder. (In this case,
+it would be ``rm -rf venv``.)
+
+After a while, though, you might end up with a lot of virtual environments
+littered across your system, and it's possible you'll forget their names or
+where they were placed.
+
+.. note::
+ Python has included venv module from version 3.3. For more details: `venv `_.
+
+Other Notes
+-----------
+
+Running ``virtualenv`` with the option ``--no-site-packages`` will not
+include the packages that are installed globally. This can be useful
+for keeping the package list clean in case it needs to be accessed later.
+[This is the default behavior for ``virtualenv`` 1.7 and later.]
+
+In order to keep your environment consistent, it's a good idea to "freeze"
+the current state of the environment packages. To do this, run:
+
+.. code-block:: console
+
+ $ pip freeze > requirements.txt
+
+This will create a :file:`requirements.txt` file, which contains a simple
+list of all the packages in the current environment, and their respective
+versions. You can see the list of installed packages without the requirements
+format using ``pip list``. Later it will be easier for a different developer
+(or you, if you need to re-create the environment) to install the same packages
+using the same versions:
+
+.. code-block:: console
+
+ $ pip install -r requirements.txt
+
+This can help ensure consistency across installations, across deployments,
+and across developers.
+
+Lastly, remember to exclude the virtual environment folder from source
+control by adding it to the ignore list (see :ref:`Version Control Ignores`).
+
+.. _virtualenvwrapper-ref:
+
+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.
+
+To install (make sure **virtualenv** is already installed):
+
+.. code-block:: console
+
+ $ pip install virtualenvwrapper
+ $ export WORKON_HOME=~/Envs
+ $ source /usr/local/bin/virtualenvwrapper.sh
+
+(`Full virtualenvwrapper install instructions `_.)
+
+For Windows, you can use the `virtualenvwrapper-win `_.
+
+To install (make sure **virtualenv** is already installed):
+
+.. code-block:: console
+
+ $ pip install virtualenvwrapper-win
+
+In Windows, the default path for WORKON_HOME is %USERPROFILE%\\Envs
+
+Basic Usage
+~~~~~~~~~~~
+
+1. Create a virtual environment:
+
+.. code-block:: console
+
+ $ mkvirtualenv project_folder
+
+This creates the :file:`project_folder` folder inside :file:`~/Envs`.
+
+2. Work on a virtual environment:
+
+.. code-block:: console
+
+ $ workon project_folder
+
+Alternatively, you can make a project, which creates the virtual environment,
+and also a project directory inside ``$WORKON_HOME``, which is ``cd``-ed into
+when you ``workon project_folder``.
+
+.. code-block:: console
+
+ $ mkproject project_folder
+
+**virtualenvwrapper** provides tab-completion on environment names. It really
+helps when you have a lot of environments and have trouble remembering their
+names.
+
+``workon`` also deactivates whatever environment you are currently in, so you
+can quickly switch between environments.
+
+3. Deactivating is still the same:
+
+.. code-block:: console
+
+ $ deactivate
+
+4. To delete:
+
+.. code-block:: console
+
+ $ rmvirtualenv venv
+
+Other useful commands
+~~~~~~~~~~~~~~~~~~~~~
+
+``lsvirtualenv``
+ List all of the environments.
+
+``cdvirtualenv``
+ Navigate into the directory of the currently activated virtual environment,
+ so you can browse its :file:`site-packages`, for example.
+
+``cdsitepackages``
+ Like the above, but directly into :file:`site-packages` directory.
+
+``lssitepackages``
+ Shows contents of :file:`site-packages` directory.
+
+`Full list of virtualenvwrapper commands `_.
+
+virtualenv-burrito
+------------------
+
+With `virtualenv-burrito `_, you
+can have a working virtualenv + virtualenvwrapper environment in a single command.
+
+direnv
+-------
+When you ``cd`` into a directory containing a :file:`.env`, `direnv `_
+automagically activates the environment.
+
+Install it on Mac OS X using ``brew``:
+
+.. code-block:: console
+
+ $ brew install direnv
+
+On Linux follow the instructions at `direnv.net `_
diff --git a/docs/index.rst b/docs/index.rst
index f3b727a0b..df7fcb8ed 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,15 +1,33 @@
-.. osxpython documentation master file, created by
+.. pythonguide documentation master file, created by
sphinx-quickstart on Wed Aug 4 22:51:11 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-The Hitchhikers Guide to Python!
-================================
+.. meta::
+ :description: An opinionated guide to the Python programming language and a best practice handbook for the installation, configuration, and usage of Python on a daily basis.
-Welcome to The Hitchhiker's Guide to Python.
-**This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub `_!
+#################################
+The Hitchhiker's Guide to Python!
+#################################
-This *opinionated* guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
+Greetings, Earthling! Welcome to The Hitchhiker's Guide to Python.
-.. include:: contents.rst.inc
\ No newline at end of file
+**This is a living, breathing guide.** If you'd like to contribute,
+`fork us on GitHub `_!
+
+This handcrafted guide exists to provide both novice and expert Python
+developers a best practice handbook for the installation, configuration, and
+usage of Python on a daily basis.
+
+This guide is **opinionated** in a way that is almost, but not quite, entirely
+*unlike* Python's official documentation. You won't find a list of every Python web framework
+available here. Rather, you'll find a nice concise list of highly recommended
+options.
+
+.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructures if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
+ —*Kenneth Reitz*
+
+Let's get started! But first, let's make sure you know where your towel is.
+
+.. include:: contents.rst.inc
diff --git a/docs/intro/community.rst b/docs/intro/community.rst
index 74b372062..4ce563658 100644
--- a/docs/intro/community.rst
+++ b/docs/intro/community.rst
@@ -1,33 +1,48 @@
+.. _the-community:
+
+
+#############
The Community
-=============
+#############
-BDFL
-----
+.. image:: /_static/photos/34689432801_78d97ecec9_k_d.jpg
-Guido van Rossum, the creator of Python, is often referred to as the BDFL — the Benevolent Dictator For Life.
+****
+BDFL
+****
+
+Guido van Rossum, the creator of Python, is often referred to as the BDFL — the
+Benevolent Dictator For Life.
+**************************
Python Software Foundation
---------------------------
+**************************
+
-The mission of the Python Software Foundation is to promote, protect, and advance the Python programming language, and to support and facilitate the growth of a diverse and international community of Python programmers.
+The mission of the Python Software Foundation is to promote, protect, and
+advance the Python programming language, and to support and facilitate the
+growth of a diverse and international community of Python programmers.
`Learn More about the PSF `_.
+****
PEPs
-----
+****
-PEPs are *Python Enhancement Proposals*. They are define change to Python itself, or the standards around it.
+PEPs are *Python Enhancement Proposals*. They describe changes to Python itself,
+or the standards around it.
-There are three different types of PEPs (as defined by `PEP1 `_):
+There are three different types of PEPs (as defined by :pep:`1`):
**Standards**
Describes a new feature or implementation.
**Informational**
- Describes a design issue, general guidelines, or information to the community.
+ Describes a design issue, general guidelines, or information to the
+ community.
**Process**
Describes a process related to Python.
@@ -38,36 +53,63 @@ Notable PEPs
There are a few PEPs that could be considered required reading:
-- `PEP8 `_: The Python Style Guide.
+- :pep:`8`: The Python Style Guide.
Read this. All of it. Follow it.
-- `PEP20 `_: The Zen of Python.
+- :pep:`20`: The Zen of Python.
A list of 19 statements that briefly explain the philosophy behind Python.
-- `PEP257 `_: Docstring Conventions.
- Gives guidelines for semantics and conventions associated with Python docstrings.
+- :pep:`257`: Docstring Conventions.
+ Gives guidelines for semantics and conventions associated with Python
+ docstrings.
You can read more at `The PEP Index `_.
Submitting a PEP
~~~~~~~~~~~~~~~~
- PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone can write and submit a PEP for review.
+PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone
+can write and submit a PEP for review.
- Here's an overview of the PEP acceptance workflow:
+Here's an overview of the PEP acceptance workflow:
- .. image:: http://www.python.org/dev/peps/pep-0001/pep-0001-1.png
+.. image:: ../_static/pep-0001-1.png
-Python Conferences
---------------------------
+******************
+Python Conferences
+******************
-The major events for the Python community are developer conferences. The two most notable conferences are PyCon, which is held in the US, and its European sibling, EuroPython.
+The major events for the Python community are developer conferences. The two
+most notable conferences are PyCon, which is held in the US, and its European
+sibling, EuroPython.
-A comprehensive list of conferences is maintained `at pycon.org `_.
+A comprehensive list of conferences is maintained at `pycon.org `_.
+******************
Python User Groups
---------------------------
+******************
+
+User Groups are where a bunch of Python developers meet to present or talk
+about Python topics of interest. A list of local user groups is maintained at
+the `Python Software Foundation Wiki `_.
+
+
+******************
+Online Communities
+******************
+
+`PythonistaCafe `_ is an invite-only, online community
+of Python and software development enthusiasts helping each other succeed and grow.
+Think of it as a club of mutual improvement for Pythonistas where a broad range of
+programming questions, career advice, and other topics are discussed every day.
+
+
+*****************
+Python Job Boards
+*****************
-User Groups are where a bunch of Python developers meet to present or talk about Python topics of interest. A list of local user groups is maintained at the `Python Software Foundation Wiki `_.
\ No newline at end of file
+`Python Jobs HQ `_ is a Python job board, by Python Developers
+for Python Developers. The site aggregates Python job postings from across the web and
+also allows employers to post Python job openings directly on the site.
diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst
index 3359f371b..887d0982b 100644
--- a/docs/intro/documentation.rst
+++ b/docs/intro/documentation.rst
@@ -1,20 +1,49 @@
+
+
+#############
Documentation
-=============
+#############
+
+.. image:: /_static/photos/33928823133_2f3d32cf32_k_d.jpg
+
+**********************
Official Documentation
-----------------------
+**********************
The official Python Language and Library documentation can be found here:
- - `Python 2.x `_
- - `Python 3.x `_
+ - `Python 2.x `_
+ - `Python 3.x `_
+*************
Read the Docs
--------------
+*************
+
+Read the Docs is a popular community project that hosts documentation
+for open source software. It holds documentation for many Python modules,
+both popular and exotic.
+
+ `Read the Docs `_
+
+
+*****
+pydoc
+*****
+
+:program:`pydoc` is a utility that is installed when you install Python.
+It allows you to quickly retrieve and search for documentation from your
+shell. For example, if you needed a quick refresher on the
+:mod:`time` module, pulling up documentation would be as simple as:
+
+ .. code-block:: console
-Read the Docs is a popular community project, providing a single location for all documentation of popular and even more exotic Python modules.
+ $ pydoc time
- `Read the Docs `_
+The above command is essentially equivalent to opening the Python REPL
+and running:
+ .. code-block:: pycon
+ >>> help(time)
diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst
index aa1cd771f..16baebc0d 100644
--- a/docs/intro/duction.rst
+++ b/docs/intro/duction.rst
@@ -1,4 +1,95 @@
+
+
+############
Introduction
-============
+############
+
+.. image:: /_static/photos/34725946825_0f85497e60_k_d.jpg
+
+From the `official Python website `_:
+
+Python is a general-purpose, high-level programming language similar
+to Tcl, Perl, Ruby, Scheme, or Java. Some of its main key features
+include:
+
+* **very clear, readable syntax**
+
+ Python's philosophy focuses on readability, from code blocks
+ delineated with significant whitespace to intuitive keywords in
+ place of inscrutable punctuation.
+
+* **extensive standard libraries and third party modules for virtually
+ any task**
+
+ Python is sometimes described with the words "batteries included"
+ because of its extensive
+ `standard library `_, which includes
+ modules for regular expressions, file IO, fraction handling,
+ object serialization, and much more.
+
+ Additionally, the
+ `Python Package Index `_ is available
+ for users to submit their packages for widespread use, similar to
+ Perl's `CPAN `_. There is a thriving community
+ of very powerful Python frameworks and tools like
+ the `Django `_ web framework and the
+ `NumPy `_ set of math routines.
+
+* **integration with other systems**
+
+ Python can integrate with `Java libraries `_,
+ enabling it to be used with the rich Java environment that corporate
+ programmers are used to. It can also be
+ `extended by C or C++ modules `_
+ when speed is of the essence.
+
+* **ubiquity on computers**
+
+ Python is available on Windows, \*nix, and Mac. It runs wherever the
+ Java virtual machine runs, and the reference implementation CPython
+ can help bring Python to wherever there is a working C compiler.
+
+* **friendly community**
+
+ Python has a vibrant and large :ref:`community `
+ which maintains wikis, conferences, countless repositories,
+ mailing lists, IRC channels, and so much more. Heck, the Python
+ community is even helping to write this guide!
+
+
+.. _about-ref:
+
+
+****************
+About This Guide
+****************
+
+Purpose
+~~~~~~~
+
+The Hitchhiker's Guide to Python exists to provide both novice and expert
+Python developers a best practice handbook for the installation, configuration,
+and usage of Python on a daily basis.
+
+
+By the Community
+~~~~~~~~~~~~~~~~
+
+This guide is architected and maintained by `Kenneth Reitz
+`_ in an open fashion. This is a
+community-driven effort that serves one purpose: to serve the community.
+
+For the Community
+~~~~~~~~~~~~~~~~~
+
+All contributions to the Guide are welcome, from Pythonistas of all levels.
+If you think there's a gap in what the Guide covers, fork the Guide on
+GitHub and submit a pull request.
+
+Contributions are welcome from everyone, whether they're an old hand or a
+first-time Pythonista, and the authors to the Guide will gladly help if you
+have any questions about the appropriateness, completeness, or accuracy of
+a contribution.
-Someone should write a general blurb introducing the Python language here
+To get started working on The Hitchhiker's Guide,
+see the :doc:`/notes/contribute` page.
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index fadf35104..b0c957398 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -1,71 +1,412 @@
+
+
+###############
Learning Python
-===============
+###############
+
+.. image:: /_static/photos/32800783863_11a00db52c_k_d.jpg
+
+********
Beginner
---------
+********
+
+The Python Tutorial
+~~~~~~~~~~~~~~~~~~~~
+
+This is the official tutorial. It covers all the basics, and offers a tour of
+the language and the standard library. Recommended for those who need a
+quick-start guide to the language.
+
+ `The Python Tutorial `_
+
+Real Python
+~~~~~~~~~~~
+
+Real Python is a repository of free and in-depth Python tutorials created by a diverse team of professional Python developers. At Real Python you can learn all things Python from the ground up. Everything from the absolute basics of Python, to web development and web scraping, to data visualization, and beyond.
+
+ `Real Python `_
+
+Python Basics
+~~~~~~~~~~~~~
+
+pythonbasics.org is an introductory tutorial for beginners. The tutorial includes exercises. It covers the basics and there are also in-depth lessons like object oriented programming and regular expressions.
+
+ `Python basics `_
+
+Python for Beginners
+~~~~~~~~~~~~~~~~~~~~
+
+thepythonguru.com is a tutorial focused on beginner programmers. It covers many Python concepts
+in depth. It also teaches you some advanced constructs of Python like lambda expressions and regular expressions.
+And last it finishes off with the tutorial "How to access MySQL db using Python"
+
+ `Python for Beginners `_
Learn Python Interactive Tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Learnpython.org is an easy non-intimidating way to get introduced to python. The website takes the same approach used on the popular `Try Ruby `_ website, it has an interactive python interpreter built into the site that allows you to go through the lessons without having to install Python locally.
+Learnpython.org is an easy non-intimidating way to get introduced to Python.
+The website takes the same approach used on the popular
+`Try Ruby `_ website. It has an interactive Python
+interpreter built into the site that allows you to go through the lessons
+without having to install Python locally.
`Learn Python `_
+Python for You and Me
+~~~~~~~~~~~~~~~~~~~~~
+
+If you want a more traditional book, *Python For You and Me* is an excellent
+resource for learning all aspects of the language.
+
+ `Python for You and Me `_
+
+Learn Python Step by Step
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial is supplemented with logically added coding snippets and equips with a follow-up quiz on the subject learned. There is a section for `Python interview questions `_ to help job seekers. You can also read essential `Python tips `_ and learn `best coding practices `_ for writing quality code. Here, you'll get the right platform to learn Python quickly.
+
+`Learn Python Basic to Advanced `_
+
+
+Online Python Tutor
+~~~~~~~~~~~~~~~~~~~
+
+Online Python Tutor gives you a visual step-by-step
+representation of how your program runs. Python Tutor
+helps people overcome a fundamental barrier to learning
+programming by understanding what happens as the computer
+executes each line of a program's source code.
+
+ `Online Python Tutor `_
+
+Invent Your Own Computer Games with Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This beginner's book is for those with no programming experience at all. Each
+chapter has the source code to a small game, using these example programs
+to demonstrate programming concepts to give the reader an idea of what
+programs "look like".
+
+ `Invent Your Own Computer Games with Python `_
+
+
+Hacking Secret Ciphers with Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This book teaches Python programming and basic cryptography for absolute
+beginners. The chapters provide the source code for various ciphers, as well
+as programs that can break them.
+
+ `Hacking Secret Ciphers with Python `_
+
+
Learn Python the Hard Way
~~~~~~~~~~~~~~~~~~~~~~~~~
-This is an excellent beginner programmer's guide to Python. It covers "hello world" from the console to the web.
+This is an excellent beginner programmer's guide to Python. It covers "hello
+world" from the console to the web.
- `Learn Python the Hard Way `_
+ `Learn Python the Hard Way `_
Crash into Python
~~~~~~~~~~~~~~~~~
-Also known as *Python for Programmers with 3 Hours*, this guide gives experienced developers from other languages a crash course on Python.
+Also known as *Python for Programmers with 3 Hours*, this guide gives
+experienced developers from other languages a crash course on Python.
- `Crash into Python `_
+ `Crash into Python `_
Dive Into Python 3
~~~~~~~~~~~~~~~~~~
-Dive Into Python 3 is a good book for those ready to jump in to Python 3. It's a
-good read if you are moving from Python 2 to 3 or if you already have some
+Dive Into Python 3 is a good book for those ready to jump in to Python 3. It's
+a good read if you are moving from Python 2 to 3 or if you already have some
experience programming in another language.
- `Dive Into Python 3 `_
+ `Dive Into Python 3 `_
+
Think Python: How to Think Like a Computer Scientist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Think Python attempts to give an introduction to basic concepts in computer science through the
-use of the python language. The focus was to create a book with plenty of exercises, minimal jargon and
-a section in each chapter devoted to the subject of debugging.
+Think Python attempts to give an introduction to basic concepts in computer
+science through the use of the Python language. The focus was to create a book
+with plenty of exercises, minimal jargon, and a section in each chapter devoted
+to the subject of debugging.
-While exploring the various features available in the python language the author weaves in various design
-patterns and best practices.
+While exploring the various features available in the Python language the
+author weaves in various design patterns and best practices.
-The book also includes several case studies which have the reader explore the topics discussed in the book
-in greater detail by applying those topics to real-world examples. Case studies include assingments in GUI
-and Markov Analysis.
+The book also includes several case studies which have the reader explore the
+topics discussed in the book in greater detail by applying those topics to
+real-world examples. Case studies include assignments in GUI programming and Markov
+Analysis.
`Think Python `_
+Python Koans
+~~~~~~~~~~~~
+
+Python Koans is a port of Edgecase's Ruby Koans. It uses a test-driven
+approach to provide an interactive tutorial
+teaching basic Python concepts. By fixing assertion statements that fail in a
+test script, this provides sequential steps to learning Python.
+
+For those used to languages and figuring out puzzles on their own, this can be
+a fun, attractive option. For those new to Python and programming, having an
+additional resource or reference will be helpful.
+
+ `Python Koans `_
+
+More information about test driven development can be found at these resources:
+
+ `Test Driven Development `_
+
+
+A Byte of Python
+~~~~~~~~~~~~~~~~
+
+A free introductory book that teaches Python at the beginner level, it assumes
+no previous programming experience.
+
+ `A Byte of Python for Python 2.x `_
+ `A Byte of Python for Python 3.x `_
+
+
+Computer Science Path on Codecademy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Codecademy course for the absolute Python beginner. This free and interactive
+course provides and teaches the basics (and beyond) of Python programming while
+testing the user's knowledge in between progress.
+This course also features a built-in interpreter for receiving instant feedback on your learning.
+
+ `Computer Science Path on Codecademy `_
+
+
+Code the blocks
+~~~~~~~~~~~~~~~
+
+*Code the blocks* provides free and interactive Python tutorials for
+beginners. It combines Python programming with a 3D environment where
+you "place blocks" and construct structures. The tutorials teach you
+how to use Python to create progressively more elaborate 3D structures,
+making the process of learning Python fun and engaging.
+
+ `Code the blocks `_
+
+
+************
+Intermediate
+************
+
+Python Tricks: The Book
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Discover Python's best practices with simple examples and start writing even more beautiful + Pythonic code. *Python Tricks: The Book* shows you exactly how.
+
+You’ll master intermediate and advanced-level features in Python with practical examples and a clear narrative.
+
+ `Python Tricks: The Book `_
+
+Effective Python
+~~~~~~~~~~~~~~~~
+
+This book contains 59 specific ways to improve writing Pythonic code. At 227
+pages, it is a very brief overview of some of the most common adaptations
+programmers need to make to become efficient intermediate level Python
+programmers.
+
+ `Effective Python `_
+
+
+********
Advanced
---------
+********
Pro Python
~~~~~~~~~~
-TODO: Write about this book
+This book is for intermediate to advanced Python programmers who are looking to
+understand how and why Python works the way it does and how they can take their
+code to the next level.
+
+ `Pro Python `_
- `Pro Python `_
Expert Python Programming
~~~~~~~~~~~~~~~~~~~~~~~~~
+Expert Python Programming deals with best practices in programming Python and
+is focused on the more advanced crowd.
+
+It starts with topics like decorators (with caching, proxy, and context manager
+case studies), method resolution order, using super() and meta-programming, and
+general :pep:`8` best practices.
+
+It has a detailed, multi-chapter case study on writing and releasing a package
+and eventually an application, including a chapter on using zc.buildout. Later
+chapters detail best practices such as writing documentation, test-driven
+development, version control, optimization, and profiling.
+
+ `Expert Python Programming `_
+
+
+A Guide to Python's Magic Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a collection of blog posts by Rafe Kettler which explain 'magic methods'
+in Python. Magic methods are surrounded by double underscores (i.e. __init__)
+and can make classes and objects behave in different and magical ways.
+
+ `A Guide to Python's Magic Methods `_
+
+.. note:: Rafekettler.com is currently down; you can go to their GitHub version directly. Here you can find a PDF version:
+ `A Guide to Python's Magic Methods (repo on GitHub) `_
+
+
+****************************
+For Engineers and Scientists
+****************************
+
+A Primer on Scientific Programming with Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Primer on Scientific Programming with Python, written by Hans Petter
+Langtangen, mainly covers Python's usage in the scientific field. In the book,
+examples are chosen from mathematics and the natural sciences.
+
+ `A Primer on Scientific Programming with Python `_
+
+Numerical Methods in Engineering with Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Numerical Methods in Engineering with Python, written by Jaan Kiusalaas,
+puts the emphasis on numerical methods and how to implement them in Python.
+
+ `Numerical Methods in Engineering with Python `_
+
+
+********************
+Miscellaneous Topics
+********************
+
+Problem Solving with Algorithms and Data Structures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Problem Solving with Algorithms and Data Structures covers a range of data
+structures and algorithms. All concepts are illustrated with Python code along
+with interactive samples that can be run directly in the browser.
+
+ `Problem Solving with Algorithms and Data Structures
+ `_
+
+Programming Collective Intelligence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Programming Collective Intelligence introduces a wide array of basic machine
+learning and data mining methods. The exposition is not very mathematically
+formal, but rather focuses on explaining the underlying intuition and shows
+how to implement the algorithms in Python.
+
+ `Programming Collective Intelligence `_
+
+
+Transforming Code into Beautiful, Idiomatic Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Transforming Code into Beautiful, Idiomatic Python is a video by Raymond Hettinger.
+Learn to take better advantage of Python's best features and improve existing code
+through a series of code transformations: "When you see this, do that instead."
+
+ `Transforming Code into Beautiful, Idiomatic Python `_
+
+
+Fullstack Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fullstack Python offers a complete top-to-bottom resource for web development
+using Python.
+
+From setting up the web server, to designing the front-end, choosing a database,
+optimizing/scaling, etc.
+
+As the name suggests, it covers everything you need to build and run a complete
+web app from scratch.
+
+ `Fullstack Python `_
+
+
+PythonistaCafe
+~~~~~~~~~~~~~~
+
+PythonistaCafe is an invite-only, online community of Python and software development enthusiasts helping each other succeed and grow. Think of it as a club of mutual improvement for Pythonistas where a broad range of programming questions, career advice, and other topics are discussed every day.
+
+ `PythonistaCafe `_
+
+
+**********
+References
+**********
+
+Python in a Nutshell
+~~~~~~~~~~~~~~~~~~~~
+
+Python in a Nutshell, written by Alex Martelli, covers most cross-platform
+Python usage, from its syntax to built-in libraries to advanced topics such
+as writing C extensions.
+
+ `Python in a Nutshell `_
+
+The Python Language Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is Python's reference manual. It covers the syntax and the core semantics
+of the language.
+
+ `The Python Language Reference `_
+
+Python Essential Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python Essential Reference, written by David Beazley, is the definitive reference
+guide to Python. It concisely explains both the core language and the most essential
+parts of the standard library. It covers Python 3 and 2.6 versions.
+
+ `Python Essential Reference `_
+
+Python Pocket Reference
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Python Pocket Reference, written by Mark Lutz, is an easy to use reference to
+the core language, with descriptions of commonly used modules and toolkits. It
+covers Python 3 and 2.6 versions.
+
+ `Python Pocket Reference `_
+
+Python Cookbook
+~~~~~~~~~~~~~~~
+
+Python Cookbook, written by David Beazley and Brian K. Jones, is packed with
+practical recipes. This book covers the core Python language as well as tasks
+common to a wide variety of application domains.
+
+ `Python Cookbook `_
+
+Writing Idiomatic Python
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Writing Idiomatic Python, written by Jeff Knupp, contains the most common and
+important Python idioms in a format that maximizes identification and
+understanding. Each idiom is presented as a recommendation of a way to write
+some commonly used piece of code, followed by an explanation of why the idiom
+is important. It also contains two code samples for each idiom: the "Harmful"
+way to write it and the "Idiomatic" way.
-TODO: Write about this book
+ `For Python 2.7.3+ `_
- `Expert Python Programming `_
+ `For Python 3.3+ `_
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
index 209ac1aaf..d1cda93be 100644
--- a/docs/intro/news.rst
+++ b/docs/intro/news.rst
@@ -1,25 +1,102 @@
-News
-====
-
-Planet Python
-~~~~~~~~~~~~~
-
-This is an aggregate of Python news from a growing number of developers.
-
- `Planet Python `_
-
-/r/python
-~~~~~~~~~
-
-/r/python is the Reddit Python community where users contribute and vote on
-Python-related news.
-
- `/r/python `_
-
-Python Weekly
-~~~~~~~~~~~~~
-
-Python Weekly is a free weekly newsletter featureing curated news, articles,
-new releases, jobs etc related to Python.
-
- `Python Weekly `_
+
+
+####
+News
+####
+
+.. image:: /_static/photos/33573767786_eececc5d27_k_d.jpg
+
+
+****************
+PyCoder’s Weekly
+****************
+
+PyCoder’s Weekly is a free weekly Python newsletter for Python developers
+by Python developers (Projects, Articles, News, and Jobs).
+
+ `PyCoder’s Weekly `_
+
+
+***********
+Real Python
+***********
+
+At Real Python you can learn all things Python from the ground up, with weekly free and in-depth tutorials. Everything from the absolute basics of Python, to web development and web scraping, to data visualization, and beyond.
+
+ `Real Python `_
+
+
+*************
+Planet Python
+*************
+
+This is an aggregate of Python news from a growing number of developers.
+
+ `Planet Python `_
+
+
+*********
+/r/python
+*********
+
+/r/python is the Reddit Python community where users contribute and vote on
+Python-related news.
+
+ `/r/python `_
+
+
+*******************
+Talk Python Podcast
+*******************
+
+The #1 Python-focused podcast covering the people and ideas in Python.
+
+ `Talk Python To Me `_
+
+
+********************
+Python Bytes Podcast
+********************
+
+A short-form Python podcast covering recent developer headlines.
+
+ `Python Bytes `_
+
+
+*************
+Python Weekly
+*************
+
+Python Weekly is a free weekly newsletter featuring curated news, articles,
+new releases, jobs, etc. related to Python.
+
+ `Python Weekly `_
+
+
+***********
+Python News
+***********
+
+Python News is the news section in the official Python web site
+(www.python.org). It briefly highlights the news from the Python community.
+
+ `Python News `_
+
+
+********************
+Import Python Weekly
+********************
+
+Weekly Python Newsletter containing Python Articles, Projects, Videos, and 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 `_
diff --git a/docs/make.bat b/docs/make.bat
index 39f2a6893..115651a00 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -7,8 +7,10 @@ if "%SPHINXBUILD%" == "" (
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
@@ -28,7 +30,11 @@ if "%1" == "help" (
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
@@ -40,8 +46,34 @@ if "%1" == "clean" (
goto end
)
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+:sphinx_ok
+
+
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
@@ -49,6 +81,7 @@ if "%1" == "html" (
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
@@ -56,6 +89,7 @@ if "%1" == "dirhtml" (
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
@@ -63,6 +97,7 @@ if "%1" == "singlehtml" (
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
@@ -70,6 +105,7 @@ if "%1" == "pickle" (
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
@@ -77,6 +113,7 @@ if "%1" == "json" (
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
@@ -85,17 +122,19 @@ if "%1" == "htmlhelp" (
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
- echo.^> qcollectiongenerator %BUILDDIR%\qthelp\osxpython.qhcp
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\pythonguide.qhcp
echo.To view the help file:
- echo.^> assistant -collectionFile %BUILDDIR%\qthelp\osxpython.ghc
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\pythonguide.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
@@ -103,6 +142,7 @@ if "%1" == "devhelp" (
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
@@ -110,13 +150,35 @@ if "%1" == "epub" (
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
@@ -124,13 +186,31 @@ if "%1" == "text" (
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
@@ -138,6 +218,7 @@ if "%1" == "changes" (
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
@@ -146,10 +227,27 @@ or in %BUILDDIR%/linkcheck/output.txt.
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
:end
diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst
index 1848fbf72..b6c72bb4f 100644
--- a/docs/notes/contribute.rst
+++ b/docs/notes/contribute.rst
@@ -1,17 +1,34 @@
+##########
Contribute
-----------
+##########
+
+.. image:: /_static/photos/33573769116_49c1ef51e7_k_d.jpg
Python-guide is under active development, and contributors are welcome.
-If you have a feature request, suggestion, or bug report, please open a new issue on GitHub_. To submit patches, please send a pull request on GitHub_. Make sure you add yourself to AUTHORS_.
+If you have a feature request, suggestion, or bug report, please open a new
+issue on GitHub_. To submit patches, please send a pull request on GitHub_.
+Once your changes get merged back in, you'll automatically be added to the
+`Contributors List `_.
+
+
+***********
+Style Guide
+***********
+
+For all contributions, please follow the :ref:`guide-style-guide`.
+.. _todo-list-ref:
+
+
+*********
+Todo List
+*********
If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
.. include:: ../../TODO.rst
-.. _GitHub: http://github.com/kennethreitz/python-guide/
-.. _AUTHORS: http://github.com/kennethreitz/python-guide/blob/master/AUTHORS
+.. _GitHub: https://github.com/kennethreitz/python-guide/
.. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst
-
diff --git a/docs/notes/license.rst b/docs/notes/license.rst
index d03e7d1f5..1dd3d340a 100644
--- a/docs/notes/license.rst
+++ b/docs/notes/license.rst
@@ -1,4 +1,7 @@
+#######
License
--------
+#######
-TBD.
\ No newline at end of file
+.. image:: /_static/photos/32800805573_568d6b72fd_k_d.jpg
+
+The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license `_.
diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst
new file mode 100644
index 000000000..5a715332e
--- /dev/null
+++ b/docs/notes/styleguide.rst
@@ -0,0 +1,216 @@
+.. _guide-style-guide:
+
+#####################
+The Guide Style Guide
+#####################
+
+.. image:: /_static/photos/33573755856_7f43d43adf_k_d.jpg
+
+As with all documentation, having a consistent format helps make the
+document more understandable. In order to make The Guide easier to digest,
+all contributions should fit within the rules of this style guide where
+appropriate.
+
+The Guide is written as :ref:`restructuredtext-ref`.
+
+.. note:: Parts of The Guide may not yet match this style guide. Feel free
+ to update those parts to be in sync with The Guide Style Guide
+
+.. note:: On any page of the rendered HTML you can click "Show Source" to
+ see how authors have styled the page.
+
+
+*********
+Relevancy
+*********
+
+Strive to keep any contributions relevant to the :ref:`purpose of The Guide
+`.
+
+* Avoid including too much information on subjects that don't directly
+ relate to Python development.
+* Prefer to link to other sources if the information is already out there.
+ Be sure to describe what and why you are linking.
+* `Cite `_
+ references where needed.
+* If a subject isn't directly relevant to Python, but useful in conjunction
+ with Python (e.g., Git, GitHub, Databases), reference by linking to useful
+ resources, and describe why it's useful to Python.
+* When in doubt, ask.
+
+
+********
+Headings
+********
+
+Use the following styles for headings.
+
+Chapter title:
+
+.. code-block:: rest
+
+ #########
+ Chapter 1
+ #########
+
+Page title:
+
+.. code-block:: rest
+
+ *******************
+ Time is an Illusion
+ *******************
+
+Section headings:
+
+.. code-block:: rest
+
+ Lunchtime Doubly So
+ ===================
+
+Sub section headings:
+
+.. code-block:: rest
+
+ Very Deep
+ ---------
+
+
+*****
+Prose
+*****
+
+Wrap text lines at 78 characters. Where necessary, lines may exceed 78
+characters, especially if wrapping would make the source text more difficult
+to read.
+
+Use Standard American English, not British English.
+
+Use of the `serial comma `_
+(also known as the Oxford comma) is 100% non-optional. Any attempt to
+submit content with a missing serial comma will result in permanent banishment
+from this project, due to complete and total lack of taste.
+
+Banishment? Is this a joke? Hopefully we will never have to find out.
+
+
+*************
+Code Examples
+*************
+
+Wrap all code examples at 70 characters to avoid horizontal scrollbars.
+
+Command line examples:
+
+.. code-block:: rest
+
+ .. code-block:: console
+
+ $ run command --help
+ $ ls ..
+
+Be sure to include the ``$`` prefix before each line for Unix console examples.
+
+For Windows console examples, use ``doscon`` or ``powershell`` instead of
+``console``, and omit the ``$`` prefix.
+
+Python interpreter examples:
+
+.. code-block:: rest
+
+ Label the example::
+
+ .. code-block:: python
+
+ >>> import this
+
+Python examples:
+
+.. code-block:: rest
+
+ Descriptive title::
+
+ .. code-block:: python
+
+ def get_answer():
+ return 42
+
+
+******************
+Externally Linking
+******************
+
+* Prefer labels for well known subjects (e.g. proper nouns) when linking:
+
+ .. code-block:: rest
+
+ Sphinx_ is used to document Python.
+
+ .. _Sphinx: https://www.sphinx-doc.org
+
+* Prefer to use descriptive labels with inline links instead of leaving bare
+ links:
+
+ .. code-block:: rest
+
+ Read the `Sphinx Tutorial `_
+
+* Avoid using labels such as "click here", "this", etc., preferring
+ descriptive labels (SEO worthy) instead.
+
+
+********************************
+Linking to Sections in The Guide
+********************************
+
+To cross-reference other parts of this documentation, use the `:ref:
+`_
+keyword and labels.
+
+To make reference labels more clear and unique, always add a ``-ref`` suffix:
+
+.. code-block:: rest
+
+ .. _some-section-ref:
+
+ Some Section
+ ------------
+
+
+******************
+Notes and Warnings
+******************
+
+Make use of the appropriate `admonitions directives
+`_ when making notes.
+
+Notes:
+
+.. code-block:: rest
+
+ .. note::
+ The Hitchhiker’s Guide to the Galaxy has a few things to say
+ on the subject of towels. A towel, it says, is about the most
+ massively useful thing an interstellar hitch hiker can have.
+
+Warnings:
+
+.. code-block:: rest
+
+ .. warning:: DON'T PANIC
+
+
+*****
+TODOs
+*****
+
+Please mark any incomplete areas of The Guide with a `todo directive
+`_. To
+avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
+documents or large incomplete sections.
+
+.. code-block:: rest
+
+ .. todo::
+ Learn the Ultimate Answer to the Ultimate Question
+ of Life, The Universe, and Everything
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
index f3a1492bd..f6433c213 100644
--- a/docs/scenarios/admin.rst
+++ b/docs/scenarios/admin.rst
@@ -1,17 +1,397 @@
+
+######################
Systems Administration
-======================
+######################
+
+.. image:: /_static/photos/34435690580_3afec7d4cd_k_d.jpg
+
+******
Fabric
-------
+******
+
+`Fabric `_ is a library for simplifying system
+administration tasks. While Chef and Puppet tend to focus on managing servers
+and system libraries, Fabric is more focused on application level tasks such
+as deployment.
+
+Install Fabric:
+
+.. code-block:: console
+
+ $ pip install fabric
+
+The following code will create two tasks that we can use: ``memory_usage`` and
+``deploy``. The former will output the memory usage on each machine. The
+latter will SSH into each server, cd to our project directory, activate the
+virtual environment, pull the newest codebase, and restart the application
+server.
+
+.. code-block:: python
+
+ from fabric.api import cd, env, prefix, run, task
+
+ env.hosts = ['my_server1', 'my_server2']
+
+ @task
+ def memory_usage():
+ run('free -m')
+
+ @task
+ def deploy():
+ with cd('/var/www/project-env/project'):
+ with prefix('. ../bin/activate'):
+ run('git pull')
+ run('touch app.wsgi')
+
+With the previous code saved in a file named :file:`fabfile.py`, we can check
+memory usage with:
+
+.. code-block:: console
+
+ $ fab memory_usage
+ [my_server1] Executing task 'memory'
+ [my_server1] run: free -m
+ [my_server1] out: total used free shared buffers cached
+ [my_server1] out: Mem: 6964 1897 5067 0 166 222
+ [my_server1] out: -/+ buffers/cache: 1509 5455
+ [my_server1] out: Swap: 0 0 0
+
+ [my_server2] Executing task 'memory'
+ [my_server2] run: free -m
+ [my_server2] out: total used free shared buffers cached
+ [my_server2] out: Mem: 1666 902 764 0 180 572
+ [my_server2] out: -/+ buffers/cache: 148 1517
+ [my_server2] out: Swap: 895 1 894
+
+and we can deploy with:
+
+.. code-block:: console
+
+ $ fab deploy
+
+Additional features include parallel execution, interaction with remote
+programs, and host grouping.
+
+ `Fabric Documentation `_
+
+
+****
+Salt
+****
+
+`Salt `_ is an open source infrastructure management
+tool. It supports remote command execution from a central point (master host)
+to multiple hosts (minions). It also supports system states which can be used
+to configure multiple servers using simple template files.
+
+Salt supports Python versions 2.6 and 2.7 and can be installed via pip:
+
+.. code-block:: console
+
+ $ pip install salt
+
+After configuring a master server and any number of minion hosts, we can run
+arbitrary shell commands or use pre-built modules of complex commands on our
+minions.
+
+The following command lists all available minion hosts, using the ping module.
+
+.. code-block:: console
+
+ $ salt '*' test.ping
+
+The host filtering is accomplished by matching the minion id
+or using the grains system. The
+`grains `_
+system uses static host information like the operating system version or the
+CPU architecture to provide a host taxonomy for the Salt modules.
+
+The following command lists all available minions running CentOS using the
+grains system:
+
+.. code-block:: console
+
+ $ salt -G 'os:CentOS' test.ping
+
+Salt also provides a state system. States can be used to configure the minion
+hosts.
+
+For example, when a minion host is ordered to read the following state file,
+it will install and start the Apache server:
+
+.. code-block:: yaml
+
+ apache:
+ pkg:
+ - installed
+ service:
+ - running
+ - enable: True
+ - require:
+ - pkg: apache
+
+State files can be written using YAML, the Jinja2 template system, or pure Python.
+
+ `Salt Documentation `_
+
+
+******
+Psutil
+******
+
+`Psutil `_ is an interface to different
+system information (e.g. CPU, memory, disks, network, users, and processes).
+
+Here is an example to be aware of some server overload. If any of the
+tests (net, CPU) fail, it will send an email.
+
+.. code-block:: python
+
+ # Functions to get system values:
+ from psutil import cpu_percent, net_io_counters
+ # Functions to take a break:
+ from time import sleep
+ # Package for email services:
+ import smtplib
+ import string
+ MAX_NET_USAGE = 400000 # bytes per seconds
+ MAX_ATTACKS = 4
+ attack = 0
+ while attack <= MAX_ATTACKS:
+ sleep(4)
+
+ # Check the net usage wit named tuples
+ neti1 = net_io_counters().bytes_recv
+ neto1 = net_io_counters().bytes_sent
+ sleep(1)
+ neti2 = net_io_counters().bytes_recv
+ neto2 = net_io_counters().bytes_sent
+
+ # Calculate the bytes per second
+ net = ((neti2+neto2) - (neti1+neto1))/2
+
+ # Check the net and cpu usage
+ if (net > MAX_NET_USAGE) or (cpu_percent(interval = 1) > 70):
+ attack+=1
+ elif attack > 1:
+ attack-=1
+
+ # Write a very important email if attack is higher than 4
+ TO = "you@your_email.com"
+ FROM = "webmaster@your_domain.com"
+ SUBJECT = "Your domain is out of system resources!"
+ text = "Go and fix your server!"
+ string="\r\n"
+ BODY = string.join(("From: %s" %FROM,"To: %s" %TO,
+ "Subject: %s" %SUBJECT, "",text))
+ server = smtplib.SMTP('127.0.0.1')
+ server.sendmail(FROM, [TO], BODY)
+ server.quit()
+
+
+A full terminal application like a widely extended top is `Glance `_, which is based on psutil and has the ability for client-server monitoring.
+*******
+Ansible
+*******
+`Ansible `_ is an open source system automation tool.
+Its biggest advantage over Puppet or Chef is that it does not require an agent on
+the client machine. Playbooks are Ansible’s configuration, deployment, and
+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:
+
+.. code-block:: console
+
+ $ pip install ansible
+
+Ansible requires an inventory file that describes the hosts to which it has
+access. Below is an example of a host and playbook that will ping all the
+hosts in the inventory file.
+
+Here is an example inventory file:
+:file:`hosts.yml`
+
+.. code-block:: yaml
+
+ [server_name]
+ 127.0.0.1
+
+Here is an example playbook:
+:file:`ping.yml`
+
+.. code-block:: yaml
+
+ ---
+ - hosts: all
+
+ tasks:
+ - name: ping
+ action: ping
+
+To run the playbook:
+
+.. code-block:: console
+
+ $ ansible-playbook ping.yml -i hosts.yml --ask-pass
+
+The Ansible playbook will ping all of the servers in the :file:`hosts.yml` file.
+You can also select groups of servers using Ansible. For more information
+about Ansible, read the `Ansible Docs `_.
+
+`An Ansible tutorial `_ is also a
+great and detailed introduction to getting started with Ansible.
+
+
+****
Chef
-----
+****
+
+`Chef `_ is a systems and cloud infrastructure automation
+framework that makes it easy to deploy servers and applications to any physical,
+virtual, or cloud location. In case this is your choice for configuration management,
+you will primarily use Ruby to write your infrastructure code.
+
+Chef clients run on every server that is part of your infrastructure and these regularly
+check with your Chef server to ensure your system is always aligned and represents the
+desired state. Since each individual server has its own distinct Chef client, each server
+configures itself and this distributed approach makes Chef a scalable automation platform.
+
+Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically
+packages for infrastructure choices, are usually stored in your Chef server.
+Read the `DigitalOcean tutorial series
+`_
+on Chef to learn how to create a simple Chef Server.
+
+To create a simple cookbook the `knife `_ command is used:
+
+.. code-block:: console
+
+ knife cookbook create cookbook_name
+
+`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 infrastructure configuration needs can be
+found on the `Chef Supermarket `_.
+
+- `Chef Documentation `_
+******
Puppet
-------
+******
+`Puppet `_ is IT Automation and configuration management
+software from Puppet Labs that allows System Administrators to define the state
+of their IT Infrastructure, thereby providing an elegant way to manage their
+fleet of physical and virtual machines.
+Puppet is available both as an Open Source and an Enterprise variant. Modules
+are small, shareable units of code written to automate or define the state of a
+system. `Puppet Forge `_ is a repository for
+modules written by the community for Open Source and Enterprise Puppet.
+
+Puppet Agents are installed on nodes whose state needs to be monitored or
+changed. A designated server known as the Puppet Master is responsible for
+orchestrating the agent nodes.
+
+Agent nodes send basic facts about the system such as the operating system,
+kernel, architecture, IP address, hostname, etc. to the Puppet Master.
+The Puppet Master then compiles a catalog with information provided by the
+agents on how each node should be configured and sends it to the agent. The
+agent enforces the change as prescribed in the catalog and sends a report back
+to the Puppet Master.
+
+Facter is an interesting tool that ships with Puppet that pulls basic facts
+about the system. These facts can be referenced as a variable while writing
+your Puppet modules.
+
+.. code-block:: console
+
+ $ facter kernel
+ Linux
+.. code-block:: console
+
+ $ facter operatingsystem
+ Ubuntu
+
+Writing Modules in Puppet is pretty straight forward. Puppet Manifests together
+form Puppet Modules. Puppet manifests end with an extension of ``.pp``.
+Here is an example of 'Hello World' in Puppet.
+
+.. code-block:: puppet
+
+ notify { 'This message is getting logged into the agent node':
+
+ #As nothing is specified in the body the resource title
+ #the notification message by default.
+ }
+
+Here is another example with system based logic. Note how the operating system
+fact is being used as a variable prepended with the ``$`` sign. Similarly, this
+holds true for other facts such as hostname which can be referenced by
+``$hostname``.
+
+.. code-block:: puppet
+
+ notify{ 'Mac Warning':
+ message => $operatingsystem ? {
+ 'Darwin' => 'This seems to be a Mac.',
+ default => 'I am a PC.',
+ },
+ }
+
+There are several resource types for Puppet but the package-file-service
+paradigm is all you need for undertaking the majority of the configuration
+management. The following Puppet code makes sure that the OpenSSH-Server
+package is installed in a system and the sshd service is notified to restart
+every time the sshd configuration file is changed.
+
+.. code-block:: puppet
+
+ package { 'openssh-server':
+ ensure => installed,
+ }
+
+ file { '/etc/ssh/sshd_config':
+ source => 'puppet:///modules/sshd/sshd_config',
+ owner => 'root',
+ group => 'root',
+ mode => '640',
+ notify => Service['sshd'], # sshd will restart
+ # whenever you edit this
+ # file
+ require => Package['openssh-server'],
+
+ }
+
+ service { 'sshd':
+ ensure => running,
+ enable => true,
+ hasstatus => true,
+ hasrestart=> true,
+ }
+
+For more information, refer to the `Puppet Labs Documentation `_
+
+
+*********
Blueprint
----------
\ No newline at end of file
+*********
+
+.. todo:: Write about Blueprint
+
+
+********
+Buildout
+********
+
+`Buildout `_ is an open source software build tool.
+Buildout is created using the Python programming language. It implements a
+principle of separation of configuration from the scripts that do the setting
+up. 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.
diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
index cd3d5ddc9..4296679c7 100644
--- a/docs/scenarios/ci.rst
+++ b/docs/scenarios/ci.rst
@@ -1,27 +1,96 @@
+
+######################
Continuous Integration
-======================
+######################
+
+.. image:: /_static/photos/33907150594_9abba7ad0a_k_d.jpg
+.. note::
+ For advice on writing your tests, see :doc:`/writing/tests`.
+
+****
Why?
-----
+****
-Martin Fowler, who first wrote about Continuous Integration (short: CI) together with Kent Beck, describes the CI as follows:
+Martin Fowler, who first wrote about `Continuous Integration `_
+(short: CI) together with Kent Beck, describes CI as follows:
- Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage.
+ Continuous Integration is a software development practice where members of
+ a team integrate their work frequently, usually each person integrates at
+ least daily - leading to multiple integrations per day. Each integration is
+ verified by an automated build (including test) to detect integration errors
+ as quickly as possible. Many teams find that this approach leads to
+ significantly reduced integration problems and allows a team to develop
+ cohesive software more rapidly.
-Source: http://martinfowler.com/articles/continuousIntegration.html
+*******
Jenkins
--------
-
-Jenkins CI (http://jenkins-ci.org) is an extensible continuous integration engine. Use it.
+*******
+`Jenkins CI `_ is an extensible Continuous Integration engine. Use it.
+********
Buildbot
---------
-Buildbot (http://buildbot.net/buildbot/docs/current) is a Python system to automate the compile/test cycle to validate code changes.
+********
+
+`Buildbot `_ is a Python system to
+automate the compile/test cycle to validate code changes.
+
+
+***
+Tox
+***
+
+`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:
+
+* Checking that packages install correctly with different Python versions and
+ interpreters
+* Running tests in each of the environments, configuring your test tool of
+ choice
+* Acting as a front-end to Continuous Integration servers, reducing boilerplate
+ and merging CI and shell-based testing
+
+
+*********
+Travis-CI
+*********
+
+`Travis-CI `_ is a distributed CI server which builds
+tests for open source projects for free. It provides multiple workers to run
+Python tests on and seamlessly integrates with GitHub. You can even have it
+comment on your Pull Requests whether this particular changeset breaks the
+build or not. So, if you are hosting your code on GitHub, Travis-CI is a great
+and easy way to get started with Continuous Integration.
+
+In order to get started, add a :file:`.travis.yml` file to your repository with
+this example content::
+
+ language: python
+ python:
+ - "2.6"
+ - "2.7"
+ - "3.2"
+ - "3.3"
+ # command to install dependencies
+ script: python tests/test_all_of_the_units.py
+ branches:
+ only:
+ - master
+
+This will get your project tested on all the listed Python versions by
+running the given script, and will only build the ``master`` branch. There are a
+lot more options you can enable, like notifications, before and after steps,
+and much more. The `Travis-CI docs `_
+explain all of these options, and are very thorough.
-Mule?
------
+In order to activate testing for your project, go to `the Travis-CI site `_
+and login with your GitHub account. Then activate your project in your
+profile settings and you're ready to go. From now on, your project's tests
+will be run on every push to GitHub.
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 216ad6b78..59f311e83 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -1,8 +1,91 @@
-Command Line Applications
-=========================
+#########################
+Command-line Applications
+#########################
+.. image:: /_static/photos/34435690330_11930b5987_k_d.jpg
-Clint
------
+Command-line applications, also referred to as `Console Applications
+`_, are computer programs
+designed to be used from a text interface, such as a `shell
+`_. Command-line applications
+usually accept various inputs as arguments, often referred to as parameters or
+sub-commands, as well as options, often referred to as flags or switches.
+Some popular command-line applications include:
+
+* `grep `_ - A plain-text data search utility
+* `curl `_ - A tool for data transfer with URL syntax
+* `httpie `_ - A command-line HTTP
+ client, a user-friendly cURL replacement
+* `Git `_ - A distributed version control system
+* `Mercurial `_ - A distributed version control
+ system primarily written in Python
+
+
+*****
+Click
+*****
+
+`click `_ is a Python package for creating
+command-line interfaces in a composable way with as little code as possible.
+This “Command-Line Interface Creation Kit” is highly configurable but comes
+with good defaults out of the box.
+
+
+******
+docopt
+******
+
+`docopt `_ is a lightweight, highly Pythonic package that
+allows creating command-line interfaces easily and intuitively, by parsing
+POSIX-style usage instructions.
+
+
+****
+Plac
+****
+
+`Plac `_ is a simple wrapper
+over the Python standard library `argparse `_,
+which hides most of its complexity by using a declarative interface: the
+argument parser is inferred rather than written down imperatively. This
+module targets unsophisticated users, programmers, sysadmins,
+scientists, and in general people writing throw-away scripts for themselves,
+who choose to create a command-line interface because it is quick and simple.
+
+
+*****
+Cliff
+*****
+
+`Cliff `_ is a framework for
+building command-line programs. It uses setuptools entry points to provide
+subcommands, output formatters, and other extensions. The framework is meant
+to be used to create multi-level commands such as ``svn`` 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 its use
+cases span from the simplicity of a micro-framework to the complexity of a
+mega-framework.
+
+
+***********
+Python Fire
+***********
+
+`Python Fire `_ is a library for
+automatically generating command-line interfaces from absolutely any Python
+object. It can help debug Python code more easily from the command line,
+create CLI interfaces to existing code, allow you to interactively explore
+code in a REPL, and simplify transitioning between Python and Bash (or any
+other shell).
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
new file mode 100644
index 000000000..13c9e4802
--- /dev/null
+++ b/docs/scenarios/clibs.rst
@@ -0,0 +1,141 @@
+
+################################
+Interfacing with C/C++ Libraries
+################################
+
+.. image:: /_static/photos/34725951345_c8f5959a2e_k_d.jpg
+
+
+****************************
+C Foreign Function Interface
+****************************
+
+`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
+exposing the same functionality as `LoadLibrary `_ or `dlopen `_), and an API mode,
+which allows you to build C extension modules.
+
+ABI Interaction
+~~~~~~~~~~~~~~~
+
+.. code-block:: python
+ :linenos:
+
+ from cffi import FFI
+ ffi = FFI()
+ ffi.cdef("size_t strlen(const char*);")
+ clib = ffi.dlopen(None)
+ length = clib.strlen("String to be evaluated.")
+ # prints: 23
+ print("{}".format(length))
+
+
+******
+ctypes
+******
+
+`ctypes `_ is the de facto standard
+library for interfacing with C/C++ from CPython, and it provides not only
+full access to the native C interface of most major operating systems (e.g.,
+kernel32 on Windows, or libc on \*nix), but also provides support for loading
+and interfacing with dynamic libraries, such as DLLs or shared objects, at
+runtime. It brings along with it a whole host of types for interacting
+with system APIs, and allows you to rather easily define your own complex
+types, such as structs and unions, and allows you to modify things such as
+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 usable by a pure C/C++ method.
+
+Struct Equivalents
+~~~~~~~~~~~~~~~~~~
+
+:file:`MyStruct.h`
+
+.. code-block:: c
+ :linenos:
+
+ struct my_struct {
+ int a;
+ int b;
+ };
+
+:file:`MyStruct.py`
+
+.. code-block:: python
+ :linenos:
+
+ import ctypes
+ class my_struct(ctypes.Structure):
+ _fields_ = [("a", c_int),
+ ("b", c_int)]
+
+
+****
+SWIG
+****
+
+`SWIG `_, though not strictly Python focused (it supports a
+large number of scripting languages), is a tool for generating bindings for
+interpreted languages from C/C++ header files. It is extremely simple to use:
+the consumer simply needs to define an interface file (detailed in the
+tutorial and documentations), include the requisite C/C++ headers, and run
+the build tool against them. While it does have some limits (it currently
+seems to have issues with a small subset of newer C++ features, and getting
+template-heavy code to work can be a bit verbose), it provides a great deal
+of power and exposes lots of features to Python with little effort.
+Additionally, you can easily extend the bindings SWIG creates (in the
+interface file) to overload operators and built-in methods, effectively re-
+cast C++ exceptions to be catchable by Python, etc.
+
+Example: Overloading __repr__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:file:`MyClass.h`
+
+.. code-block:: c++
+ :linenos:
+
+ #include
+ class MyClass {
+ private:
+ std::string name;
+ public:
+ std::string getName();
+ };
+
+
+:file:`myclass.i`
+
+.. code-block:: idl
+ :linenos:
+
+ %include "string.i"
+
+ %module myclass
+ %{
+ #include
+ #include "MyClass.h"
+ %}
+
+ %extend MyClass {
+ std::string __repr__()
+ {
+ return $self->getName();
+ }
+ }
+
+ %include "MyClass.h"
+
+
+************
+Boost.Python
+************
+
+`Boost.Python `_
+requires a bit more manual work to expose C++ object functionality, but
+it is capable of providing all the same features SWIG does and then some,
+to include providing wrappers to access PyObjects in C++, extracting SWIG
+wrapper objects, and even embedding bits of Python into your C++ code.
diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst
new file mode 100644
index 000000000..c2d5c289b
--- /dev/null
+++ b/docs/scenarios/client.rst
@@ -0,0 +1,60 @@
+
+####################
+Network Applications
+####################
+
+.. image:: /_static/photos/34364815780_bea6614025_k_d.jpg
+
+
+****
+HTTP
+****
+
+The Hypertext Transfer Protocol (HTTP) is an application protocol for
+distributed, collaborative, hypermedia information systems. HTTP is the
+foundation of data communication for the World Wide Web.
+
+Requests
+--------
+
+Python’s standard urllib2 module provides most of the HTTP capabilities you
+need, but the API is thoroughly broken. It was built for a different time —
+and a different web. It requires an enormous amount of work (even method
+overrides) to perform the simplest of tasks.
+
+Requests takes all of the work out of Python HTTP — making your integration
+with web services seamless. There’s no need to manually add query strings to
+your URLs, or to form-encode your POST data. Keep-alive and HTTP connection
+pooling are 100% automatic, powered by urllib3, which is embedded within
+Requests.
+
+- `Documentation `_
+- `PyPi `_
+- `GitHub `_
+
+
+*******************
+Distributed Systems
+*******************
+
+
+ZeroMQ
+------
+
+ØMQ (also spelled ZeroMQ, 0MQ or ZMQ) is a high-performance asynchronous
+messaging library aimed at use in scalable distributed or concurrent
+applications. It provides a message queue, but unlike message-oriented
+middleware, a ØMQ system can run without a dedicated message broker. The
+library is designed to have a familiar socket-style API.
+
+RabbitMQ
+--------
+
+RabbitMQ is an open source message broker software that implements the Advanced
+Message Queuing Protocol (AMQP). The RabbitMQ server is written in the Erlang
+programming language and is built on the Open Telecom Platform framework for
+clustering and failover. Client libraries to interface with the broker are
+available for all major programming languages.
+
+- `Homepage `_
+- `GitHub Organization `_
diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst
new file mode 100644
index 000000000..262337204
--- /dev/null
+++ b/docs/scenarios/crypto.rst
@@ -0,0 +1,91 @@
+
+############
+Cryptography
+############
+
+.. image:: /_static/photos/33907152824_bf91078cc1_k_d.jpg
+
+
+************
+cryptography
+************
+
+`cryptography `_ is an actively developed
+library that provides cryptographic recipes and primitives. It supports
+Python 2.6-2.7, Python 3.3+, and PyPy.
+
+
+cryptography is divided into two layers of recipes and hazardous materials
+(hazmat). The recipes layer provides a simple API for proper symmetric
+encryption and the hazmat layer provides low-level cryptographic primitives.
+
+
+
+Installation
+~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ pip install cryptography
+
+Example
+~~~~~~~
+
+Example code using high level symmetric encryption recipe:
+
+.. code-block:: python
+
+ from cryptography.fernet import Fernet
+ key = Fernet.generate_key()
+ cipher_suite = Fernet(key)
+ cipher_text = cipher_suite.encrypt(b"A really secret message. Not for prying eyes.")
+ plain_text = cipher_suite.decrypt(cipher_text)
+
+
+**************
+GPGME bindings
+**************
+
+The `GPGME Python bindings `_ provide Pythonic access to `GPG Made Easy `_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt, and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4, and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.
+
+
+A more comprehensive `GPGME Python Bindings HOWTO `_ is available with the source, and an HTML version is available `at http://files.au.adversary.org `_. Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `at gnupg.org `_.
+
+Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause.
+
+Installation
+~~~~~~~~~~~~
+
+Included by default when compiling GPGME if the configure script locates a supported python version (which it will if it's in $PATH during configuration).
+
+Example
+~~~~~~~
+
+.. code-block:: python3
+
+ import gpg
+
+ # Encryption to public key specified in rkey.
+ a_key = input("Enter the fingerprint or key ID to encrypt to: ")
+ filename = input("Enter the filename to encrypt: ")
+ with open(filename, "rb") as afile:
+ text = afile.read()
+ c = gpg.core.Context(armor=True)
+ rkey = list(c.keylist(pattern=a_key, secret=False))
+ ciphertext, result, sign_result = c.encrypt(text, recipients=rkey,
+ always_trust=True,
+ add_encrypt_to=True)
+ with open("{0}.asc".format(filename), "wb") as bfile:
+ bfile.write(ciphertext)
+ # Decryption with corresponding secret key
+ # invokes gpg-agent and pinentry.
+ with open("{0}.asc".format(filename), "rb") as cfile:
+ plaintext, result, verify_result = gpg.Context().decrypt(cfile)
+ with open("new-{0}".format(filename), "wb") as dfile:
+ dfile.write(plaintext)
+ # Matching the data.
+ # Also running a diff on filename and the new filename should match.
+ if text == plaintext:
+ print("Hang on ... did you say *all* of GnuPG? Yep.")
+ else:
+ pass
diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst
index ad04d04cc..21217477a 100644
--- a/docs/scenarios/db.rst
+++ b/docs/scenarios/db.rst
@@ -1,24 +1,118 @@
+
+#########
Databases
-=========
+#########
+
+.. image:: /_static/photos/33907152464_a99fdcc8de_k_d.jpg
+
+******
DB-API
-------
+******
The Python Database API (DB-API) defines a standard interface for Python
-database access modules. It's documented in `PEP 249 `_.
-Nearly all Python database modules such as `sqlite3`, `psycopg` and
+database access modules. It's documented in :pep:`249`.
+Nearly all Python database modules such as `sqlite3`, `psycopg`, and
`mysql-python` conform to this interface.
+Tutorials that explain how to work with modules that conform to this interface can be found
+`here `__ and
+`here `__.
+**********
SQLAlchemy
-----------
+**********
+
+`SQLAlchemy `_ is a commonly used database toolkit.
+Unlike many database libraries it not only provides an ORM layer but also a
+generalized API for writing database-agnostic code without SQL.
+
+.. code-block:: console
+
+ $ pip install sqlalchemy
+
+
+*******
+Records
+*******
+
+`Records `_ is minimalist SQL library,
+designed for sending raw SQL queries to various databases. Data can be used
+programmatically or exported to a number of useful data formats.
+
+.. code-block:: console
+
+ $ pip install records
+
+Also included is a command-line tool for exporting SQL data.
+
+
+******
+PugSQL
+******
+
+`PugSQL `_ is a simple Python interface for organizing
+and using parameterized, handwritten SQL. It is an anti-ORM that is
+philosophically lo-fi, but it still presents a clean interface in Python.
+
+.. code-block:: console
+
+ $ pip install pugsql
+
+
+**********
+Django ORM
+**********
+
+The Django ORM is the interface used by `Django `_
+to provide database access.
+
+It's based on the idea of
+`models `_,
+an abstraction that makes it easier to manipulate data in Python.
+
+The basics:
+
+- Each model is a Python class that subclasses django.db.models.Model.
+- Each attribute of the model represents a database field.
+- Django gives you an automatically-generated database-access API; see
+ `Making queries `__.
+
+
+******
+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 PostgreSQL by default. The
+`model layer `_
+is similar to that of the Django ORM and it has
+`SQL-like methods `_
+to query data. While SQLite, MySQL, and PostgreSQL are supported out-of-the-box,
+there is a `collection of add-ons `_
+available.
+
+
+*******
+PonyORM
+*******
+
+`PonyORM `_ is an ORM that takes a different approach to
+querying the database. Instead of writing an SQL-like language or boolean
+expressions, Python's generator syntax is used. There's also a graphical
+schema editor that can generate PonyORM entities for you. It supports Python
+2.6+ and Python 3.3+ and can connect to SQLite, MySQL, PostgreSQL, and Oracle.
-`SQLAlchemy `_ is a commonly used database toolkit. Unlike many database libraries
-it not only provides an ORM layer but also a generalized API for writing
-database-agnostic code without SQL.
-::
+*********
+SQLObject
+*********
- pip install sqlalchemy
+`SQLObject `_ is yet another ORM. It supports a wide
+variety of databases: common database systems like MySQL, PostgreSQL, and SQLite and
+more exotic systems like SAP DB, SyBase, and Microsoft SQL Server. It only supports Python 2
+from Python 2.6 upwards.
+.. There's no official information on this on their page; this information was gathered by looking at their source code.
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index de4e47d51..3ad0af364 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -1,36 +1,185 @@
+
+################
GUI Applications
-================
+################
+.. image:: /_static/photos/33907143624_cd621b535c_k_d.jpg
-Qt
-::
-Qt is a cross-platform application framework that is widely used for developing software with a GUI but can also be used for non-GUI applications.
+Alphabetical list of GUI Applications.
+
+
+*******
+Camelot
+*******
+
+`Camelot `_ provides components for building
+applications on top of Python, SQLAlchemy, and Qt. It is inspired by the Django
+admin interface.
+
+The main resource for information is the website:
+http://www.python-camelot.com
+and the mailing list https://groups.google.com/forum/#!forum/project-camelot.
+
+
+*****
+Cocoa
+*****
+
+.. note:: The Cocoa framework is only available on OS X. Don't pick this if you're writing a cross-platform application!
+
+
+***
+GTk
+***
+
+.. note:: PyGTK provides Python bindings for the GTK+ toolkit. However, it has been superseded by PyGObject. PyGTK should not be used for new projects and existing projects should be ported 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 `_.
+
+`API Reference `_
+
+
+****
+Kivy
+****
+
+`Kivy `_ is a Python library for development of multi-touch
+enabled media rich applications. The aim is to allow for quick and easy
+interaction design and rapid prototyping, while making your code reusable and
+deployable.
+
+Kivy is written in Python, based on OpenGL, and supports different input devices
+such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products,
+and so on.
+
+Kivy is actively being developed by a community and is free to use. It operates
+on all major platforms (Linux, OS X, Windows, Android).
+
+The main resource for information is the website: http://kivy.org
+
+
+******
+PyObjC
+******
+
+.. note:: Only available on OS X. Don't pick this if you're writing a cross-platform application.
+
+
+******
PySide
-------
-http://developer.qt.nokia.com/wiki/PySideDownloads/
+******
+
+PySide is a Python binding of the cross-platform GUI toolkit Qt.
+The package name depends on the major Qt version (`PySide` for Qt4,
+`PySide2` for Qt5, and `PySide6` for Qt6).
+This set of bindings is developed by `The Qt Company `_.
+
+.. code-block:: console
+ $ pip install pyside6
+
+https://pyside.org
+
+
+****
PyQt
-----
-*Note: If your software does not fully comply with the GPL you will need a commercial license!*
+****
+
+.. note:: If your software does not fully comply with the GPL you will need a commercial license!
+
+PyQt provides Python bindings for the Qt Framework (see below).
+
http://www.riverbankcomputing.co.uk/software/pyqt/download
-Cocoa
-:::::
-*Note: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!*
-PyObjC
-------
-*Note: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.*
+***************************************
+Pyjs Desktop (formerly Pyjamas Desktop)
+***************************************
+
+Pyjs Desktop is a application widget set for desktop and a cross-platform
+framework. It allows the exact same Python web application source code to be
+executed as a standalone desktop application.
+
+
+The main website: `pyjs `_.
+
+
+**
+Qt
+**
+
+`Qt `_ is a cross-platform application framework that is
+widely used for developing software with a GUI but can also be used for non-GUI
+applications.
+
+
+***********
+PySimpleGUI
+***********
+
+`PySimpleGUI `_ is a wrapper for Tkinter
+and Qt (others on the way). The amount of code required to implement custom
+GUIs is much shorter using PySimpleGUI than if the same GUI were written
+directly using Tkinter or Qt. PySimpleGUI code can be "ported" between GUI
+frameworks by changing import statements.
+
+.. code-block:: console
+
+ $ pip install pysimplegui
+
+PySimpleGUI is contained in a single PySimpleGUI.py file. Should pip
+installation be impossible, copying the PySimpleGUI.py file into a project's
+folder is all that's required to import and begin using.
+
+
+****
+Toga
+****
+
+`Toga `_ is a Python native, OS native,
+cross platform GUI toolkit. Toga consists of a library of base components with a
+shared interface to simplify platform-agnostic GUI development.
+
+Toga is available on macOS, Windows, Linux (GTK), and mobile platforms such as
+Android and iOS.
+
+
+**
+Tk
+**
+
+Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
+of being included with the Python standard library, making it the most
+convenient and compatible toolkit to program with.**
+
+Both Tk and Tkinter are available on most Unix platforms, as well as on Windows
+and Macintosh systems. Starting with the 8.0 release, Tk offers native look and
+feel on all platforms.
+
+There's a good multi-language Tk tutorial with Python examples at `TkDocs
+`_. There's more information
+available on the `Python Wiki `_.
+
-WXPython
-::::::::
-Install (Stable)
-----
-*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.*
+********
+wxPython
+********
-Gtk
-:::
+wxPython is a GUI toolkit for the Python programming language. It allows Python
+programmers to create programs with a robust, highly functional graphical user
+interface, simply and easily. It is implemented as a Python extension module
+(native code) that wraps the popular wxWidgets cross platform GUI library, which
+is written in C++.
-tk
-::
\ No newline at end of file
+**Install (Stable) wxPython**
+*go to https://www.wxpython.org/pages/downloads/ and download the appropriate
+package for your OS.*
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
new file mode 100644
index 000000000..8fe7e08fe
--- /dev/null
+++ b/docs/scenarios/imaging.rst
@@ -0,0 +1,112 @@
+
+##################
+Image Manipulation
+##################
+
+.. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg
+
+Most image processing and manipulation techniques can be carried out
+effectively using two libraries: Python Imaging Library (PIL) and Open Source
+Computer Vision (OpenCV).
+
+A brief description of both is given below.
+
+
+**********************
+Python Imaging Library
+**********************
+
+The `Python Imaging Library `_, or PIL
+for short, is one of the core libraries for image manipulation in Python. Unfortunately,
+its development has stagnated, with its last release in 2009.
+
+Luckily for you, there's an actively-developed fork of PIL called
+`Pillow `_ -- it's easier to install, runs on
+all major operating systems, and supports Python 3.
+
+Installation
+~~~~~~~~~~~~
+
+Before installing Pillow, you'll have to install Pillow's prerequisites. Find
+the instructions for your platform in the
+`Pillow installation instructions `_.
+
+After that, it's straightforward:
+
+.. code-block:: console
+
+ $ pip install Pillow
+
+Example
+~~~~~~~
+
+.. code-block:: python
+
+ from PIL import Image, ImageFilter
+ #Read image
+ im = Image.open( 'image.jpg' )
+ #Display image
+ im.show()
+
+ #Applying a filter to the image
+ im_sharp = im.filter( ImageFilter.SHARPEN )
+ #Saving the filtered image to a new file
+ im_sharp.save( 'image_sharpened.jpg', 'JPEG' )
+
+ #Splitting the image into its respective bands, i.e. Red, Green,
+ #and Blue for RGB
+ r,g,b = im_sharp.split()
+
+ #Viewing EXIF data embedded in image
+ exif_data = im._getexif()
+ exif_data
+
+There are more examples of the Pillow library in the
+`Pillow tutorial `_.
+
+
+***************************
+Open Source Computer Vision
+***************************
+
+Open Source Computer Vision, more commonly known as OpenCV, is a more advanced
+image manipulation and processing software than PIL. It has been implemented
+in several languages and is widely used.
+
+Installation
+~~~~~~~~~~~~
+
+In Python, image processing using OpenCV is implemented using the ``cv2`` and
+``NumPy`` modules. The `installation instructions for OpenCV
+`_
+should guide you through configuring the project for yourself.
+
+NumPy can be downloaded from the Python Package Index(PyPI):
+
+.. code-block:: console
+
+ $ pip install numpy
+
+
+Example
+~~~~~~~
+
+.. code-block:: python
+
+ import cv2
+ #Read Image
+ img = cv2.imread('testimg.jpg')
+ #Display Image
+ cv2.imshow('image',img)
+ cv2.waitKey(0)
+ cv2.destroyAllWindows()
+
+ #Applying Grayscale filter to image
+ gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+ #Saving filtered image to new file
+ cv2.imwrite('graytest.jpg',gray)
+
+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
new file mode 100644
index 000000000..1c3663777
--- /dev/null
+++ b/docs/scenarios/json.rst
@@ -0,0 +1,48 @@
+
+####
+JSON
+####
+
+.. image:: /_static/photos/33928819683_97b5c6a184_k_d.jpg
+
+The `json `_ library can parse
+JSON from strings or files. The library parses JSON into a Python dictionary
+or list. It can also convert Python dictionaries or lists into JSON strings.
+
+
+************
+Parsing JSON
+************
+
+Take the following string containing JSON data:
+
+.. code-block:: python
+
+ json_string = '{"first_name": "Guido", "last_name":"Rossum"}'
+
+It can be parsed like this:
+
+.. code-block:: python
+
+ import json
+ parsed_json = json.loads(json_string)
+
+and can now be used as a normal dictionary:
+
+.. code-block:: python
+
+ print(parsed_json['first_name'])
+ "Guido"
+
+You can also convert the following to JSON:
+
+.. code-block:: python
+
+ d = {
+ 'first_name': 'Guido',
+ 'second_name': 'Rossum',
+ 'titles': ['BDFL', 'Developer'],
+ }
+
+ print(json.dumps(d))
+ '{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'
diff --git a/docs/scenarios/ml.rst b/docs/scenarios/ml.rst
new file mode 100644
index 000000000..b3655c819
--- /dev/null
+++ b/docs/scenarios/ml.rst
@@ -0,0 +1,125 @@
+
+
+################
+Machine Learning
+################
+
+.. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg
+
+Python has a vast number of libraries for data analysis, statistics, and Machine Learning itself, making it a language of choice for many data scientists.
+
+Some widely used packages for Machine Learning and other data science applications are listed 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 ease of, 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 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 `_.
diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst
new file mode 100644
index 000000000..bb751b78e
--- /dev/null
+++ b/docs/scenarios/network.rst
@@ -0,0 +1,46 @@
+
+##########
+Networking
+##########
+
+.. image:: /_static/photos/34151833832_6bdfd930af_k_d.jpg
+
+
+*******
+Twisted
+*******
+
+`Twisted `_ is an event-driven networking
+engine. It can be used to build applications around many different networking
+protocols, including HTTP servers and clients, applications using SMTP, POP3,
+IMAP, or SSH protocols, instant messaging,
+and `much more `_.
+
+
+*****
+PyZMQ
+*****
+
+`PyZMQ `_ is the Python binding for
+`ZeroMQ `_, which is a high-performance asynchronous
+messaging library. One great advantage of ZeroMQ is that it can be used for
+message queuing without a message broker. The basic patterns for this are:
+
+- request-reply: connects a set of clients to a set of services. This is a
+ remote procedure call and task distribution pattern.
+- publish-subscribe: connects a set of publishers to a set of subscribers.
+ This is a data distribution pattern.
+- push-pull (or pipeline): connects nodes in a fan-out/fan-in pattern that
+ can have multiple steps and loops. This is a parallel task distribution
+ and collection pattern.
+
+For a quick start, read the `ZeroMQ guide `_.
+
+
+******
+gevent
+******
+
+`gevent `_ is a coroutine-based Python networking
+library that uses greenlets to provide a high-level synchronous API on top of
+the libev event loop.
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
new file mode 100644
index 000000000..bb0547323
--- /dev/null
+++ b/docs/scenarios/scientific.rst
@@ -0,0 +1,166 @@
+
+#######################
+Scientific Applications
+#######################
+
+.. image:: /_static/photos/33925223870_97e44f5629_k_d.jpg
+
+
+*******
+Context
+*******
+
+Python is frequently used for high-performance scientific applications. It
+is widely used in academia and scientific projects because it is easy to write
+and performs well.
+
+Due to its high performance nature, scientific computing in Python often
+utilizes external libraries, typically written in faster languages (like C, or
+Fortran for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
+and `Matplotlib`_. Going into detail about these libraries is beyond the scope
+of the Python guide. However, a comprehensive introduction to the scientific
+Python ecosystem can be found in the `Python Scientific Lecture Notes
+`_.
+
+
+*****
+Tools
+*****
+
+IPython
+-------
+
+`IPython `_ is an enhanced version of Python interpreter,
+which provides features of great interest to scientists. The `inline mode`
+allows graphics and plots to be displayed in the terminal (Qt based version).
+Moreover, the `notebook` mode supports literate programming and reproducible
+science generating a web-based Python notebook. This notebook allows you to
+store chunks of Python code alongside the results and additional comments
+(HTML, LaTeX, Markdown). The notebook can then be shared and exported in various
+file formats.
+
+
+*********
+Libraries
+*********
+
+NumPy
+-----
+
+`NumPy `_ is a low level library written in C (and
+Fortran) for high level mathematical functions. NumPy cleverly overcomes the
+problem of running slower algorithms on Python by using multidimensional arrays
+and functions that operate on arrays. Any algorithm can then be expressed as a
+function on arrays, allowing the algorithms to be run quickly.
+
+NumPy is part of the SciPy project, and is released as a separate library so
+people who only need the basic requirements can use it without installing the
+rest of SciPy.
+
+NumPy is compatible with Python versions 2.4 through 2.7.2 and 3.1+.
+
+Numba
+-----
+
+`Numba `_ is a NumPy aware Python compiler
+(just-in-time (JIT) specializing compiler) which compiles annotated Python (and
+NumPy) code to LLVM (Low Level Virtual Machine) through special decorators.
+Briefly, Numba uses a system that compiles Python code with LLVM to code which
+can be natively executed at runtime.
+
+SciPy
+-----
+
+`SciPy `_ is a library that uses NumPy for more mathematical
+functions. SciPy uses NumPy arrays as the basic data structure, and comes
+with modules for various commonly used tasks in scientific programming,
+including linear algebra, integration (calculus), ordinary differential equation
+solving, and signal processing.
+
+Matplotlib
+----------
+
+`Matplotlib `_ is a flexible plotting
+library for creating interactive 2D and 3D plots that can also be saved as
+manuscript-quality figures. The API in many ways reflects that of `MATLAB
+`_, easing transition of MATLAB
+users to Python. Many examples, along with the source code to recreate them,
+are available in the `matplotlib gallery
+`_.
+
+Pandas
+------
+
+`Pandas `_ is a data manipulation library
+based on NumPy which provides many useful functions for accessing,
+indexing, merging, and grouping data easily. The main data structure (DataFrame)
+is close to what could be found in the R statistical package; that is,
+heterogeneous data tables with name indexing, time series operations, and
+auto-alignment of data.
+
+xarray
+------
+
+`xarray `_ is similar to Pandas, but it
+is intended for wrapping multidimensional scientific data. By labelling the
+data with dimensions, coordinates, and attributes, it makes complex
+multidimensional operations clearer and more intuitive. It also wraps
+matplotlib for quick plotting, and can apply most operations in parallel using
+`dask `_.
+
+
+Rpy2
+----
+
+`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 `_
+bindings.
+
+PsychoPy
+--------
+
+`PsychoPy `_ is a library for cognitive scientists
+allowing the creation of cognitive psychology and neuroscience experiments.
+The library handles presentation of stimuli, scripting of experimental design,
+and data collection.
+
+
+*********
+Resources
+*********
+
+Installation of scientific Python packages can be troublesome, as many of
+these packages are implemented as Python C extensions which need to be compiled.
+This section lists various so-called scientific Python distributions which
+provide precompiled and easy-to-install collections of scientific Python
+packages.
+
+Unofficial Windows Binaries for Python Extension Packages
+---------------------------------------------------------
+
+Many people who do scientific computing are on Windows, yet many of the
+scientific computing packages are notoriously difficult to build and install on
+this platform. `Christoph Gohlke `_,
+however, has compiled a list of Windows binaries for many useful Python
+packages. The list of packages has grown from a mainly scientific Python
+resource to a more general list. If you're on Windows, you may want to check it
+out.
+
+Anaconda
+--------
+
+The `Anaconda Python Distribution `_
+includes all the common scientific Python packages as well as many packages
+related to data analytics and big data. Anaconda itself is free, and a number
+of proprietary add-ons are available for a fee. Free licenses for the
+add-ons are available for academics and researchers.
+
+Canopy
+------
+
+`Canopy `_ is another scientific
+Python distribution, produced by `Enthought `_.
+A limited 'Canopy Express' variant is available for free, but Enthought
+charges for the full distribution. Free licenses are available for academics.
diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst
new file mode 100644
index 000000000..527719200
--- /dev/null
+++ b/docs/scenarios/scrape.rst
@@ -0,0 +1,113 @@
+
+#############
+HTML Scraping
+#############
+
+.. image:: /_static/photos/34268661876_442428e122_k_d.jpg
+
+
+************
+Web Scraping
+************
+
+Web sites are written using HTML, which means that each web page is a
+structured document. Sometimes it would be great to obtain some data from
+them and preserve the structure while we're at it. Web sites don't always
+provide their data in comfortable formats such as CSV or JSON.
+
+This is where web scraping comes in. Web scraping is the practice of using a
+computer program to sift through a web page and gather the data that you need
+in a format most useful to you while at the same time preserving the structure
+of the data.
+
+
+*****************
+lxml and Requests
+*****************
+
+`lxml `_ is a pretty extensive library written for parsing
+XML and HTML documents very quickly, even handling messed up tags in the
+process. We will also be using the
+`Requests `_ module instead of the
+already built-in urllib2 module due to improvements in speed and readability.
+You can easily install both using ``pip install lxml`` and
+``pip install requests``.
+
+Let's start with the imports:
+
+.. code-block:: python
+
+ from lxml import html
+ import requests
+
+Next we will use ``requests.get`` to retrieve the web page with our data,
+parse it using the ``html`` module, and save the results in ``tree``:
+
+.. code-block:: python
+
+ page = requests.get('http://econpy.pythonanywhere.com/ex/001.html')
+ tree = html.fromstring(page.content)
+
+(We need to use ``page.content`` rather than ``page.text`` because
+``html.fromstring`` implicitly expects ``bytes`` as input.)
+
+``tree`` now contains the whole HTML file in a nice tree structure which
+we can go over two different ways: XPath and CSSSelect. In this example, we
+will focus on the former.
+
+XPath is a way of locating information in structured documents such as
+HTML or XML documents. A good introduction to XPath is on
+`W3Schools `_ .
+
+There are also various tools for obtaining the XPath of elements such as
+FireBug for Firefox or the Chrome Inspector. If you're using Chrome, you
+can right click an element, choose 'Inspect element', highlight the code,
+right click again, and choose 'Copy XPath'.
+
+After a quick analysis, we see that in our page the data is contained in
+two elements -- one is a div with title 'buyer-name' and the other is a
+span with class 'item-price':
+
+.. code-block:: html
+
+
Carson Busses
+ $29.95
+
+Knowing this we can create the correct XPath query and use the lxml
+``xpath`` function like this:
+
+.. code-block:: python
+
+ #This will create a list of buyers:
+ buyers = tree.xpath('//div[@title="buyer-name"]/text()')
+ #This will create a list of prices
+ prices = tree.xpath('//span[@class="item-price"]/text()')
+
+Let's see what we got exactly:
+
+.. code-block:: python
+
+ print('Buyers: ', buyers)
+ print('Prices: ', prices)
+
+::
+
+ Buyers: ['Carson Busses', 'Earl E. Byrd', 'Patty Cakes',
+ 'Derri Anne Connecticut', 'Moe Dess', 'Leda Doggslife', 'Dan Druff',
+ 'Al Fresco', 'Ido Hoe', 'Howie Kisses', 'Len Lease', 'Phil Meup',
+ 'Ira Pent', 'Ben D. Rules', 'Ave Sectomy', 'Gary Shattire',
+ 'Bobbi Soks', 'Sheila Takya', 'Rose Tattoo', 'Moe Tell']
+
+ Prices: ['$29.95', '$8.37', '$15.26', '$19.25', '$19.25',
+ '$13.99', '$31.57', '$8.49', '$14.47', '$15.86', '$11.11',
+ '$15.98', '$16.27', '$7.50', '$50.85', '$14.26', '$5.68',
+ '$15.00', '$114.07', '$10.09']
+
+Congratulations! We have successfully scraped all the data we wanted from
+a web page using lxml and Requests. We have it stored in memory as two
+lists. Now we can do all sorts of cool stuff with it: we can analyze it
+using Python or we can save it to a file and share it with the world.
+
+Some more cool ideas to think about are modifying this script to iterate
+through the rest of the pages of this example dataset, or rewriting this
+application to use threads for improved speed.
diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst
new file mode 100644
index 000000000..3edc6aaa2
--- /dev/null
+++ b/docs/scenarios/serialization.rst
@@ -0,0 +1,237 @@
+
+##################
+Data Serialization
+##################
+
+.. image:: /_static/photos/33467946364_3e59bd376a_k_d.jpg
+
+
+***************************
+What is data serialization?
+***************************
+
+Data serialization is the process of converting structured data to a format
+that allows sharing or storage of the data in a form that allows recovery of its original
+structure. In some cases, the secondary intention of data
+serialization is to minimize the data's size which then
+reduces disk space or bandwidth requirements.
+
+********************
+Flat vs. Nested data
+********************
+
+Before beginning to serialize data, it is important to identify or decide how the
+data should be structured during data serialization - flat or nested.
+The differences in the two styles are shown in the below examples.
+
+Flat style:
+
+.. code-block:: python
+
+ { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" }
+
+
+Nested style:
+
+.. code-block:: python
+
+ {"A"
+ { "field1": "value1", "field2": "value2", "field3": "value3" } }
+
+
+For more reading on the two styles, please see the discussion on
+`Python mailing list `__,
+`IETF mailing list `__ and
+`in stackexchange `__.
+
+****************
+Serializing Text
+****************
+
+=======================
+Simple file (flat data)
+=======================
+
+If the data to be serialized is located in a file and contains flat data, Python offers two methods to serialize data.
+
+repr
+----
+
+The repr method in Python takes a single object parameter and returns a printable representation of the input:
+
+.. code-block:: python
+
+ # input as flat text
+ a = { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" }
+
+ # the same input can also be read from a file
+ a = open('/tmp/file.py', 'r')
+
+ # returns a printable representation of the input;
+ # the output can be written to a file as well
+ print(repr(a))
+
+ # write content to files using repr
+ with open('/tmp/file.py') as f:f.write(repr(a))
+
+
+ast.literal_eval
+----------------
+
+The literal_eval method safely parses and evaluates an expression for a Python datatype.
+Supported data types are: strings, numbers, tuples, lists, dicts, booleans, and None.
+
+.. code-block:: python
+
+ with open('/tmp/file.py', 'r') as f: inp = ast.literal_eval(f.read())
+
+====================
+CSV file (flat data)
+====================
+
+The CSV module in Python implements classes to read and write tabular
+data in CSV format.
+
+Simple example for reading:
+
+.. code-block:: python
+
+ # Reading CSV content from a file
+ import csv
+ with open('/tmp/file.csv', newline='') as f:
+ reader = csv.reader(f)
+ for row in reader:
+ print(row)
+
+Simple example for writing:
+
+.. code-block:: python
+
+ # Writing CSV content to a file
+ import csv
+ with open('/temp/file.csv', 'w', newline='') as f:
+ writer = csv.writer(f)
+ writer.writerows(iterable)
+
+
+The module's contents, functions, and examples can be found
+`in the Python documentation `__.
+
+==================
+YAML (nested data)
+==================
+
+There are many third party modules to parse and read/write YAML file
+structures in Python. One such example is below.
+
+.. code-block:: python
+
+ # Reading YAML content from a file using the load method
+ import yaml
+ with open('/tmp/file.yaml', 'r', newline='') as f:
+ try:
+ print(yaml.load(f))
+ except yaml.YAMLError as ymlexcp:
+ print(ymlexcp)
+
+Documentation on the third party module can be found
+`in the PyYAML Documentation `__.
+
+=======================
+JSON file (nested data)
+=======================
+
+Python's JSON module can be used to read and write JSON files.
+Example code is below.
+
+Reading:
+
+.. code-block:: python
+
+ # Reading JSON content from a file
+ import json
+ with open('/tmp/file.json', 'r') as f:
+ data = json.load(f)
+
+Writing:
+
+.. code-block:: python
+
+ # Writing JSON content to a file using the dump method
+ import json
+ with open('/tmp/file.json', 'w') as f:
+ json.dump(data, f, sort_keys=True)
+
+=================
+XML (nested data)
+=================
+
+XML parsing in Python is possible using the `xml` package.
+
+Example:
+
+.. code-block:: python
+
+ # reading XML content from a file
+ import xml.etree.ElementTree as ET
+ tree = ET.parse('country_data.xml')
+ root = tree.getroot()
+
+More documentation on using the `xml.dom` and `xml.sax` packages can be found
+`in the Python XML library documentation `__.
+
+
+*******
+Binary
+*******
+
+=======================
+NumPy Array (flat data)
+=======================
+
+Python's NumPy array can be used to serialize and deserialize data to and from byte representation.
+
+Example:
+
+.. code-block:: python
+
+ import NumPy as np
+
+ # Converting NumPy array to byte format
+ byte_output = np.array([ [1, 2, 3], [4, 5, 6], [7, 8, 9] ]).tobytes()
+
+ # Converting byte format back to NumPy array
+ array_format = np.frombuffer(byte_output)
+
+
+
+====================
+Pickle (nested data)
+====================
+
+The native data serialization module for Python is called `Pickle
+`_.
+
+Here's an example:
+
+.. code-block:: python
+
+ import pickle
+
+ #Here's an example dict
+ grades = { 'Alice': 89, 'Bob': 72, 'Charles': 87 }
+
+ #Use dumps to convert the object to a serialized string
+ serial_grades = pickle.dumps( grades )
+
+ #Use loads to de-serialize an object
+ received_grades = pickle.loads( serial_grades )
+
+
+********
+Protobuf
+********
+
+If you're looking for a serialization module that has support in multiple
+languages, Google's `Protobuf
+`_ library is an option.
diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst
index 5a4bd13b6..5dc0cd845 100644
--- a/docs/scenarios/speed.rst
+++ b/docs/scenarios/speed.rst
@@ -1,35 +1,225 @@
+
+#####
Speed
-=====
+#####
+
+.. image:: /_static/photos/33175625804_e225b90f3e_k_d.jpg
+
+CPython, the most commonly used implementation of Python, is slow for CPU bound
+tasks. `PyPy`_ is fast.
+
+Using a slightly modified version of `David Beazley's`_ CPU bound test code
+(added loop for multiple tests), you can see the difference between CPython
+and PyPy's processing.
+
+.. code-block:: console
+
+ # PyPy
+ $ ./pypy -V
+ Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10)
+ [PyPy 1.7.0 with GCC 4.4.3]
+ $ ./pypy measure2.py
+ 0.0683999061584
+ 0.0483210086823
+ 0.0388588905334
+ 0.0440690517426
+ 0.0695300102234
-CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast.
+.. code-block:: console
+ # CPython
+ $ ./python -V
+ Python 2.7.1
+ $ ./python measure2.py
+ 1.06774401665
+ 1.45412397385
+ 1.51485204697
+ 1.54693889618
+ 1.60109114647
+
+*******
Context
-:::::::
+*******
The GIL
-------
+`The GIL`_ (Global Interpreter Lock) is how Python allows multiple threads to
+operate at the same time. Python's memory management isn't entirely thread-safe,
+so the GIL is required to prevent multiple threads from running the same
+Python code at once.
+David Beazley has a great `guide`_ on how the GIL operates. He also covers the
+`new GIL`_ in Python 3.2. His results show that maximizing performance in a
+Python application requires a strong understanding of the GIL, how it affects
+your specific application, how many cores you have, and where your application
+bottlenecks are.
-C Extentions
+C Extensions
------------
The GIL
-------
+`Special care`_ must be taken when writing C extensions to make sure you
+register your threads with the interpreter.
-
-C Extentions
-::::::::::::
+************
+C Extensions
+************
Cython
------
+`Cython `_ implements a superset of the Python language
+with which you are able to write C and C++ modules for Python. Cython also
+allows you to call functions from compiled C libraries. Using Cython allows
+you to take advantage of Python's strong typing of variables and operations.
+
+Here's an example of strong typing with Cython:
+
+.. code-block:: cython
+
+ def primes(int kmax):
+ """Calculation of prime numbers with additional
+ Cython keywords"""
+
+ cdef int n, k, i
+ cdef int p[1000]
+ result = []
+ if kmax > 1000:
+ kmax = 1000
+ k = 0
+ n = 2
+ while k < kmax:
+ i = 0
+ while i < k and n % p[i] != 0:
+ i = i + 1
+ if i == k:
+ p[k] = n
+ k = k + 1
+ result.append(n)
+ n = n + 1
+ return result
+
+
+This implementation of an algorithm to find prime numbers has some additional
+keywords compared to the next one, which is implemented in pure Python:
+
+.. code-block:: python
+
+ def primes(kmax):
+ """Calculation of prime numbers in standard Python syntax"""
+
+ p = range(1000)
+ result = []
+ if kmax > 1000:
+ kmax = 1000
+ k = 0
+ n = 2
+ while k < kmax:
+ i = 0
+ while i < k and n % p[i] != 0:
+ i = i + 1
+ if i == k:
+ p[k] = n
+ k = k + 1
+ result.append(n)
+ n = n + 1
+ return result
+
+Notice that in the Cython version you declare integers and integer arrays
+to be compiled into C types while also creating a Python list:
+
+
+.. code-block:: cython
+
+ def primes(int kmax):
+ """Calculation of prime numbers with additional
+ Cython keywords"""
+
+ cdef int n, k, i
+ cdef int p[1000]
+ result = []
+
+
+.. code-block:: python
+
+ def primes(kmax):
+ """Calculation of prime numbers in standard Python syntax"""
+
+ p = range(1000)
+ result = []
+
+What is the difference? In the upper Cython version you can see the
+declaration of the variable types and the integer array in a similar way as
+in standard C. For example `cdef int n,k,i` in line 3. This additional type
+declaration (i.e. integer) allows the Cython compiler to generate more
+efficient C code from the second version. While standard Python code is saved
+in :file:`*.py` files, Cython code is saved in :file:`*.pyx` files.
+
+What's the difference in speed? Let's try it!
+
+.. code-block:: python
+
+ import time
+ # Activate pyx compiler
+ import pyximport
+ pyximport.install()
+ import primesCy # primes implemented with Cython
+ import primes # primes implemented with Python
+
+ print("Cython:")
+ t1 = time.time()
+ print(primesCy.primes(500))
+ t2 = time.time()
+ print("Cython time: %s" % (t2 - t1))
+ print("")
+ print("Python")
+ t1 = time.time()
+ print(primes.primes(500))
+ t2 = time.time()
+ print("Python time: %s" % (t2 - t1))
+
+
+These lines both need a remark:
+
+.. code-block:: python
+
+ import pyximport
+ pyximport.install()
+
+
+The `pyximport` module allows you to import :file:`*.pyx` files (e.g.,
+:file:`primesCy.pyx`) with the Cython-compiled version of the `primes`
+function. The `pyximport.install()` command allows the Python interpreter to
+start the Cython compiler directly to generate C code, which is automatically
+compiled to a :file:`*.so` C library. Cython is then able to import this
+library for you in your Python code, easily and efficiently. With the
+`time.time()` function you are able to compare the time between these 2
+different calls to find 500 prime numbers. On a standard notebook (dual core
+AMD E-450 1.6 GHz), the measured values are:
+
+.. code-block:: console
+
+ Cython time: 0.0054 seconds
+
+ Python time: 0.0566 seconds
+
+
+And here is the output of an embedded `ARM beaglebone `_ machine:
+
+.. code-block:: console
+
+ Cython time: 0.0196 seconds
+
+ Python time: 0.3302 seconds
+
Pyrex
-----
@@ -39,16 +229,215 @@ Shedskin?
---------
+***********
+Concurrency
+***********
-Threading
-:::::::::
+Concurrent.futures
+------------------
-Threading
+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.
+
+.. code-block:: python
+
+ from concurrent.futures import ThreadPoolExecutor
+ import requests
+
+ def get_webpage(url):
+ 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.
+
+
+.. code-block:: python
+
+ 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
---------
+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
+its arguments to `Thread`'s constructor and then calling `start()`:
+
+.. code-block:: python
+
+ 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()`:
+
+.. 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):
+
+.. code-block:: python
+
+ 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 `Stack Overflow post`_.
+
+The way this can be avoided is by using a `Lock`_ that each thread needs to
+acquire before writing to a shared resource. Locks can be acquired and released
+through either the contextmanager protocol (`with` statement), or by using
+`acquire()` and `release()` directly. Here is a (rather contrived) example:
+
+
+.. code-block:: python
+
+ 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.
-Spanwing Processes
+Spawning Processes
------------------
@@ -56,4 +445,15 @@ Multiprocessing
---------------
-.. _`PyPy`: http://pypy.org
\ No newline at end of file
+.. _`PyPy`: http://pypy.org
+.. _`The GIL`: https://wiki.python.org/moin/GlobalInterpreterLock
+.. _`guide`: http://www.dabeaz.com/python/UnderstandingGIL.pdf
+.. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf
+.. _`Special care`: https://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
+.. _`threading`: https://docs.python.org/3/library/threading.html
+.. _`Stack Overflow post`: https://stackoverflow.com/questions/26688424/python-threads-are-printing-at-the-same-time-messing-up-the-text-output
+.. _`data race`: https://en.wikipedia.org/wiki/Race_condition
+.. _`Lock`: https://docs.python.org/3/library/threading.html#lock-objects
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 60a478d3d..a2c84818b 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -1,9 +1,19 @@
-Web Applications
-================
+#############################
+Web Applications & Frameworks
+#############################
+.. image:: /_static/photos/34309496175_b82d104282_k_d.jpg
+
+As a powerful scripting language adapted to both fast prototyping
+and bigger projects, Python is widely used in web application
+development.
+
+
+*******
Context
-:::::::
+*******
+
WSGI
@@ -13,24 +23,25 @@ The Web Server Gateway Interface (or "WSGI" for short) is a standard
interface between web servers and Python web application frameworks. By
standardizing behavior and communication between web servers and Python web
frameworks, WSGI makes it possible to write portable Python web code that
-can be deployed in any `WSGI-compliant web server <#servers>`_. WSGI is
-documented in `PEP-3333 `_.
+can be deployed in any :ref:`WSGI-compliant web server `.
+WSGI is documented in :pep:`3333`.
+**********
Frameworks
-::::::::::
+**********
-Broadly speaking, a web framework is a set of libraries upon which you can
-build custom code to implement a web application (i.e. an interactive web
-site). Most web frameworks include patterns and utilities to accomplish at
-least the following:
+Broadly speaking, a web framework consists of a set of libraries and a main
+handler within which you can build custom code to implement a web application
+(i.e. an interactive web site). Most web frameworks include patterns and
+utilities to accomplish at least the following:
URL Routing
Matches an incoming HTTP request to a particular piece of Python code to
be invoked
Request and Response Objects
- Encapsulate the information received from or sent to a user's browser
+ Encapsulates the information received from or sent to a user's browser
Template Engine
Allows for separating Python code implementing an application's logic from
@@ -44,177 +55,491 @@ Development Web Server
Django
------
-`Django `_ is a "batteries included" web
-application framework. By providing many utilities and patterns out of the
-box, Django aims to make it possible to build complex, database-backed web
-applications quickly, while encouraging best practices in code written using
-it.
+`Django `_ is a "batteries included" web
+application framework, and is an excellent choice for creating content-oriented
+websites. By providing many utilities and patterns out of the box, Django aims
+to make it possible to build complex, database-backed web applications quickly,
+while encouraging best practices in code written using it.
Django has a large and active community, and many pre-built `re-usable
modules `_ that can be incorporated into a new
project as-is, or customized to fit your needs.
There are annual Django conferences `in the United States
-`_ and `in Europe `_.
+`_, `Europe `_, and `Australia `_.
+The majority of new Python web applications today are built with Django.
Flask
-----
-`Flask `_ is a "microframework" for Python. Rather
-than aiming to provide everything you could possibly need, Flask implements
-the most commonly-used core components of a web application framework, like
-URL routing, request and response objects, and templates. As a user of
-Flask, it is therefore up to you to choose and integrate other components
-you may need, such as database access or form generation and validation. For
-many popular modules, `Extensions `_ may
-already exist to suit your needs.
+`Flask `_ is a "microframework" for Python, and is
+an excellent choice for building smaller applications, APIs, and web services.
+
+Building an app with Flask is a lot like writing standard Python modules,
+except some functions have routes attached to them. It's really beautiful.
+
+Rather than aiming to provide everything you could possibly need, Flask
+implements the most commonly-used core components of a web application
+framework, like URL routing, request and response objects, and templates.
+
+If you use Flask, it is up to you to choose other components for your
+application, if any. For example, database access or form generation and
+validation are not built-in functions of Flask.
+
+This is great, because many web applications don't need those features.
+For those that do, there are many
+`Extensions `_ available that may
+suit your needs. Or, you can easily use any library you want yourself!
+
+Flask is default choice for any Python web application that isn't a good
+fit for Django.
+
+Falcon
+------
+
+`Falcon `_ is a good choice when your goal is
+to build RESTful API microservices that are fast and scalable.
+
+It is a reliable, high-performance Python web framework for building large-scale
+app backends and microservices. Falcon encourages the REST architectural style of
+mapping URIs to resources, trying to do as little as possible while remaining highly effective.
+Falcon highlights four main focuses: speed, reliability, flexibility, and debuggability.
+It implements HTTP through "responders" such as ``on_get()``, ``on_put()``, etc.
+These responders receive intuitive request and response objects.
+
+Tornado
+--------
+
+`Tornado `_ is an asynchronous web framework
+for Python that has its own event loop. This allows it to natively support
+WebSockets, for example. Well-written Tornado applications are known to
+have excellent performance characteristics.
+
+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. A set of
+provided cookiecutter templates helps making new project decisions for users.
+It powers one of the most important parts of python infrastructure
+`PyPI `_.
+
+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
+applications today.
+
+Masonite
+--------
+
+`Masonite `_ is a modern and developer centric, "batteries included", web framework.
+
+The Masonite framework follows the MVC (Model-View-Controller) architecture pattern and is heavily inspired by frameworks such as Rails and Laravel, so if you are coming to Python from a Ruby or PHP background then you will feel right at home!
+
+Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools, and the Orator active record style ORM.
+
+Masonite is perfect for beginners or experienced developers alike and works hard to be fast and easy from install through to deployment. Try it once and you’ll fall in love.
+
+FastAPI
-------
+`FastAPI `_ is a modern web framework for building
+APIs with Python 3.6+.
+
+It has very high performance as it is based on `Starlette `_
+and `Pydantic `_.
-Servers
-:::::::
+FastAPI takes advantage of standard Python type declarations in function parameters
+to declare request parameters and bodies, perform data conversion (serialization,
+parsing), data validation, and automatic API documentation with **OpenAPI 3**
+(including **JSON Schema**).
-Apache + mod_wsgi
------------------
+It includes tools and utilities for security and authentication (including OAuth2 with JWT
+tokens), a dependency injection system, automatic generation of interactive API
+documentation, and other features.
-Apache + mod_python
--------------------
+***********
+Web Servers
+***********
-Nginx + gunicorn
-----------------
+.. _nginx-ref:
+
+Nginx
+-----
`Nginx `_ (pronounced "engine-x") is a web server and
-reverse-proxy for HTTP, SMTP and other protocols. It is known for its
+reverse-proxy for HTTP, SMTP, and other protocols. It is known for its
high performance, relative simplicity, and compatibility with many
application servers (like WSGI servers). It also includes handy features
like load-balancing, basic authentication, streaming, and others. Designed
to serve high-load websites, Nginx is gradually becoming quite popular.
-`gUnicorn `_ (Green Unicorn) is a WSGI server used
-to serve Python applications. It is a Python fork of the Ruby
-`Unicorn `_ server. gUnicorn is designed to be
-lightweight, easy to use, and uses many UNIX idioms. gUnicorn is not designed
-to face the internet, in fact it was designed to run behind Nginx which buffers
-slow requests, and takes care of other important considerations. A sample
-setup for Nginx + gUnicorn can be found in the gUnicorn
-`help `_.
-Mongrel2 + Brubeck
-------------------
+.. _wsgi-servers-ref:
-Mongrel2 + wsgid
-----------------
+************
+WSGI Servers
+************
-Mongrel2 is an application, language, and network architecture agnostic web server. It uses a high performance queue (zeromq) to communicate
-with your applications, all asynchronously. There is a well defined protocol to be used between mongrel2 and a backend handler (your app).
+Stand-alone WSGI servers typically use less resources than traditional web
+servers and provide top performance [1]_.
-Wsgid is a generic mongrel2 handler that speaks both mongrel2 protocol and WSGI. This makes it possible to run your python webapp written with any
-WSGI compliant framework. Wsgid has built-in Django support but has also a generic way to load your WSGI application object directly. It's possible
-to add support for other frameworks through wsgid's pluggable Apploading interface.
+.. _gunicorn-ref:
-To know more about mongrel2 and wsgid go to: http://mongrel2.org and http://wsgid.com
+Gunicorn
+--------
-There is also a tutorial about deploying Django using this stack: http://daltonmatos.wordpress.com/2011/11/06/deploying-your-django-application-with-mongrel2-and-wsgid/
+`Gunicorn `_ (Green Unicorn) is a pure-Python WSGI
+server used to serve Python applications. Unlike other Python web servers,
+it has a thoughtful user interface, and is extremely easy to use and
+configure.
+Gunicorn has sane and reasonable defaults for configurations. However, some
+other servers, like uWSGI, are tremendously more customizable, and therefore,
+are much more difficult to effectively use.
-Hosting
-:::::::
+Gunicorn is the recommended choice for new Python web applications today.
+
+
+Waitress
+--------
+
+`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).
+
+Waitress is gaining popularity within the Python web development community.
+
+.. _uwsgi-ref:
+
+uWSGI
+-----
+
+`uWSGI `_ is a full stack for building
+hosting services. In addition to process management, process monitoring,
+and other functionality, uWSGI acts as an application server for various
+programming languages and protocols -- including Python and WSGI. uWSGI can
+either be run as a stand-alone web router, or be run behind a full web
+server (such as Nginx or Apache). In the latter case, a web server can
+configure uWSGI and an application's operation over the
+`uwsgi protocol `_.
+uWSGI's web server support allows for dynamically configuring
+Python, passing environment variables, and further tuning. For full details,
+see `uWSGI magic
+variables `_.
+
+I do not recommend using uWSGI unless you know why you need it.
-Platform-as-a-Service
----------------------
+.. _server-best-practices-ref:
+
+
+*********************
+Server Best Practices
+*********************
+
+The majority of self-hosted Python applications today are hosted with a WSGI
+server such as :ref:`Gunicorn `, either directly or behind a
+lightweight web server such as :ref:`nginx `.
+
+The WSGI servers serve the Python applications while the web server handles
+tasks better suited for it such as static file serving, request routing, DDoS
+protection, and basic authentication.
+
+
+*******
+Hosting
+*******
Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure
which abstracts and manages infrastructure, routing, and scaling of web
-applications. When using PaaS, application developers can focus on writing
+applications. When using a PaaS, application developers can focus on writing
application code rather than needing to be concerned with deployment
details.
-Most PaaS services offer a command-line interface that developers can use to
-set up and interrogate configuration, and to deploy new releases of an
-application to the service.
+Heroku
+------
-PaaS services and their partners offer add-on functionality which is well
-integrated into the platform, such as database hosting, email services,
-logging, scheduled and background tasks, billing and payment, etc.
+`Heroku `_ offers first-class support for
+Python 2.7–3.5 applications.
+Heroku supports all types of Python web applications, servers, and frameworks.
+Applications can be developed on Heroku for free. Once your application is
+ready for production, you can upgrade to a Hobby or Professional application.
-Heroku
-~~~~~~
+Heroku maintains `detailed articles `_
+on using Python with Heroku, as well as `step-by-step instructions
+`_ on
+how to set up your first application.
-`Heroku `_'s
-`Cedar `_ stack supports Python
-web applications running on Python version 2.7. At this time, Cedar is in
-public beta, but it is intended to become the default stack for all new
-Heroku applications at some point.
+Heroku is the recommended PaaS for deploying Python web applications today.
-Heroku uses a git-based workflow, so it is well-suited for use with
-applications whose source control is managed in a git repository.
-Heroku publishes `step-by-step instructions
-`_ on how to set up your first
-application for use in Heroku, and maintains a list of `example applications
-`_ using Heroku.
+**********
+Templating
+**********
+Most WSGI applications are responding to HTTP requests to serve content in HTML
+or other markup languages. Instead of directly generating textual content from
+Python, the concept of separation of concerns advises us to use templates. A
+template engine manages a suite of template files, with a system of hierarchy
+and inclusion to avoid unnecessary repetition, and is in charge of rendering
+(generating) the actual content, filling the static content of the templates
+with the dynamic content generated by the application.
-DotCloud
-~~~~~~~~
+As template files are
+sometimes written by designers or front-end developers, it can be difficult to
+handle increasing complexity.
-`DotCloud `_ supports WSGI applications and
-background/worker tasks natively on their platform. Web applications running
-Python version 2.6, and uses `nginx `_ and `uWSGI
-`_, and allows custom configuration of both
-for advanced users.
+Some general good practices apply to the part of the application passing
+dynamic content to the template engine, and to the templates themselves.
-DotCloud uses a custom command-line API client which can work with
-applications managed in git repositories or any other version control
-system.
+- Template files should be passed only the dynamic
+ content that is needed for rendering the template. Avoid
+ the temptation to pass additional content "just in case":
+ it is easier to add some missing variable when needed than to remove
+ a likely unused variable later.
-See the `DotCloud documentation on Python
-`_ for more information and help
-getting started.
+- Many template engines allow for complex statements
+ or assignments in the template itself, and many
+ allow some Python code to be evaluated in the
+ templates. This convenience can lead to uncontrolled
+ increase in complexity, and often make it harder to find bugs.
+- It is often necessary to mix JavaScript templates with
+ HTML templates. A sane approach to this design is to isolate
+ the parts where the HTML template passes some variable content
+ to the JavaScript code.
-ep.io
-~~~~~
-`ep.io `_ is a PaaS designed specifically for Python web
-applications. It supports Python versions 2.6 and 2.7, and has Pythonic
-integrations with a variety of services.
-ep.io publishes `step-by-step instructions
-`_ on how to get started with their
-platform and how to deploy Django, Flask, or generic WSGI applications.
+Jinja2
+------
+`Jinja2 `_ is a very well-regarded template engine.
+
+It uses a text-based template language and can thus be used to generate any
+type of markup, not just HTML. It allows customization of filters, tags, tests,
+and globals. It features many improvements over Django's templating system.
+
+Here some important HTML tags in Jinja2:
+
+.. code-block:: html
+
+ {# This is a comment #}
+
+ {# The next tag is a variable output: #}
+ {{title}}
+
+ {# Tag for a block, can be replaced through inheritance with other html code #}
+ {% block head %}
+
This is the head!
+ {% endblock %}
+
+ {# Output of an array as an iteration #}
+ {% for item in list %}
+
{{ item }}
+ {% endfor %}
+
+
+The next listings are an example of a web site in combination with the Tornado
+web server. Tornado is not very complicated to use.
+
+.. code-block:: python
+
+ # import Jinja2
+ from jinja2 import Environment, FileSystemLoader
+
+ # import Tornado
+ import tornado.ioloop
+ import tornado.web
+
+ # Load template file templates/site.html
+ TEMPLATE_FILE = "site.html"
+ templateLoader = FileSystemLoader( searchpath="templates/" )
+ templateEnv = Environment( loader=templateLoader )
+ template = templateEnv.get_template(TEMPLATE_FILE)
+
+ # List for famous movie rendering
+ movie_list = [[1,"The Hitchhiker's Guide to the Galaxy"],[2,"Back to future"],[3,"Matrix"]]
+
+ # template.render() returns a string which contains the rendered html
+ html_output = template.render(list=movie_list,
+ title="Here is my favorite movie list")
+
+ # Handler for main page
+ class MainHandler(tornado.web.RequestHandler):
+ def get(self):
+ # Returns rendered template string to the browser request
+ self.write(html_output)
+
+ # Assign handler to the server root (127.0.0.1:PORT/)
+ application = tornado.web.Application([
+ (r"/", MainHandler),
+ ])
+ PORT=8884
+ if __name__ == "__main__":
+ # Setup the server
+ application.listen(PORT)
+ tornado.ioloop.IOLoop.instance().start()
+
+The :file:`base.html` file can be used as base for all site pages which are
+for example implemented in the content block.
+
+.. code-block:: html
+
+
+
+
+
+
+ {{title}} - My Webpage
+
+
+
+ {# In the next line the content from the site.html template will be added #}
+ {% block content %}{% endblock %}
+
+
+
+
+
+The next listing is our site page (:file:`site.html`) loaded in the Python
+app which extends :file:`base.html`. The content block is automatically set
+into the corresponding block in the :file:`base.html` page.
+
+.. code-block:: html
+
+ {% extends "base.html" %}
+ {% block content %}
+
+
+
{{title}}
+
{{ list_title }}
+
+ {% for item in list %}
+
{{ item[0]}} : {{ item[1]}}
+ {% endfor %}
+
+
+
+ {% endblock %}
+
+
+Jinja2 is the recommended templating library for new Python web applications.
+
+Chameleon
+---------
+
+`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.
+
+Chameleon is available for Python 2.5 and up (including 3.x and PyPy), and
+is commonly used by the `Pyramid Framework `_.
+
+Page Templates add within your document structure special element attributes
+and text markup. Using a set of simple language constructs, you control the
+document flow, element repetition, text replacement, and translation. Because
+of the attribute-based syntax, unrendered page templates are valid HTML and can
+be viewed in a browser and even edited in WYSIWYG editors. This can make
+round-trip collaboration with designers and prototyping with static files in a
+browser easier.
+
+The basic TAL language is simple enough to grasp from an example:
+
+.. code-block:: html
+
+
+
+
Hello, World!
+
+
+
+
+
+
+
+
+
+
+
+The `` pattern for text insertion is common
+enough that if you do not require strict validity in your unrendered templates,
+you can replace it with a more terse and readable syntax that uses the pattern
+`${expression}`, as follows:
+
+.. code-block:: html
+
+
+
+
Hello, ${world}!
+
+
+
+ ${row.capitalize()} ${col}
+
+
+
+
+
+
+
+But keep in mind that the full `Default Text`
+syntax also allows for default content in the unrendered template.
+
+Being from the Pyramid world, Chameleon is not widely used.
+
+Mako
+----
-ep.io is currently in invite-only beta.
+`Mako `_ is a template language that compiles to Python
+for maximum performance. Its syntax and API are borrowed from the best parts of other
+templating languages like Django and Jinja2 templates. It is the default template
+language included with the `Pylons and Pyramid `_ web
+frameworks.
+An example template in Mako looks like:
-Gondor
-~~~~~~
+.. code-block:: mako
-`Gondor `_ is a PaaS specailized for deploying Django
-and Pinax applications. Gondor supports Django versions 1.2 and 1.3 on
-Python version 2.7, and can automatically configure your Django site if you
-use ``local_settings.py`` for site-specific configuration information.
+ <%inherit file="base.html"/>
+ <%
+ rows = [[v for v in range(0,10)] for row in range(0,10)]
+ %>
+
+ % for row in rows:
+ ${makerow(row)}
+ % endfor
+
-Gondor publishes guides to deploying `Django projects
-`_ and `Pinax projects
-`_ on their platform.
+ <%def name="makerow(row)">
+
+ % for name in row:
+
${name}
\
+ % endfor
+
+ %def>
-Shared Web Hosting
-------------------
+To render a very basic template, you can do the following:
-WebFaction
-~~~~~~~~~~~
+.. code-block:: python
+ from mako.template import Template
+ print(Template("hello ${data}!").render(data="world"))
-Twisted
-:::::::
+Mako is well respected within the Python web community.
+.. rubric:: References
-Node.js.
+.. [1] `Benchmark of Python WSGI Servers `_
diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst
new file mode 100644
index 000000000..24dab5869
--- /dev/null
+++ b/docs/scenarios/xml.rst
@@ -0,0 +1,110 @@
+
+###########
+XML parsing
+###########
+
+.. image:: /_static/photos/33888714601_a1f7d020a2_k_d.jpg
+
+
+********
+untangle
+********
+
+`untangle `_ is a simple library which
+takes an XML document and returns a Python object which mirrors the nodes and
+attributes in its structure.
+
+For example, an XML file like this:
+
+.. code-block:: xml
+
+
+
+
+
+
+can be loaded like this:
+
+.. code-block:: python
+
+ import untangle
+ obj = untangle.parse('path/to/file.xml')
+
+and then you can get the child element's name attribute like this:
+
+.. code-block:: python
+
+ obj.root.child['name']
+
+untangle also supports loading XML from a string or a URL.
+
+
+*********
+xmltodict
+*********
+
+`xmltodict `_ is another simple
+library that aims at making XML feel like working with JSON.
+
+An XML file like this:
+
+.. code-block:: xml
+
+
+
+ elements
+ more elements
+
+
+ element as well
+
+
+
+can be loaded into a Python dict like this:
+
+.. code-block:: python
+
+ import xmltodict
+
+ with open('path/to/file.xml') as fd:
+ doc = xmltodict.parse(fd.read())
+
+and then you can access elements, attributes, and values like this:
+
+.. code-block:: python
+
+ doc['mydocument']['@has'] # == u'an attribute'
+ doc['mydocument']['and']['many'] # == [u'elements', u'more elements']
+ doc['mydocument']['plus']['@a'] # == u'complex'
+ doc['mydocument']['plus']['#text'] # == u'element as well'
+
+xmltodict also lets you roundtrip back to XML with the unparse function,
+has a streaming mode suitable for handling files that don't fit in memory,
+and supports XML namespaces.
+
+**********
+xmlschema
+**********
+
+`xmlschema `_ provides support for using XSD-Schemas in Python.
+Unlike other XML libraries, automatic type parsing is available, so f.e. if the schema defines an element to be of type ``int``, the parsed ``dict`` will contain also an ``int`` value for that element.
+Moreover the library supports automatic and explicit validation of XML documents against a schema.
+
+.. code-block:: python
+
+ from xmlschema import XMLSchema, etree_tostring
+
+ # load a XSD schema file
+ schema = XMLSchema("your_schema.xsd")
+
+ # validate against the schema
+ schema.validate("your_file.xml")
+
+ # or
+ schema.is_valid("your_file.xml")
+
+ # decode a file
+ data = schmema.decode("your_file.xml")
+
+ # encode to string
+ s = etree_tostring(schema.encode(data))
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 1f9fd4a7b..841fa2040 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -1,46 +1,266 @@
+.. _freezing-your-code-ref:
+
+
+##################
Freezing Your Code
-==================
+##################
+
+.. image:: /_static/photos/33907151034_e0a9e53402_k_d.jpg
+
+"Freezing" your code is creating a single-file executable file to distribute
+to end-users, that contains all of your application code as well as the
+Python interpreter.
+
+Applications such as 'Dropbox', 'Eve Online', 'Civilization IV', and
+BitTorrent clients do this.
+
+The advantage of distributing this way is that your application will "just work",
+even if the user doesn't already have the required version of Python (or any)
+installed. On Windows, and even on many Linux distributions and OS X, the right
+version of Python will not already be installed.
+
+Besides, end-user software should always be in an executable format. Files
+ending in ``.py`` are for software engineers and system administrators.
+
+One disadvantage of freezing is that it will increase the size of your
+distribution by about 2–12 MB. Also, you will be responsible for shipping
+updated versions of your application when security vulnerabilities to
+Python are patched.
+
+
+************************
+Alternatives to Freezing
+************************
+
+:ref:`Packaging your code ` is for distributing
+libraries or tools to other developers.
-An alternative to shipping your code is freezing it — shipping it as an
-executable with a bundled Python interpreter.
+On Linux, an alternative to freezing is to
+:ref:`create a Linux distro package `
+(e.g. .deb files for Debian or Ubuntu, or .rpm files for Red Hat and SuSE.)
-Many applications you use every day do this:
+.. todo:: Fill in "Freezing Your Code" stub
-- Dropbox
-- BitTorrent
--
+****************************
+Comparison of Freezing Tools
+****************************
+
+Date of this writing: Oct 5, 2019
+Solutions and platforms/features supported:
+
+=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== =====================
+Solution Windows Linux OS X Python 3 License One-file mode Zipfile import Eggs pkg_resources support Latest release date
+=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== =====================
+bbFreeze yes yes yes no MIT no yes yes yes Jan 20, 2014
+py2exe yes no no yes MIT yes yes no no Oct 21, 2014
+pyInstaller yes yes yes yes GPL yes no yes no Jul 9, 2019
+cx_Freeze yes yes yes yes PSF no yes yes no Aug 29, 2019
+py2app no no yes yes MIT no yes yes yes Mar 25, 2019
+=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== =====================
+
+.. note::
+ Freezing Python code on Linux into a Windows executable was only once
+ supported in PyInstaller `and later dropped
+ `_.
+
+.. note::
+ All solutions need a Microsoft Visual C++ to be installed on the target machine, except py2app.
+ Only PyInstaller makes a self-executable exe that bundles the appropriate DLL when
+ passing ``--onefile`` to :file:`Configure.py`.
+
+
+*******
Windows
-:::::::
+*******
+
+bbFreeze
+~~~~~~~~
+
+Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Windows `.
+
+1. Install :code:`bbfreeze`:
+
+.. code-block:: console
+ $ pip install bbfreeze
+
+2. Write most basic :file:`bb_setup.py`
+
+.. code-block:: python
+
+ from bbfreeze import Freezer
+
+ freezer = Freezer(distdir='dist')
+ freezer.addScript('foobar.py', gui_only=True)
+ freezer()
+
+.. note::
+
+ This will work for the most basic one file scripts. For more advanced freezing you will have to provide
+ include and exclude paths like so:
+
+ .. code-block:: python
+
+ freezer = Freezer(distdir='dist', includes=['my_code'], excludes=['docs'])
+
+3. (Optionally) include icon
+
+.. code-block:: python
+
+ freezer.setIcon('my_awesome_icon.ico')
+
+4. Provide the Microsoft Visual C++ runtime DLL for the freezer. It might be possible to append your :code:`sys.path`
+with the Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script
+resides.
+
+5. Freeze!
+
+.. code-block:: console
+
+ $ python bb_setup.py
py2exe
-------
+~~~~~~
+Prerequisite is to install :ref:`Python on Windows `. The last release of py2exe is from the year 2014. There is not active development.
+1. Download and install http://sourceforge.net/projects/py2exe/files/py2exe/
-OSX
-:::
+2. Write :file:`setup.py` (`List of configuration options `_):
+.. code-block:: python
-py2app
-------
+ from distutils.core import setup
+ import py2exe
+
+ setup(
+ windows=[{'script': 'foobar.py'}],
+ )
+
+3. (Optionally) `include icon `_
+
+4. (Optionally) `one-file mode `_
+
+5. Generate :file:`.exe` into :file:`dist` directory:
+
+.. code-block:: console
+ $ python setup.py py2exe
+6. Provide the Microsoft Visual C++ runtime DLL. Two options: `globally install dll on target machine `_ or `distribute dll alongside with .exe `_.
+
+PyInstaller
+~~~~~~~~~~~
+
+Prerequisite is to have installed :ref:`Python, Setuptools and pywin32 dependency on Windows `.
+
+- `Most basic tutorial `_
+- `Manual `_
+
+
+****
+OS X
+****
+py2app
+~~~~~~
+
PyInstaller
------------
+~~~~~~~~~~~
+
+PyInstaller can be used to build Unix executables and windowed apps on Mac OS X 10.6 (Snow Leopard) or newer.
+
+To install PyInstaller, use pip:
+
+.. code-block:: console
+
+ $ pip install pyinstaller
+
+To create a standard Unix executable, from say :code:`script.py`, use:
+
+.. code-block:: console
+
+ $ pyinstaller script.py
+
+This creates:
+
+- a :code:`script.spec` file, analogous to a :code:`make` file
+- a :code:`build` folder, that holds some log files
+- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries
+
+all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder.
+
+The :code:`script.spec` file can be edited to `customise the build `_, with options such as:
+
+- bundling data files with the executable
+- including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically
+- adding Python run-time options to the executable
+
+Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again):
+
+.. code-block:: console
+ $ pyinstaller script.spec
+To create a standalone windowed OS X application, use the :code:`--windowed` option:
+.. code-block:: console
+ $ pyinstaller --windowed script.spec
+
+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.
+
+
+*****
Linux
-:::::
+*****
bbFreeze
---------
+~~~~~~~~
+.. warning:: bbFreeze will ONLY work in Python 2.x environment, since it's no longer being maintained as stated by it's former maintainer. If you're interested in it, check the repository in `here `_.
+
+bbFreeze can be used with all distributions that has Python installed along with pip2 and/or easy_install.
+
+For pip2, use the following:
+
+.. code-block:: console
+
+ $ pip2 install bbfreeze
+
+Or, for easy_install:
+
+.. code-block:: console
+
+ $ easy_install bbfreeze
+
+With bbFreeze installed, you're ready to freeze your applications.
+
+Let's assume you have a script, say, "hello.py" and a module called "module.py" and you have a function in it that's being used in your script.
+No need to worry, you can just ask to freeze the main entrypoint of your script and it should freeze entirely:
+
+.. code-block:: console
+
+ $ bbfreeze script.py
+
+With this, it creates a folder called dist/, of which contains the executable of the script and required .so (shared objects) files linked against libraries used within the Python script.
+
+Alternatively, you can create a script that does the freezing for you. An API for the freezer is available from the library within:
+
+.. code-block:: python
+
+ from bbfreeze import Freezer
+
+ freezer = Freezer(distdir='dist')
+ freezer.addScript('script.py', gui_only=True) # Enable gui_only kwarg for app that uses GUI packages.
+ freezer()
PyInstaller
------------
+~~~~~~~~~~~
+PyInstaller can be used in a similar fashion as in OS X. The installation goes in the same manner as shown in the OS X section.
+
+Don't forget to have dependencies such as Python and pip installed for usage.
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 40a0ac48b..34674cff2 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -1,32 +1,77 @@
+.. _packaging-your-code-ref:
+
+
+###################
Packaging Your Code
-===================
+###################
+
+.. image:: /_static/photos/36137234682_be6898bf57_k_d.jpg
+
+Package your code to share it with other developers. For example,
+to share a library for other developers to use in their application,
+or for development tools like 'py.test'.
+
+An advantage of this method of distribution is its well established ecosystem
+of tools such as PyPI and pip, which make it easy for other developers to
+download and install your package either for casual experiments, or as part of
+large, professional systems.
+
+It is a well-established convention for Python code to be shared this way.
+If your code isn't packaged on PyPI, then it will be harder
+for other developers to find it and to use it as part of their existing
+process. They will regard such projects with substantial suspicion of being
+either badly managed or abandoned.
+
+The downside of distributing code like this is that it relies on the
+recipient understanding how to install the required version of Python,
+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 `_
+provides an extensive guide on creating and maintaining Python packages.
-Packaging your code is important.
+*************************
+Alternatives to Packaging
+*************************
+To distribute applications to end-users, you should
+:ref:`freeze your application `.
+
+On Linux, you may also want to consider
+:ref:`creating a Linux distro package `
+(e.g. a .deb file for Debian or Ubuntu.)
+
+
+*********************
For Python Developers
-:::::::::::::::::::::
+*********************
-If you're writing an open source Python module, `PyPI `_, more properly known as *The Cheeseshop*, is the place to host it.
+If you're writing an open source Python module, `PyPI `_
+, more properly known as *The Cheeseshop*, is the place to host it.
Pip vs. easy_install
--------------------
-Use pip. More details `here `_
+Use `pip `_. More details
+`here `_.
Personal PyPI
-------------
-If you want to install packages from a source different from PyPI, (say, if
-your packages are *proprietary*), you can do it by hosting a simple http server,
-running from the directory which holds those packages which need to be installed.
+If you want to install packages from a source other than PyPI (say, if
+your packages are *proprietary*), you can do it by hosting a simple HTTP
+server, running from the directory which holds those packages which need to be
+installed.
**Showing an example is always beneficial**
-Say if you are after installing a package called MyPackage.tar.gz, and assuming this is your directory structure
+For example, if you want to install a package called :file:`MyPackage.tar.gz`,
+and assuming this is your directory structure:
- archive
@@ -34,32 +79,118 @@ Say if you are after installing a package called MyPackage.tar.gz, and assuming
- MyPackage.tar.gz
Go to your command prompt and type:
-::
-$ cd archive
-$ python -m SimpleHTTPServer 9000
+.. code-block:: console
+
+ $ cd archive
+ $ python -m http.server 9000
-This runs a simple http server running on port 9000 and will list all packages (like **MyPackage**). Now you can install **MyPackage** using any python package installer. Using Pip, you would do it like:
-::
+This runs a simple HTTP server running on port 9000 and will list all packages
+(like **MyPackage**). Now you can install **MyPackage** using any Python
+package installer. Using pip, you would do it like:
-$ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage
+.. code-block:: console
+
+ $ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage
Having a folder with the same name as the package name is **crucial** here.
I got fooled by that, one time. But if you feel that creating a folder called
-**MyPackage** and keeping **MyPackage.tar.gz** inside that, is *redundant*, you can still install MyPackage using:
-::
+:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that is
+*redundant*, you can still install MyPackage using:
+
+.. code-block:: console
+
+ $ pip install http://127.0.0.1:9000/MyPackage.tar.gz
+
+pypiserver
+++++++++++
+
+`pypiserver `_ is a minimal PyPI
+compatible server. It can be used to serve a set of packages to easy_install
+or pip. It includes helpful features like an administrative command
+(``-U``) which will update all its packages to their latest versions
+found on PyPI.
+
+
+S3-Hosted PyPi
+++++++++++++++
+
+One simple option for a personal PyPI server is to use Amazon S3. A
+prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
+
+1. **Install all your requirements from PyPi or another source**
+2. **Install pip2pi**
+
+* :code:`pip install git+https://github.com/wolever/pip2pi.git`
+
+3. **Follow pip2pi README for pip2tgz and dir2pi commands**
+
+* :code:`pip2tgz packages/ YourPackage` (or :code:`pip2tgz packages/ -r requirements.txt`)
+* :code:`dir2pi packages/`
+
+4. **Upload the new files**
+
+* Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket.
+* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories.
+
+5. **Fix new file permissions**
+
+* By default, when you upload new files to the S3 bucket, they will have the wrong permissions set.
+* Use the Amazon web console to set the READ permission of the files to EVERYONE.
+* If you get HTTP 403 when trying to install a package, make sure you've set the permissions correctly.
+
+6. **All done**
-$ pip install http://127.0.0.1:9000/MyPackage.tar.gz
+* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`.
-Chishop
-+++++++
+.. _packaging-for-linux-distributions-ref:
+***********************
For Linux Distributions
-::::::::::::::::::::::::
+***********************
+
+Creating a Linux distro package is arguably the "right way" to distribute code
+on Linux.
+
+Because a distribution package doesn't include the Python interpreter, it
+makes the download and install about 2-12 MB smaller than
+:ref:`freezing your application `.
+
+Also, if a distribution releases a new security update for Python, then your
+application will automatically start using that new version of Python.
+
+The bdist_rpm command makes `producing an RPM file `_
+for use by distributions like Red Hat or SuSE trivially easy.
+
+However, creating and maintaining the different configurations required for
+each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red
+Hat/Fedora, etc.) is a fair amount of work. If your code is an application that
+you plan to distribute on other platforms, then you'll also have to create and
+maintain the separate config required to freeze your application for Windows
+and OS X. It would be much less work to simply create and maintain a single
+config for one of the cross platform :ref:`freezing tools
+`, which will produce stand-alone executables for all
+distributions of Linux, as well as Windows and OS X.
+
+Creating a distribution package is also problematic if your code is for a
+version of Python that isn't currently supported by a distribution.
+Having to tell *some versions* of Ubuntu end-users that they need to add `the
+'dead-snakes' PPA `_
+using `sudo apt-repository` commands before they can install your .deb file
+makes for an extremely hostile user experience. Not only that, but you'd have
+to maintain a custom equivalent of these instructions for every distribution,
+and worse, have your users read, understand, and act on them.
+
+Having said all that, here's how to do it:
+
+* `Fedora `_
+* `Debian and Ubuntu `_
+* `Arch `_
Useful Tools
------------
-- epm
-- alien
+- `fpm `_
+- `alien `_
+- `dh-virtualenv `_ (for APT/DEB omnibus packaging)
diff --git a/docs/shipping/publishing.rst b/docs/shipping/publishing.rst
new file mode 100644
index 000000000..4b480f801
--- /dev/null
+++ b/docs/shipping/publishing.rst
@@ -0,0 +1,66 @@
+.. _publishing-your-code-ref:
+
+
+####################
+Publishing Your Code
+####################
+
+.. todo:: Replace this kitten with the photo we want.
+
+.. image:: https://placekitten.com/800/600
+
+A healthy open source project needs a place to publish its code and project
+management stuff so other developers can collaborate with you. This lets your
+users gain a better understanding of your code, keep up with new developments,
+report bugs, and contribute code.
+
+This development web site should include the source code history itself, a bug
+tracker, a patch submission (aka "Pull Request") queue, and possibly additional
+developer-oriented documentation.
+
+There are several free open source project hosting sites (aka "forges"). These
+include GitHub, SourceForge, Bitbucket, and GitLab. GitHub is currently the best.
+Use GitHub.
+
+
+*********************************
+Creating a Project Repo on GitHub
+*********************************
+
+To publish your Python project on GitHub:
+
+1. Create a GitHub account if you don't already have one.
+
+2. Create a new repo for your project.
+
+ 1. Click on the "+" menu next to your avatar in the upper right of the page and choose "New repository".
+
+ 2. Name it after your project and give it an SEO-friendly description.
+
+ 3. If you don't have an existing project repo, choose the settings to add a
+ README, `.gitignore`, and license. Use the Python `.gitignore` option.
+
+3. On the newly created repo page, click "Manage topics" and add the tags "python" and "python3" and/or "python2" as appropriate.
+
+4. Include a link to your new GitHub repo in your project's README file so people who just have the project distribution know where to find it.
+
+If this is a brand new repo, clone it to your local machine and start working:
+
+.. code-block:: console
+
+ $ git clone https://github.com//
+
+Or, if you already have a project Git repo, add your new GitHub repo as a remote:
+
+.. code-block:: console
+
+ $ cd
+ $ git remote add origin https://github.com//
+ $ git push --tags
+
+***********************
+When Your Project Grows
+***********************
+
+For more information about managing an open source software project, see the book
+`Producing Open Source Software `_.
diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst
deleted file mode 100644
index b1f249846..000000000
--- a/docs/starting/dev-env.rst
+++ /dev/null
@@ -1,137 +0,0 @@
-Your Development Environment
-============================
-
-
-Text Editors
-::::::::::::
-
-
-VIM
----
-
-
-There exist a couple of plugins and settings for the VIM editor to aid python
-development. If you only develop in Python, a good start is to set the default
-settings for indentation and linewrapping to values compliant with PEP8::
-
- set textwidth=79
- set shiftwidth=4
- set tabstop=4
- set expandtab
- set softtabstop=4
- set shiftround
-
-With these settings newlines are inserted after 79 characters and indentation
-is set to 4 spaces per tab. If you also use VIM for other languages, there is a
-handy plugin at indent_, which handles indentation settings for python source
-files.
-Additionally there is also a handy syntax plugin at syntax_ featuring some
-improvements over the syntax file included in VIM 6.1.
-
-These plugins supply you with a basic environment for developing in Python.
-However in order to improve the programming flow we also want to continually
-check for PEP8 compliance and check syntax. Luckily there exist PEP8_ and
-Pyflakes_ to do this for you. If your VIM is compiled with `+python` you can
-also utilize some very handy plugins to do these checks from within the editor.
-For PEP8 checking install vim-pep8_. Now you can map the vim function
-`Pep8()` to any hotkey or action you want. Similarly for pyflakes you can
-install vim-pyflakes_. Now you can map `Pyflakes()` like the PEP8 function and
-have it called quickly. Both plugins will display errors in a quickfix list and
-provide an easy way to jump to the corresponding line. A very handy setting is
-calling these functions whenever a buffer is saved. In order to do this, enter
-the following lines into your vimrc::
-
- autocmd BufWritePost *.py call Pyflakes()
- autocmd BufWritePost *.py call Pep8()
-
-
-.. _indent: http://www.vim.org/scripts/script.php?script_id=974
-.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
-.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
-.. _vim-pyflakes: https://github.com/nvie/vim-pyflakes
-.. _PEP8: http://pypi.python.org/pypi/pep8/
-.. _vim-pep8: https://github.com/nvie/vim-pep8
-
-.. todo:: add supertab notes
-
-
-IDEs
-::::
-
-PyCharm / IntelliJ IDEA
------------------------
-
-PyCharm is developed by JetBrains, also known for IntelliJ IDEA. Both share the same code base and most of PyCharm's features can be brought to IntelliJ with the free `Python Plug-In `_..
-
-Eclipse
--------
-
-The most popular Eclipse plugin for Python development is Aptana's
-`PyDev `_.
-
-
-Komodo IDE
------------
-`Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac
-and Linux.
-
-Spyder
-------
-
-`Spyder `_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy `_).
-Includes integration with `pyflakes `_, `pylint `_,
-and `rope `_.
-
-Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object
-inspection
-
-
-
-Interpreter Tools
-:::::::::::::::::
-
-
-virtualenv
-----------
-
-Virtualenv is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.
-It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable.
-
-virtualenvwrapper
------------------
-
-Virtualenvwrapper makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
-
-::
-
- pip install virtualenvwrapper
-
-
-Put this into your `~/.bash_profile` (Linux/Mac) file:
-
-::
-
- export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
-
-This will prevent your virtualenvs from relying on your (global) site packages directory, so that they are completely separate..
-
-Other Tools
-:::::::::::
-
-IPython
--------
-
-::
-
- $ pip install ipython
-
-
-
-BPython
--------
-
-::
-
- $ pip install bpython
-
-
diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst
new file mode 100644
index 000000000..4198be8be
--- /dev/null
+++ b/docs/starting/install/linux.rst
@@ -0,0 +1,79 @@
+.. _install-linux:
+
+
+############################
+Installing Python 2 on Linux
+############################
+
+.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
+
+.. note::
+ Check out our :ref:`guide for installing Python 3 on Linux`.
+
+The latest versions of CentOS, Red Hat Enterprise Linux (RHEL) and Ubuntu
+**come with Python 2.7 out of the box**.
+
+To see which version of Python you have installed, open a command prompt and run
+
+.. code-block:: console
+
+ $ python2 --version
+
+However, with the growing popularity of Python 3, some distributions, such as
+Fedora, don't come with Python 2 pre-installed. You can install the ``python2``
+package with your distribution package manager:
+
+.. code-block:: console
+
+ $ sudo dnf install python2
+
+You do not need to install or configure anything else to use Python. Having
+said that, I would strongly recommend that you install the tools and libraries
+described in the next section before you start building Python applications
+for real-world use. In particular, you should always install Setuptools and pip, as
+it makes it much easier for you to use other third-party Python libraries.
+
+
+****************
+Setuptools & Pip
+****************
+
+The two most crucial third-party Python packages are `setuptools `_ and `pip `_.
+
+Once installed, you can download, install and uninstall any compliant Python software
+product with a single command. It also enables you to add this network installation
+capability to your own Python software with very little work.
+
+Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
+pip by default.
+
+To see if pip is installed, open a command prompt and run
+
+.. code-block:: console
+
+ $ command -v pip
+
+To install pip, `follow the official pip installation guide `_ - this will automatically install the latest version of setuptools.
+
+
+********************
+Virtual Environments
+********************
+
+A Virtual Environment is a tool to keep the dependencies required by different projects
+in separate places, by creating virtual Python environments for them. It solves the
+"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
+your global site-packages directory clean and manageable.
+
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
+
+To start using this and see more information: :ref:`Virtual Environments ` docs.
+
+You can also use :ref:`virtualenvwrapper ` to make it easier to
+manage your virtual environments.
+
+--------------------------------
+
+This page is a remixed version of `another guide `_,
+which is available under the same license.
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
new file mode 100644
index 000000000..4a8a8e03b
--- /dev/null
+++ b/docs/starting/install/osx.rst
@@ -0,0 +1,134 @@
+.. _install-osx:
+
+
+###############################
+Installing Python 2 on Mac OS X
+###############################
+
+.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
+
+.. note::
+ Check out our :ref:`guide for installing Python 3 on OS X`.
+
+**Mac OS X comes with Python 2.7 out of the box between versions 10.8 and 12.3.**
+
+If your Mac OS X version is between the above versions,
+you do not need to install or configure anything else to use Python. Having said
+that, I would strongly recommend that you install the tools and libraries
+described in the next section before you start building Python applications for
+real-world use. In particular, you should always install Setuptools, as it makes
+it much easier for you to install and manage other third-party Python libraries.
+
+The version of Python that ships with OS X is great for learning, but it's not
+good for development. The version shipped with OS X may be out of date from the
+`official current Python release `_,
+which is considered the stable production version.
+
+
+**************
+Doing it Right
+**************
+
+Let's install a real version of Python.
+
+Before installing Python, you'll need to install 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.
+
+.. 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.
+
+To `install Homebrew `_, open :file:`Terminal` or
+your favorite OS X terminal emulator and run
+
+.. code-block:: console
+
+ $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
+The script will explain what changes it will make and prompt you before the
+installation begins.
+Once you've installed Homebrew, insert the Homebrew directory at the top
+of your :envvar:`PATH` environment variable. You can do this by adding the following
+line at the bottom of your :file:`~/.profile` file
+
+.. code-block:: console
+
+ export PATH="/usr/local/bin:/usr/local/sbin:$PATH"
+
+Now, we can install Python 2.7:
+
+.. code-block:: console
+
+ $ brew install python@2
+
+Because ``python@2`` is a "keg", we need to update our ``PATH`` again, to point at our new installation:
+
+.. code-block:: console
+
+ export PATH="/usr/local/opt/python@2/libexec/bin:$PATH"
+
+Homebrew names the executable ``python2`` so that you can still run the system Python via the executable ``python``.
+
+
+.. code-block:: console
+
+ $ python -V # Homebrew installed Python 3 interpreter (if installed)
+ $ python2 -V # Homebrew installed Python 2 interpreter
+ $ python3 -V # Homebrew installed Python 3 interpreter (if installed)
+
+
+****************
+Setuptools & Pip
+****************
+
+Homebrew installs Setuptools and ``pip`` for you.
+
+Setuptools enables you to download and install any compliant Python
+software over a network (usually the Internet) with a single command
+(``easy_install``). It also enables you to add this network installation
+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 `_,
+and is actively maintained.
+
+.. code-block:: console
+
+ $ pip2 -V # pip pointing to the Homebrew installed Python 2 interpreter
+ $ pip -V # pip pointing to the Homebrew installed Python 3 interpreter (if installed)
+
+
+********************
+Virtual Environments
+********************
+
+A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep the dependencies required by different projects
+in separate places, by creating virtual Python environments for them. It solves the
+"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
+your global site-packages directory clean and manageable.
+
+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.
+
+--------------------------------
+
+This page is a remixed version of `another guide `_,
+which is available under the same license.
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
new file mode 100644
index 000000000..67f8885d6
--- /dev/null
+++ b/docs/starting/install/win.rst
@@ -0,0 +1,96 @@
+.. _install-windows:
+
+
+##############################
+Installing Python 2 on Windows
+##############################
+
+.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
+
+.. note::
+ Check out our :ref:`guide for installing Python 3 on Windows`.
+
+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 `_ .
+
+The Windows version is provided as an MSI package. To install it manually, just
+double-click the file. The MSI package format allows Windows administrators to
+automate installation with their standard tools.
+
+By design, Python installs to a directory with the version number embedded,
+e.g. Python version 2.7 will install at :file:`C:\\Python27\\`, so that you can
+have multiple versions of Python on the
+same system without conflicts. Of course, only one interpreter can be the
+default application for Python file types. It also does not automatically
+modify the :envvar:`PATH` environment variable, so that you always have control over
+which copy of Python is run.
+
+Typing the full path name for a Python interpreter each time quickly gets
+tedious, so add the directories for your default Python version to the :envvar:`PATH`.
+Assuming that your Python installation is in :file:`C:\\Python27\\`, add this to your
+:envvar:`PATH`:
+
+.. code-block:: doscon
+
+ C:\Python27\;C:\Python27\Scripts\
+
+You can do this easily by running the following in ``powershell``:
+
+.. code-block:: powershell
+
+ [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User")
+
+This is also an option during the installation process.
+
+The second (:file:`Scripts`) directory receives command files when certain
+packages are installed, so it is a very useful addition.
+You do not need to install or configure anything else to use Python. Having
+said that, I would strongly recommend that you install the tools and libraries
+described in the next section before you start building Python applications for
+real-world use. In particular, you should always install Setuptools, as it
+makes it much easier for you to use other third-party Python libraries.
+
+
+****************
+Setuptools + Pip
+****************
+
+The two most crucial third-party Python packages are `setuptools `_ and `pip `_.
+
+Once installed, you can download, install and uninstall any compliant Python software
+product with a single command. It also enables you to add this network installation
+capability to your own Python software with very little work.
+
+Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
+pip by default.
+
+To see if pip is installed, open a command prompt and run
+
+.. code-block:: doscon
+
+ command -v pip
+
+To install pip, `follow the official pip installation guide `_ - this will automatically install the latest version of setuptools.
+
+
+********************
+Virtual Environments
+********************
+
+A Virtual Environment is a tool to keep the dependencies required by different projects
+in separate places, by creating virtual Python environments for them. It solves the
+"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
+your global site-packages directory clean and manageable.
+
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
+
+To start using this and see more information: :ref:`Virtual Environments ` docs.
+
+
+--------------------------------
+
+This page is a remixed version of `another guide `_,
+which is available under the same license.
diff --git a/docs/starting/install3/linux.rst b/docs/starting/install3/linux.rst
new file mode 100644
index 000000000..b02204bc0
--- /dev/null
+++ b/docs/starting/install3/linux.rst
@@ -0,0 +1,117 @@
+.. _install3-linux:
+
+
+############################
+Installing Python 3 on Linux
+############################
+
+.. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg
+
+This document describes how to install Python 3.6 or 3.8 on Ubuntu Linux machines.
+
+To see which version of Python 3 you have installed, open a command prompt and run
+
+.. code-block:: console
+
+ $ python3 --version
+
+If you are using Ubuntu 16.10 or newer, then you can easily install Python 3.6 with the following commands::
+
+ $ sudo apt-get update
+ $ sudo apt-get install python3.6
+
+If you're using another version of Ubuntu (e.g. the latest LTS release) or you want to use a more current Python, we recommend using the `deadsnakes PPA `_ to install Python 3.8::
+
+ $ sudo apt-get install software-properties-common
+ $ sudo add-apt-repository ppa:deadsnakes/ppa
+ $ sudo apt-get update
+ $ sudo apt-get install python3.8
+
+If you are using other Linux distribution, chances are you already have Python 3
+pre-installed as well. If not, use your distribution's package manager.
+For example on Fedora, you would use `dnf`:
+
+.. code-block:: console
+
+ $ sudo dnf install python3
+
+Note that if the version of the ``python3`` package is not recent enough
+for you, there may be ways of installing more recent versions as well,
+depending on you distribution. For example installing the ``python3.9`` package
+on Fedora 32 to get Python 3.9. If you are a Fedora user, you might want
+to read about `multiple Python versions available in Fedora`_.
+
+.. _multiple Python versions available in Fedora: https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html
+
+
+*********************
+Working with Python 3
+*********************
+
+At this point, you may have system Python 2.7 available as well.
+
+.. code-block:: console
+
+ $ python
+
+This might launch the Python 2 interpreter.
+
+.. code-block:: console
+
+ $ python3
+
+This will always launch the Python 3 interpreter.
+
+
+****************
+Setuptools & Pip
+****************
+
+The two most crucial third-party Python packages are `setuptools `_ and `pip `_.
+
+Once installed, you can download, install and uninstall any compliant Python software
+product with a single command. It also enables you to add this network installation
+capability to your own Python software with very little work.
+
+Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
+pip by default.
+
+To see if pip is installed, open a command prompt and run
+
+.. code-block:: console
+
+ $ command -v pip
+
+To install pip, `follow the official pip installation guide `_ - this will automatically install the latest version of setuptools.
+
+Note that on some Linux distributions including Ubuntu and Fedora the ``pip``
+command is meant for Python 2, while the ``pip3`` command is meant for Python 3.
+
+.. code-block:: console
+
+ $ command -v pip3
+
+However, when using virtual environments (described below), you don't need to
+care about that.
+
+
+*****************************
+Pipenv & Virtual Environments
+*****************************
+
+The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
+
+A Virtual Environment is a tool to keep the dependencies required by different projects
+in separate places, by creating virtual Python environments for them. It solves the
+"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
+your global site-packages directory clean and manageable.
+
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
+
+So, onward! To the :ref:`Pipenv & Virtual Environments ` docs!
+
+--------------------------------
+
+This page is a remixed version of `another guide