├── .gitignore
├── .travis.yml
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── Makefile
├── Readme.rst
├── TODO.rst
├── docs
    ├── 404.rst
    ├── Makefile
    ├── _extra
    │   ├── _redirects
    │   ├── ads.txt
    │   └── robots.txt
    ├── _static
    │   ├── guide-book-cover.jpg
    │   ├── pep-0001-1.png
    │   ├── photos
    │   │   ├── 32800783863_11a00db52c_k_d.jpg
    │   │   ├── 32800805573_568d6b72fd_k_d.jpg
    │   │   ├── 33175624924_7febc46cc4_k_d.jpg
    │   │   ├── 33175625804_e225b90f3e_k_d.jpg
    │   │   ├── 33467946364_3e59bd376a_k_d.jpg
    │   │   ├── 33573755856_7f43d43adf_k_d.jpg
    │   │   ├── 33573767786_eececc5d27_k_d.jpg
    │   │   ├── 33573769116_49c1ef51e7_k_d.jpg
    │   │   ├── 33888714601_a1f7d020a2_k_d.jpg
    │   │   ├── 33907143624_cd621b535c_k_d.jpg
    │   │   ├── 33907149294_82d7535a6c_k_d.jpg
    │   │   ├── 33907150054_5ee79e8940_k_d.jpg
    │   │   ├── 33907150594_9abba7ad0a_k_d.jpg
    │   │   ├── 33907151034_e0a9e53402_k_d.jpg
    │   │   ├── 33907151224_0574e7dfc2_k_d.jpg
    │   │   ├── 33907152464_a99fdcc8de_k_d.jpg
    │   │   ├── 33907152824_bf91078cc1_k_d.jpg
    │   │   ├── 33925223870_97e44f5629_k_d.jpg
    │   │   ├── 33928819683_97b5c6a184_k_d.jpg
    │   │   ├── 33928823133_2f3d32cf32_k_d.jpg
    │   │   ├── 34018729885_002ced9b54_k_d.jpg
    │   │   ├── 34018732105_f0e6758859_k_d.jpg
    │   │   ├── 34151833832_6bdfd930af_k_d.jpg
    │   │   ├── 34268661876_442428e122_k_d.jpg
    │   │   ├── 34309496175_b82d104282_k_d.jpg
    │   │   ├── 34364815780_bea6614025_k_d.jpg
    │   │   ├── 34435687940_8f73fc1fa6_k_d.jpg
    │   │   ├── 34435688380_b5a740762b_k_d.jpg
    │   │   ├── 34435688560_4cc2a7bcbb_k_d.jpg
    │   │   ├── 34435689480_2e6f358510_k_d.jpg
    │   │   ├── 34435690330_11930b5987_k_d.jpg
    │   │   ├── 34435690580_3afec7d4cd_k_d.jpg
    │   │   ├── 34484834733_5b80f65ab1_k_d.jpg
    │   │   ├── 34575689432_3de8e9a348_k_d.jpg
    │   │   ├── 34689432801_78d97ecec9_k_d.jpg
    │   │   ├── 34689452831_93d7fd0571_k_d.jpg
    │   │   ├── 34725946825_0f85497e60_k_d.jpg
    │   │   ├── 34725951345_c8f5959a2e_k_d.jpg
    │   │   ├── 35254379756_c9fe23f843_k_d.jpg
    │   │   ├── 35294660055_42c02b2316_k_d.jpg
    │   │   ├── 35620636012_f66aa88f93_k_d.jpg
    │   │   ├── 36137232412_fdcb0f84eb_k_d.jpg
    │   │   └── 36137234682_be6898bf57_k_d.jpg
    │   ├── python-guide-logo.png
    │   └── social-card.jpg
    ├── _templates
    │   ├── hacks.html
    │   ├── layout.html
    │   ├── sidebarintro.html
    │   └── sidebarlogo.html
    ├── _themes
    │   ├── .gitignore
    │   ├── LICENSE
    │   └── flask_theme_support.py
    ├── conf.py
    ├── contents.rst.inc
    ├── dev
    │   ├── env.rst
    │   ├── pip-virtualenv.rst
    │   └── virtualenvs.rst
    ├── index.rst
    ├── intro
    │   ├── community.rst
    │   ├── documentation.rst
    │   ├── duction.rst
    │   ├── learning.rst
    │   └── news.rst
    ├── make.bat
    ├── notes
    │   ├── contribute.rst
    │   ├── license.rst
    │   └── styleguide.rst
    ├── scenarios
    │   ├── admin.rst
    │   ├── ci.rst
    │   ├── cli.rst
    │   ├── clibs.rst
    │   ├── client.rst
    │   ├── crypto.rst
    │   ├── db.rst
    │   ├── gui.rst
    │   ├── imaging.rst
    │   ├── json.rst
    │   ├── ml.rst
    │   ├── network.rst
    │   ├── scientific.rst
    │   ├── scrape.rst
    │   ├── serialization.rst
    │   ├── speed.rst
    │   ├── web.rst
    │   └── xml.rst
    ├── shipping
    │   ├── freezing.rst
    │   ├── packaging.rst
    │   └── publishing.rst
    ├── starting
    │   ├── install
    │   │   ├── linux.rst
    │   │   ├── osx.rst
    │   │   └── win.rst
    │   ├── install3
    │   │   ├── linux.rst
    │   │   ├── osx.rst
    │   │   └── win.rst
    │   ├── installation.rst
    │   └── which-python.rst
    └── writing
    │   ├── documentation.rst
    │   ├── gotchas.rst
    │   ├── license.rst
    │   ├── logging.rst
    │   ├── reading.rst
    │   ├── structure.rst
    │   ├── style.rst
    │   └── tests.rst
├── ext
    └── python-guide-logo.ai
├── make.bat
├── requirements-to-freeze.txt
├── requirements.txt
└── runtime.txt


/.gitignore:
--------------------------------------------------------------------------------
 1 | docs/_build
 2 | .idea
 3 | 
 4 | # Ignore irrelevant files from the Sublime Text editor
 5 | *.sublime-workspace
 6 | *.sublime-project
 7 | 
 8 | # Ignore .hgignore for contributors using Mercurial.
 9 | .hgignore
10 | 
11 | # Ignore files generated during build
12 | build/
13 | 
14 | venv/
15 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | sudo: false
2 | language: python
3 | python:
4 |   - "3.6"
5 | install: pip install sphinx
6 | script:
7 |   - make doctest
8 |   - make html
9 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | Be cordial or be on your way.
2 | 
3 | https://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way
4 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | How to contribute
 2 | -----------------
 3 | 
 4 | This guide is under heavy development. If you would like to contribute, please
 5 | see:
 6 | 
 7 | https://docs.python-guide.org/notes/contribute/
 8 | 
 9 | How to test your changes
10 | ------------------------
11 | 
12 | 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).
13 | 
14 | ``` bash
15 | pip install --user sphinx
16 | ```
17 | 
18 | 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/`
19 | 
20 | After navigating to this folder, you can then use Python's built in web server to view your changes locally:
21 | 
22 | ``` bash
23 | python3 -m http.server
24 | ```
25 | 
26 | 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:
27 | 
28 | ``` bash
29 | python3 -m http.server 8005 --bind 127.0.0.1
30 | ```
31 | 
32 | Style Guide
33 | -----------
34 | 
35 | For all contributions, please follow the `Guide Style Guide`:
36 | 
37 | https://docs.python-guide.org/notes/styleguide/
38 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | .PHONY: build
2 | build: html
3 | 
4 | # this pattern rule lets you run "make build" (or any other target
5 | # in docs/Makefile) in this directory as though you were in docs/
6 | %:
7 | 	cd docs && make $@
8 | 


--------------------------------------------------------------------------------
/Readme.rst:
--------------------------------------------------------------------------------
 1 | Hitchhiker's Guide to Python
 2 | ============================
 3 | 
 4 | **Python Best Practices Guidebook**
 5 | 
 6 | → Read the free guide at: `docs.python-guide.org <https://docs.python-guide.org>`_
 7 | 
 8 | .. image:: https://farm1.staticflickr.com/628/33173824932_58add34581_k_d.jpg
 9 | 
10 | -----------
11 | 
12 | **Work in progress. If you'd like to help, please do. There's a lot of work to
13 | be done.**
14 | 
15 | This guide is currently under heavy development. This opinionated guide
16 | exists to provide both novice and expert Python developers a best practice
17 | handbook to the installation, configuration, and usage of Python on a daily
18 | basis.
19 | 
20 | 
21 | Topics include:
22 | 
23 | - Platform and version-specific installations
24 | - Py2app, Py2exe, bbfreeze, pyInstaller
25 | - Pip
26 | - Numpy, scipy, statpy, pyplot, matplotlib
27 | - Virtualenv
28 | - Fabric
29 | - Exhaustive module recommendations, grouped by topic/purpose
30 | - Which libraries to use for what
31 | - Server configurations & tools for various web frameworks
32 | - Documentation: writing it
33 | - Testing: Jenkins & tox guides
34 | - How to easily interface ``hg`` from ``git``
35 | 
36 | If you aren't fond of reading reStructuredText, there is an
37 | almost up-to-date `HTML version at docs.python-guide.org
38 | <https://docs.python-guide.org>`_.
39 | 


--------------------------------------------------------------------------------
/TODO.rst:
--------------------------------------------------------------------------------
1 | * Establish "use this" vs "alternatives are...." recommendations
2 | 
3 | .. todolist::


--------------------------------------------------------------------------------
/docs/404.rst:
--------------------------------------------------------------------------------
 1 | :orphan:
 2 | 
 3 | #################
 4 | 404 — Not Found
 5 | #################
 6 | 
 7 | **Sorry, but we couldn't find the page you requested.**
 8 | 
 9 | It looks like this was the result of either:
10 | 
11 | - a mistyped address
12 | - an out-of-date link
13 | 
14 | `Click here to go back to the homepage. <https://docs.python-guide.org/>`_
15 | 
16 | Or, try `searching <https://docs.python-guide.org/search/>`_.
17 | 
18 | .. raw:: html
19 | 
20 |     <script>
21 |     ga('send', {
22 |         hitType: 'event',
23 |         eventCategory: 'error',
24 |         eventAction: '404',
25 |         eventLabel: document.referrer,
26 |         nonInteraction: true
27 |       });
28 |     </script>
29 | 


--------------------------------------------------------------------------------
/docs/Makefile:
--------------------------------------------------------------------------------
  1 | # Makefile for Sphinx documentation
  2 | #
  3 | 
  4 | # You can set these variables from the command line.
  5 | SPHINXOPTS    =
  6 | SPHINXBUILD   = sphinx-build
  7 | PAPER         =
  8 | BUILDDIR      = _build
  9 | 
 10 | # User-friendly check for sphinx-build
 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 12 | $(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/)
 13 | endif
 14 | 
 15 | # Internal variables.
 16 | PAPEROPT_a4     = -D latex_paper_size=a4
 17 | PAPEROPT_letter = -D latex_paper_size=letter
 18 | ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 19 | # the i18n builder cannot share the environment and doctrees with the others
 20 | I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 21 | 
 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man changes linkcheck doctest gettext
 23 | 
 24 | help:
 25 | 	@echo "Please use \`make <target>' where <target> is one of"
 26 | 	@echo "  html       to make standalone HTML files"
 27 | 	@echo "  dirhtml    to make HTML files named index.html in directories"
 28 | 	@echo "  singlehtml to make a single large HTML file"
 29 | 	@echo "  pickle     to make pickle files"
 30 | 	@echo "  json       to make JSON files"
 31 | 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 32 | 	@echo "  qthelp     to make HTML files and a qthelp project"
 33 | 	@echo "  devhelp    to make HTML files and a Devhelp project"
 34 | 	@echo "  epub       to make an epub"
 35 | 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 36 | 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 37 | 	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 38 | 	@echo "  text       to make text files"
 39 | 	@echo "  man        to make manual pages"
 40 | 	@echo "  texinfo    to make Texinfo files"
 41 | 	@echo "  info       to make Texinfo files and run them through makeinfo"
 42 | 	@echo "  gettext    to make PO message catalogs"
 43 | 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 44 | 	@echo "  xml        to make Docutils-native XML files"
 45 | 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 46 | 	@echo "  linkcheck  to check all external links for integrity"
 47 | 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 48 | 
 49 | clean:
 50 | 	rm -rf $(BUILDDIR)/*
 51 | 
 52 | html:
 53 | 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 54 | 	@echo
 55 | 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 56 | 
 57 | dirhtml:
 58 | 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 59 | 	@echo
 60 | 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 61 | 
 62 | netlify: dirhtml
 63 | 	@cp $(BUILDDIR)/dirhtml/404/index.html $(BUILDDIR)/dirhtml/404.html
 64 | 	@sed -i -e 's/src="..\//src="\//g' $(BUILDDIR)/dirhtml/404.html
 65 | 	@sed -i -e 's/href="..\//href="\//g' $(BUILDDIR)/dirhtml/404.html
 66 | 	@cp _extra/* $(BUILDDIR)/dirhtml/
 67 | 
 68 | singlehtml:
 69 | 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 70 | 	@echo
 71 | 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 72 | 
 73 | pickle:
 74 | 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 75 | 	@echo
 76 | 	@echo "Build finished; now you can process the pickle files."
 77 | 
 78 | json:
 79 | 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 80 | 	@echo
 81 | 	@echo "Build finished; now you can process the JSON files."
 82 | 
 83 | htmlhelp:
 84 | 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 85 | 	@echo
 86 | 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 87 | 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 88 | 
 89 | qthelp:
 90 | 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 91 | 	@echo
 92 | 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 93 | 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 94 | 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pythonguide.qhcp"
 95 | 	@echo "To view the help file:"
 96 | 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pythonguide.qhc"
 97 | 
 98 | devhelp:
 99 | 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
100 | 	@echo
101 | 	@echo "Build finished."
102 | 	@echo "To view the help file:"
103 | 	@echo "# mkdir -p $$HOME/.local/share/devhelp/pythonguide"
104 | 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pythonguide"
105 | 	@echo "# devhelp"
106 | 
107 | epub:
108 | 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
109 | 	@echo
110 | 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
111 | 
112 | latex:
113 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
114 | 	@echo
115 | 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
116 | 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
117 | 	      "(use \`make latexpdf' here to do that automatically)."
118 | 
119 | latexpdf:
120 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121 | 	@echo "Running LaTeX files through pdflatex..."
122 | 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
123 | 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124 | 
125 | latexpdfja:
126 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
127 | 	@echo "Running LaTeX files through platex and dvipdfmx..."
128 | 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
129 | 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
130 | 
131 | text:
132 | 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
133 | 	@echo
134 | 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
135 | 
136 | man:
137 | 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
138 | 	@echo
139 | 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
140 | 
141 | texinfo:
142 | 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
143 | 	@echo
144 | 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
145 | 	@echo "Run \`make' in that directory to run these through makeinfo" \
146 | 	      "(use \`make info' here to do that automatically)."
147 | 
148 | info:
149 | 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
150 | 	@echo "Running Texinfo files through makeinfo..."
151 | 	make -C $(BUILDDIR)/texinfo info
152 | 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
153 | 
154 | gettext:
155 | 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
156 | 	@echo
157 | 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
158 | 
159 | changes:
160 | 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
161 | 	@echo
162 | 	@echo "The overview file is in $(BUILDDIR)/changes."
163 | 
164 | linkcheck:
165 | 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
166 | 	@echo
167 | 	@echo "Link check complete; look for any errors in the above output " \
168 | 	      "or in $(BUILDDIR)/linkcheck/output.txt."
169 | 
170 | doctest:
171 | 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
172 | 	@echo "Testing of doctests in the sources finished, look at the " \
173 | 	      "results in $(BUILDDIR)/doctest/output.txt."
174 | 
175 | xml:
176 | 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
177 | 	@echo
178 | 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
179 | 
180 | pseudoxml:
181 | 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
182 | 	@echo
183 | 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
184 | 
185 | serve:
186 | 	cd $(BUILDDIR)/dirhtml && python3 -m http.server 8005
187 | 


--------------------------------------------------------------------------------
/docs/_extra/_redirects:
--------------------------------------------------------------------------------
 1 | # Redirect rules
 2 | # Docs: https://www.netlify.com/docs/redirects/
 3 | 
 4 | # Redirect http to https (avoid one extra hop with an explicit rule for /en/latest/)
 5 | http://docs.python-guide.org/en/latest/*        https://docs.python-guide.org/:splat       301!
 6 | http://docs.python-guide.org/*                  https://docs.python-guide.org/:splat       301!
 7 | 
 8 | # Redirect RTD prefix to /
 9 | /en/latest/*                                    /:splat                                    301!
10 | 
11 | # Redirect domain aliases to primary domain
12 | http://python-guide.org/*                       http://docs.python-guide.org/:splat        301!
13 | https://python-guide.org/*                      https://docs.python-guide.org/:splat       301!
14 | 
15 | # Redirect Netlify version to primary domain
16 | https://python-guide.netlify.com/*              https://docs.python-guide.org/:splat       301!
17 | 
18 | /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
19 | 


--------------------------------------------------------------------------------
/docs/_extra/robots.txt:
--------------------------------------------------------------------------------
1 | User-agent: *
2 | Disallow:
3 | 


--------------------------------------------------------------------------------
/docs/_static/guide-book-cover.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/guide-book-cover.jpg


--------------------------------------------------------------------------------
/docs/_static/pep-0001-1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/pep-0001-1.png


--------------------------------------------------------------------------------
/docs/_static/photos/32800783863_11a00db52c_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/32800783863_11a00db52c_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33573767786_eececc5d27_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33573767786_eececc5d27_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907143624_cd621b535c_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907143624_cd621b535c_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33925223870_97e44f5629_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33925223870_97e44f5629_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34018729885_002ced9b54_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34018729885_002ced9b54_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34018732105_f0e6758859_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34018732105_f0e6758859_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34268661876_442428e122_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34268661876_442428e122_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34309496175_b82d104282_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34309496175_b82d104282_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34364815780_bea6614025_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34364815780_bea6614025_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435688380_b5a740762b_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435688380_b5a740762b_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435689480_2e6f358510_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435689480_2e6f358510_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435690330_11930b5987_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435690330_11930b5987_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34725946825_0f85497e60_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34725946825_0f85497e60_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/35294660055_42c02b2316_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/35294660055_42c02b2316_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/photos/36137234682_be6898bf57_k_d.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/photos/36137234682_be6898bf57_k_d.jpg


--------------------------------------------------------------------------------
/docs/_static/python-guide-logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/python-guide-logo.png


--------------------------------------------------------------------------------
/docs/_static/social-card.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/docs/_static/social-card.jpg


--------------------------------------------------------------------------------
/docs/_templates/hacks.html:
--------------------------------------------------------------------------------
1 | <!-- Alabaster (krTheme++) Hacks -->
2 | 


--------------------------------------------------------------------------------
/docs/_templates/layout.html:
--------------------------------------------------------------------------------
  1 | {% extends "!layout.html" %}
  2 | 
  3 | {%- block extrahead %}
  4 |   {# No super() because we want to avoid loading an empty custom.css file #}
  5 | 
  6 |   {# <meta name="viewport" content="width=device-width, initial-scale=0.75, maximum-scale=0.75" /> #}
  7 | 
  8 |   <meta name="viewport" content="width=device-width, initial-scale=1">
  9 |   <style>
 10 |     div.body {
 11 |       min-width: initial;
 12 |       max-width: initial;
 13 |     }
 14 |   </style>
 15 | 
 16 |   {% if pagename == 'index' %}
 17 |   <link rel="canonical" href="https://docs.python-guide.org/"/>
 18 |   <meta property="og:url" content="https://docs.python-guide.org/">
 19 |   {% elif pagename == '404' %}
 20 |   {# No canonical on our 404 template. #}
 21 |   {% else %}
 22 |   <link rel="canonical" href="https://docs.python-guide.org/{{ pagename }}/"/>
 23 |   <meta property="og:url" content="https://docs.python-guide.org/{{ pagename }}">
 24 |   {% endif %}
 25 | 
 26 |   <link rel="icon" type="image/png" href="https://media.readthedocs.org/images/favicon.png">
 27 | 
 28 |   <meta name="google-site-verification" content="013PxE2_8KX9jdUSC5gr8QsfdxTXr1mFgmD9zplp5II" />
 29 | 
 30 |   <meta name="twitter:card" content="summary">
 31 |   <meta property="twitter:image" content="https://docs.python-guide.org/_static/social-card.jpg">
 32 |   <meta property="og:image" content="https://docs.python-guide.org/_static/social-card.jpg">
 33 |   <meta property="og:title" content="{{ title }}{{ titlesuffix }}">
 34 |   <meta property="og:type" content="article">
 35 |   {%- if metatags is defined %}
 36 |   {# FIXME: For some reason the `meta` dict is always empty. Extract the desc from the `metatags` text.  #}
 37 |   <meta property="og:description" content="{{ metatags[15:-24] }}">
 38 |   {%- endif %}
 39 | 
 40 |   <script>window.rp_prop_id = '29182759436';</script>
 41 |   <script src="https://srv.realpython.net/tag.js" async></script>
 42 | 
 43 |   <script src="https://d31vxm9ubutrmw.cloudfront.net/static/js/2169.js"></script>
 44 | 
 45 |   {# Alabaster theme native GA integration is outdated (ga.js). #}
 46 |   {# Insert our own GA snippet instead. #}
 47 |   <script>
 48 |     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
 49 |     (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
 50 |     m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 51 |     })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
 52 | 
 53 |     ga('create', 'UA-37242602-11', 'auto');
 54 |     ga('send', 'pageview');
 55 |     </script>
 56 | {% endblock %}
 57 | 
 58 | {# From: https://github.com/bitprophet/alabaster/blob/5f249677242be96601e034edb3697b7482a6abcf/alabaster/layout.html #}
 59 | {# Nav should appear before content, not after #}
 60 | {%- block content %}
 61 | {%- if theme_fixed_sidebar|lower == 'true' %}
 62 |   <div class="document">
 63 |     {{ sidebar() }}
 64 |     {%- block document %}
 65 |       <div class="documentwrapper">
 66 |       {%- if render_sidebar %}
 67 |         <div class="bodywrapper">
 68 |       {%- endif %}
 69 | 
 70 |           {%- block relbar_top %}
 71 |             {%- if theme_show_relbar_top|tobool %}
 72 |               <div class="related top">
 73 |                 &nbsp;
 74 |                 {{- rellink_markup () }}
 75 |               </div>
 76 |             {%- endif %}
 77 |           {% endblock %}
 78 | 
 79 |           <div class="body" role="main">
 80 |             <div style="display:block;position:relative; margin-bottom: 1em;">
 81 |               <div style="display:block;width:100%;padding-top:12.5%;"></div>
 82 |               <div class="rpad" data-unit="8x1" style="position:absolute;left:0;top:0;right:0;bottom:0;overflow:hidden;"></div>
 83 |             </div>
 84 |             {% block body %} {% endblock %}
 85 |           </div>
 86 | 
 87 |           {%- block relbar_bottom %}
 88 |             {%- if theme_show_relbar_bottom|tobool %}
 89 |               <div class="related bottom">
 90 |                 &nbsp;
 91 |                 {{- rellink_markup () }}
 92 |               </div>
 93 |             {%- endif %}
 94 |           {% endblock %}
 95 | 
 96 |       {%- if render_sidebar %}
 97 |         </div>
 98 |       {%- endif %}
 99 |       </div>
100 |     {%- endblock %}
101 |     <div class="clearer"></div>
102 |   </div>
103 | {%- else %}
104 | {{ super() }}
105 | {%- endif %}
106 | {%- endblock %}
107 | 
108 | {%- block footer %}
109 | <div class="footer">
110 |   <div style="text-align: center;" id="waldo-tag-2171"></div>
111 |   {% if show_copyright %}<p>&copy;{{ copyright }}</p>{% endif %}
112 | </div>
113 | {% endblock %}
114 | 


--------------------------------------------------------------------------------
/docs/_templates/sidebarintro.html:
--------------------------------------------------------------------------------
 1 | <p class="logo">
 2 |   <a href="{{ pathto(master_doc) }}">
 3 |     <img class="logo" src="{{ pathto('_static/python-guide-logo.png', 1) }}" title="The Hitchhiker's Guide to Python"/>
 4 |   </a>
 5 | </p>
 6 | 
 7 | <p style="margin-left:auto; margin-right: auto;"><iframe src="https://ghbtns.com/github-btn.html?user=realpython&repo=python-guide&type=watch&count=true&size=large" allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe></p>
 8 | 
 9 | <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
10 | <style>
11 | .algolia-autocomplete{
12 |   width: 100%;
13 |   height: 1.5em
14 | }
15 | .algolia-autocomplete a{
16 |   border-bottom: none !important;
17 | }
18 | #doc_search{
19 |   width: 100%;
20 |   height: 100%;
21 | }
22 | </style>
23 | <input id="doc_search" placeholder="Search the doc" autofocus/>
24 | <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js" onload="docsearch({
25 |   apiKey: '512b0d6c0c8578bed7662f5279c2249c',
26 |   indexName: 'python-guide',
27 |   inputSelector: '#doc_search',
28 |   debug: false // Set debug to true if you want to inspect the dropdown
29 | })" async></script>
30 | 
31 | <p>
32 |   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.
33 | </p>
34 | 
35 | <div style="display:block;position:relative;margin: 1em 0 1em 0;">
36 |   <div style="display:block;width:100%;padding-top:100%;"></div>
37 |   <div class="rpad" data-unit="1x1" style="position:absolute;left:0;top:0;right:0;bottom:0;overflow:hidden;"></div>
38 | </div>
39 | 
40 | <h3>O'Reilly Book</h3>
41 | 
42 | <p>This guide is now available in tangible book form!</p>
43 | 
44 | <p><a href="/guide-book" target="_blank"><img style="max-width: 100%; text-align: center;" src="/_static/guide-book-cover.jpg" alt="Python Guide Book Cover"></a></p>
45 | 
46 | <p>All proceeds are being directly donated to the <a href="https://djangogirls.org">DjangoGirls</a> organization.</p>
47 | 
48 | <h3>Contributors</h3>
49 | <p>
50 |   This guide is the result of the collaboration of
51 |   <a href="https://github.com/kennethreitz/python-guide/graphs/contributors">hundreds of people</a>
52 |   around the world, and your contributions
53 |   <a href="https://docs.python-guide.org/notes/contribute/">are welcome</a>!
54 | </p>
55 | 
56 | <h3>Useful Links</h3>
57 | <ul>
58 |   <li><a href="https://docs.python-guide.org/">The Guide Website</a></li>
59 |   <li><a href="https://github.com/realpython/python-guide">The Guide @ GitHub</a></li>
60 |   <li><a href="https://github.com/realpython/python-guide/issues">Issue Tracker</a></li>
61 |   <li><a href="https://media.readthedocs.org/pdf/python-guide/latest/python-guide.pdf">The Guide as a PDF</a></li>
62 | </ul>
63 | 
64 | <h3>Translations</h3>
65 | <ul>
66 |   <li><a href="https://docs.python-guide.org/">English</a></li>
67 |   <li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
68 |   <li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
69 |   <li><a href="https://python-guideja.readthedocs.io/ja/latest/">Japanese</a></li>
70 |   <li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
71 |   <li><a href="https://python-guide-fil.readthedocs.io/en/latest/">Filipino</a></li>
72 |   <li><a href="https://python-guide-pt-br.readthedocs.io/pt_BR/latest/">Brazilian Portuguese</a></li>
73 | </ul>
74 | 


--------------------------------------------------------------------------------
/docs/_templates/sidebarlogo.html:
--------------------------------------------------------------------------------
 1 | <p class="logo">
 2 |   <a href="{{ pathto(master_doc) }}">
 3 |     <img class="logo" src="{{ pathto('_static/python-guide-logo.png', 1) }}" title="The Hitchhiker's Guide to Python"/>
 4 |   </a>
 5 | </p>
 6 | 
 7 | <p style="margin-left:auto; margin-right: auto;"><iframe src="https://ghbtns.com/github-btn.html?user=realpython&repo=python-guide&type=watch&count=true&size=large" allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe></p>
 8 | 
 9 | <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
10 | <style>
11 | .algolia-autocomplete{
12 |   width: 100%;
13 |   height: 1.5em
14 | }
15 | .algolia-autocomplete a{
16 |   border-bottom: none !important;
17 | }
18 | #doc_search{
19 |   width: 100%;
20 |   height: 100%;
21 | }
22 | </style>
23 | <input id="doc_search" placeholder="Search the doc" autofocus/>
24 | <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js" onload="docsearch({
25 |   apiKey: '512b0d6c0c8578bed7662f5279c2249c',
26 |   indexName: 'python-guide',
27 |   inputSelector: '#doc_search',
28 |   debug: false // Set debug to true if you want to inspect the dropdown
29 | })" async></script>
30 | 
31 | <p>
32 |   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.
33 | </p>
34 | 
35 | <div style="display:block;position:relative;margin: 1em 0 1em 0;">
36 |   <div style="display:block;width:100%;padding-top:100%;"></div>
37 |   <div class="rpad" data-unit="1x1" style="position:absolute;left:0;top:0;right:0;bottom:0;overflow:hidden;"></div>
38 | </div>
39 | 
40 | <h3>O'Reilly Book</h3>
41 | 
42 | <p>This guide is now available in tangible book form!</p>
43 | 
44 | <p><a href="/guide-book" target="_blank"><img style="max-width: 100%; text-align: center;" src="/_static/guide-book-cover.jpg" alt="Python Guide Book Cover"></a></p>
45 | 
46 | <p>All proceeds are being directly donated to the <a href="https://djangogirls.org">DjangoGirls</a> organization.</p>
47 | 
48 | <h3>Translations</h3>
49 | <ul>
50 |   <li><a href="https://docs.python-guide.org/">English</a></li>
51 |   <li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
52 |   <li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
53 |   <li><a href="http://python-guideja.readthedocs.io/ja/latest/">Japanese</a></li>
54 |   <li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
55 |   <li><a href="http://python-guide-fil.readthedocs.io/en/latest/">Filipino</a></li>
56 |   <li><a href="http://python-guide-pt-br.readthedocs.io/pt_BR/latest/">Brazilian Portuguese</a></li>
57 | </ul>
58 | 


--------------------------------------------------------------------------------
/docs/_themes/.gitignore:
--------------------------------------------------------------------------------
1 | *.pyc
2 | *.pyo
3 | .DS_Store
4 | 


--------------------------------------------------------------------------------
/docs/_themes/LICENSE:
--------------------------------------------------------------------------------
 1 | Modifications: 
 2 | 
 3 | Copyright (c) 2010 Kenneth Reitz.
 4 | 
 5 | 
 6 | Original Project: 
 7 | 
 8 | Copyright (c) 2010 by Armin Ronacher.
 9 | 
10 | 
11 | Some rights reserved.
12 | 
13 | Redistribution and use in source and binary forms of the theme, with or
14 | without modification, are permitted provided that the following conditions
15 | are met:
16 | 
17 | * Redistributions of source code must retain the above copyright
18 |   notice, this list of conditions and the following disclaimer.
19 | 
20 | * Redistributions in binary form must reproduce the above
21 |   copyright notice, this list of conditions and the following
22 |   disclaimer in the documentation and/or other materials provided
23 |   with the distribution.
24 | 
25 | * The names of the contributors may not be used to endorse or
26 |   promote products derived from this software without specific
27 |   prior written permission.
28 | 
29 | We kindly ask you to only use these themes in an unmodified manner just
30 | for Flask and Flask-related products, not for unrelated projects.  If you
31 | like the visual style and want to use it for your own projects, please
32 | consider making some larger changes to the themes (such as changing
33 | font faces, sizes, colors or margins).
34 | 
35 | THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
36 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
37 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
38 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
39 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
40 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
41 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
42 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
43 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
44 | ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
45 | POSSIBILITY OF SUCH DAMAGE.
46 | 


--------------------------------------------------------------------------------
/docs/_themes/flask_theme_support.py:
--------------------------------------------------------------------------------
 1 | # flasky extensions.  flasky pygments style based on tango style
 2 | from pygments.style import Style
 3 | from pygments.token import Keyword, Name, Comment, String, Error, \
 4 |      Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
 5 | 
 6 | 
 7 | class FlaskyStyle(Style):
 8 |     background_color = "#f8f8f8"
 9 |     default_style = ""
10 | 
11 |     styles = {
12 |         # No corresponding class for the following:
13 |         #Text:                     "", # class:  ''
14 |         Whitespace:                "underline #f8f8f8",      # class: 'w'
15 |         Error:                     "#a40000 border:#ef2929", # class: 'err'
16 |         Other:                     "#000000",                # class 'x'
17 | 
18 |         Comment:                   "italic #8f5902", # class: 'c'
19 |         Comment.Preproc:           "noitalic",       # class: 'cp'
20 | 
21 |         Keyword:                   "bold #004461",   # class: 'k'
22 |         Keyword.Constant:          "bold #004461",   # class: 'kc'
23 |         Keyword.Declaration:       "bold #004461",   # class: 'kd'
24 |         Keyword.Namespace:         "bold #004461",   # class: 'kn'
25 |         Keyword.Pseudo:            "bold #004461",   # class: 'kp'
26 |         Keyword.Reserved:          "bold #004461",   # class: 'kr'
27 |         Keyword.Type:              "bold #004461",   # class: 'kt'
28 | 
29 |         Operator:                  "#582800",   # class: 'o'
30 |         Operator.Word:             "bold #004461",   # class: 'ow' - like keywords
31 | 
32 |         Punctuation:               "bold #000000",   # class: 'p'
33 | 
34 |         # because special names such as Name.Class, Name.Function, etc.
35 |         # are not recognized as such later in the parsing, we choose them
36 |         # to look the same as ordinary variables.
37 |         Name:                      "#000000",        # class: 'n'
38 |         Name.Attribute:            "#c4a000",        # class: 'na' - to be revised
39 |         Name.Builtin:              "#004461",        # class: 'nb'
40 |         Name.Builtin.Pseudo:       "#3465a4",        # class: 'bp'
41 |         Name.Class:                "#000000",        # class: 'nc' - to be revised
42 |         Name.Constant:             "#000000",        # class: 'no' - to be revised
43 |         Name.Decorator:            "#888",           # class: 'nd' - to be revised
44 |         Name.Entity:               "#ce5c00",        # class: 'ni'
45 |         Name.Exception:            "bold #cc0000",   # class: 'ne'
46 |         Name.Function:             "#000000",        # class: 'nf'
47 |         Name.Property:             "#000000",        # class: 'py'
48 |         Name.Label:                "#f57900",        # class: 'nl'
49 |         Name.Namespace:            "#000000",        # class: 'nn' - to be revised
50 |         Name.Other:                "#000000",        # class: 'nx'
51 |         Name.Tag:                  "bold #004461",   # class: 'nt' - like a keyword
52 |         Name.Variable:             "#000000",        # class: 'nv' - to be revised
53 |         Name.Variable.Class:       "#000000",        # class: 'vc' - to be revised
54 |         Name.Variable.Global:      "#000000",        # class: 'vg' - to be revised
55 |         Name.Variable.Instance:    "#000000",        # class: 'vi' - to be revised
56 | 
57 |         Number:                    "#990000",        # class: 'm'
58 | 
59 |         Literal:                   "#000000",        # class: 'l'
60 |         Literal.Date:              "#000000",        # class: 'ld'
61 | 
62 |         String:                    "#4e9a06",        # class: 's'
63 |         String.Backtick:           "#4e9a06",        # class: 'sb'
64 |         String.Char:               "#4e9a06",        # class: 'sc'
65 |         String.Doc:                "italic #8f5902", # class: 'sd' - like a comment
66 |         String.Double:             "#4e9a06",        # class: 's2'
67 |         String.Escape:             "#4e9a06",        # class: 'se'
68 |         String.Heredoc:            "#4e9a06",        # class: 'sh'
69 |         String.Interpol:           "#4e9a06",        # class: 'si'
70 |         String.Other:              "#4e9a06",        # class: 'sx'
71 |         String.Regex:              "#4e9a06",        # class: 'sr'
72 |         String.Single:             "#4e9a06",        # class: 's1'
73 |         String.Symbol:             "#4e9a06",        # class: 'ss'
74 | 
75 |         Generic:                   "#000000",        # class: 'g'
76 |         Generic.Deleted:           "#a40000",        # class: 'gd'
77 |         Generic.Emph:              "italic #000000", # class: 'ge'
78 |         Generic.Error:             "#ef2929",        # class: 'gr'
79 |         Generic.Heading:           "bold #000080",   # class: 'gh'
80 |         Generic.Inserted:          "#00A000",        # class: 'gi'
81 |         Generic.Output:            "#888",           # class: 'go'
82 |         Generic.Prompt:            "#745334",        # class: 'gp'
83 |         Generic.Strong:            "bold #000000",   # class: 'gs'
84 |         Generic.Subheading:        "bold #800080",   # class: 'gu'
85 |         Generic.Traceback:         "bold #a40000",   # class: 'gt'
86 |     }
87 | 


--------------------------------------------------------------------------------
/docs/contents.rst.inc:
--------------------------------------------------------------------------------
  1 | Getting Started with Python
  2 | ---------------------------
  3 | 
  4 | New to Python? Let's properly setup up your Python environment:
  5 | 
  6 | .. toctree::
  7 |    :maxdepth: 2
  8 | 
  9 |    starting/which-python
 10 | 
 11 | - Properly Install Python on your system:
 12 | 
 13 |  .. toctree::
 14 |     :maxdepth: 1
 15 | 
 16 |     starting/installation
 17 |     starting/install3/osx
 18 |     starting/install3/win
 19 |     starting/install3/linux
 20 |     starting/install/osx
 21 |     starting/install/win
 22 |     starting/install/linux
 23 | 
 24 | 
 25 | - Using Virtualenvs with Pipenv:
 26 | 
 27 |  .. toctree::
 28 |     :maxdepth: 2
 29 | 
 30 |     dev/virtualenvs
 31 | 
 32 | 
 33 | Python Development Environments
 34 | -------------------------------
 35 | 
 36 | This part of the guide focuses on the Python development environment,
 37 | and the best-practice tools that are available for writing Python code.
 38 | 
 39 | .. toctree::
 40 |    :maxdepth: 2
 41 | 
 42 |    dev/env
 43 |    dev/virtualenvs
 44 |    dev/pip-virtualenv
 45 | 
 46 | 
 47 | 
 48 | 
 49 | Writing Great Python Code
 50 | -------------------------
 51 | 
 52 | This part of the guide focuses on the best-practices for writing Python code.
 53 | 
 54 | .. toctree::
 55 |    :maxdepth: 2
 56 | 
 57 |    writing/structure
 58 |    writing/style
 59 |    writing/reading
 60 |    writing/documentation
 61 |    writing/tests
 62 |    writing/logging
 63 |    writing/gotchas
 64 |    writing/license
 65 | 
 66 | 
 67 | 
 68 | Scenario Guide for Python Applications
 69 | --------------------------------------
 70 | 
 71 | This part of the guide focuses on tool and module advice based on
 72 | different scenarios.
 73 | 
 74 | .. toctree::
 75 |    :maxdepth: 2
 76 | 
 77 |    scenarios/client
 78 |    scenarios/web
 79 |    scenarios/scrape
 80 |    scenarios/cli
 81 |    scenarios/gui
 82 |    scenarios/db
 83 |    scenarios/network
 84 |    scenarios/admin
 85 |    scenarios/ci
 86 |    scenarios/speed
 87 |    scenarios/scientific
 88 |    scenarios/imaging
 89 |    scenarios/serialization
 90 |    scenarios/xml
 91 |    scenarios/json
 92 |    scenarios/crypto
 93 |    scenarios/ml
 94 |    scenarios/clibs
 95 | 
 96 | 
 97 | Shipping Great Python Code
 98 | --------------------------
 99 | 
100 | This part of the guide focuses on sharing and deploying your Python code.
101 | 
102 | .. toctree::
103 |    :maxdepth: 2
104 | 
105 |    shipping/publishing
106 |    shipping/packaging
107 |    shipping/freezing
108 | 
109 | 
110 | Additional Notes
111 | ----------------
112 | 
113 | This part of the guide, which is mostly prose, begins with some
114 | background information about Python, and then focuses on next steps.
115 | 
116 | .. toctree::
117 |    :maxdepth: 2
118 | 
119 |    intro/duction
120 |    intro/community
121 |    intro/learning
122 |    intro/documentation
123 |    intro/news
124 | 
125 | .. note::
126 |    Notes defined within all diatonic and chromatic musical scales have been
127 |    intentionally excluded from this list of additional notes. Additionally,
128 |    this note.
129 | 
130 | 
131 | --------------------------------------
132 | 
133 | Contribution notes and legal information (for those interested).
134 | 
135 | .. toctree::
136 |    :maxdepth: 2
137 | 
138 |    notes/contribute
139 |    notes/license
140 |    notes/styleguide
141 | 


--------------------------------------------------------------------------------
/docs/dev/pip-virtualenv.rst:
--------------------------------------------------------------------------------
  1 | .. _pip-virtualenv:
  2 | 
  3 | Further Configuration of pip and Virtualenv
  4 | ===========================================
  5 | 
  6 | .. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg
  7 | 
  8 | Requiring an active virtual environment for ``pip``
  9 | ---------------------------------------------------
 10 | 
 11 | By now it should be clear that using virtual environments is a great way to
 12 | keep your development environment clean and keeping different projects'
 13 | requirements separate.
 14 | 
 15 | When you start working on many different projects, it can be hard to remember to
 16 | activate the related virtual environment when you come back to a specific
 17 | project.  As a result of this, it is very easy to install packages globally
 18 | while thinking that you are actually installing the package for the virtual
 19 | environment of the project. Over time this can result in a messy global package
 20 | list.
 21 | 
 22 | In order to make sure that you install packages to your active virtual
 23 | environment when you use ``pip install``, consider adding the following
 24 | line to your :file:`~/.bashrc` file:
 25 | 
 26 | .. code-block:: console
 27 | 
 28 |     export PIP_REQUIRE_VIRTUALENV=true
 29 | 
 30 | After saving this change and sourcing the :file:`~/.bashrc` file with
 31 | ``source ~/.bashrc``, pip will no longer let you install packages if you are not
 32 | in a virtual environment.  If you try to use ``pip install`` outside of a
 33 | virtual environment pip will gently remind you that an activated virtual
 34 | environment is needed to install packages.
 35 | 
 36 | .. code-block:: console
 37 | 
 38 |     $ pip install requests
 39 |     Could not find an activated virtualenv (required).
 40 | 
 41 | You can also do this configuration by editing your :file:`pip.conf` or
 42 | :file:`pip.ini` file. :file:`pip.conf` is used by Unix and Mac OS X operating
 43 | systems and it can be found at:
 44 | 
 45 | .. code-block:: console
 46 | 
 47 |     $HOME/.pip/pip.conf
 48 | 
 49 | Similarly, the :file:`pip.ini` file is used by Windows operating systems and it
 50 | can be found at:
 51 | 
 52 | .. code-block:: console
 53 | 
 54 |     %USERPROFILE%\pip\pip.ini
 55 | 
 56 | If you don't have a :file:`pip.conf` or :file:`pip.ini` file at these locations,
 57 | you can create a new file with the correct name for your operating system.
 58 | 
 59 | If you already have a configuration file, just add the following line under the
 60 | ``[global]`` settings to require an active virtual environment:
 61 | 
 62 | .. code-block:: console
 63 | 
 64 |     require-virtualenv = true
 65 | 
 66 | If you did not have a configuration file, you will need to create a new one and
 67 | add the following lines to this new file:
 68 | 
 69 | .. code-block:: console
 70 | 
 71 |     [global]
 72 |     require-virtualenv = true
 73 | 
 74 | 
 75 | You will of course need to install some packages globally (usually ones that
 76 | you use across different projects consistently) and this can be accomplished by
 77 | adding the following to your :file:`~/.bashrc` file:
 78 | 
 79 | .. code-block:: console
 80 | 
 81 |     gpip() {
 82 |         PIP_REQUIRE_VIRTUALENV=false pip "$@"
 83 |     }
 84 | 
 85 | After saving the changes and sourcing your :file:`~/.bashrc` file you can now
 86 | install packages globally by running ``gpip install``. You can change the name
 87 | of the function to anything you like, just keep in mind that you will have to
 88 | use that name when trying to install packages globally with pip.
 89 | 
 90 | Caching packages for future use
 91 | -------------------------------
 92 | 
 93 | Every developer has preferred libraries and when you are working on a lot of
 94 | different projects, you are bound to have some overlap between the libraries
 95 | that you use. For example, you may be using the ``requests`` library in a lot
 96 | of different projects.
 97 | 
 98 | It is surely unnecessary to re-download the same packages/libraries each time
 99 | you start working on a new project (and in a new virtual environment as a
100 | result). Fortunately, starting with version 6.0, pip provides an `on-by-default
101 | caching mechanism
102 | <https://pip.pypa.io/en/stable/reference/pip_install/#caching>`_ that doesn't
103 | need any configuration.
104 | 
105 | When using older versions, you can configure pip in such a way that it tries to
106 | reuse already installed packages, too.
107 | 
108 | On Unix systems, you can add the following line to your :file:`.bashrc` or
109 | :file:`.bash_profile` file.
110 | 
111 | .. code-block:: console
112 | 
113 |     export PIP_DOWNLOAD_CACHE=$HOME/.pip/cache
114 | 
115 | You can set the path to anywhere you like (as long as you have write
116 | access). After adding this line, ``source`` your :file:`.bashrc`
117 | (or :file:`.bash_profile`) file and you will be all set.
118 | 
119 | Another way of doing the same configuration is via the :file:`pip.conf` or
120 | :file:`pip.ini` files, depending on your system. If you are on Windows, you can
121 | add the following line to your :file:`pip.ini` file under ``[global]`` settings:
122 | 
123 | .. code-block:: console
124 | 
125 |     download-cache = %USERPROFILE%\pip\cache
126 | 
127 | Similarly, on Unix systems you should simply add the following line to your
128 | :file:`pip.conf` file under ``[global]`` settings:
129 | 
130 | .. code-block:: console
131 | 
132 |     download-cache = $HOME/.pip/cache
133 | 
134 | Even though you can use any path you like to store your cache, it is recommended
135 | that you create a new folder *in* the folder where your :file:`pip.conf` or
136 | :file:`pip.ini` file lives. If you don't trust yourself with all of this path
137 | voodoo, just use the values provided here and you will be fine.
138 | 


--------------------------------------------------------------------------------
/docs/index.rst:
--------------------------------------------------------------------------------
 1 | .. pythonguide documentation master file, created by
 2 |    sphinx-quickstart on Wed Aug  4 22:51:11 2010.
 3 |    You can adapt this file completely to your liking, but it should at least
 4 |    contain the root `toctree` directive.
 5 | 
 6 | .. meta::
 7 |    :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.
 8 | 
 9 | 
10 | #################################
11 | The Hitchhiker's Guide to Python!
12 | #################################
13 | 
14 | Greetings, Earthling! Welcome to The Hitchhiker's Guide to Python.
15 | 
16 | **This is a living, breathing guide.**  If you'd like to contribute,
17 | `fork us on GitHub <https://github.com/realpython/python-guide>`_!
18 | 
19 | This handcrafted guide exists to provide both novice and expert Python
20 | developers a best practice handbook for the installation, configuration, and
21 | usage of Python on a daily basis.
22 | 
23 | This guide is **opinionated** in a way that is almost, but not quite, entirely
24 | *unlike* Python's official documentation. You won't find a list of every Python web framework
25 | available here. Rather, you'll find a nice concise list of highly recommended
26 | options.
27 | 
28 | .. 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.
29 |   —*Kenneth Reitz*
30 | 
31 | Let's get started! But first, let's make sure you know where your towel is.
32 | 
33 | .. include:: contents.rst.inc
34 | 


--------------------------------------------------------------------------------
/docs/intro/community.rst:
--------------------------------------------------------------------------------
  1 | .. _the-community:
  2 | 
  3 | 
  4 | #############
  5 | The Community
  6 | #############
  7 | 
  8 | .. image:: /_static/photos/34689432801_78d97ecec9_k_d.jpg
  9 | 
 10 | 
 11 | ****
 12 | BDFL
 13 | ****
 14 | 
 15 | Guido van Rossum, the creator of Python, is often referred to as the BDFL — the
 16 | Benevolent Dictator For Life.
 17 | 
 18 | 
 19 | **************************
 20 | Python Software Foundation
 21 | **************************
 22 | 
 23 | 
 24 | The mission of the Python Software Foundation is to promote, protect, and
 25 | advance the Python programming language, and to support and facilitate the
 26 | growth of a diverse and international community of Python programmers.
 27 | 
 28 | `Learn More about the PSF <http://www.python.org/psf/>`_.
 29 | 
 30 | 
 31 | ****
 32 | PEPs
 33 | ****
 34 | 
 35 | PEPs are *Python Enhancement Proposals*. They describe changes to Python itself,
 36 | or the standards around it.
 37 | 
 38 | There are three different types of PEPs (as defined by :pep:`1`):
 39 | 
 40 |     **Standards**
 41 |         Describes a new feature or implementation.
 42 | 
 43 |     **Informational**
 44 |         Describes a design issue, general guidelines, or information to the
 45 |         community.
 46 | 
 47 |     **Process**
 48 |         Describes a process related to Python.
 49 | 
 50 | 
 51 | Notable PEPs
 52 | ~~~~~~~~~~~~
 53 | 
 54 | There are a few PEPs that could be considered required reading:
 55 | 
 56 | - :pep:`8`: The Python Style Guide.
 57 |     Read this. All of it. Follow it.
 58 | 
 59 | - :pep:`20`: The Zen of Python.
 60 |     A list of 19 statements that briefly explain the philosophy behind Python.
 61 | 
 62 | - :pep:`257`: Docstring Conventions.
 63 |     Gives guidelines for semantics and conventions associated with Python
 64 |     docstrings.
 65 | 
 66 | You can read more at `The PEP Index <http://www.python.org/dev/peps/>`_.
 67 | 
 68 | Submitting a PEP
 69 | ~~~~~~~~~~~~~~~~
 70 | 
 71 | PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone
 72 | can write and submit a PEP for review.
 73 | 
 74 | Here's an overview of the PEP acceptance workflow:
 75 | 
 76 | .. image:: ../_static/pep-0001-1.png
 77 | 
 78 | 
 79 | ******************
 80 | Python Conferences
 81 | ******************
 82 | 
 83 | The major events for the Python community are developer conferences. The two
 84 | most notable conferences are PyCon, which is held in the US, and its European
 85 | sibling, EuroPython.
 86 | 
 87 | A comprehensive list of conferences is maintained at `pycon.org <http://www.pycon.org/>`_.
 88 | 
 89 | 
 90 | ******************
 91 | Python User Groups
 92 | ******************
 93 | 
 94 | User Groups are where a bunch of Python developers meet to present or talk
 95 | about Python topics of interest. A list of local user groups is maintained at
 96 | the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.
 97 | 
 98 | 
 99 | ******************
100 | Online Communities
101 | ******************
102 | 
103 | `PythonistaCafe <https://www.pythonistacafe.com>`_ is an invite-only, online community
104 | of Python and software development enthusiasts helping each other succeed and grow.
105 | Think of it as a club of mutual improvement for Pythonistas where a broad range of
106 | programming questions, career advice, and other topics are discussed every day.
107 | 
108 | 
109 | *****************
110 | Python Job Boards
111 | *****************
112 | 
113 | `Python Jobs HQ <https://www.pythonjobshq.com>`_ is a Python job board, by Python Developers
114 | for Python Developers. The site aggregates Python job postings from across the web and
115 | also allows employers to post Python job openings directly on the site.
116 | 


--------------------------------------------------------------------------------
/docs/intro/documentation.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | #############
 4 | Documentation
 5 | #############
 6 | 
 7 | .. image:: /_static/photos/33928823133_2f3d32cf32_k_d.jpg
 8 | 
 9 | 
10 | **********************
11 | Official Documentation
12 | **********************
13 | 
14 | The official Python Language and Library documentation can be found here:
15 | 
16 |     - `Python 2.x <https://docs.python.org/2/>`_
17 |     - `Python 3.x <https://docs.python.org/3/>`_
18 | 
19 | 
20 | *************
21 | Read the Docs
22 | *************
23 | 
24 | Read the Docs is a popular community project that hosts documentation
25 | for open source software. It holds documentation for many Python modules,
26 | both popular and exotic.
27 | 
28 |     `Read the Docs <https://readthedocs.org/>`_
29 | 
30 | 
31 | *****
32 | pydoc
33 | *****
34 | 
35 | :program:`pydoc` is a utility that is installed when you install Python.
36 | It allows you to quickly retrieve and search for documentation from your
37 | shell. For example, if you needed a quick refresher on the
38 | :mod:`time` module, pulling up documentation would be as simple as:
39 | 
40 |     .. code-block:: console
41 | 
42 |        $ pydoc time
43 | 
44 | The above command is essentially equivalent to opening the Python REPL
45 | and running:
46 | 
47 |     .. code-block:: pycon
48 | 
49 |        >>> help(time)
50 | 


--------------------------------------------------------------------------------
/docs/intro/duction.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | ############
 4 | Introduction
 5 | ############
 6 | 
 7 | .. image:: /_static/photos/34725946825_0f85497e60_k_d.jpg
 8 | 
 9 | From the `official Python website <http://python.org/about/>`_:
10 | 
11 | Python is a general-purpose, high-level programming language similar
12 | to Tcl, Perl, Ruby, Scheme, or Java. Some of its main key features
13 | include:
14 | 
15 | * **very clear, readable syntax**
16 | 
17 |   Python's philosophy focuses on readability, from code blocks
18 |   delineated with significant whitespace to intuitive keywords in
19 |   place of inscrutable punctuation.
20 | 
21 | * **extensive standard libraries and third party modules for virtually
22 |   any task**
23 | 
24 |   Python is sometimes described with the words "batteries included"
25 |   because of its extensive
26 |   `standard library <http://docs.python.org/library/>`_, which includes
27 |   modules for regular expressions, file IO, fraction handling,
28 |   object serialization, and much more.
29 | 
30 |   Additionally, the
31 |   `Python Package Index <https://pypi.org>`_ is available
32 |   for users to submit their packages for widespread use, similar to
33 |   Perl's `CPAN <https://www.cpan.org>`_. There is a thriving community
34 |   of very powerful Python frameworks and tools like
35 |   the `Django <https://www.djangoproject.com>`_ web framework and the
36 |   `NumPy <http://numpy.scipy.org>`_ set of math routines.
37 | 
38 | * **integration with other systems**
39 | 
40 |   Python can integrate with `Java libraries <http://www.jython.org>`_,
41 |   enabling it to be used with the rich Java environment that corporate
42 |   programmers are used to. It can also be
43 |   `extended by C or C++ modules <http://docs.python.org/extending/>`_
44 |   when speed is of the essence.
45 | 
46 | * **ubiquity on computers**
47 | 
48 |   Python is available on Windows, \*nix, and Mac. It runs wherever the
49 |   Java virtual machine runs, and the reference implementation CPython
50 |   can help bring Python to wherever there is a working C compiler.
51 | 
52 | * **friendly community**
53 | 
54 |   Python has a vibrant and large :ref:`community <the-community>`
55 |   which maintains wikis, conferences, countless repositories,
56 |   mailing lists, IRC channels, and so much more. Heck, the Python
57 |   community is even helping to write this guide!
58 | 
59 | 
60 | .. _about-ref:
61 | 
62 | 
63 | ****************
64 | About This Guide
65 | ****************
66 | 
67 | Purpose
68 | ~~~~~~~
69 | 
70 | The Hitchhiker's Guide to Python exists to provide both novice and expert
71 | Python developers a best practice handbook for the installation, configuration,
72 | and usage of Python on a daily basis.
73 | 
74 | 
75 | By the Community
76 | ~~~~~~~~~~~~~~~~
77 | 
78 | This guide is architected and maintained by `Kenneth Reitz
79 | <https://github.com/kennethreitz>`_ in an open fashion. This is a
80 | community-driven effort that serves one purpose: to serve the community.
81 | 
82 | For the Community
83 | ~~~~~~~~~~~~~~~~~
84 | 
85 | All contributions to the Guide are welcome, from Pythonistas of all levels.
86 | If you think there's a gap in what the Guide covers, fork the Guide on
87 | GitHub and submit a pull request.
88 | 
89 | Contributions are welcome from everyone, whether they're an old hand or a
90 | first-time Pythonista, and the authors to the Guide will gladly help if you
91 | have any questions about the appropriateness, completeness, or accuracy of
92 | a contribution.
93 | 
94 | To get started working on The Hitchhiker's Guide,
95 | see the :doc:`/notes/contribute` page.
96 | 


--------------------------------------------------------------------------------
/docs/intro/news.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | ####
  4 | News
  5 | ####
  6 | 
  7 | .. image:: /_static/photos/33573767786_eececc5d27_k_d.jpg
  8 | 
  9 | 
 10 | ****************
 11 | PyCoder’s Weekly
 12 | ****************
 13 | 
 14 | PyCoder’s Weekly is a free weekly Python newsletter for Python developers
 15 | by Python developers (Projects, Articles, News, and Jobs).
 16 | 
 17 |     `PyCoder’s Weekly <https://pycoders.com/>`_
 18 | 
 19 | 
 20 | ***********
 21 | Real Python
 22 | ***********
 23 | 
 24 | 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.
 25 | 
 26 |     `Real Python <https://realpython.com/>`_
 27 | 
 28 | 
 29 | *************
 30 | Planet Python
 31 | *************
 32 | 
 33 | This is an aggregate of Python news from a growing number of developers.
 34 | 
 35 |     `Planet Python <https://planetpython.org>`_
 36 | 
 37 | 
 38 | *********
 39 | /r/python
 40 | *********
 41 | 
 42 | /r/python is the Reddit Python community where users contribute and vote on
 43 | Python-related news.
 44 | 
 45 |     `/r/python <https://reddit.com/r/python>`_
 46 | 
 47 | 
 48 | *******************
 49 | Talk Python Podcast
 50 | *******************
 51 | 
 52 | The #1 Python-focused podcast covering the people and ideas in Python.
 53 | 
 54 |     `Talk Python To Me <https://talkpython.fm>`_
 55 | 
 56 | 
 57 | ********************
 58 | Python Bytes Podcast
 59 | ********************
 60 | 
 61 | A short-form Python podcast covering recent developer headlines.
 62 | 
 63 |     `Python Bytes <https://pythonbytes.fm>`_
 64 | 
 65 | 
 66 | *************
 67 | Python Weekly
 68 | *************
 69 | 
 70 | Python Weekly is a free weekly newsletter featuring curated news, articles,
 71 | new releases, jobs, etc. related to Python.
 72 | 
 73 |     `Python Weekly <https://www.pythonweekly.com/>`_
 74 | 
 75 | 
 76 | ***********
 77 | Python News
 78 | ***********
 79 | 
 80 | Python News is the news section in the official Python web site
 81 | (www.python.org). It briefly highlights the news from the Python community.
 82 | 
 83 |     `Python News <http://www.python.org/blogs/>`_
 84 | 
 85 | 
 86 | ********************
 87 | Import Python Weekly
 88 | ********************
 89 | 
 90 | Weekly Python Newsletter containing Python Articles, Projects, Videos, and Tweets
 91 | delivered in your inbox.  Keep Your Python Programming Skills Updated.
 92 | 
 93 |     `Import Python Weekly Newsletter <http://www.importpython.com/newsletter/>`_
 94 | 
 95 | 
 96 | *************************
 97 | Awesome Python Newsletter
 98 | *************************
 99 | 
100 | A weekly overview of the most popular Python news, articles, and packages.
101 | 
102 |     `Awesome Python Newsletter <https://python.libhunt.com/newsletter>`_
103 | 


--------------------------------------------------------------------------------
/docs/make.bat:
--------------------------------------------------------------------------------
  1 | @ECHO OFF
  2 | 
  3 | REM Command file for Sphinx documentation
  4 | 
  5 | if "%SPHINXBUILD%" == "" (
  6 | 	set SPHINXBUILD=sphinx-build
  7 | )
  8 | set BUILDDIR=_build
  9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 10 | set I18NSPHINXOPTS=%SPHINXOPTS% .
 11 | if NOT "%PAPER%" == "" (
 12 | 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 13 | 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 14 | )
 15 | 
 16 | if "%1" == "" goto help
 17 | 
 18 | if "%1" == "help" (
 19 | 	:help
 20 | 	echo.Please use `make ^<target^>` where ^<target^> is one of
 21 | 	echo.  html       to make standalone HTML files
 22 | 	echo.  dirhtml    to make HTML files named index.html in directories
 23 | 	echo.  singlehtml to make a single large HTML file
 24 | 	echo.  pickle     to make pickle files
 25 | 	echo.  json       to make JSON files
 26 | 	echo.  htmlhelp   to make HTML files and a HTML help project
 27 | 	echo.  qthelp     to make HTML files and a qthelp project
 28 | 	echo.  devhelp    to make HTML files and a Devhelp project
 29 | 	echo.  epub       to make an epub
 30 | 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 31 | 	echo.  text       to make text files
 32 | 	echo.  man        to make manual pages
 33 | 	echo.  texinfo    to make Texinfo files
 34 | 	echo.  gettext    to make PO message catalogs
 35 | 	echo.  changes    to make an overview over all changed/added/deprecated items
 36 | 	echo.  xml        to make Docutils-native XML files
 37 | 	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
 38 | 	echo.  linkcheck  to check all external links for integrity
 39 | 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 40 | 	goto end
 41 | )
 42 | 
 43 | if "%1" == "clean" (
 44 | 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
 45 | 	del /q /s %BUILDDIR%\*
 46 | 	goto end
 47 | )
 48 | 
 49 | 
 50 | REM Check if sphinx-build is available and fallback to Python version if any
 51 | %SPHINXBUILD% 2> nul
 52 | if errorlevel 9009 goto sphinx_python
 53 | goto sphinx_ok
 54 | 
 55 | :sphinx_python
 56 | 
 57 | set SPHINXBUILD=python -m sphinx.__init__
 58 | %SPHINXBUILD% 2> nul
 59 | if errorlevel 9009 (
 60 | 	echo.
 61 | 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
 62 | 	echo.installed, then set the SPHINXBUILD environment variable to point
 63 | 	echo.to the full path of the 'sphinx-build' executable. Alternatively you
 64 | 	echo.may add the Sphinx directory to PATH.
 65 | 	echo.
 66 | 	echo.If you don't have Sphinx installed, grab it from
 67 | 	echo.http://sphinx-doc.org/
 68 | 	exit /b 1
 69 | )
 70 | 
 71 | :sphinx_ok
 72 | 
 73 | 
 74 | if "%1" == "html" (
 75 | 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 76 | 	if errorlevel 1 exit /b 1
 77 | 	echo.
 78 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
 79 | 	goto end
 80 | )
 81 | 
 82 | if "%1" == "dirhtml" (
 83 | 	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
 84 | 	if errorlevel 1 exit /b 1
 85 | 	echo.
 86 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
 87 | 	goto end
 88 | )
 89 | 
 90 | if "%1" == "singlehtml" (
 91 | 	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
 92 | 	if errorlevel 1 exit /b 1
 93 | 	echo.
 94 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
 95 | 	goto end
 96 | )
 97 | 
 98 | if "%1" == "pickle" (
 99 | 	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
100 | 	if errorlevel 1 exit /b 1
101 | 	echo.
102 | 	echo.Build finished; now you can process the pickle files.
103 | 	goto end
104 | )
105 | 
106 | if "%1" == "json" (
107 | 	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
108 | 	if errorlevel 1 exit /b 1
109 | 	echo.
110 | 	echo.Build finished; now you can process the JSON files.
111 | 	goto end
112 | )
113 | 
114 | if "%1" == "htmlhelp" (
115 | 	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
116 | 	if errorlevel 1 exit /b 1
117 | 	echo.
118 | 	echo.Build finished; now you can run HTML Help Workshop with the ^
119 | .hhp project file in %BUILDDIR%/htmlhelp.
120 | 	goto end
121 | )
122 | 
123 | if "%1" == "qthelp" (
124 | 	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
125 | 	if errorlevel 1 exit /b 1
126 | 	echo.
127 | 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
128 | .qhcp project file in %BUILDDIR%/qthelp, like this:
129 | 	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\pythonguide.qhcp
130 | 	echo.To view the help file:
131 | 	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\pythonguide.ghc
132 | 	goto end
133 | )
134 | 
135 | if "%1" == "devhelp" (
136 | 	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
137 | 	if errorlevel 1 exit /b 1
138 | 	echo.
139 | 	echo.Build finished.
140 | 	goto end
141 | )
142 | 
143 | if "%1" == "epub" (
144 | 	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
145 | 	if errorlevel 1 exit /b 1
146 | 	echo.
147 | 	echo.Build finished. The epub file is in %BUILDDIR%/epub.
148 | 	goto end
149 | )
150 | 
151 | if "%1" == "latex" (
152 | 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
153 | 	if errorlevel 1 exit /b 1
154 | 	echo.
155 | 	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
156 | 	goto end
157 | )
158 | 
159 | if "%1" == "latexpdf" (
160 | 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
161 | 	cd %BUILDDIR%/latex
162 | 	make all-pdf
163 | 	cd %BUILDDIR%/..
164 | 	echo.
165 | 	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
166 | 	goto end
167 | )
168 | 
169 | if "%1" == "latexpdfja" (
170 | 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
171 | 	cd %BUILDDIR%/latex
172 | 	make all-pdf-ja
173 | 	cd %BUILDDIR%/..
174 | 	echo.
175 | 	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
176 | 	goto end
177 | )
178 | 
179 | if "%1" == "text" (
180 | 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
181 | 	if errorlevel 1 exit /b 1
182 | 	echo.
183 | 	echo.Build finished. The text files are in %BUILDDIR%/text.
184 | 	goto end
185 | )
186 | 
187 | if "%1" == "man" (
188 | 	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
189 | 	if errorlevel 1 exit /b 1
190 | 	echo.
191 | 	echo.Build finished. The manual pages are in %BUILDDIR%/man.
192 | 	goto end
193 | )
194 | 
195 | if "%1" == "texinfo" (
196 | 	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
197 | 	if errorlevel 1 exit /b 1
198 | 	echo.
199 | 	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
200 | 	goto end
201 | )
202 | 
203 | if "%1" == "gettext" (
204 | 	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
205 | 	if errorlevel 1 exit /b 1
206 | 	echo.
207 | 	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
208 | 	goto end
209 | )
210 | 
211 | if "%1" == "changes" (
212 | 	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
213 | 	if errorlevel 1 exit /b 1
214 | 	echo.
215 | 	echo.The overview file is in %BUILDDIR%/changes.
216 | 	goto end
217 | )
218 | 
219 | if "%1" == "linkcheck" (
220 | 	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
221 | 	if errorlevel 1 exit /b 1
222 | 	echo.
223 | 	echo.Link check complete; look for any errors in the above output ^
224 | or in %BUILDDIR%/linkcheck/output.txt.
225 | 	goto end
226 | )
227 | 
228 | if "%1" == "doctest" (
229 | 	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
230 | 	if errorlevel 1 exit /b 1
231 | 	echo.
232 | 	echo.Testing of doctests in the sources finished, look at the ^
233 | results in %BUILDDIR%/doctest/output.txt.
234 | 	goto end
235 | )
236 | 
237 | if "%1" == "xml" (
238 | 	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
239 | 	if errorlevel 1 exit /b 1
240 | 	echo.
241 | 	echo.Build finished. The XML files are in %BUILDDIR%/xml.
242 | 	goto end
243 | )
244 | 
245 | if "%1" == "pseudoxml" (
246 | 	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
247 | 	if errorlevel 1 exit /b 1
248 | 	echo.
249 | 	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
250 | 	goto end
251 | )
252 | 
253 | :end
254 | 


--------------------------------------------------------------------------------
/docs/notes/contribute.rst:
--------------------------------------------------------------------------------
 1 | ##########
 2 | Contribute
 3 | ##########
 4 | 
 5 | .. image:: /_static/photos/33573769116_49c1ef51e7_k_d.jpg
 6 | 
 7 | Python-guide is under active development, and contributors are welcome.
 8 | 
 9 | If you have a feature request, suggestion, or bug report, please open a new
10 | issue on GitHub_. To submit patches, please send a pull request on GitHub_.
11 | Once your changes get merged back in, you'll automatically be added to the
12 | `Contributors List <https://github.com/kennethreitz/python-guide/contributors>`_.
13 | 
14 | 
15 | ***********
16 | Style Guide
17 | ***********
18 | 
19 | For all contributions, please follow the :ref:`guide-style-guide`.
20 | 
21 | .. _todo-list-ref:
22 | 
23 | 
24 | *********
25 | Todo List
26 | *********
27 | 
28 | If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
29 | 
30 |     .. include:: ../../TODO.rst
31 | 
32 | 
33 | .. _GitHub: https://github.com/kennethreitz/python-guide/
34 | .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst
35 | 


--------------------------------------------------------------------------------
/docs/notes/license.rst:
--------------------------------------------------------------------------------
1 | #######
2 | License
3 | #######
4 | 
5 | .. image:: /_static/photos/32800805573_568d6b72fd_k_d.jpg
6 | 
7 | The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license <https://creativecommons.org/licenses/by-nc-sa/3.0/>`_.
8 | 


--------------------------------------------------------------------------------
/docs/notes/styleguide.rst:
--------------------------------------------------------------------------------
  1 | .. _guide-style-guide:
  2 | 
  3 | #####################
  4 | The Guide Style Guide
  5 | #####################
  6 | 
  7 | .. image:: /_static/photos/33573755856_7f43d43adf_k_d.jpg
  8 | 
  9 | As with all documentation, having a consistent format helps make the
 10 | document more understandable. In order to make The Guide easier to digest,
 11 | all contributions should fit within the rules of this style guide where
 12 | appropriate.
 13 | 
 14 | The Guide is written as :ref:`restructuredtext-ref`.
 15 | 
 16 | .. note:: Parts of The Guide may not yet match this style guide. Feel free
 17 |    to update those parts to be in sync with The Guide Style Guide
 18 | 
 19 | .. note:: On any page of the rendered HTML you can click "Show Source" to
 20 |    see how authors have styled the page.
 21 | 
 22 | 
 23 | *********
 24 | Relevancy
 25 | *********
 26 | 
 27 | Strive to keep any contributions relevant to the :ref:`purpose of The Guide
 28 | <about-ref>`.
 29 | 
 30 | * Avoid including too much information on subjects that don't directly
 31 |   relate to Python development.
 32 | * Prefer to link to other sources if the information is already out there.
 33 |   Be sure to describe what and why you are linking.
 34 | * `Cite <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#citations>`_
 35 |   references where needed.
 36 | * If a subject isn't directly relevant to Python, but useful in conjunction
 37 |   with Python (e.g., Git, GitHub, Databases), reference by linking to useful
 38 |   resources, and describe why it's useful to Python.
 39 | * When in doubt, ask.
 40 | 
 41 | 
 42 | ********
 43 | Headings
 44 | ********
 45 | 
 46 | Use the following styles for headings.
 47 | 
 48 | Chapter title:
 49 | 
 50 | .. code-block:: rest
 51 | 
 52 |     #########
 53 |     Chapter 1
 54 |     #########
 55 | 
 56 | Page title:
 57 | 
 58 | .. code-block:: rest
 59 | 
 60 |     *******************
 61 |     Time is an Illusion
 62 |     *******************
 63 | 
 64 | Section headings:
 65 | 
 66 | .. code-block:: rest
 67 | 
 68 |     Lunchtime Doubly So
 69 |     ===================
 70 | 
 71 | Sub section headings:
 72 | 
 73 | .. code-block:: rest
 74 | 
 75 |     Very Deep
 76 |     ---------
 77 | 
 78 | 
 79 | *****
 80 | Prose
 81 | *****
 82 | 
 83 | Wrap text lines at 78 characters. Where necessary, lines may exceed 78
 84 | characters, especially if wrapping would make the source text more difficult
 85 | to read.
 86 | 
 87 | Use Standard American English, not British English.
 88 | 
 89 | Use of the `serial comma <https://en.wikipedia.org/wiki/Serial_comma>`_
 90 | (also known as the Oxford comma) is 100% non-optional. Any attempt to
 91 | submit content with a missing serial comma will result in permanent banishment
 92 | from this project, due to complete and total lack of taste.
 93 | 
 94 | Banishment? Is this a joke? Hopefully we will never have to find out.
 95 | 
 96 | 
 97 | *************
 98 | Code Examples
 99 | *************
100 | 
101 | Wrap all code examples at 70 characters to avoid horizontal scrollbars.
102 | 
103 | Command line examples:
104 | 
105 | .. code-block:: rest
106 | 
107 |     .. code-block:: console
108 | 
109 |         $ run command --help
110 |         $ ls ..
111 | 
112 | Be sure to include the ``$`` prefix before each line for Unix console examples.
113 | 
114 | For Windows console examples, use ``doscon`` or ``powershell`` instead of
115 | ``console``, and omit the ``$`` prefix.
116 | 
117 | Python interpreter examples:
118 | 
119 | .. code-block:: rest
120 | 
121 |     Label the example::
122 | 
123 |     .. code-block:: python
124 | 
125 |         >>> import this
126 | 
127 | Python examples:
128 | 
129 | .. code-block:: rest
130 | 
131 |     Descriptive title::
132 | 
133 |     .. code-block:: python
134 | 
135 |         def get_answer():
136 |             return 42
137 | 
138 | 
139 | ******************
140 | Externally Linking
141 | ******************
142 | 
143 | * Prefer labels for well known subjects (e.g. proper nouns) when linking:
144 | 
145 |   .. code-block:: rest
146 | 
147 |       Sphinx_ is used to document Python.
148 | 
149 |       .. _Sphinx: https://www.sphinx-doc.org
150 | 
151 | * Prefer to use descriptive labels with inline links instead of leaving bare
152 |   links:
153 | 
154 |   .. code-block:: rest
155 | 
156 |       Read the `Sphinx Tutorial <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
157 | 
158 | * Avoid using labels such as "click here", "this", etc., preferring
159 |   descriptive labels (SEO worthy) instead.
160 | 
161 | 
162 | ********************************
163 | Linking to Sections in The Guide
164 | ********************************
165 | 
166 | To cross-reference other parts of this documentation, use the `:ref:
167 | <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref>`_
168 | keyword and labels.
169 | 
170 | To make reference labels more clear and unique, always add a ``-ref`` suffix:
171 | 
172 | .. code-block:: rest
173 | 
174 |     .. _some-section-ref:
175 | 
176 |     Some Section
177 |     ------------
178 | 
179 | 
180 | ******************
181 | Notes and Warnings
182 | ******************
183 | 
184 | Make use of the appropriate `admonitions directives
185 | <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives>`_ when making notes.
186 | 
187 | Notes:
188 | 
189 | .. code-block:: rest
190 | 
191 |     .. note::
192 |         The Hitchhiker’s Guide to the Galaxy has a few things to say
193 |         on the subject of towels. A towel, it says, is about the most
194 |         massively useful thing an interstellar hitch hiker can have.
195 | 
196 | Warnings:
197 | 
198 | .. code-block:: rest
199 | 
200 |     .. warning:: DON'T PANIC
201 | 
202 | 
203 | *****
204 | TODOs
205 | *****
206 | 
207 | Please mark any incomplete areas of The Guide with a `todo directive
208 | <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html>`_. To
209 | avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
210 | documents or large incomplete sections.
211 | 
212 | .. code-block:: rest
213 | 
214 |     .. todo::
215 |         Learn the Ultimate Answer to the Ultimate Question
216 |         of Life, The Universe, and Everything
217 | 


--------------------------------------------------------------------------------
/docs/scenarios/ci.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | ######################
 3 | Continuous Integration
 4 | ######################
 5 | 
 6 | .. image:: /_static/photos/33907150594_9abba7ad0a_k_d.jpg
 7 | 
 8 | .. note::
 9 |     For advice on writing your tests, see :doc:`/writing/tests`.
10 | 
11 | 
12 | ****
13 | Why?
14 | ****
15 | 
16 | Martin Fowler, who first wrote about `Continuous Integration <http://martinfowler.com/articles/continuousIntegration.html>`_
17 | (short: CI) together with Kent Beck, describes CI as follows:
18 | 
19 |     Continuous Integration is a software development practice where members of
20 |     a team integrate their work frequently, usually each person integrates at
21 |     least daily - leading to multiple integrations per day. Each integration is
22 |     verified by an automated build (including test) to detect integration errors
23 |     as quickly as possible. Many teams find that this approach leads to
24 |     significantly reduced integration problems and allows a team to develop
25 |     cohesive software more rapidly.
26 | 
27 | 
28 | *******
29 | Jenkins
30 | *******
31 | 
32 | `Jenkins CI <http://jenkins-ci.org>`_ is an extensible Continuous Integration engine. Use it.
33 | 
34 | 
35 | ********
36 | Buildbot
37 | ********
38 | 
39 | `Buildbot <http://docs.buildbot.net/current/>`_ is a Python system to
40 | automate the compile/test cycle to validate code changes.
41 | 
42 | 
43 | ***
44 | Tox
45 | ***
46 | 
47 | `tox <https://tox.readthedocs.io/en/latest/>`_ is an automation tool providing
48 | packaging, testing, and deployment of Python software right from the console or
49 | CI server. It is a generic virtualenv management and test command line tool
50 | which provides the following features:
51 | 
52 | * Checking that packages install correctly with different Python versions and
53 |   interpreters
54 | * Running tests in each of the environments, configuring your test tool of
55 |   choice
56 | * Acting as a front-end to Continuous Integration servers, reducing boilerplate
57 |   and merging CI and shell-based testing
58 | 
59 | 
60 | *********
61 | Travis-CI
62 | *********
63 | 
64 | `Travis-CI <https://travis-ci.org/>`_ is a distributed CI server which builds
65 | tests for open source projects for free. It provides multiple workers to run
66 | Python tests on and seamlessly integrates with GitHub. You can even have it
67 | comment on your Pull Requests whether this particular changeset breaks the
68 | build or not. So, if you are hosting your code on GitHub, Travis-CI is a great
69 | and easy way to get started with Continuous Integration.
70 | 
71 | In order to get started, add a :file:`.travis.yml` file to your repository with
72 | this example content::
73 | 
74 |     language: python
75 |     python:
76 |       - "2.6"
77 |       - "2.7"
78 |       - "3.2"
79 |       - "3.3"
80 |     # command to install dependencies
81 |     script: python tests/test_all_of_the_units.py
82 |     branches:
83 |       only:
84 |         - master
85 | 
86 | 
87 | This will get your project tested on all the listed Python versions by
88 | running the given script, and will only build the ``master`` branch. There are a
89 | lot more options you can enable, like notifications, before and after steps,
90 | and much more. The `Travis-CI docs <https://docs.travis-ci.com/user/languages/python/>`_
91 | explain all of these options, and are very thorough.
92 | 
93 | In order to activate testing for your project, go to `the Travis-CI site <https://travis-ci.org/>`_
94 | and login with your GitHub account. Then activate your project in your
95 | profile settings and you're ready to go. From now on, your project's tests
96 | will be run on every push to GitHub.
97 | 


--------------------------------------------------------------------------------
/docs/scenarios/cli.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | #########################
 3 | Command-line Applications
 4 | #########################
 5 | 
 6 | .. image:: /_static/photos/34435690330_11930b5987_k_d.jpg
 7 | 
 8 | Command-line applications, also referred to as `Console Applications
 9 | <http://en.wikipedia.org/wiki/Console_application>`_, are computer programs
10 | designed to be used from a text interface, such as a `shell
11 | <http://en.wikipedia.org/wiki/Shell_(computing)>`_. Command-line applications
12 | usually accept various inputs as arguments, often referred to as parameters or
13 | sub-commands, as well as options, often referred to as flags or switches.
14 | 
15 | Some popular command-line applications include:
16 | 
17 | * `grep <http://en.wikipedia.org/wiki/grep>`_ - A plain-text data search utility
18 | * `curl <http://curl.haxx.se/>`_ - A tool for data transfer with URL syntax
19 | * `httpie <https://github.com/jakubroztocil/httpie>`_ - A command-line HTTP
20 |   client, a user-friendly cURL replacement
21 | * `Git <http://git-scm.com/>`_ - A distributed version control system
22 | * `Mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
23 |   system primarily written in Python
24 | 
25 | 
26 | *****
27 | Click
28 | *****
29 | 
30 | `click <https://click.palletsprojects.com>`_ is a Python package for creating
31 | command-line interfaces in a composable way with as little code as possible.
32 | This “Command-Line Interface Creation Kit” is highly configurable but comes
33 | with good defaults out of the box.
34 | 
35 | 
36 | ******
37 | docopt
38 | ******
39 | 
40 | `docopt <http://docopt.org/>`_ is a lightweight, highly Pythonic package that
41 | allows creating command-line interfaces easily and intuitively, by parsing
42 | POSIX-style usage instructions.
43 | 
44 | 
45 | ****
46 | Plac
47 | ****
48 | 
49 | `Plac <https://pypi.org/project/plac>`_ is a simple wrapper
50 | over the Python standard library `argparse <http://docs.python.org/2/library/argparse.html>`_,
51 | which hides most of its complexity by using a declarative interface: the
52 | argument parser is inferred rather than written down imperatively. This
53 | module targets unsophisticated users, programmers, sysadmins,
54 | scientists, and in general people writing throw-away scripts for themselves,
55 | who choose to create a command-line interface because it is quick and simple.
56 | 
57 | 
58 | *****
59 | Cliff
60 | *****
61 | 
62 | `Cliff <http://docs.openstack.org/developer/cliff/>`_  is a framework for
63 | building command-line programs. It uses setuptools entry points to provide
64 | subcommands, output formatters, and other extensions. The framework is meant
65 | to be used to create multi-level commands such as ``svn`` and ``git``, where
66 | the main program handles some basic argument parsing and then invokes a
67 | sub-command to do the work.
68 | 
69 | 
70 | ******
71 | Cement
72 | ******
73 | 
74 | `Cement <http://builtoncement.com/>`_ is an advanced CLI Application
75 | Framework. Its goal is to introduce a standard and feature-full platform for
76 | both simple and complex command line applications as well as support rapid
77 | development needs without sacrificing quality. Cement is flexible, and its use
78 | cases span from the simplicity of a micro-framework to the complexity of a
79 | mega-framework.
80 | 
81 | 
82 | ***********
83 | Python Fire
84 | ***********
85 | 
86 | `Python Fire <https://github.com/google/python-fire/>`_ is a library for
87 | automatically generating command-line interfaces from absolutely any Python
88 | object. It can help debug Python code more easily from the command line,
89 | create CLI interfaces to existing code, allow you to interactively explore
90 | code in a REPL, and simplify transitioning between Python and Bash (or any
91 | other shell).
92 | 


--------------------------------------------------------------------------------
/docs/scenarios/clibs.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | ################################
  3 | Interfacing with C/C++ Libraries
  4 | ################################
  5 | 
  6 | .. image:: /_static/photos/34725951345_c8f5959a2e_k_d.jpg
  7 | 
  8 | 
  9 | ****************************
 10 | C Foreign Function Interface
 11 | ****************************
 12 | 
 13 | `CFFI <https://cffi.readthedocs.io/en/latest/>`_ provides a simple to use
 14 | mechanism for interfacing with C from both CPython and PyPy. It supports two
 15 | modes: an inline `ABI <https://stackoverflow.com/questions/2171177/what-is-an-application-binary-interface-abi>`_ compatibility mode (example provided below), which allows
 16 | you to dynamically load and run functions from executable modules (essentially
 17 | exposing the same functionality as `LoadLibrary <https://docs.microsoft.com/en-us/windows/desktop/api/libloaderapi/nf-libloaderapi-loadlibrarya>`_ or `dlopen <https://www.tldp.org/HOWTO/C++-dlopen/index.html>`_), and an API mode,
 18 | which allows you to build C extension modules.
 19 | 
 20 | ABI Interaction
 21 | ~~~~~~~~~~~~~~~
 22 | 
 23 | .. code-block:: python
 24 |     :linenos:
 25 | 
 26 |     from cffi import FFI
 27 |     ffi = FFI()
 28 |     ffi.cdef("size_t strlen(const char*);")
 29 |     clib = ffi.dlopen(None)
 30 |     length = clib.strlen("String to be evaluated.")
 31 |     # prints: 23
 32 |     print("{}".format(length))
 33 | 
 34 | 
 35 | ******
 36 | ctypes
 37 | ******
 38 | 
 39 | `ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto standard
 40 | library for interfacing with C/C++ from CPython, and it provides not only
 41 | full access to the native C interface of most major operating systems (e.g.,
 42 | kernel32 on Windows, or libc on \*nix), but also provides support for loading
 43 | and interfacing with dynamic libraries, such as DLLs or shared objects, at
 44 | runtime. It brings along with it a whole host of types for interacting
 45 | with system APIs, and allows you to rather easily define your own complex
 46 | types, such as structs and unions, and allows you to modify things such as
 47 | padding and alignment, if needed. It can be a bit crufty to use, but in
 48 | conjunction with the `struct <https://docs.python.org/3/library/struct.html>`_
 49 | module, you are essentially provided full control over how your data types get
 50 | translated into something usable by a pure C/C++ method.
 51 | 
 52 | Struct Equivalents
 53 | ~~~~~~~~~~~~~~~~~~
 54 | 
 55 | :file:`MyStruct.h`
 56 | 
 57 | .. code-block:: c
 58 |     :linenos:
 59 | 
 60 |     struct my_struct {
 61 |         int a;
 62 |         int b;
 63 |     };
 64 | 
 65 | :file:`MyStruct.py`
 66 | 
 67 | .. code-block:: python
 68 |     :linenos:
 69 | 
 70 |     import ctypes
 71 |     class my_struct(ctypes.Structure):
 72 |         _fields_ = [("a", c_int),
 73 |                     ("b", c_int)]
 74 | 
 75 | 
 76 | ****
 77 | SWIG
 78 | ****
 79 | 
 80 | `SWIG <http://www.swig.org>`_, though not strictly Python focused (it supports a
 81 | large number of scripting languages), is a tool for generating bindings for
 82 | interpreted languages from C/C++ header files. It is extremely simple to use:
 83 | the consumer simply needs to define an interface file (detailed in the
 84 | tutorial and documentations), include the requisite C/C++ headers, and run
 85 | the build tool against them. While it does have some limits (it currently
 86 | seems to have issues with a small subset of newer C++ features, and getting
 87 | template-heavy code to work can be a bit verbose), it provides a great deal
 88 | of power and exposes lots of features to Python with little effort.
 89 | Additionally, you can easily extend the bindings SWIG creates (in the
 90 | interface file) to overload operators and built-in methods, effectively re-
 91 | cast C++ exceptions to be catchable by Python, etc.
 92 | 
 93 | Example: Overloading __repr__
 94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 95 | 
 96 | :file:`MyClass.h`
 97 | 
 98 | .. code-block:: c++
 99 |     :linenos:
100 | 
101 |     #include <string>
102 |     class MyClass {
103 |     private:
104 |         std::string name;
105 |     public:
106 |         std::string getName();
107 |     };
108 | 
109 | 
110 | :file:`myclass.i`
111 | 
112 | .. code-block:: idl
113 |     :linenos:
114 | 
115 |     %include "string.i"
116 | 
117 |     %module myclass
118 |     %{
119 |     #include <string>
120 |     #include "MyClass.h"
121 |     %}
122 | 
123 |     %extend MyClass {
124 |         std::string __repr__()
125 |         {
126 |             return $self->getName();
127 |         }
128 |     }
129 | 
130 |     %include "MyClass.h"
131 | 
132 | 
133 | ************
134 | Boost.Python
135 | ************
136 | 
137 | `Boost.Python <http://www.boost.org/doc/libs/1_59_0/libs/python/doc/>`_
138 | requires a bit more manual work to expose C++ object functionality, but
139 | it is capable of providing all the same features SWIG does and then some,
140 | to include providing wrappers to access PyObjects in C++, extracting SWIG
141 | wrapper objects, and even embedding bits of Python into your C++ code.
142 | 


--------------------------------------------------------------------------------
/docs/scenarios/client.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | ####################
 3 | Network Applications
 4 | ####################
 5 | 
 6 | .. image:: /_static/photos/34364815780_bea6614025_k_d.jpg
 7 | 
 8 | 
 9 | ****
10 | HTTP
11 | ****
12 | 
13 | The Hypertext Transfer Protocol (HTTP) is an application protocol for
14 | distributed, collaborative, hypermedia information systems. HTTP is the
15 | foundation of data communication for the World Wide Web.
16 | 
17 | Requests
18 | --------
19 | 
20 | Python’s standard urllib2 module provides most of the HTTP capabilities you
21 | need, but the API is thoroughly broken. It was built for a different time —
22 | and a different web. It requires an enormous amount of work (even method
23 | overrides) to perform the simplest of tasks.
24 | 
25 | Requests takes all of the work out of Python HTTP — making your integration
26 | with web services seamless. There’s no need to manually add query strings to
27 | your URLs, or to form-encode your POST data. Keep-alive and HTTP connection
28 | pooling are 100% automatic, powered by urllib3, which is embedded within
29 | Requests.
30 | 
31 | - `Documentation <https://requests.readthedocs.io/en/latest/>`_
32 | - `PyPi <http://pypi.org/project/requests>`_
33 | - `GitHub <https://github.com/kennethreitz/requests>`_
34 | 
35 | 
36 | *******************
37 | Distributed Systems
38 | *******************
39 | 
40 | 
41 | ZeroMQ
42 | ------
43 | 
44 | ØMQ (also spelled ZeroMQ, 0MQ or ZMQ) is a high-performance asynchronous
45 | messaging library aimed at use in scalable distributed or concurrent
46 | applications. It provides a message queue, but unlike message-oriented
47 | middleware, a ØMQ system can run without a dedicated message broker. The
48 | library is designed to have a familiar socket-style API.
49 | 
50 | RabbitMQ
51 | --------
52 | 
53 | RabbitMQ is an open source message broker software that implements the Advanced
54 | Message Queuing Protocol (AMQP).  The RabbitMQ server is written in the Erlang
55 | programming language and is built on the Open Telecom Platform framework for
56 | clustering and failover. Client libraries to interface with the broker are
57 | available for all major programming languages.
58 | 
59 | - `Homepage <http://www.rabbitmq.com/>`_
60 | - `GitHub Organization <https://github.com/rabbitmq?page=1>`_
61 | 


--------------------------------------------------------------------------------
/docs/scenarios/crypto.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | ############
 3 | Cryptography
 4 | ############
 5 | 
 6 | .. image:: /_static/photos/33907152824_bf91078cc1_k_d.jpg
 7 | 
 8 | 
 9 | ************
10 | cryptography
11 | ************
12 | 
13 | `cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
14 | library that provides cryptographic recipes and primitives. It supports
15 | Python 2.6-2.7, Python 3.3+, and PyPy.
16 | 
17 | 
18 | cryptography is divided into two layers of recipes and hazardous materials
19 | (hazmat).  The recipes layer provides a simple API for proper symmetric
20 | encryption and the hazmat layer provides low-level cryptographic primitives.
21 | 
22 | 
23 | 
24 | Installation
25 | ~~~~~~~~~~~~
26 | 
27 | .. code-block:: console
28 | 
29 |     $ pip install cryptography
30 | 
31 | Example
32 | ~~~~~~~
33 | 
34 | Example code using high level symmetric encryption recipe:
35 | 
36 | .. code-block:: python
37 | 
38 | 	from cryptography.fernet import Fernet
39 | 	key = Fernet.generate_key()
40 | 	cipher_suite = Fernet(key)
41 | 	cipher_text = cipher_suite.encrypt(b"A really secret message. Not for prying eyes.")
42 | 	plain_text = cipher_suite.decrypt(cipher_text)
43 | 
44 | 
45 | **************
46 | GPGME bindings
47 | **************
48 | 
49 | The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide Pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, 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.
50 | 
51 | 
52 | A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org>`_ is available with the source, and an HTML version is available `at http://files.au.adversary.org <http://files.au.adversary.org/crypto/GPGMEpythonHOWTOen.html>`_.  Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `at gnupg.org <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/examples/howto/>`_.
53 | 
54 | Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause.
55 | 
56 | Installation
57 | ~~~~~~~~~~~~
58 | 
59 | 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).
60 | 
61 | Example
62 | ~~~~~~~
63 | 
64 | .. code-block:: python3
65 | 
66 | 	import gpg
67 | 
68 | 	# Encryption to public key specified in rkey.
69 | 	a_key = input("Enter the fingerprint or key ID to encrypt to: ")
70 | 	filename = input("Enter the filename to encrypt: ")
71 | 	with open(filename, "rb") as afile:
72 | 	    text = afile.read()
73 | 	c = gpg.core.Context(armor=True)
74 | 	rkey = list(c.keylist(pattern=a_key, secret=False))
75 | 	ciphertext, result, sign_result = c.encrypt(text, recipients=rkey,
76 | 	                                            always_trust=True,
77 | 						    add_encrypt_to=True)
78 | 	with open("{0}.asc".format(filename), "wb") as bfile:
79 | 	    bfile.write(ciphertext)
80 | 	# Decryption with corresponding secret key
81 | 	# invokes gpg-agent and pinentry.
82 | 	with open("{0}.asc".format(filename), "rb") as cfile:
83 | 	    plaintext, result, verify_result = gpg.Context().decrypt(cfile)
84 | 	with open("new-{0}".format(filename), "wb") as dfile:
85 | 	    dfile.write(plaintext)
86 | 	# Matching the data.
87 | 	# Also running a diff on filename and the new filename should match.
88 | 	if text == plaintext:
89 | 	    print("Hang on ... did you say *all* of GnuPG?  Yep.")
90 | 	else:
91 | 	    pass
92 | 


--------------------------------------------------------------------------------
/docs/scenarios/db.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | #########
  3 | Databases
  4 | #########
  5 | 
  6 | .. image:: /_static/photos/33907152464_a99fdcc8de_k_d.jpg
  7 | 
  8 | 
  9 | ******
 10 | DB-API
 11 | ******
 12 | 
 13 | The Python Database API (DB-API) defines a standard interface for Python
 14 | database access modules. It's documented in :pep:`249`.
 15 | Nearly all Python database modules such as `sqlite3`, `psycopg`, and
 16 | `mysql-python` conform to this interface.
 17 | 
 18 | Tutorials that explain how to work with modules that conform to this interface can be found
 19 | `here <http://halfcooked.com/presentations/osdc2006/python_databases.html>`__ and
 20 | `here <http://web.archive.org/web/20120815130844/http://www.amk.ca/python/writing/DB-API.html>`__.
 21 | 
 22 | 
 23 | **********
 24 | SQLAlchemy
 25 | **********
 26 | 
 27 | `SQLAlchemy <http://www.sqlalchemy.org/>`_ is a commonly used database toolkit.
 28 | Unlike many database libraries it not only provides an ORM layer but also a
 29 | generalized API for writing database-agnostic code without SQL.
 30 | 
 31 | .. code-block:: console
 32 | 
 33 |     $ pip install sqlalchemy
 34 | 
 35 | 
 36 | *******
 37 | Records
 38 | *******
 39 | 
 40 | `Records <https://github.com/kennethreitz/records>`_ is minimalist SQL library,
 41 | designed for sending raw SQL queries to various databases. Data can be used
 42 | programmatically or exported to a number of useful data formats.
 43 | 
 44 | .. code-block:: console
 45 | 
 46 |     $ pip install records
 47 | 
 48 | Also included is a command-line tool for exporting SQL data.
 49 | 
 50 | 
 51 | ******
 52 | PugSQL
 53 | ******
 54 | 
 55 | `PugSQL <https://pugsql.org>`_ is a simple Python interface for organizing
 56 | and using parameterized, handwritten SQL. It is an anti-ORM that is
 57 | philosophically lo-fi, but it still presents a clean interface in Python.
 58 | 
 59 | .. code-block:: console
 60 | 
 61 |     $ pip install pugsql
 62 | 
 63 | 
 64 | **********
 65 | Django ORM
 66 | **********
 67 | 
 68 | The Django ORM is the interface used by `Django <https://www.djangoproject.com>`_
 69 | to provide database access.
 70 | 
 71 | It's based on the idea of
 72 | `models <https://docs.djangoproject.com/en/dev/#the-model-layer>`_,
 73 | an abstraction that makes it easier to manipulate data in Python.
 74 | 
 75 | The basics:
 76 | 
 77 | - Each model is a Python class that subclasses django.db.models.Model.
 78 | - Each attribute of the model represents a database field.
 79 | - Django gives you an automatically-generated database-access API; see
 80 |   `Making queries <https://docs.djangoproject.com/en/dev/topics/db/queries/>`__.
 81 | 
 82 | 
 83 | ******
 84 | peewee
 85 | ******
 86 | 
 87 | `peewee <http://docs.peewee-orm.com/en/latest/>`_ is another ORM with a focus
 88 | on being lightweight with support for Python 2.6+ and 3.2+ which supports
 89 | SQLite, MySQL, and PostgreSQL by default. The
 90 | `model layer <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#model-definition>`_
 91 | is similar to that of the Django ORM and it has
 92 | `SQL-like methods <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#retrieving-data>`_
 93 | to query data. While SQLite, MySQL, and PostgreSQL are supported out-of-the-box,
 94 | there is a `collection of add-ons <https://peewee.readthedocs.io/en/latest/peewee/playhouse.html#playhouse>`_
 95 | available.
 96 | 
 97 | 
 98 | *******
 99 | PonyORM
100 | *******
101 | 
102 | `PonyORM <http://ponyorm.com/>`_ is an ORM that takes a different approach to
103 | querying the database. Instead of writing an SQL-like language or boolean
104 | expressions, Python's generator syntax is used. There's also a graphical
105 | schema editor that can generate PonyORM entities for you. It supports Python
106 | 2.6+ and Python 3.3+ and can connect to SQLite, MySQL, PostgreSQL, and Oracle.
107 | 
108 | 
109 | *********
110 | SQLObject
111 | *********
112 | 
113 | `SQLObject <http://www.sqlobject.org/>`_ is yet another ORM. It supports a wide
114 | variety of databases: common database systems like MySQL, PostgreSQL, and SQLite and
115 | more exotic systems like SAP DB, SyBase, and Microsoft SQL Server. It only supports Python 2
116 | from Python 2.6 upwards.
117 | 
118 | .. There's no official information on this on their page; this information was gathered by looking at their source code.
119 | 


--------------------------------------------------------------------------------
/docs/scenarios/gui.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | ################
  3 | GUI Applications
  4 | ################
  5 | 
  6 | .. image:: /_static/photos/33907143624_cd621b535c_k_d.jpg
  7 | 
  8 | 
  9 | Alphabetical list of GUI Applications.
 10 | 
 11 | 
 12 | *******
 13 | Camelot
 14 | *******
 15 | 
 16 | `Camelot <http://www.python-camelot.com>`_ provides components for building
 17 | applications on top of Python, SQLAlchemy, and Qt.  It is inspired by the Django
 18 | admin interface.
 19 | 
 20 | The main resource for information is the website:
 21 | http://www.python-camelot.com
 22 | and the mailing list https://groups.google.com/forum/#!forum/project-camelot.
 23 | 
 24 | 
 25 | *****
 26 | Cocoa
 27 | *****
 28 | 
 29 | .. note:: The Cocoa framework is only available on OS X. Don't pick this if you're writing a cross-platform application!
 30 | 
 31 | 
 32 | ***
 33 | GTk
 34 | ***
 35 | 
 36 | .. 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.
 37 | 
 38 | 
 39 | ********************
 40 | PyGObject aka (PyGi)
 41 | ********************
 42 | 
 43 | `PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python
 44 | bindings which gives access to the entire GNOME software platform. It is fully
 45 | compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3
 46 | Tutorial <https://python-gtk-3-tutorial.readthedocs.io/en/latest/>`_.
 47 | 
 48 | `API Reference <http://lazka.github.io/pgi-docs/>`_
 49 | 
 50 | 
 51 | ****
 52 | Kivy
 53 | ****
 54 | 
 55 | `Kivy <http://kivy.org>`_ is a Python library for development of multi-touch
 56 | enabled media rich applications. The aim is to allow for quick and easy
 57 | interaction design and rapid prototyping, while making your code reusable and
 58 | deployable.
 59 | 
 60 | Kivy is written in Python, based on OpenGL, and supports different input devices
 61 | such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products,
 62 | and so on.
 63 | 
 64 | Kivy is actively being developed by a community and is free to use. It operates
 65 | on all major platforms (Linux, OS X, Windows, Android).
 66 | 
 67 | The main resource for information is the website: http://kivy.org
 68 | 
 69 | 
 70 | ******
 71 | PyObjC
 72 | ******
 73 | 
 74 | .. note:: Only available on OS X. Don't pick this if you're writing a cross-platform application.
 75 | 
 76 | 
 77 | ******
 78 | PySide
 79 | ******
 80 | 
 81 | PySide is a Python binding of the cross-platform GUI toolkit Qt.
 82 | The package name depends on the major Qt version (`PySide` for Qt4,
 83 | `PySide2` for Qt5, and `PySide6` for Qt6).
 84 | This set of bindings is developed by `The Qt Company <https://qt.io>`_.
 85 | 
 86 | .. code-block:: console
 87 | 
 88 |   $ pip install pyside6
 89 | 
 90 | https://pyside.org
 91 | 
 92 | 
 93 | ****
 94 | PyQt
 95 | ****
 96 | 
 97 | .. note:: If your software does not fully comply with the GPL you will need a commercial license!
 98 | 
 99 | PyQt provides Python bindings for the Qt Framework (see below).
100 | 
101 | http://www.riverbankcomputing.co.uk/software/pyqt/download
102 | 
103 | 
104 | ***************************************
105 | Pyjs Desktop (formerly Pyjamas Desktop)
106 | ***************************************
107 | 
108 | Pyjs Desktop is a application widget set for desktop and a cross-platform
109 | framework. It allows the exact same Python web application source code to be
110 | executed as a standalone desktop application.
111 | 
112 | 
113 | The main website: `pyjs <http://pyjs.org/>`_.
114 | 
115 | 
116 | **
117 | Qt
118 | **
119 | 
120 | `Qt <http://qt-project.org/>`_ is a cross-platform application framework that is
121 | widely used for developing software with a GUI but can also be used for non-GUI
122 | applications.
123 | 
124 | 
125 | ***********
126 | PySimpleGUI
127 | ***********
128 | 
129 | `PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter
130 | and Qt (others on the way).  The amount of code required to implement custom
131 | GUIs is much shorter using PySimpleGUI than if the same GUI were written
132 | directly using Tkinter or Qt.  PySimpleGUI code can be "ported" between GUI
133 | frameworks by changing import statements.
134 | 
135 | .. code-block:: console
136 | 
137 |   $ pip install pysimplegui
138 | 
139 | PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip
140 | installation be impossible, copying the PySimpleGUI.py file into a project's
141 | folder is all that's required to import and begin using.
142 | 
143 | 
144 | ****
145 | Toga
146 | ****
147 | 
148 | `Toga <https://toga.readthedocs.io/en/latest/>`_ is a Python native, OS native,
149 | cross platform GUI toolkit. Toga consists of a library of base components with a
150 | shared interface to simplify platform-agnostic GUI development.
151 | 
152 | Toga is available on macOS, Windows, Linux (GTK), and mobile platforms such as
153 | Android and iOS.
154 | 
155 | 
156 | **
157 | Tk
158 | **
159 | 
160 | Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
161 | of being included with the Python standard library, making it the most
162 | convenient and compatible toolkit to program with.**
163 | 
164 | Both Tk and Tkinter are available on most Unix platforms, as well as on Windows
165 | and Macintosh systems. Starting with the 8.0 release, Tk offers native look and
166 | feel on all platforms.
167 | 
168 | There's a good multi-language Tk tutorial with Python examples at `TkDocs
169 | <http://www.tkdocs.com/tutorial/index.html>`_. There's more information
170 | available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.
171 | 
172 | 
173 | ********
174 | wxPython
175 | ********
176 | 
177 | wxPython is a GUI toolkit for the Python programming language. It allows Python
178 | programmers to create programs with a robust, highly functional graphical user
179 | interface, simply and easily. It is implemented as a Python extension module
180 | (native code) that wraps the popular wxWidgets cross platform GUI library, which
181 | is written in C++.
182 | 
183 | **Install (Stable) wxPython**
184 | *go to https://www.wxpython.org/pages/downloads/ and download the appropriate
185 | package for your OS.*
186 | 


--------------------------------------------------------------------------------
/docs/scenarios/imaging.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | ##################
  3 | Image Manipulation
  4 | ##################
  5 | 
  6 | .. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg
  7 | 
  8 | Most image processing and manipulation techniques can be carried out
  9 | effectively using two libraries: Python Imaging Library (PIL) and Open Source
 10 | Computer Vision (OpenCV).
 11 | 
 12 | A brief description of both is given below.
 13 | 
 14 | 
 15 | **********************
 16 | Python Imaging Library
 17 | **********************
 18 | 
 19 | The `Python Imaging Library <http://www.pythonware.com/products/pil/>`_, or PIL
 20 | for short, is one of the core libraries for image manipulation in Python. Unfortunately,
 21 | its development has stagnated, with its last release in 2009.
 22 | 
 23 | Luckily for you, there's an actively-developed fork of PIL called
 24 | `Pillow <http://python-pillow.github.io/>`_ -- it's easier to install, runs on
 25 | all major operating systems, and supports Python 3.
 26 | 
 27 | Installation
 28 | ~~~~~~~~~~~~
 29 | 
 30 | Before installing Pillow, you'll have to install Pillow's prerequisites. Find
 31 | the instructions for your platform in the
 32 | `Pillow installation instructions <https://pillow.readthedocs.io/en/3.0.0/installation.html>`_.
 33 | 
 34 | After that, it's straightforward:
 35 | 
 36 | .. code-block:: console
 37 | 
 38 |     $ pip install Pillow
 39 | 
 40 | Example
 41 | ~~~~~~~
 42 | 
 43 | .. code-block:: python
 44 | 
 45 |     from PIL import Image, ImageFilter
 46 |     #Read image
 47 |     im = Image.open( 'image.jpg' )
 48 |     #Display image
 49 |     im.show()
 50 | 
 51 |     #Applying a filter to the image
 52 |     im_sharp = im.filter( ImageFilter.SHARPEN )
 53 |     #Saving the filtered image to a new file
 54 |     im_sharp.save( 'image_sharpened.jpg', 'JPEG' )
 55 | 
 56 |     #Splitting the image into its respective bands, i.e. Red, Green,
 57 |     #and Blue for RGB
 58 |     r,g,b = im_sharp.split()
 59 | 
 60 |     #Viewing EXIF data embedded in image
 61 |     exif_data = im._getexif()
 62 |     exif_data
 63 | 
 64 | There are more examples of the Pillow library in the
 65 | `Pillow tutorial <https://pillow.readthedocs.io/en/stable/handbook/tutorial.html>`_.
 66 | 
 67 | 
 68 | ***************************
 69 | Open Source Computer Vision
 70 | ***************************
 71 | 
 72 | Open Source Computer Vision, more commonly known as OpenCV, is a more advanced
 73 | image manipulation and processing software than PIL. It has been implemented
 74 | in several languages and is widely used.
 75 | 
 76 | Installation
 77 | ~~~~~~~~~~~~
 78 | 
 79 | In Python, image processing using OpenCV is implemented using the ``cv2`` and
 80 | ``NumPy`` modules.  The `installation instructions for OpenCV
 81 | <http://docs.opencv.org/2.4/doc/tutorials/introduction/table_of_content_introduction/table_of_content_introduction.html#table-of-content-introduction>`_
 82 | should guide you through configuring the project for yourself.
 83 | 
 84 | NumPy can be downloaded from the Python Package Index(PyPI):
 85 | 
 86 | .. code-block:: console
 87 | 
 88 |     $ pip install numpy
 89 | 
 90 | 
 91 | Example
 92 | ~~~~~~~
 93 | 
 94 | .. code-block:: python
 95 | 
 96 |     import cv2
 97 |     #Read Image
 98 |     img = cv2.imread('testimg.jpg')
 99 |     #Display Image
100 |     cv2.imshow('image',img)
101 |     cv2.waitKey(0)
102 |     cv2.destroyAllWindows()
103 | 
104 |     #Applying Grayscale filter to image
105 |     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
106 | 
107 |     #Saving filtered image to new file
108 |     cv2.imwrite('graytest.jpg',gray)
109 | 
110 | There are more Python-implemented examples of OpenCV in this `collection of
111 | tutorials
112 | <https://opencv-tutorial.readthedocs.io/en/latest/>`_.
113 | 


--------------------------------------------------------------------------------
/docs/scenarios/json.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | ####
 3 | JSON
 4 | ####
 5 | 
 6 | .. image:: /_static/photos/33928819683_97b5c6a184_k_d.jpg
 7 | 
 8 | The `json <https://docs.python.org/3/library/json.html>`_ library can parse
 9 | JSON from strings or files. The library parses JSON into a Python dictionary
10 | or list. It can also convert Python dictionaries or lists into JSON strings.
11 | 
12 | 
13 | ************
14 | Parsing JSON
15 | ************
16 | 
17 | Take the following string containing JSON data:
18 | 
19 | .. code-block:: python
20 | 
21 |     json_string = '{"first_name": "Guido", "last_name":"Rossum"}'
22 | 
23 | It can be parsed like this:
24 | 
25 | .. code-block:: python
26 | 
27 |     import json
28 |     parsed_json = json.loads(json_string)
29 | 
30 | and can now be used as a normal dictionary:
31 | 
32 | .. code-block:: python
33 | 
34 |     print(parsed_json['first_name'])
35 |     "Guido"
36 | 
37 | You can also convert the following to JSON:
38 | 
39 | .. code-block:: python
40 | 
41 |     d = {
42 |         'first_name': 'Guido',
43 |         'second_name': 'Rossum',
44 |         'titles': ['BDFL', 'Developer'],
45 |     }
46 | 
47 |     print(json.dumps(d))
48 |     '{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'
49 | 


--------------------------------------------------------------------------------
/docs/scenarios/ml.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | ################
  4 | Machine Learning
  5 | ################
  6 | 
  7 | .. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg
  8 | 
  9 | 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.
 10 | 
 11 | Some widely used packages for Machine Learning and other data science applications are listed below.
 12 | 
 13 | 
 14 | ***********
 15 | SciPy Stack
 16 | ***********
 17 | 
 18 | 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.
 19 | 
 20 | The Stack consists of the following packages (link to documentation given):
 21 | 
 22 | 1. `NumPy <http://www.numpy.org/>`_
 23 | 2. `SciPy library <https://www.scipy.org/>`_
 24 | 3. `Matplotlib <http://matplotlib.org/>`_
 25 | 4. `IPython <https://ipython.org/>`_
 26 | 5. `pandas <http://pandas.pydata.org/>`_
 27 | 6. `Sympy <http://www.sympy.org/en/index.html>`_
 28 | 7. `nose <http://nose.readthedocs.io/en/latest/>`_
 29 | 
 30 | The stack also comes with Python bundled in, but has been excluded from the above list.
 31 | 
 32 | Installation
 33 | ~~~~~~~~~~~~
 34 | 
 35 | For installing the full stack, or individual packages, you can refer to the instructions given `here <https://www.scipy.org/install.html>`_.
 36 | 
 37 | **NB:** `Anaconda <https://www.continuum.io/anaconda-overview>`_ is highly preferred and recommended for installing and maintaining data science packages seamlessly.
 38 | 
 39 | 
 40 | ************
 41 | scikit-learn
 42 | ************
 43 | 
 44 | 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.
 45 | 
 46 | Because of its speed, robustness, and ease of, it's one of the most widely-used libraries for many Machine Learning applications.
 47 | 
 48 | Installation
 49 | ~~~~~~~~~~~~
 50 | 
 51 | Through PyPI:
 52 | 
 53 | .. code-block:: python
 54 | 
 55 | 	pip install -U scikit-learn
 56 | 
 57 | Through conda:
 58 | 
 59 | .. code-block:: python
 60 | 
 61 | 	conda install scikit-learn
 62 | 
 63 | scikit-learn also comes shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link <http://scikit-learn.org/stable/install.html>`_.
 64 | 
 65 | Example
 66 | ~~~~~~~
 67 | 
 68 | For this example, we train a simple classifier on the `Iris dataset <http://en.wikipedia.org/wiki/Iris_flower_data_set>`_, which comes bundled in with scikit-learn.
 69 | 
 70 | 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).
 71 | 
 72 | 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.
 73 | 
 74 | .. code-block:: python
 75 | 
 76 | 	from sklearn.datasets import load_iris
 77 | 	from sklearn import tree
 78 | 	from sklearn.metrics import accuracy_score
 79 | 	import numpy as np
 80 | 
 81 | 	#loading the iris dataset
 82 | 	iris = load_iris()
 83 | 
 84 | 	x = iris.data #array of the data
 85 | 	y = iris.target #array of labels (i.e answers) of each data entry
 86 | 
 87 | 	#getting label names i.e the three flower species
 88 | 	y_names = iris.target_names
 89 | 
 90 | 	#taking random indices to split the dataset into train and test
 91 | 	test_ids = np.random.permutation(len(x))
 92 | 
 93 | 	#splitting data and labels into train and test
 94 | 	#keeping last 10 entries for testing, rest for training
 95 | 
 96 | 	x_train = x[test_ids[:-10]]
 97 | 	x_test = x[test_ids[-10:]]
 98 | 
 99 | 	y_train = y[test_ids[:-10]]
100 | 	y_test = y[test_ids[-10:]]
101 | 
102 | 	#classifying using decision tree
103 | 	clf = tree.DecisionTreeClassifier()
104 | 
105 | 	#training (fitting) the classifier with the training set
106 | 	clf.fit(x_train, y_train)
107 | 
108 | 	#predictions on the test dataset
109 | 	pred = clf.predict(x_test)
110 | 
111 | 	print pred #predicted labels i.e flower species
112 | 	print y_test #actual labels
113 | 	print (accuracy_score(pred, y_test))*100 #prediction accuracy
114 | 
115 | Since we're splitting randomly and the classifier trains on every iteration, the accuracy may vary. Running the above code gives:
116 | 
117 | .. code-block:: python
118 | 
119 | 	[0 1 1 1 0 2 0 2 2 2]
120 | 	[0 1 1 1 0 2 0 2 2 2]
121 | 	100.0
122 | 
123 | 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.
124 | 
125 | More on scikit-learn can be read in the `documentation <http://scikit-learn.org/stable/user_guide.html>`_.
126 | 


--------------------------------------------------------------------------------
/docs/scenarios/network.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | ##########
 3 | Networking
 4 | ##########
 5 | 
 6 | .. image:: /_static/photos/34151833832_6bdfd930af_k_d.jpg
 7 | 
 8 | 
 9 | *******
10 | Twisted
11 | *******
12 | 
13 | `Twisted <https://twistedmatrix.com/trac/>`_ is an event-driven networking
14 | engine. It can be used to build applications around many different networking
15 | protocols, including HTTP servers and clients, applications using SMTP, POP3,
16 | IMAP, or SSH protocols, instant messaging,
17 | and `much more <https://twistedmatrix.com/trac/wiki/Documentation>`_.
18 | 
19 | 
20 | *****
21 | PyZMQ
22 | *****
23 | 
24 | `PyZMQ <https://zeromq.github.com/pyzmq/>`_ is the Python binding for
25 | `ZeroMQ <http://zeromq.org/>`_, which is a high-performance asynchronous
26 | messaging library. One great advantage of ZeroMQ is that it can be used for
27 | message queuing without a message broker. The basic patterns for this are:
28 | 
29 | - request-reply: connects a set of clients to a set of services. This is a
30 |   remote procedure call and task distribution pattern.
31 | - publish-subscribe: connects a set of publishers to a set of subscribers.
32 |   This is a data distribution pattern.
33 | - push-pull (or pipeline): connects nodes in a fan-out/fan-in pattern that
34 |   can have multiple steps and loops. This is a parallel task distribution
35 |   and collection pattern.
36 | 
37 | For a quick start, read the `ZeroMQ guide <http://zguide.zeromq.org/page:all>`_.
38 | 
39 | 
40 | ******
41 | gevent
42 | ******
43 | 
44 | `gevent <http://www.gevent.org/>`_ is a coroutine-based Python networking
45 | library that uses greenlets to provide a high-level synchronous API on top of
46 | the libev event loop.
47 | 


--------------------------------------------------------------------------------
/docs/scenarios/scientific.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | #######################
  3 | Scientific Applications
  4 | #######################
  5 | 
  6 | .. image:: /_static/photos/33925223870_97e44f5629_k_d.jpg
  7 | 
  8 | 
  9 | *******
 10 | Context
 11 | *******
 12 | 
 13 | Python is frequently used for high-performance scientific applications. It
 14 | is widely used in academia and scientific projects because it is easy to write
 15 | and performs well.
 16 | 
 17 | Due to its high performance nature, scientific computing in Python often
 18 | utilizes external libraries, typically written in faster languages (like C, or
 19 | Fortran for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
 20 | and `Matplotlib`_. Going into detail about these libraries is beyond the scope
 21 | of the Python guide. However, a comprehensive introduction to the scientific
 22 | Python ecosystem can be found in the `Python Scientific Lecture Notes
 23 | <http://scipy-lectures.github.com/>`_.
 24 | 
 25 | 
 26 | *****
 27 | Tools
 28 | *****
 29 | 
 30 | IPython
 31 | -------
 32 | 
 33 | `IPython <http://ipython.org/>`_ is an enhanced version of Python interpreter,
 34 | which provides features of great interest to scientists. The `inline mode`
 35 | allows graphics and plots to be displayed in the terminal (Qt based version).
 36 | Moreover, the `notebook` mode supports literate programming and reproducible
 37 | science generating a web-based Python notebook. This notebook allows you to
 38 | store chunks of Python code alongside the results and additional comments
 39 | (HTML, LaTeX, Markdown). The notebook can then be shared and exported in various
 40 | file formats.
 41 | 
 42 | 
 43 | *********
 44 | Libraries
 45 | *********
 46 | 
 47 | NumPy
 48 | -----
 49 | 
 50 | `NumPy <http://numpy.scipy.org/>`_ is a low level library written in C (and
 51 | Fortran) for high level mathematical functions. NumPy cleverly overcomes the
 52 | problem of running slower algorithms on Python by using multidimensional arrays
 53 | and functions that operate on arrays. Any algorithm can then be expressed as a
 54 | function on arrays, allowing the algorithms to be run quickly.
 55 | 
 56 | NumPy is part of the SciPy project, and is released as a separate library so
 57 | people who only need the basic requirements can use it without installing the
 58 | rest of SciPy.
 59 | 
 60 | NumPy is compatible with Python versions 2.4 through 2.7.2 and 3.1+.
 61 | 
 62 | Numba
 63 | -----
 64 | 
 65 | `Numba <http://numba.pydata.org>`_ is a NumPy aware Python compiler
 66 | (just-in-time (JIT) specializing compiler) which compiles annotated Python (and
 67 | NumPy) code to LLVM (Low Level Virtual Machine) through special decorators.
 68 | Briefly, Numba uses a system that compiles Python code with LLVM to code which
 69 | can be natively executed at runtime.
 70 | 
 71 | SciPy
 72 | -----
 73 | 
 74 | `SciPy <http://scipy.org/>`_ is a library that uses NumPy for more mathematical
 75 | functions. SciPy uses NumPy arrays as the basic data structure, and comes
 76 | with modules for various commonly used tasks in scientific programming,
 77 | including linear algebra, integration (calculus), ordinary differential equation
 78 | solving, and signal processing.
 79 | 
 80 | Matplotlib
 81 | ----------
 82 | 
 83 | `Matplotlib <http://matplotlib.sourceforge.net/>`_ is a flexible plotting
 84 | library for creating interactive 2D and 3D plots that can also be saved as
 85 | manuscript-quality figures. The API in many ways reflects that of `MATLAB
 86 | <http://www.mathworks.com/products/matlab/>`_, easing transition of MATLAB
 87 | users to Python. Many examples, along with the source code to recreate them,
 88 | are available in the `matplotlib gallery
 89 | <http://matplotlib.sourceforge.net/gallery.html>`_.
 90 | 
 91 | Pandas
 92 | ------
 93 | 
 94 | `Pandas <http://pandas.pydata.org/>`_ is a data manipulation library
 95 | based on NumPy which provides many useful functions for accessing,
 96 | indexing, merging, and grouping data easily. The main data structure (DataFrame)
 97 | is close to what could be found in the R statistical package; that is,
 98 | heterogeneous data tables with name indexing, time series operations, and
 99 | auto-alignment of data.
100 | 
101 | xarray
102 | ------
103 | 
104 | `xarray <http://xarray.pydata.org/en/stable/>`_ is similar to Pandas, but it 
105 | is intended for wrapping multidimensional scientific data. By labelling the 
106 | data with dimensions, coordinates, and attributes, it makes complex 
107 | multidimensional operations clearer and more intuitive. It also wraps 
108 | matplotlib for quick plotting, and can apply most operations in parallel using 
109 | `dask <http://xarray.pydata.org/en/stable/dask.html>`_.
110 | 
111 | 
112 | Rpy2
113 | ----
114 | 
115 | `Rpy2 <http://rpy2.bitbucket.org>`_ is a Python binding for the R
116 | statistical package allowing the execution of R functions from Python and
117 | passing data back and forth between the two environments. Rpy2 is the object
118 | oriented implementation of the `Rpy <http://rpy.sourceforge.net/rpy.html>`_
119 | bindings.
120 | 
121 | PsychoPy
122 | --------
123 | 
124 | `PsychoPy <http://www.psychopy.org/>`_ is a library for cognitive scientists
125 | allowing the creation of cognitive psychology and neuroscience experiments.
126 | The library handles presentation of stimuli, scripting of experimental design,
127 | and data collection.
128 | 
129 | 
130 | *********
131 | Resources
132 | *********
133 | 
134 | Installation of scientific Python packages can be troublesome, as many of
135 | these packages are implemented as Python C extensions which need to be compiled.
136 | This section lists various so-called scientific Python distributions which
137 | provide precompiled and easy-to-install collections of scientific Python
138 | packages.
139 | 
140 | Unofficial Windows Binaries for Python Extension Packages
141 | ---------------------------------------------------------
142 | 
143 | Many people who do scientific computing are on Windows, yet many of the
144 | scientific computing packages are notoriously difficult to build and install on
145 | this platform. `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_,
146 | however, has compiled a list of Windows binaries for many useful Python
147 | packages.  The list of packages has grown from a mainly scientific Python
148 | resource to a more general list. If you're on Windows, you may want to check it
149 | out.
150 | 
151 | Anaconda
152 | --------
153 | 
154 | The `Anaconda Python Distribution <https://www.anaconda.com/>`_
155 | includes all the common scientific Python packages as well as many packages
156 | related to data analytics and big data. Anaconda itself is free, and a number
157 | of proprietary add-ons are available for a fee. Free licenses for the
158 | add-ons are available for academics and researchers.
159 | 
160 | Canopy
161 | ------
162 | 
163 | `Canopy <https://www.enthought.com/product/canopy/>`_ is another scientific
164 | Python distribution, produced by `Enthought <https://www.enthought.com/>`_.
165 | A limited 'Canopy Express' variant is available for free, but Enthought
166 | charges for the full distribution. Free licenses are available for academics.
167 | 


--------------------------------------------------------------------------------
/docs/scenarios/scrape.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | #############
  3 | HTML Scraping
  4 | #############
  5 | 
  6 | .. image:: /_static/photos/34268661876_442428e122_k_d.jpg
  7 | 
  8 | 
  9 | ************
 10 | Web Scraping
 11 | ************
 12 | 
 13 | Web sites are written using HTML, which means that each web page is a
 14 | structured document. Sometimes it would be great to obtain some data from
 15 | them and preserve the structure while we're at it. Web sites don't always
 16 | provide their data in comfortable formats such as CSV or JSON.
 17 | 
 18 | This is where web scraping comes in. Web scraping is the practice of using a
 19 | computer program to sift through a web page and gather the data that you need
 20 | in a format most useful to you while at the same time preserving the structure
 21 | of the data.
 22 | 
 23 | 
 24 | *****************
 25 | lxml and Requests
 26 | *****************
 27 | 
 28 | `lxml <http://lxml.de/>`_ is a pretty extensive library written for parsing
 29 | XML and HTML documents very quickly, even handling messed up tags in the
 30 | process. We will also be using the
 31 | `Requests <https://requests.readthedocs.io/en/latest/>`_ module instead of the
 32 | already built-in urllib2 module due to improvements in speed and readability.
 33 | You can easily install both using ``pip install lxml`` and
 34 | ``pip install requests``.
 35 | 
 36 | Let's start with the imports:
 37 | 
 38 | .. code-block:: python
 39 | 
 40 |     from lxml import html
 41 |     import requests
 42 | 
 43 | Next we will use ``requests.get`` to retrieve the web page with our data,
 44 | parse it using the ``html`` module, and save the results in ``tree``:
 45 | 
 46 | .. code-block:: python
 47 | 
 48 |     page = requests.get('http://econpy.pythonanywhere.com/ex/001.html')
 49 |     tree = html.fromstring(page.content)
 50 | 
 51 | (We need to use ``page.content`` rather than ``page.text`` because
 52 | ``html.fromstring`` implicitly expects ``bytes`` as input.)
 53 | 
 54 | ``tree`` now contains the whole HTML file in a nice tree structure which
 55 | we can go over two different ways: XPath and CSSSelect. In this example, we
 56 | will focus on the former.
 57 | 
 58 | XPath is a way of locating information in structured documents such as
 59 | HTML or XML documents. A good introduction to XPath is on
 60 | `W3Schools <http://www.w3schools.com/xml/xpath_intro.asp>`_ .
 61 | 
 62 | There are also various tools for obtaining the XPath of elements such as
 63 | FireBug for Firefox or the Chrome Inspector. If you're using Chrome, you
 64 | can right click an element, choose 'Inspect element', highlight the code,
 65 | right click again, and choose 'Copy XPath'.
 66 | 
 67 | After a quick analysis, we see that in our page the data is contained in
 68 | two elements -- one is a div with title 'buyer-name' and the other is a
 69 | span with class 'item-price':
 70 | 
 71 | .. code-block:: html
 72 | 
 73 |     <div title="buyer-name">Carson Busses</div>
 74 |     <span class="item-price">$29.95</span>
 75 | 
 76 | Knowing this we can create the correct XPath query and use the lxml
 77 | ``xpath`` function like this:
 78 | 
 79 | .. code-block:: python
 80 | 
 81 |     #This will create a list of buyers:
 82 |     buyers = tree.xpath('//div[@title="buyer-name"]/text()')
 83 |     #This will create a list of prices
 84 |     prices = tree.xpath('//span[@class="item-price"]/text()')
 85 | 
 86 | Let's see what we got exactly:
 87 | 
 88 | .. code-block:: python
 89 | 
 90 |     print('Buyers: ', buyers)
 91 |     print('Prices: ', prices)
 92 | 
 93 | ::
 94 | 
 95 |     Buyers:  ['Carson Busses', 'Earl E. Byrd', 'Patty Cakes',
 96 |     'Derri Anne Connecticut', 'Moe Dess', 'Leda Doggslife', 'Dan Druff',
 97 |     'Al Fresco', 'Ido Hoe', 'Howie Kisses', 'Len Lease', 'Phil Meup',
 98 |     'Ira Pent', 'Ben D. Rules', 'Ave Sectomy', 'Gary Shattire',
 99 |     'Bobbi Soks', 'Sheila Takya', 'Rose Tattoo', 'Moe Tell']
100 | 
101 |     Prices:  ['$29.95', '$8.37', '$15.26', '$19.25', '$19.25',
102 |     '$13.99', '$31.57', '$8.49', '$14.47', '$15.86', '$11.11',
103 |     '$15.98', '$16.27', '$7.50', '$50.85', '$14.26', '$5.68',
104 |     '$15.00', '$114.07', '$10.09']
105 | 
106 | Congratulations! We have successfully scraped all the data we wanted from
107 | a web page using lxml and Requests. We have it stored in memory as two
108 | lists. Now we can do all sorts of cool stuff with it: we can analyze it
109 | using Python or we can save it to a file and share it with the world.
110 | 
111 | Some more cool ideas to think about are modifying this script to iterate
112 | through the rest of the pages of this example dataset, or rewriting this
113 | application to use threads for improved speed.
114 | 


--------------------------------------------------------------------------------
/docs/scenarios/serialization.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | ##################
  3 | Data Serialization
  4 | ##################
  5 | 
  6 | .. image:: /_static/photos/33467946364_3e59bd376a_k_d.jpg
  7 | 
  8 | 
  9 | ***************************
 10 | What is data serialization?
 11 | ***************************
 12 | 
 13 | Data serialization is the process of converting structured data to a format
 14 | that allows sharing or storage of the data in a form that allows recovery of its original
 15 | structure. In some cases, the secondary intention of data
 16 | serialization is to minimize the data's size which then
 17 | reduces disk space or bandwidth requirements.
 18 | 
 19 | ********************
 20 | Flat vs. Nested data
 21 | ********************
 22 | 
 23 | Before beginning to serialize data, it is important to identify or decide how the
 24 | data should be structured during data serialization - flat or nested.
 25 | The differences in the two styles are shown in the below examples.
 26 | 
 27 | Flat style:
 28 | 
 29 | .. code-block:: python
 30 | 
 31 |         { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" }
 32 | 
 33 | 
 34 | Nested style:
 35 | 
 36 | .. code-block:: python
 37 | 
 38 |         {"A"
 39 |             { "field1": "value1", "field2": "value2", "field3": "value3" } }
 40 | 
 41 | 
 42 | For more reading on the two styles, please see the discussion on
 43 | `Python mailing list <https://mail.python.org/pipermail/python-list/2010-October/590762.html>`__,
 44 | `IETF mailing list <https://www.ietf.org/mail-archive/web/json/current/msg03739.html>`__ and
 45 | `in stackexchange <https://softwareengineering.stackexchange.com/questions/350623/flat-or-nested-json-for-hierarchal-data>`__.
 46 | 
 47 | ****************
 48 | Serializing Text
 49 | ****************
 50 | 
 51 | =======================
 52 | Simple file (flat data)
 53 | =======================
 54 | 
 55 | If the data to be serialized is located in a file and contains flat data, Python offers two methods to serialize data.
 56 | 
 57 | repr
 58 | ----
 59 | 
 60 | The repr method in Python takes a single object parameter and returns a printable representation of the input:
 61 | 
 62 | .. code-block:: python
 63 | 
 64 |         # input as flat text
 65 |         a =  { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" }
 66 | 
 67 |         # the same input can also be read from a file
 68 |         a = open('/tmp/file.py', 'r')
 69 | 
 70 |         # returns a printable representation of the input;
 71 |         # the output can be written to a file as well
 72 |         print(repr(a))
 73 | 
 74 |         # write content to files using repr
 75 |         with open('/tmp/file.py') as f:f.write(repr(a))
 76 | 
 77 | 
 78 | ast.literal_eval
 79 | ----------------
 80 | 
 81 | The literal_eval method safely parses and evaluates an expression for a Python datatype.
 82 | Supported data types are: strings, numbers, tuples, lists, dicts, booleans, and None.
 83 | 
 84 | .. code-block:: python
 85 | 
 86 |         with open('/tmp/file.py', 'r') as f: inp = ast.literal_eval(f.read())
 87 | 
 88 | ====================
 89 | CSV file (flat data)
 90 | ====================
 91 | 
 92 | The CSV module in Python implements classes to read and write tabular
 93 | data in CSV format.
 94 | 
 95 | Simple example for reading:
 96 | 
 97 | .. code-block:: python
 98 | 
 99 |         # Reading CSV content from a file
100 |         import csv
101 |         with open('/tmp/file.csv', newline='') as f:
102 |             reader = csv.reader(f)
103 |             for row in reader:
104 |                 print(row)
105 | 
106 | Simple example for writing:
107 | 
108 | .. code-block:: python
109 | 
110 |         # Writing CSV content to a file
111 |         import csv
112 |         with open('/temp/file.csv', 'w', newline='') as f:
113 |             writer = csv.writer(f)
114 |             writer.writerows(iterable)
115 | 
116 | 
117 | The module's contents, functions, and examples can be found
118 | `in the Python documentation <https://docs.python.org/3/library/csv.html>`__.
119 | 
120 | ==================
121 | YAML (nested data)
122 | ==================
123 | 
124 | There are many third party modules to parse and read/write YAML file
125 | structures in Python. One such example is below.
126 | 
127 | .. code-block:: python
128 | 
129 |         # Reading YAML content from a file using the load method
130 |         import yaml
131 |         with open('/tmp/file.yaml', 'r', newline='') as f:
132 |             try:
133 |                 print(yaml.load(f))
134 |             except yaml.YAMLError as ymlexcp:
135 |                 print(ymlexcp)
136 | 
137 | Documentation on the third party module can be found
138 | `in the PyYAML Documentation <https://pyyaml.org/wiki/PyYAMLDocumentation>`__.
139 | 
140 | =======================
141 | JSON file (nested data)
142 | =======================
143 | 
144 | Python's JSON module can be used to read and write JSON files.
145 | Example code is below.
146 | 
147 | Reading:
148 | 
149 | .. code-block:: python
150 | 
151 |         # Reading JSON content from a file
152 |         import json
153 |         with open('/tmp/file.json', 'r') as f:
154 |             data = json.load(f)
155 | 
156 | Writing:
157 | 
158 | .. code-block:: python
159 | 
160 |         # Writing JSON content to a file using the dump method
161 |         import json
162 |         with open('/tmp/file.json', 'w') as f:
163 |             json.dump(data, f, sort_keys=True)
164 | 
165 | =================
166 | XML (nested data)
167 | =================
168 | 
169 | XML parsing in Python is possible using the `xml` package.
170 | 
171 | Example:
172 | 
173 | .. code-block:: python
174 | 
175 |         # reading XML content from a file
176 |         import xml.etree.ElementTree as ET
177 |         tree = ET.parse('country_data.xml')
178 |         root = tree.getroot()
179 | 
180 | More documentation on using the `xml.dom` and `xml.sax` packages can be found
181 | `in the Python XML library documentation <https://docs.python.org/3/library/xml.html>`__.
182 | 
183 | 
184 | *******
185 | Binary
186 | *******
187 | 
188 | =======================
189 | NumPy Array (flat data)
190 | =======================
191 | 
192 | Python's NumPy array can be used to serialize and deserialize data to and from byte representation.
193 | 
194 | Example:
195 | 
196 | .. code-block:: python
197 | 
198 |     import NumPy as np
199 | 
200 |     # Converting NumPy array to byte format
201 |     byte_output = np.array([ [1, 2, 3], [4, 5, 6], [7, 8, 9] ]).tobytes()
202 | 
203 |     # Converting byte format back to NumPy array
204 |     array_format = np.frombuffer(byte_output)
205 | 
206 | 
207 | 
208 | ====================
209 | Pickle (nested data)
210 | ====================
211 | 
212 | The native data serialization module for Python is called `Pickle
213 | <https://docs.python.org/2/library/pickle.html>`_.
214 | 
215 | Here's an example:
216 | 
217 | .. code-block:: python
218 | 
219 |         import pickle
220 | 
221 |         #Here's an example dict
222 |         grades = { 'Alice': 89, 'Bob': 72, 'Charles': 87 }
223 | 
224 |         #Use dumps to convert the object to a serialized string
225 |         serial_grades = pickle.dumps( grades )
226 | 
227 |         #Use loads to de-serialize an object
228 |         received_grades = pickle.loads( serial_grades )
229 | 
230 | 
231 | ********
232 | Protobuf
233 | ********
234 | 
235 | If you're looking for a serialization module that has support in multiple
236 | languages, Google's `Protobuf
237 | <https://developers.google.com/protocol-buffers>`_ library is an option.
238 | 


--------------------------------------------------------------------------------
/docs/scenarios/xml.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | ###########
  3 | XML parsing
  4 | ###########
  5 | 
  6 | .. image:: /_static/photos/33888714601_a1f7d020a2_k_d.jpg
  7 | 
  8 | 
  9 | ********
 10 | untangle
 11 | ********
 12 | 
 13 | `untangle <https://github.com/stchris/untangle>`_ is a simple library which
 14 | takes an XML document and returns a Python object which mirrors the nodes and
 15 | attributes in its structure.
 16 | 
 17 | For example, an XML file like this:
 18 | 
 19 | .. code-block:: xml
 20 | 
 21 |     <?xml version="1.0"?>
 22 |     <root>
 23 |         <child name="child1">
 24 |     </root>
 25 | 
 26 | can be loaded like this:
 27 | 
 28 | .. code-block:: python
 29 | 
 30 |     import untangle
 31 |     obj = untangle.parse('path/to/file.xml')
 32 | 
 33 | and then you can get the child element's name attribute like this:
 34 | 
 35 | .. code-block:: python
 36 | 
 37 |     obj.root.child['name']
 38 | 
 39 | untangle also supports loading XML from a string or a URL.
 40 | 
 41 | 
 42 | *********
 43 | xmltodict
 44 | *********
 45 | 
 46 | `xmltodict <https://github.com/martinblech/xmltodict>`_ is another simple
 47 | library that aims at making XML feel like working with JSON.
 48 | 
 49 | An XML file like this:
 50 | 
 51 | .. code-block:: xml
 52 | 
 53 |     <mydocument has="an attribute">
 54 |       <and>
 55 |         <many>elements</many>
 56 |         <many>more elements</many>
 57 |       </and>
 58 |       <plus a="complex">
 59 |         element as well
 60 |       </plus>
 61 |     </mydocument>
 62 | 
 63 | can be loaded into a Python dict like this:
 64 | 
 65 | .. code-block:: python
 66 | 
 67 |     import xmltodict
 68 | 
 69 |     with open('path/to/file.xml') as fd:
 70 |         doc = xmltodict.parse(fd.read())
 71 | 
 72 | and then you can access elements, attributes, and values like this:
 73 | 
 74 | .. code-block:: python
 75 | 
 76 |     doc['mydocument']['@has'] # == u'an attribute'
 77 |     doc['mydocument']['and']['many'] # == [u'elements', u'more elements']
 78 |     doc['mydocument']['plus']['@a'] # == u'complex'
 79 |     doc['mydocument']['plus']['#text'] # == u'element as well'
 80 | 
 81 | xmltodict also lets you roundtrip back to XML with the unparse function,
 82 | has a streaming mode suitable for handling files that don't fit in memory,
 83 | and supports XML namespaces.
 84 | 
 85 | **********
 86 | xmlschema
 87 | **********
 88 | 
 89 | `xmlschema <https://github.com/sissaschool/xmlschema>`_ provides support for using XSD-Schemas in Python.
 90 | 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. 
 91 | Moreover the library supports automatic and explicit validation of XML documents against a schema.
 92 | 
 93 | .. code-block:: python
 94 | 
 95 |     from xmlschema import XMLSchema, etree_tostring
 96 | 
 97 |     # load a XSD schema file
 98 |     schema = XMLSchema("your_schema.xsd")
 99 |     
100 |     # validate against the schema
101 |     schema.validate("your_file.xml")
102 |     
103 |     # or
104 |     schema.is_valid("your_file.xml")
105 |     
106 |     # decode a file
107 |     data = schmema.decode("your_file.xml")
108 |     
109 |     # encode to string
110 |     s = etree_tostring(schema.encode(data))
111 | 


--------------------------------------------------------------------------------
/docs/shipping/packaging.rst:
--------------------------------------------------------------------------------
  1 | .. _packaging-your-code-ref:
  2 | 
  3 | 
  4 | ###################
  5 | Packaging Your Code
  6 | ###################
  7 | 
  8 | .. image:: /_static/photos/36137234682_be6898bf57_k_d.jpg
  9 | 
 10 | Package your code to share it with other developers. For example,
 11 | to share a library for other developers to use in their application,
 12 | or for development tools like 'py.test'.
 13 | 
 14 | An advantage of this method of distribution is its well established ecosystem
 15 | of tools such as PyPI and pip, which make it easy for other developers to
 16 | download and install your package either for casual experiments, or as part of
 17 | large, professional systems.
 18 | 
 19 | It is a well-established convention for Python code to be shared this way.
 20 | If your code isn't packaged on PyPI, then it will be harder
 21 | for other developers to find it and to use it as part of their existing
 22 | process. They will regard such projects with substantial suspicion of being
 23 | either badly managed or abandoned.
 24 | 
 25 | The downside of distributing code like this is that it relies on the
 26 | recipient understanding how to install the required version of Python,
 27 | and being able and willing to use tools such as pip to install your code's
 28 | other dependencies. This is fine when distributing to other developers, but
 29 | makes this method unsuitable for distributing applications to end-users.
 30 | 
 31 | The `Python Packaging Guide <https://python-packaging-user-guide.readthedocs.io/>`_
 32 | provides an extensive guide on creating and maintaining Python packages.
 33 | 
 34 | 
 35 | *************************
 36 | Alternatives to Packaging
 37 | *************************
 38 | 
 39 | To distribute applications to end-users, you should
 40 | :ref:`freeze your application <freezing-your-code-ref>`.
 41 | 
 42 | On Linux, you may also want to consider
 43 | :ref:`creating a Linux distro package <packaging-for-linux-distributions-ref>`
 44 | (e.g. a .deb file for Debian or Ubuntu.)
 45 | 
 46 | 
 47 | *********************
 48 | For Python Developers
 49 | *********************
 50 | 
 51 | If you're writing an open source Python module, `PyPI <http://pypi.org>`_
 52 | , more properly known as *The Cheeseshop*, is the place to host it.
 53 | 
 54 | 
 55 | 
 56 | Pip vs. easy_install
 57 | --------------------
 58 | 
 59 | Use `pip <http://pypi.org/project/pip>`_.  More details
 60 | `here <https://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_.
 61 | 
 62 | 
 63 | Personal PyPI
 64 | -------------
 65 | 
 66 | If you want to install packages from a source other than PyPI (say, if
 67 | your packages are *proprietary*), you can do it by hosting a simple HTTP
 68 | server, running from the directory which holds those packages which need to be
 69 | installed.
 70 | 
 71 | **Showing an example is always beneficial**
 72 | 
 73 | For example, if you want to install a package called :file:`MyPackage.tar.gz`,
 74 | and assuming this is your directory structure:
 75 | 
 76 | 
 77 | - archive
 78 |    - MyPackage
 79 |        - MyPackage.tar.gz
 80 | 
 81 | Go to your command prompt and type:
 82 | 
 83 | .. code-block:: console
 84 | 
 85 |    $ cd archive
 86 |    $ python -m http.server 9000
 87 | 
 88 | This runs a simple HTTP server running on port 9000 and will list all packages
 89 | (like **MyPackage**). Now you can install **MyPackage** using any Python
 90 | package installer. Using pip, you would do it like:
 91 | 
 92 | .. code-block:: console
 93 | 
 94 |    $ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage
 95 | 
 96 | Having a folder with the same name as the package name is **crucial** here.
 97 | I got fooled by that, one time. But if you feel that creating a folder called
 98 | :file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that is
 99 | *redundant*, you can still install MyPackage using:
100 | 
101 | .. code-block:: console
102 | 
103 |    $ pip install  http://127.0.0.1:9000/MyPackage.tar.gz
104 | 
105 | pypiserver
106 | ++++++++++
107 | 
108 | `pypiserver <https://pypi.org/project/pypiserver>`_ is a minimal PyPI
109 | compatible server.  It can be used to serve a set of packages to easy_install
110 | or pip.  It includes helpful features like an administrative command
111 | (``-U``) which will update all its packages to their latest versions
112 | found on PyPI.
113 | 
114 | 
115 | S3-Hosted PyPi
116 | ++++++++++++++
117 | 
118 | One simple option for a personal PyPI server is to use Amazon S3. A
119 | prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
120 | 
121 | 1. **Install all your requirements from PyPi or another source**
122 | 2. **Install pip2pi**
123 | 
124 | * :code:`pip install git+https://github.com/wolever/pip2pi.git`
125 | 
126 | 3. **Follow pip2pi README for pip2tgz and dir2pi commands**
127 | 
128 | * :code:`pip2tgz packages/ YourPackage` (or :code:`pip2tgz packages/ -r requirements.txt`)
129 | * :code:`dir2pi packages/`
130 | 
131 | 4. **Upload the new files**
132 | 
133 | * Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket.
134 | * Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories.
135 | 
136 | 5. **Fix new file permissions**
137 | 
138 | * By default, when you upload new files to the S3 bucket, they will have the wrong permissions set.
139 | * Use the Amazon web console to set the READ permission of the files to EVERYONE.
140 | * If you get HTTP 403 when trying to install a package, make sure you've set the permissions correctly.
141 | 
142 | 6. **All done**
143 | 
144 | * You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`.
145 | 
146 | .. _packaging-for-linux-distributions-ref:
147 | 
148 | 
149 | ***********************
150 | For Linux Distributions
151 | ***********************
152 | 
153 | Creating a Linux distro package is arguably the "right way" to distribute code
154 | on Linux.
155 | 
156 | Because a distribution package doesn't include the Python interpreter, it
157 | makes the download and install about 2-12 MB smaller than
158 | :ref:`freezing your application <freezing-your-code-ref>`.
159 | 
160 | Also, if a distribution releases a new security update for Python, then your
161 | application will automatically start using that new version of Python.
162 | 
163 | The bdist_rpm command makes `producing an RPM file <https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages>`_
164 | for use by distributions like Red Hat or SuSE trivially easy.
165 | 
166 | However, creating and maintaining the different configurations required for
167 | each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red
168 | Hat/Fedora, etc.) is a fair amount of work. If your code is an application that
169 | you plan to distribute on other platforms, then you'll also have to create and
170 | maintain the separate config required to freeze your application for Windows
171 | and OS X. It would be much less work to simply create and maintain a single
172 | config for one of the cross platform :ref:`freezing tools
173 | <freezing-your-code-ref>`, which will produce stand-alone executables for all
174 | distributions of Linux, as well as Windows and OS X.
175 | 
176 | Creating a distribution package is also problematic if your code is for a
177 | version of Python that isn't currently supported by a distribution.
178 | Having to tell *some versions* of Ubuntu end-users that they need to add `the
179 | 'dead-snakes' PPA <https://launchpad.net/~fkrull/+archive/ubuntu/deadsnakes>`_
180 | using `sudo apt-repository` commands before they can install your .deb file
181 | makes for an extremely hostile user experience. Not only that, but you'd have
182 | to maintain a custom equivalent of these instructions for every distribution,
183 | and worse, have your users read, understand, and act on them.
184 | 
185 | Having said all that, here's how to do it:
186 | 
187 | * `Fedora <https://fedoraproject.org/wiki/Packaging:Python>`_
188 | * `Debian and Ubuntu <http://www.debian.org/doc/packaging-manuals/python-policy/>`_
189 | * `Arch <https://wiki.archlinux.org/index.php/Python_Package_Guidelines>`_
190 | 
191 | Useful Tools
192 | ------------
193 | 
194 | - `fpm <https://github.com/jordansissel/fpm>`_
195 | - `alien <http://joeyh.name/code/alien/>`_
196 | - `dh-virtualenv <https://dh-virtualenv.readthedocs.io/>`_ (for APT/DEB omnibus packaging)
197 | 


--------------------------------------------------------------------------------
/docs/shipping/publishing.rst:
--------------------------------------------------------------------------------
 1 | .. _publishing-your-code-ref:
 2 | 
 3 | 
 4 | ####################
 5 | Publishing Your Code
 6 | ####################
 7 | 
 8 | .. todo:: Replace this kitten with the photo we want.
 9 | 
10 | .. image:: https://placekitten.com/800/600
11 | 
12 | A healthy open source project needs a place to publish its code and project
13 | management stuff so other developers can collaborate with you. This lets your
14 | users gain a better understanding of your code, keep up with new developments,
15 | report bugs, and contribute code.
16 | 
17 | This development web site should include the source code history itself, a bug
18 | tracker, a patch submission (aka "Pull Request") queue, and possibly additional
19 | developer-oriented documentation.
20 | 
21 | There are several free open source project hosting sites (aka "forges"). These
22 | include GitHub, SourceForge, Bitbucket, and GitLab. GitHub is currently the best.
23 | Use GitHub.
24 | 
25 | 
26 | *********************************
27 | Creating a Project Repo on GitHub
28 | *********************************
29 | 
30 | To publish your Python project on GitHub:
31 | 
32 | 1. Create a GitHub account if you don't already have one.
33 | 
34 | 2. Create a new repo for your project.
35 | 
36 |    1. Click on the "+" menu next to your avatar in the upper right of the page and choose "New repository".
37 | 
38 |    2. Name it after your project and give it an SEO-friendly description.
39 | 
40 |    3. If you don't have an existing project repo, choose the settings to add a
41 |       README, `.gitignore`, and license. Use the Python `.gitignore` option.
42 | 
43 | 3. On the newly created repo page, click "Manage topics" and add the tags "python" and "python3" and/or "python2" as appropriate.
44 | 
45 | 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.
46 | 
47 | If this is a brand new repo, clone it to your local machine and start working:
48 | 
49 | .. code-block:: console
50 | 
51 |     $ git clone https://github.com/<username>/<projectname>
52 | 
53 | Or, if you already have a project Git repo, add your new GitHub repo as a remote:
54 | 
55 | .. code-block:: console
56 | 
57 |     $ cd <projectname>
58 |     $ git remote add origin https://github.com/<username>/<projectname>
59 |     $ git push --tags
60 | 
61 | ***********************
62 | When Your Project Grows
63 | ***********************
64 | 
65 | For more information about managing an open source software project, see the book
66 | `Producing Open Source Software <https://producingoss.com/>`_.
67 | 


--------------------------------------------------------------------------------
/docs/starting/install/linux.rst:
--------------------------------------------------------------------------------
 1 | .. _install-linux:
 2 | 
 3 | 
 4 | ############################
 5 | Installing Python 2 on Linux
 6 | ############################
 7 | 
 8 | .. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
 9 | 
10 | .. note::
11 |     Check out our :ref:`guide for installing Python 3 on Linux<install3-linux>`.
12 | 
13 | The latest versions of CentOS, Red Hat Enterprise Linux (RHEL) and Ubuntu
14 | **come with Python 2.7 out of the box**.
15 | 
16 | To see which version of Python you have installed, open a command prompt and run
17 | 
18 | .. code-block:: console
19 | 
20 |     $ python2 --version
21 | 
22 | However, with the growing popularity of Python 3, some distributions, such as
23 | Fedora, don't come with Python 2 pre-installed. You can install the ``python2``
24 | package with your distribution package manager:
25 | 
26 | .. code-block:: console
27 | 
28 |     $ sudo dnf install python2
29 | 
30 | You do not need to install or configure anything else to use Python. Having
31 | said that, I would strongly recommend that you install the tools and libraries
32 | described in the next section before you start building Python applications
33 | for real-world use. In particular, you should always install Setuptools and pip, as
34 | it makes it much easier for you to use other third-party Python libraries.
35 | 
36 | 
37 | ****************
38 | Setuptools & Pip
39 | ****************
40 | 
41 | The two most crucial third-party Python packages are `setuptools <https://pypi.org/project/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
42 | 
43 | Once installed, you can download, install and uninstall any compliant Python software
44 | product with a single command. It also enables you to add this network installation
45 | capability to your own Python software with very little work.
46 | 
47 | Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
48 | pip by default.
49 | 
50 | To see if pip is installed, open a command prompt and run
51 | 
52 | .. code-block:: console
53 | 
54 |     $ command -v pip
55 | 
56 | To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
57 | 
58 | 
59 | ********************
60 | Virtual Environments
61 | ********************
62 | 
63 | A Virtual Environment is a tool to keep the dependencies required by different projects
64 | in separate places, by creating virtual Python environments for them. It solves the
65 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
66 | your global site-packages directory clean and manageable.
67 | 
68 | For example, you can work on a project which requires Django 1.10 while also
69 | maintaining a project which requires Django 1.8.
70 | 
71 | To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
72 | 
73 | You can also use :ref:`virtualenvwrapper <virtualenvwrapper-ref>` to make it easier to
74 | manage your virtual environments.
75 | 
76 | --------------------------------
77 | 
78 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
79 | which is available under the same license.
80 | 


--------------------------------------------------------------------------------
/docs/starting/install/osx.rst:
--------------------------------------------------------------------------------
  1 | .. _install-osx:
  2 | 
  3 | 
  4 | ###############################
  5 | Installing Python 2 on Mac OS X
  6 | ###############################
  7 | 
  8 | .. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
  9 | 
 10 | .. note::
 11 |     Check out our :ref:`guide for installing Python 3 on OS X<install3-osx>`.
 12 | 
 13 | **Mac OS X comes with Python 2.7 out of the box between versions 10.8 and 12.3.**
 14 | 
 15 | If your Mac OS X version is between the above versions,
 16 | you do not need to install or configure anything else to use Python. Having said
 17 | that, I would strongly recommend that you install the tools and libraries
 18 | described in the next section before you start building Python applications for
 19 | real-world use. In particular, you should always install Setuptools, as it makes
 20 | it much easier for you to install and manage other third-party Python libraries.
 21 | 
 22 | The version of Python that ships with OS X is great for learning, but it's not
 23 | good for development. The version shipped with OS X may be out of date from the
 24 | `official current Python release <https://www.python.org/downloads/mac-osx/>`_,
 25 | which is considered the stable production version.
 26 | 
 27 | 
 28 | **************
 29 | Doing it Right
 30 | **************
 31 | 
 32 | Let's install a real version of Python.
 33 | 
 34 | Before installing Python, you'll need to install a C compiler. The fastest way
 35 | is to install the Xcode Command Line Tools by running
 36 | ``xcode-select --install``. You can also download the full version of
 37 | `Xcode <https://developer.apple.com/xcode/>`_ from the Mac App Store, or the
 38 | minimal but unofficial
 39 | `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
 40 | package.
 41 | 
 42 | .. note::
 43 |     If you already have Xcode installed, do not install OSX-GCC-Installer.
 44 |     In combination, the software can cause issues that are difficult to
 45 |     diagnose.
 46 | 
 47 | .. note::
 48 |     If you perform a fresh install of Xcode, you will also need to add the
 49 |     commandline tools by running ``xcode-select --install`` on the terminal.
 50 | 
 51 | 
 52 | While OS X comes with a large number of Unix utilities, those familiar with
 53 | Linux systems will notice one key component missing: a decent package manager.
 54 | `Homebrew <https://brew.sh>`_ fills this void.
 55 | 
 56 | To `install Homebrew <https://brew.sh/#install>`_, open :file:`Terminal` or
 57 | your favorite OS X terminal emulator and run
 58 | 
 59 | .. code-block:: console
 60 | 
 61 |     $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 62 | 
 63 | The script will explain what changes it will make and prompt you before the
 64 | installation begins.
 65 | Once you've installed Homebrew, insert the Homebrew directory at the top
 66 | of your :envvar:`PATH` environment variable. You can do this by adding the following
 67 | line at the bottom of your :file:`~/.profile` file
 68 | 
 69 | .. code-block:: console
 70 | 
 71 |     export PATH="/usr/local/bin:/usr/local/sbin:$PATH"
 72 | 
 73 | Now, we can install Python 2.7:
 74 | 
 75 | .. code-block:: console
 76 | 
 77 |     $ brew install python@2
 78 | 
 79 | Because ``python@2`` is a "keg", we need to update our ``PATH`` again, to point at our new installation:
 80 | 
 81 | .. code-block:: console
 82 | 
 83 |     export PATH="/usr/local/opt/python@2/libexec/bin:$PATH"
 84 | 
 85 | Homebrew names the executable ``python2`` so that you can still run the system Python via the executable ``python``.
 86 | 
 87 | 
 88 | .. code-block:: console
 89 | 
 90 |     $ python -V   # Homebrew installed Python 3 interpreter (if installed)
 91 |     $ python2 -V  # Homebrew installed Python 2 interpreter
 92 |     $ python3 -V  # Homebrew installed Python 3 interpreter (if installed)
 93 | 
 94 | 
 95 | ****************
 96 | Setuptools & Pip
 97 | ****************
 98 | 
 99 | Homebrew installs Setuptools and ``pip`` for you.
100 | 
101 | Setuptools enables you to download and install any compliant Python
102 | software over a network (usually the Internet) with a single command
103 | (``easy_install``). It also enables you to add this network installation
104 | capability to your own Python software with very little work.
105 | 
106 | ``pip`` is a tool for easily installing and managing Python packages,
107 | that is recommended over ``easy_install``. It is superior to ``easy_install``
108 | in `several ways <https://python-packaging-user-guide.readthedocs.io/pip_easy_install/#pip-vs-easy-install>`_,
109 | and is actively maintained.
110 | 
111 | .. code-block:: console
112 | 
113 |     $ pip2 -V  # pip pointing to the Homebrew installed Python 2 interpreter
114 |     $ pip -V  # pip pointing to the Homebrew installed Python 3 interpreter (if installed)
115 | 
116 | 
117 | ********************
118 | Virtual Environments
119 | ********************
120 | 
121 | A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep the dependencies required by different projects
122 | in separate places, by creating virtual Python environments for them. It solves the
123 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
124 | your global site-packages directory clean and manageable.
125 | 
126 | For example, you can work on a project which requires Django 1.10 while also
127 | maintaining a project which requires Django 1.8.
128 | 
129 | To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
130 | 
131 | --------------------------------
132 | 
133 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
134 | which is available under the same license.
135 | 


--------------------------------------------------------------------------------
/docs/starting/install/win.rst:
--------------------------------------------------------------------------------
 1 | .. _install-windows:
 2 | 
 3 | 
 4 | ##############################
 5 | Installing Python 2 on Windows
 6 | ##############################
 7 | 
 8 | .. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg
 9 | 
10 | .. note::
11 |     Check out our :ref:`guide for installing Python 3 on Windows<install3-windows>`.
12 | 
13 | First, download the `latest version <https://www.python.org/ftp/python/2.7.15/python-2.7.15.msi>`_
14 | of Python 2.7 from the official website. If you want to be sure you are installing a fully
15 | up-to-date version, click the Downloads > Windows link from the home page of the
16 | `Python.org web site <https://python.org>`_ .
17 | 
18 | The Windows version is provided as an MSI package. To install it manually, just
19 | double-click the file. The MSI package format allows Windows administrators to
20 | automate installation with their standard tools.
21 | 
22 | By design, Python installs to a directory with the version number embedded,
23 | e.g. Python version 2.7 will install at :file:`C:\\Python27\\`, so that you can
24 | have multiple versions of Python on the
25 | same system without conflicts. Of course, only one interpreter can be the
26 | default application for Python file types. It also does not automatically
27 | modify the :envvar:`PATH` environment variable, so that you always have control over
28 | which copy of Python is run.
29 | 
30 | Typing the full path name for a Python interpreter each time quickly gets
31 | tedious, so add the directories for your default Python version to the :envvar:`PATH`.
32 | Assuming that your Python installation is in :file:`C:\\Python27\\`, add this to your
33 | :envvar:`PATH`:
34 | 
35 | .. code-block:: doscon
36 | 
37 |     C:\Python27\;C:\Python27\Scripts\
38 | 
39 | You can do this easily by running the following in ``powershell``:
40 | 
41 | .. code-block:: powershell
42 | 
43 |     [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User")
44 | 
45 | This is also an option during the installation process.
46 | 
47 | The second (:file:`Scripts`) directory receives command files when certain
48 | packages are installed, so it is a very useful addition.
49 | You do not need to install or configure anything else to use Python. Having
50 | said that, I would strongly recommend that you install the tools and libraries
51 | described in the next section before you start building Python applications for
52 | real-world use. In particular, you should always install Setuptools, as it
53 | makes it much easier for you to use other third-party Python libraries.
54 | 
55 | 
56 | ****************
57 | Setuptools + Pip
58 | ****************
59 | 
60 | The two most crucial third-party Python packages are `setuptools <https://pypi.org/project/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
61 | 
62 | Once installed, you can download, install and uninstall any compliant Python software
63 | product with a single command. It also enables you to add this network installation
64 | capability to your own Python software with very little work.
65 | 
66 | Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
67 | pip by default.
68 | 
69 | To see if pip is installed, open a command prompt and run
70 | 
71 | .. code-block:: doscon
72 | 
73 |     command -v pip
74 | 
75 | To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
76 | 
77 | 
78 | ********************
79 | Virtual Environments
80 | ********************
81 | 
82 | A Virtual Environment is a tool to keep the dependencies required by different projects
83 | in separate places, by creating virtual Python environments for them. It solves the
84 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
85 | your global site-packages directory clean and manageable.
86 | 
87 | For example, you can work on a project which requires Django 1.10 while also
88 | maintaining a project which requires Django 1.8.
89 | 
90 | To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
91 | 
92 | 
93 | --------------------------------
94 | 
95 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
96 | which is available under the same license.
97 | 


--------------------------------------------------------------------------------
/docs/starting/install3/linux.rst:
--------------------------------------------------------------------------------
  1 | .. _install3-linux:
  2 | 
  3 | 
  4 | ############################
  5 | Installing Python 3 on Linux
  6 | ############################
  7 | 
  8 | .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg
  9 | 
 10 | This document describes how to install Python 3.6 or 3.8 on Ubuntu Linux machines.
 11 | 
 12 | To see which version of Python 3 you have installed, open a command prompt and run
 13 | 
 14 | .. code-block:: console
 15 | 
 16 |     $ python3 --version
 17 | 
 18 | If you are using Ubuntu 16.10 or newer, then you can easily install Python 3.6 with the following commands::
 19 | 
 20 |     $ sudo apt-get update
 21 |     $ sudo apt-get install python3.6
 22 | 
 23 | 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 <https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa>`_ to install Python 3.8::
 24 | 
 25 |     $ sudo apt-get install software-properties-common
 26 |     $ sudo add-apt-repository ppa:deadsnakes/ppa
 27 |     $ sudo apt-get update
 28 |     $ sudo apt-get install python3.8
 29 | 
 30 | If you are using other Linux distribution, chances are you already have Python 3
 31 | pre-installed as well. If not, use your distribution's package manager.
 32 | For example on Fedora, you would use `dnf`:
 33 | 
 34 | .. code-block:: console
 35 | 
 36 |     $ sudo dnf install python3
 37 | 
 38 | Note that if the version of the ``python3`` package is not recent enough
 39 | for you, there may be ways of installing more recent versions as well,
 40 | depending on you distribution. For example installing the ``python3.9`` package
 41 | on Fedora 32 to get Python 3.9. If you are a Fedora user, you might want
 42 | to read about `multiple Python versions available in Fedora`_.
 43 | 
 44 | .. _multiple Python versions available in Fedora: https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html
 45 | 
 46 | 
 47 | *********************
 48 | Working with Python 3
 49 | *********************
 50 | 
 51 | At this point, you may have system Python 2.7 available as well.
 52 | 
 53 | .. code-block:: console
 54 | 
 55 |     $ python
 56 | 
 57 | This might launch the Python 2 interpreter.
 58 | 
 59 | .. code-block:: console
 60 | 
 61 |     $ python3
 62 | 
 63 | This will always launch the Python 3 interpreter.
 64 | 
 65 | 
 66 | ****************
 67 | Setuptools & Pip
 68 | ****************
 69 | 
 70 | The two most crucial third-party Python packages are `setuptools <https://pypi.org/project/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
 71 | 
 72 | Once installed, you can download, install and uninstall any compliant Python software
 73 | product with a single command. It also enables you to add this network installation
 74 | capability to your own Python software with very little work.
 75 | 
 76 | Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
 77 | pip by default.
 78 | 
 79 | To see if pip is installed, open a command prompt and run
 80 | 
 81 | .. code-block:: console
 82 | 
 83 |     $ command -v pip
 84 | 
 85 | To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
 86 | 
 87 | Note that on some Linux distributions including Ubuntu and Fedora the ``pip``
 88 | command is meant for Python 2, while the ``pip3`` command is meant for Python 3.
 89 | 
 90 | .. code-block:: console
 91 | 
 92 |     $ command -v pip3
 93 | 
 94 | However, when using virtual environments (described below), you don't need to
 95 | care about that.
 96 | 
 97 | 
 98 | *****************************
 99 | Pipenv & Virtual Environments
100 | *****************************
101 | 
102 | The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
103 | 
104 | A Virtual Environment is a tool to keep the dependencies required by different projects
105 | in separate places, by creating virtual Python environments for them. It solves the
106 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
107 | your global site-packages directory clean and manageable.
108 | 
109 | For example, you can work on a project which requires Django 1.10 while also
110 | maintaining a project which requires Django 1.8.
111 | 
112 | So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
113 | 
114 | --------------------------------
115 | 
116 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
117 | which is available under the same license.
118 | 


--------------------------------------------------------------------------------
/docs/starting/install3/osx.rst:
--------------------------------------------------------------------------------
  1 | :orphan: This article should not be added to a toctree for now
  2 | 
  3 | .. _install3-osx:
  4 | 
  5 | 
  6 | ###############################
  7 | Installing Python 3 on Mac OS X
  8 | ###############################
  9 | 
 10 | .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg
 11 | 
 12 | **Mac OS X comes with Python 2.7 out of the box between versions 10.8 and 12.3.**
 13 | 
 14 | If your Mac OS X version is between the above versions,
 15 | you do not need to install or configure anything else to use Python 2. These
 16 | instructions document the installation of Python 3.
 17 | 
 18 | The version of Python that ships with OS X is great for learning, but it's not
 19 | good for development. The version shipped with OS X may be out of date from the
 20 | `official current Python release <https://www.python.org/downloads/mac-osx/>`_,
 21 | which is considered the stable production version.
 22 | 
 23 | 
 24 | **************
 25 | Doing it Right
 26 | **************
 27 | 
 28 | Let's install a real version of Python.
 29 | 
 30 | Before installing Python, you'll need to install GCC. GCC can be obtained
 31 | by downloading `Xcode <https://developer.apple.com/xcode/>`_, the smaller
 32 | `Command Line Tools <https://developer.apple.com/downloads/>`_ (must have an
 33 | Apple account) or the even smaller `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
 34 | package.
 35 | 
 36 | .. note::
 37 |     If you already have Xcode installed, do not install OSX-GCC-Installer.
 38 |     In combination, the software can cause issues that are difficult to
 39 |     diagnose.
 40 | 
 41 | .. note::
 42 |     If you perform a fresh install of Xcode, you will also need to add the
 43 |     commandline tools by running ``xcode-select --install`` on the terminal.
 44 | 
 45 | While OS X comes with a large number of Unix utilities, those familiar with
 46 | Linux systems will notice one key component missing: a package manager.
 47 | `Homebrew <https://brew.sh>`_ fills this void.
 48 | 
 49 | To `install Homebrew <https://brew.sh/#install>`_, open :file:`Terminal` or
 50 | your favorite OS X terminal emulator and run
 51 | 
 52 | .. code-block:: console
 53 | 
 54 |     $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 55 | 
 56 | The script will explain what changes it will make and prompt you before the
 57 | installation begins.
 58 | Once you've installed Homebrew, insert the Homebrew directory at the top
 59 | of your :envvar:`PATH` environment variable. You can do this by adding the following
 60 | line at the bottom of your :file:`~/.profile` file
 61 | 
 62 | .. code-block:: console
 63 | 
 64 |     export PATH="/usr/local/opt/python/libexec/bin:$PATH"
 65 | 
 66 | If you have OS X 10.12 (Sierra) or older use this line instead
 67 | 
 68 | .. code-block:: console
 69 | 
 70 |     export PATH=/usr/local/bin:/usr/local/sbin:$PATH
 71 | 
 72 | Now, we can install Python 3:
 73 | 
 74 | .. code-block:: console
 75 | 
 76 |     $ brew install python
 77 | 
 78 | This will take a minute or two.
 79 | 
 80 | ***
 81 | Pip
 82 | ***
 83 | 
 84 | Homebrew installs ``pip`` pointing to the Homebrew'd Python 3 for you.
 85 | 
 86 | 
 87 | *********************
 88 | Working with Python 3
 89 | *********************
 90 | 
 91 | At this point, you have the system Python 2.7 available, potentially the
 92 | :ref:`Homebrew version of Python 2 <install-osx>` installed, and the Homebrew
 93 | version of Python 3 as well.
 94 | 
 95 | .. code-block:: console
 96 | 
 97 |     $ python
 98 | 
 99 | will launch the Homebrew-installed Python 3 interpreter.
100 | 
101 | .. code-block:: console
102 | 
103 |     $ python2
104 | 
105 | will launch the Homebrew-installed Python 2 interpreter (if any).
106 | 
107 | .. code-block:: console
108 | 
109 |     $ python3
110 | 
111 | will launch the Homebrew-installed Python 3 interpreter.
112 | 
113 | If the Homebrew version of Python 2 is installed then ``pip2`` will point to Python 2.
114 | If the Homebrew version of Python 3 is installed then ``pip`` will point to Python 3.
115 | 
116 | The rest of the guide will assume that ``python`` references Python 3.
117 | 
118 | .. code-block:: console
119 | 
120 |     # Do I have a Python 3 installed?
121 |     $ python --version
122 |     Python 3.7.1 # Success!
123 | 
124 | 
125 | *****************************
126 | Pipenv & Virtual Environments
127 | *****************************
128 | 
129 | The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
130 | 
131 | A Virtual Environment is a tool to keep the dependencies required by different projects
132 | in separate places, by creating virtual Python environments for them. It solves the
133 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
134 | your global site-packages directory clean and manageable.
135 | 
136 | For example, you can work on a project which requires Django 1.10 while also
137 | maintaining a project which requires Django 1.8.
138 | 
139 | So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
140 | 
141 | --------------------------------
142 | 
143 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
144 | which is available under the same license.
145 | 


--------------------------------------------------------------------------------
/docs/starting/install3/win.rst:
--------------------------------------------------------------------------------
 1 | .. _install3-windows:
 2 | 
 3 | 
 4 | ##############################
 5 | Installing Python 3 on Windows
 6 | ##############################
 7 | 
 8 | .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg
 9 | 
10 | First, follow the installation instructions for `Chocolatey <https://chocolatey.org/install>`_.
11 | It's a community system packager manager for Windows 7+. (It's very much like Homebrew on OS X.)
12 | 
13 | Once done, installing Python 3 is very simple, because Chocolatey pushes Python 3 as the default.
14 | 
15 | .. code-block:: doscon
16 | 
17 |     choco install python
18 | 
19 | Once you've run this command, you should be able to launch Python directly from to the console.
20 | (Chocolatey is fantastic and automatically adds Python to your path.)
21 | 
22 | 
23 | ****************
24 | Setuptools + Pip
25 | ****************
26 | 
27 | The two most crucial third-party Python packages are `setuptools <https://pypi.org/project/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_,
28 | which let you download, install and uninstall any compliant Python software
29 | product with a single command. It also enables you to add this network installation
30 | capability to your own Python software with very little work.
31 | 
32 | All supported versions of Python 3 include pip, so just make sure it's up to date:
33 | 
34 | .. code-block:: doscon
35 | 
36 |     python -m pip install -U pip
37 | 
38 | 
39 | *****************************
40 | Pipenv & Virtual Environments
41 | *****************************
42 | 
43 | The next step is to install Pipenv, so you can install dependencies and manage virtual environments.
44 | 
45 | A Virtual Environment is a tool to keep the dependencies required by different projects
46 | in separate places, by creating virtual Python environments for them. It solves the
47 | "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
48 | your global site-packages directory clean and manageable.
49 | 
50 | For example, you can work on a project which requires Django 2.0 while also
51 | maintaining a project which requires Django 1.8.
52 | 
53 | So, onward! To the :ref:`Pipenv & Virtual Environments <virtualenvironments-ref>` docs!
54 | 
55 | --------------------------------
56 | 
57 | This page is a remixed version of `another guide <https://www.stuartellis.name/articles/python-development-windows/>`_,
58 | which is available under the same license.
59 | 


--------------------------------------------------------------------------------
/docs/starting/installation.rst:
--------------------------------------------------------------------------------
 1 | .. _installation:
 2 | 
 3 | 
 4 | ##########################
 5 | Properly Installing Python
 6 | ##########################
 7 | 
 8 | .. image:: /_static/photos/36137232412_fdcb0f84eb_k_d.jpg
 9 | 
10 | There's a good chance that you already have Python on your operating system.
11 | 
12 | If so, you do not need to install or configure anything else to use Python.
13 | Having said that, I would strongly recommend that you install the tools and
14 | libraries described in the guides below before you start building Python
15 | applications for real-world use. In particular, you should always install
16 | Setuptools, Pip, and Virtualenv — they make it much easier for you to use
17 | other third-party Python libraries.
18 | 
19 | .. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
20 |   —*Kenneth Reitz*
21 | 
22 | *******************
23 | Installation Guides
24 | *******************
25 | 
26 | These guides go over the proper installation of :ref:`Python <which-python>`
27 | for development purposes, as well as setuptools, pip and virtualenv.
28 | 
29 | Python 3 Installation Guides
30 | ////////////////////////////
31 | 
32 | - :ref:`Python 3 on MacOS <install3-osx>`.
33 | - :ref:`Python 3 on Windows <install3-windows>`.
34 | - :ref:`Python 3 on Linux <install3-linux>`.
35 | 
36 | Legacy Python 2 Installation Guides
37 | ///////////////////////////////////
38 | 
39 | - :ref:`Python 2 on MacOS <install-osx>`.
40 | - :ref:`Python 2 on Microsoft Windows <install-windows>`.
41 | - :ref:`Python 2 on Linux <install-linux>`.
42 | 


--------------------------------------------------------------------------------
/docs/starting/which-python.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | #####################################
  4 | Picking a Python Interpreter (3 vs 2)
  5 | #####################################
  6 | 
  7 | .. image:: /_static/photos/34484834733_5b80f65ab1_k_d.jpg
  8 | 
  9 | .. _which-python:
 10 | 
 11 | 
 12 | ***************************
 13 | The State of Python (3 & 2)
 14 | ***************************
 15 | 
 16 | When choosing a Python interpreter, one looming question is always present:
 17 | "Should I choose Python 2 or Python 3"? The answer is a bit more subtle than
 18 | one might think.
 19 | 
 20 | 
 21 | The basic gist of the state of things is as follows:
 22 | 
 23 | 1. Most production applications today use Python 3.
 24 | 2. Python 3 is ready for the production deployment of applications today.
 25 | 3. Python 2 reached the end of its life on January 1, 2020 [#pep373_eol]_.
 26 | 4. The brand name "Python" encapsulates both Python 3 and Python 2.
 27 | 
 28 | 
 29 | ***************
 30 | Recommendations
 31 | ***************
 32 | 
 33 | 
 34 | .. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
 35 |   —*Kenneth Reitz*
 36 | 
 37 | I'll be blunt:
 38 | 
 39 | - Use Python 3 for new Python applications.
 40 | - If you're learning Python for the first time, familiarizing yourself with Python 2.7 will be very
 41 |   useful, but not more useful than learning Python 3.
 42 | - Learn both. They are both "Python".
 43 | 
 44 | 
 45 | *********
 46 | So.... 3?
 47 | *********
 48 | 
 49 | If you're choosing a Python interpreter to use, I
 50 | recommend you use the newest Python 3.x, since every version brings new and
 51 | improved standard library modules, security and bug fixes.
 52 | 
 53 | Given such, only use Python 2 if you have a strong reason to, such as a
 54 | pre-existing code-base, a Python 2 exclusive library, simplicity/familiarity,
 55 | or, of course, you absolutely love and are inspired by Python 2. No harm in that.
 56 | 
 57 | 
 58 | `Further Reading <http://wiki.python.org/moin/Python2orPython3>`_
 59 | 
 60 | It is possible to `write code that works on Python 2.6, 2.7, and Python 3
 61 | <https://docs.python.org/3/howto/pyporting.html>`_. This
 62 | ranges from trivial to hard depending upon the kind of software
 63 | you are writing; if you're a beginner there are far more important things to
 64 | worry about.
 65 | 
 66 | 
 67 | ***************
 68 | Implementations
 69 | ***************
 70 | 
 71 | When people speak of *Python* they often mean not just the language but also
 72 | the CPython implementation. *Python* is actually a specification for a language
 73 | that can be implemented in many different ways.
 74 | 
 75 | CPython
 76 | -------
 77 | 
 78 | `CPython <http://www.python.org>`_ is the reference implementation of Python,
 79 | written in C. It compiles Python code to intermediate bytecode which is then
 80 | interpreted by a virtual machine. CPython provides the highest
 81 | level of compatibility with Python packages and C extension modules.
 82 | 
 83 | If you are writing open source Python code and want to reach the widest possible
 84 | audience, targeting CPython is best. To use packages which rely on C extensions
 85 | to function, CPython is your only implementation option.
 86 | 
 87 | All versions of the Python language are implemented in C because CPython is the
 88 | reference implementation.
 89 | 
 90 | PyPy
 91 | ----
 92 | 
 93 | `PyPy <http://pypy.org/>`_ is a Python interpreter implemented in a restricted
 94 | statically-typed subset of the Python language called RPython. The interpreter
 95 | features a just-in-time compiler and supports multiple back-ends (C, CLI, JVM).
 96 | 
 97 | PyPy aims for maximum compatibility with the reference CPython implementation
 98 | while improving performance.
 99 | 
100 | If you are looking to increase performance of your Python code, it's
101 | worth giving PyPy a try. On a suite of benchmarks, it's currently `over 5 times
102 | faster than CPython <http://speed.pypy.org/>`_.
103 | 
104 | PyPy supports Python 2.7. PyPy3 [#pypy_ver]_, released in beta, targets Python 3.
105 | 
106 | Jython
107 | ------
108 | 
109 | `Jython <http://www.jython.org/>`_ is a Python implementation that compiles
110 | Python code to Java bytecode which is then executed by the JVM (Java Virtual Machine).
111 | Additionally, it is able to import and use any Java class like a Python
112 | module.
113 | 
114 | If you need to interface with an existing Java codebase or have other reasons to
115 | need to write Python code for the JVM, Jython is the best choice.
116 | 
117 | Jython currently supports up to Python 2.7. [#jython_ver]_
118 | 
119 | IronPython
120 | ----------
121 | 
122 | `IronPython <http://ironpython.net/>`_  is an implementation of Python for the .NET
123 | framework. It can use both Python and .NET framework libraries, and can also
124 | expose Python code to other languages in the .NET framework.
125 | 
126 | `Python Tools for Visual Studio <http://ironpython.net/tools/>`_ integrates
127 | IronPython directly into the Visual Studio development environment, making it
128 | an ideal choice for Windows developers.
129 | 
130 | IronPython supports Python 2.7. [#iron_ver]_ IronPython 3 [#iron_ver3]_
131 | is being developed, but is not ready for use as of September 2020.
132 | 
133 | PythonNet
134 | ---------
135 | 
136 | `Python for .NET <http://pythonnet.github.io/>`_ is a package which
137 | provides near seamless integration of a natively installed Python
138 | installation with the .NET Common Language Runtime (CLR).  This is the
139 | inverse approach to that taken by IronPython (see above), to which it
140 | is more complementary than competing with.
141 | 
142 | In conjunction with Mono, pythonnet enables native Python
143 | installations on non-Windows operating systems, such as OS X and
144 | Linux, to operate within the .NET framework.  It can be run in
145 | addition to IronPython without conflict.
146 | 
147 | Pythonnet is compatible with Python 2.7 and 3.5-3.8. [#pythonnet_ver1]_
148 | 
149 | .. [#pypy_ver] https://pypy.org/compat.html
150 | 
151 | .. [#jython_ver] https://hg.python.org/jython/file/412a8f9445f7/NEWS
152 | 
153 | .. [#iron_ver] https://ironpython.net/download/
154 | 
155 | .. [#iron_ver3] https://github.com/IronLanguages/ironpython3
156 | 
157 | .. [#pythonnet_ver1] https://pythonnet.github.io/
158 | 
159 | .. [#pep373_eol] https://www.python.org/dev/peps/pep-0373/#id2
160 | 


--------------------------------------------------------------------------------
/docs/writing/gotchas.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | ##############
  4 | Common Gotchas
  5 | ##############
  6 | 
  7 | .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg
  8 | 
  9 | For the most part, Python aims to be a clean and consistent language that
 10 | avoids surprises. However, there are a few cases that can be confusing for
 11 | newcomers.
 12 | 
 13 | Some of these cases are intentional but can be potentially surprising. Some
 14 | could arguably be considered language warts. In general, what follows
 15 | is a collection of potentially tricky behavior that might seem strange at first
 16 | glance, but are generally sensible, once you're aware of the underlying cause for
 17 | the surprise.
 18 | 
 19 | 
 20 | .. _default_args:
 21 | 
 22 | 
 23 | *************************
 24 | Mutable Default Arguments
 25 | *************************
 26 | 
 27 | Seemingly the *most* common surprise new Python programmers encounter is
 28 | Python's treatment of mutable default arguments in function definitions.
 29 | 
 30 | What You Wrote
 31 | ~~~~~~~~~~~~~~
 32 | 
 33 | .. code-block:: python
 34 | 
 35 |     def append_to(element, to=[]):
 36 |         to.append(element)
 37 |         return to
 38 | 
 39 | What You Might Have Expected to Happen
 40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 41 | 
 42 | .. code-block:: python
 43 | 
 44 |     my_list = append_to(12)
 45 |     print(my_list)
 46 | 
 47 |     my_other_list = append_to(42)
 48 |     print(my_other_list)
 49 | 
 50 | A new list is created each time the function is called if a second argument
 51 | isn't provided, so that the output is::
 52 | 
 53 |     [12]
 54 |     [42]
 55 | 
 56 | What Actually Happens
 57 | ~~~~~~~~~~~~~~~~~~~~~
 58 | 
 59 | .. testoutput::
 60 | 
 61 |     [12]
 62 |     [12, 42]
 63 | 
 64 | A new list is created *once* when the function is defined, and the same list is
 65 | used in each successive call.
 66 | 
 67 | Python's default arguments are evaluated *once* when the function is defined,
 68 | not each time the function is called (like it is in say, Ruby). This means that
 69 | if you use a mutable default argument and mutate it, you *will* and have
 70 | mutated that object for all future calls to the function as well.
 71 | 
 72 | What You Should Do Instead
 73 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
 74 | 
 75 | Create a new object each time the function is called, by using a default arg to
 76 | signal that no argument was provided (:py:data:`None` is often a good choice).
 77 | 
 78 | .. code-block:: python
 79 | 
 80 |     def append_to(element, to=None):
 81 |         if to is None:
 82 |             to = []
 83 |         to.append(element)
 84 |         return to
 85 | 
 86 | Do not forget, you are passing a *list* object as the second argument.
 87 | 
 88 | When the Gotcha Isn't a Gotcha
 89 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 90 | 
 91 | Sometimes you can specifically "exploit" (read: use as intended) this behavior
 92 | to maintain state between calls of a function. This is often done when writing
 93 | a caching function.
 94 | 
 95 | 
 96 | ****************************
 97 | Late Binding Closures
 98 | ****************************
 99 | 
100 | Another common source of confusion is the way Python binds its variables in
101 | closures (or in the surrounding global scope).
102 | 
103 | 
104 | What You Wrote
105 | ~~~~~~~~~~~~~~
106 | 
107 | .. testcode::
108 | 
109 |     def create_multipliers():
110 |         return [lambda x : i * x for i in range(5)]
111 | 
112 | What You Might Have Expected to Happen
113 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114 | 
115 | .. testcode::
116 | 
117 |     for multiplier in create_multipliers():
118 |         print(multiplier(2))
119 | 
120 | A list containing five functions that each have their own closed-over ``i``
121 | variable that multiplies their argument, producing::
122 | 
123 |     0
124 |     2
125 |     4
126 |     6
127 |     8
128 | 
129 | What Actually Happens
130 | ~~~~~~~~~~~~~~~~~~~~~
131 | 
132 | .. testoutput::
133 | 
134 |     8
135 |     8
136 |     8
137 |     8
138 |     8
139 | 
140 | Five functions are created; instead all of them just multiply ``x`` by 4.
141 | 
142 | Python's closures are *late binding*.
143 | This means that the values of variables used in closures are looked
144 | up at the time the inner function is called.
145 | 
146 | Here, whenever *any* of the returned functions are called, the value of ``i``
147 | is looked up in the surrounding scope at call time. By then, the loop has
148 | completed and ``i`` is left with its final value of 4.
149 | 
150 | What's particularly nasty about this gotcha is the seemingly prevalent
151 | misinformation that this has something to do with :ref:`lambdas <python:lambda>`
152 | in Python. Functions created with a ``lambda`` expression are in no way special,
153 | and in fact the same exact behavior is exhibited by just using an ordinary
154 | ``def``:
155 | 
156 | .. code-block:: python
157 | 
158 |     def create_multipliers():
159 |         multipliers = []
160 | 
161 |         for i in range(5):
162 |             def multiplier(x):
163 |                 return i * x
164 |             multipliers.append(multiplier)
165 | 
166 |         return multipliers
167 | 
168 | What You Should Do Instead
169 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
170 | 
171 | The most general solution is arguably a bit of a hack. Due to Python's
172 | aforementioned behavior concerning evaluating default arguments to functions
173 | (see :ref:`default_args`), you can create a closure that binds immediately to
174 | its arguments by using a default arg like so:
175 | 
176 | .. code-block:: python
177 | 
178 |     def create_multipliers():
179 |         return [lambda x, i=i : i * x for i in range(5)]
180 | 
181 | Alternatively, you can use the functools.partial function:
182 | 
183 | .. code-block:: python
184 | 
185 |     from functools import partial
186 |     from operator import mul
187 | 
188 |     def create_multipliers():
189 |         return [partial(mul, i) for i in range(5)]
190 | 
191 | When the Gotcha Isn't a Gotcha
192 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193 | 
194 | Sometimes you want your closures to behave this way. Late binding is good in
195 | lots of situations. Looping to create unique functions is unfortunately a case
196 | where they can cause hiccups.
197 | 
198 | 
199 | *********************************
200 | Bytecode (.pyc) Files Everywhere!
201 | *********************************
202 | 
203 | By default, when executing Python code from files, the Python interpreter
204 | will automatically write a bytecode version of that file to disk, e.g.
205 | ``module.pyc``.
206 | 
207 | These ``.pyc`` files should not be checked into your source code repositories.
208 | 
209 | Theoretically, this behavior is on by default for performance reasons.
210 | Without these bytecode files, Python would re-generate the bytecode
211 | every time the file is loaded.
212 | 
213 | 
214 | Disabling Bytecode (.pyc) Files
215 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
216 | 
217 | Luckily, the process of generating the bytecode is extremely fast, and isn't
218 | something you need to worry about while developing your code.
219 | 
220 | Those files are annoying, so let's get rid of them!
221 | 
222 | ::
223 | 
224 |     $ export PYTHONDONTWRITEBYTECODE=1
225 | 
226 | With the ``$PYTHONDONTWRITEBYTECODE`` environment variable set, Python will
227 | no longer write these files to disk, and your development environment will
228 | remain nice and clean.
229 | 
230 | I recommend setting this environment variable in your ``~/.profile``.
231 | 
232 | Removing Bytecode (.pyc) Files
233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234 | 
235 | Here's nice trick for removing all of these files, if they already exist::
236 | 
237 |     $ find . -type f -name "*.py[co]" -delete -or -type d -name "__pycache__" -delete
238 | 
239 | Run that from the root directory of your project, and all ``.pyc`` files
240 | will suddenly vanish. Much better.
241 | 
242 | .. _version_control_ignores:
243 | 
244 | Version Control Ignores
245 | ~~~~~~~~~~~~~~~~~~~~~~~
246 | 
247 | If you still need the ``.pyc`` files for performance reasons, you can always add them
248 | to the ignore files of your version control repositories. Popular version control
249 | systems have the ability to use wildcards defined in a file to apply special
250 | rules.
251 | 
252 | An ignore file will make sure the matching files don't get checked into the repository.
253 | Git_ uses ``.gitignore`` while Mercurial_ uses ``.hgignore``.
254 | 
255 | .. _Git: https://git-scm.com/
256 | .. _Mercurial: https://www.mercurial-scm.org/
257 | 
258 | At the minimum your ignore files should look like this.
259 | 
260 | ::
261 | 
262 |     syntax:glob   # This line is not needed for .gitignore files.
263 |     *.py[cod]     # Will match .pyc, .pyo and .pyd files.
264 |     __pycache__/  # Exclude the whole folder
265 | 
266 | You may wish to include more files and directories depending on your needs.
267 | The next time you commit to the repository, these files will not be included.
268 | 


--------------------------------------------------------------------------------
/docs/writing/license.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | ##################
 4 | Choosing a License
 5 | ##################
 6 | 
 7 | .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg
 8 | 
 9 | Your source publication *needs* a license. In the US, unless a license is
10 | specified, users have no legal right to download, modify, or distribute the product.
11 | Furthermore, people can't contribute to your code unless you tell them what
12 | rules to play by. Choosing a license is complicated, so here are some pointers:
13 | 
14 | Open source. There are plenty of `open source licenses
15 | <http://opensource.org/licenses/alphabetical>`_ available to choose
16 | from.
17 | 
18 | In general, these licenses tend to fall into one of two categories:
19 | 
20 | 1. licenses that focus more on the user's freedom to do with the
21 |    software as they please (these are the more permissive open
22 |    source licenses such as the MIT, BSD, and Apache)
23 | 
24 | 2. licenses that focus more on making sure that the code itself —
25 |    including any changes made to it and distributed along with it —
26 |    always remains free (these are the less permissive free software
27 |    licenses such as the GPL and LGPL)
28 | 
29 | The latter are less permissive in the sense that they don't permit
30 | someone to add code to the software and distribute it without also
31 | including the source code for their changes.
32 | 
33 | To help you choose one for your project, there's a `license chooser <http://choosealicense.com/>`_;
34 | **use it**.
35 | 
36 | **More Permissive**
37 | 
38 | - PSFL (Python Software Foundation License) -- for contributing to Python itself
39 | - MIT / BSD / ISC
40 | 
41 |   + MIT (X11)
42 |   + New BSD
43 |   + ISC
44 | 
45 | - Apache
46 | 
47 | **Less Permissive:**
48 | 
49 | - LGPL
50 | - GPL
51 | 
52 |   + GPLv2
53 |   + GPLv3
54 | 
55 | A good overview of licenses with explanations of what one can, cannot,
56 | and must do using a particular software can be found at
57 | `tl;drLegal <https://tldrlegal.com/>`_.
58 | 


--------------------------------------------------------------------------------
/docs/writing/logging.rst:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 | #######
  4 | Logging
  5 | #######
  6 | 
  7 | .. image:: /_static/photos/35254379756_c9fe23f843_k_d.jpg
  8 | 
  9 | The :mod:`logging` module has been a part of Python's Standard Library since
 10 | version 2.3.  It is succinctly described in :pep:`282`.  The documentation
 11 | is notoriously hard to read, except for the `basic logging tutorial`_.
 12 | 
 13 | As an alternative, `loguru <https://github.com/Delgan/loguru>`_ provides an approach for logging, nearly as simple as using a simple ``print`` statement.
 14 | 
 15 | Logging serves two purposes:
 16 | 
 17 | - **Diagnostic logging** records events related to the application's
 18 |   operation. If a user calls in to report an error, for example, the logs
 19 |   can be searched for context.
 20 | - **Audit logging** records events for business analysis. A user's
 21 |   transactions can be extracted and combined with other user details for
 22 |   reports or to optimize a business goal.
 23 | 
 24 | 
 25 | *************
 26 | ... or Print?
 27 | *************
 28 | 
 29 | The only time that ``print`` is a better option than logging is when
 30 | the goal is to display a help statement for a command line application.
 31 | Other reasons why logging is better than ``print``:
 32 | 
 33 | - The `log record`_, which is created with every logging event, contains
 34 |   readily available diagnostic information such as the file name, full path,
 35 |   function, and line number of the logging event.
 36 | - Events logged in included modules are automatically accessible via the root
 37 |   logger to your application's logging stream, unless you filter them out.
 38 | - Logging can be selectively silenced by using the method
 39 |   :meth:`logging.Logger.setLevel` or disabled by setting the attribute
 40 |   :attr:`logging.Logger.disabled` to ``True``.
 41 | 
 42 | 
 43 | ********************
 44 | Logging in a Library
 45 | ********************
 46 | 
 47 | Notes for `configuring logging for a library`_ are in the
 48 | `logging tutorial`_.  Because the *user*, not the library, should
 49 | dictate what happens when a logging event occurs, one admonition bears
 50 | repeating:
 51 | 
 52 | .. note::
 53 |     It is strongly advised that you do not add any handlers other than
 54 |     NullHandler to your library’s loggers.
 55 | 
 56 | 
 57 | Best practice when instantiating loggers in a library is to only create them
 58 | using the ``__name__`` global variable: the :mod:`logging` module creates a
 59 | hierarchy of loggers using dot notation, so using ``__name__`` ensures
 60 | no name collisions.
 61 | 
 62 | Here is an example of the best practice from the `requests source`_ -- place
 63 | this in your ``__init__.py``:
 64 | 
 65 | .. code-block:: python
 66 | 
 67 |     import logging
 68 |     logging.getLogger(__name__).addHandler(logging.NullHandler())
 69 | 
 70 | 
 71 | *************************
 72 | Logging in an Application
 73 | *************************
 74 | 
 75 | The `twelve factor app <https://12factor.net>`_, an authoritative reference
 76 | for good practice in application development, contains a section on
 77 | `logging best practice <https://12factor.net/logs>`_. It emphatically
 78 | advocates for treating log events as an event stream, and for
 79 | sending that event stream to standard output to be handled by the
 80 | application environment.
 81 | 
 82 | 
 83 | There are at least three ways to configure a logger:
 84 | 
 85 | - Using an INI-formatted file:
 86 |     - **Pro**: possible to update configuration while running, using the
 87 |       function :func:`logging.config.listen` to listen on a socket.
 88 |     - **Con**: less control (e.g. custom subclassed filters or loggers)
 89 |       than possible when configuring a logger in code.
 90 | - Using a dictionary or a JSON-formatted file:
 91 |     - **Pro**: in addition to updating while running, it is possible to load
 92 |       from a file using the :mod:`json` module, in the standard library since
 93 |       Python 2.6.
 94 |     - **Con**: less control than when configuring a logger in code.
 95 | - Using code:
 96 |     - **Pro**: complete control over the configuration.
 97 |     - **Con**: modifications require a change to the source code.
 98 | 
 99 | 
100 | Example Configuration via an INI File
101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 | 
103 | Let us say that the file is named ``logging_config.ini``.
104 | More details for the file format are in the `logging configuration`_
105 | section of the `logging tutorial`_.
106 | 
107 | .. code-block:: ini
108 | 
109 |     [loggers]
110 |     keys=root
111 | 
112 |     [handlers]
113 |     keys=stream_handler
114 | 
115 |     [formatters]
116 |     keys=formatter
117 | 
118 |     [logger_root]
119 |     level=DEBUG
120 |     handlers=stream_handler
121 | 
122 |     [handler_stream_handler]
123 |     class=StreamHandler
124 |     level=DEBUG
125 |     formatter=formatter
126 |     args=(sys.stderr,)
127 | 
128 |     [formatter_formatter]
129 |     format=%(asctime)s %(name)-12s %(levelname)-8s %(message)s
130 | 
131 | 
132 | Then use :meth:`logging.config.fileConfig` in the code:
133 | 
134 | .. code-block:: python
135 | 
136 |     import logging
137 |     from logging.config import fileConfig
138 | 
139 |     fileConfig('logging_config.ini')
140 |     logger = logging.getLogger()
141 |     logger.debug('often makes a very good meal of %s', 'visiting tourists')
142 | 
143 | 
144 | Example Configuration via a Dictionary
145 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146 | 
147 | As of Python 2.7, you can use a dictionary with configuration details.
148 | :pep:`391` contains a list of the mandatory and optional elements in
149 | the configuration dictionary.
150 | 
151 | .. code-block:: python
152 | 
153 |     import logging
154 |     from logging.config import dictConfig
155 | 
156 |     logging_config = dict(
157 |         version = 1,
158 |         formatters = {
159 |             'f': {'format':
160 |                   '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
161 |             },
162 |         handlers = {
163 |             'h': {'class': 'logging.StreamHandler',
164 |                   'formatter': 'f',
165 |                   'level': logging.DEBUG}
166 |             },
167 |         root = {
168 |             'handlers': ['h'],
169 |             'level': logging.DEBUG,
170 |             },
171 |     )
172 | 
173 |     dictConfig(logging_config)
174 | 
175 |     logger = logging.getLogger()
176 |     logger.debug('often makes a very good meal of %s', 'visiting tourists')
177 | 
178 | 
179 | Example Configuration Directly in Code
180 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
181 | 
182 | .. code-block:: python
183 | 
184 |     import logging
185 | 
186 |     logger = logging.getLogger()
187 |     handler = logging.StreamHandler()
188 |     formatter = logging.Formatter(
189 |             '%(asctime)s %(name)-12s %(levelname)-8s %(message)s')
190 |     handler.setFormatter(formatter)
191 |     logger.addHandler(handler)
192 |     logger.setLevel(logging.DEBUG)
193 | 
194 |     logger.debug('often makes a very good meal of %s', 'visiting tourists')
195 | 
196 | 
197 | .. _basic logging tutorial: http://docs.python.org/3/howto/logging.html#logging-basic-tutorial
198 | .. _logging configuration: https://docs.python.org/3/howto/logging.html#configuring-logging
199 | .. _logging tutorial: http://docs.python.org/3/howto/logging.html
200 | .. _configuring logging for a library: https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library
201 | .. _log record: https://docs.python.org/3/library/logging.html#logrecord-attributes
202 | .. _requests source: https://github.com/kennethreitz/requests
203 | 


--------------------------------------------------------------------------------
/docs/writing/reading.rst:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | ##################
 4 | Reading Great Code
 5 | ##################
 6 | 
 7 | .. image:: /_static/photos/34689452831_93d7fd0571_k_d.jpg
 8 | 
 9 | One of the secrets of becoming a great Python programmer is to read,
10 | understand, and comprehend excellent code.
11 | 
12 | Excellent code typically follows the guidelines outlined in
13 | :ref:`code_style`, and does its best to express a clear and concise
14 | intent to the reader.
15 | 
16 | Included below is a list of recommended Python projects for
17 | reading. Each one of these projects is a paragon of Python coding.
18 | 
19 | - `Howdoi <https://github.com/gleitz/howdoi>`_
20 |   Howdoi is a code search tool, written in Python.
21 | 
22 | - `Flask <https://github.com/mitsuhiko/flask>`_
23 |   Flask is a microframework for Python based on Werkzeug and Jinja2.
24 |   It's intended for getting started very quickly and was developed with
25 |   best intentions in mind.
26 | 
27 | - `Diamond <https://github.com/python-diamond/Diamond>`_
28 |   Diamond is a Python daemon that collects metrics
29 |   and publishes them to Graphite or other backends.
30 |   It is capable of collecting CPU, memory, network, I/O, load, and disk metrics.
31 |   Additionally, it features an API for implementing custom collectors
32 |   for gathering metrics from almost any source.
33 | 
34 | - `Werkzeug <https://github.com/mitsuhiko/werkzeug>`_
35 |   Werkzeug started as a simple collection of various utilities for WSGI
36 |   applications and has become one of the most advanced WSGI utility modules.
37 |   It includes a powerful debugger, full-featured request and response objects,
38 |   HTTP utilities to handle entity tags, cache control headers, HTTP dates,
39 |   cookie handling, file uploads, a powerful URL routing system, and a bunch
40 |   of community-contributed addon modules.
41 | 
42 | - `Requests <https://github.com/kennethreitz/requests>`_
43 |   Requests is an Apache2 Licensed HTTP library, written in Python,
44 |   for human beings.
45 | 
46 | - `Tablib <https://github.com/jazzband/tablib>`_
47 |   Tablib is a format-agnostic tabular dataset library, written in Python.
48 | 
49 | 
50 | .. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples.
51 | 
52 | .. todo:: Explain techniques to rapidly identify data structures and algorithms and determine what the code is doing.
53 | 


--------------------------------------------------------------------------------
/ext/python-guide-logo.ai:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/realpython/python-guide/5b67cf2e6c791c571bdf6f4b49291a7230d3d123/ext/python-guide-logo.ai


--------------------------------------------------------------------------------
/make.bat:
--------------------------------------------------------------------------------
  1 | @ECHO OFF
  2 | 
  3 | REM Command file for Sphinx documentation
  4 | 
  5 | if "%SPHINXBUILD%" == "" (
  6 | 	set SPHINXBUILD=sphinx-build
  7 | )
  8 | set BUILDDIR=build
  9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% docs
 10 | if NOT "%PAPER%" == "" (
 11 | 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 12 | )
 13 | 
 14 | if "%1" == "" goto help
 15 | 
 16 | if "%1" == "help" (
 17 | 	:help
 18 | 	echo.Please use `make ^<target^>` where ^<target^> is one of
 19 | 	echo.  html       to make standalone HTML files
 20 | 	echo.  dirhtml    to make HTML files named index.html in directories
 21 | 	echo.  singlehtml to make a single large HTML file
 22 | 	echo.  pickle     to make pickle files
 23 | 	echo.  json       to make JSON files
 24 | 	echo.  htmlhelp   to make HTML files and a HTML help project
 25 | 	echo.  qthelp     to make HTML files and a qthelp project
 26 | 	echo.  devhelp    to make HTML files and a Devhelp project
 27 | 	echo.  epub       to make an epub
 28 | 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 29 | 	echo.  text       to make text files
 30 | 	echo.  man        to make manual pages
 31 | 	echo.  changes    to make an overview over all changed/added/deprecated items
 32 | 	echo.  linkcheck  to check all external links for integrity
 33 | 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 34 | 	goto end
 35 | )
 36 | 
 37 | if "%1" == "clean" (
 38 | 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
 39 | 	del /q /s %BUILDDIR%\*
 40 | 	goto end
 41 | )
 42 | 
 43 | if "%1" == "html" (
 44 | 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 45 | 	echo.
 46 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
 47 | 	goto end
 48 | )
 49 | 
 50 | if "%1" == "dirhtml" (
 51 | 	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
 52 | 	echo.
 53 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
 54 | 	goto end
 55 | )
 56 | 
 57 | if "%1" == "singlehtml" (
 58 | 	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
 59 | 	echo.
 60 | 	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
 61 | 	goto end
 62 | )
 63 | 
 64 | if "%1" == "pickle" (
 65 | 	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
 66 | 	echo.
 67 | 	echo.Build finished; now you can process the pickle files.
 68 | 	goto end
 69 | )
 70 | 
 71 | if "%1" == "json" (
 72 | 	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
 73 | 	echo.
 74 | 	echo.Build finished; now you can process the JSON files.
 75 | 	goto end
 76 | )
 77 | 
 78 | if "%1" == "htmlhelp" (
 79 | 	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
 80 | 	echo.
 81 | 	echo.Build finished; now you can run HTML Help Workshop with the ^
 82 | .hhp project file in %BUILDDIR%/htmlhelp.
 83 | 	goto end
 84 | )
 85 | 
 86 | if "%1" == "qthelp" (
 87 | 	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
 88 | 	echo.
 89 | 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 90 | .qhcp project file in %BUILDDIR%/qthelp, like this:
 91 | 	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\SublimeDocs.qhcp
 92 | 	echo.To view the help file:
 93 | 	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\SublimeDocs.ghc
 94 | 	goto end
 95 | )
 96 | 
 97 | if "%1" == "devhelp" (
 98 | 	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
 99 | 	echo.
100 | 	echo.Build finished.
101 | 	goto end
102 | )
103 | 
104 | if "%1" == "epub" (
105 | 	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
106 | 	echo.
107 | 	echo.Build finished. The epub file is in %BUILDDIR%/epub.
108 | 	goto end
109 | )
110 | 
111 | if "%1" == "latex" (
112 | 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
113 | 	echo.
114 | 	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
115 | 	goto end
116 | )
117 | 
118 | if "%1" == "text" (
119 | 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
120 | 	echo.
121 | 	echo.Build finished. The text files are in %BUILDDIR%/text.
122 | 	goto end
123 | )
124 | 
125 | if "%1" == "man" (
126 | 	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
127 | 	echo.
128 | 	echo.Build finished. The manual pages are in %BUILDDIR%/man.
129 | 	goto end
130 | )
131 | 
132 | if "%1" == "changes" (
133 | 	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
134 | 	echo.
135 | 	echo.The overview file is in %BUILDDIR%/changes.
136 | 	goto end
137 | )
138 | 
139 | if "%1" == "linkcheck" (
140 | 	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
141 | 	echo.
142 | 	echo.Link check complete; look for any errors in the above output ^
143 | or in %BUILDDIR%/linkcheck/output.txt.
144 | 	goto end
145 | )
146 | 
147 | if "%1" == "doctest" (
148 | 	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
149 | 	echo.
150 | 	echo.Testing of doctests in the sources finished, look at the ^
151 | results in %BUILDDIR%/doctest/output.txt.
152 | 	goto end
153 | )
154 | 
155 | :end
156 | 


--------------------------------------------------------------------------------
/requirements-to-freeze.txt:
--------------------------------------------------------------------------------
1 | sphinx


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
 1 | alabaster==0.7.11
 2 | Babel==2.6.0
 3 | certifi==2018.4.16
 4 | chardet==3.0.4
 5 | docutils==0.14
 6 | idna==2.7
 7 | imagesize==1.0.0
 8 | Jinja2==2.10
 9 | MarkupSafe==1.1.1
10 | packaging==17.1
11 | Pygments==2.2.0
12 | pyparsing==2.2.0
13 | pytz==2018.5
14 | requests==2.19.1
15 | six==1.11.0
16 | snowballstemmer==1.2.1
17 | Sphinx==1.7.6
18 | sphinx-sitemap==0.3.1
19 | sphinxcontrib-websupport==1.1.0
20 | urllib3==1.23
21 | 


--------------------------------------------------------------------------------
/runtime.txt:
--------------------------------------------------------------------------------
1 | 3.8
2 | 


--------------------------------------------------------------------------------