diff --git a/Readme.rst b/Readme.rst index d7d26dfb1..1bdce6b40 100644 --- a/Readme.rst +++ b/Readme.rst @@ -3,7 +3,7 @@ Hitchhiker's Guide to Python **Python Best Practices Guidebook** -.. image:: https://farm1.staticflickr.com/628/33173824932_58add34581_k_d.jpg +.. image:: /_static/photos/33173824932_58add34581_k_d.jpg ----------- diff --git a/docs/_static/photos/32800783863_11a00db52c_k_d.jpg b/docs/_static/photos/32800783863_11a00db52c_k_d.jpg new file mode 100644 index 000000000..649272a69 Binary files /dev/null and b/docs/_static/photos/32800783863_11a00db52c_k_d.jpg differ diff --git a/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg b/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg new file mode 100644 index 000000000..208bbe8f9 Binary files /dev/null and b/docs/_static/photos/32800805573_568d6b72fd_k_d.jpg differ diff --git a/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg b/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg new file mode 100644 index 000000000..040660b87 Binary files /dev/null and b/docs/_static/photos/33175624924_7febc46cc4_k_d.jpg differ diff --git a/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg b/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg new file mode 100644 index 000000000..c356d03d3 Binary files /dev/null and b/docs/_static/photos/33175625804_e225b90f3e_k_d.jpg differ diff --git a/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg b/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg new file mode 100644 index 000000000..75a02fd7b Binary files /dev/null and b/docs/_static/photos/33467946364_3e59bd376a_k_d.jpg differ diff --git a/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg b/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg new file mode 100644 index 000000000..54781c3ec Binary files /dev/null and b/docs/_static/photos/33573755856_7f43d43adf_k_d.jpg differ diff --git a/docs/_static/photos/33573767786_eececc5d27_k_d.jpg b/docs/_static/photos/33573767786_eececc5d27_k_d.jpg new file mode 100644 index 000000000..1b529faad Binary files /dev/null and b/docs/_static/photos/33573767786_eececc5d27_k_d.jpg differ diff --git a/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg b/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg new file mode 100644 index 000000000..a7734c79d Binary files /dev/null and b/docs/_static/photos/33573769116_49c1ef51e7_k_d.jpg differ diff --git a/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg b/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg new file mode 100644 index 000000000..efdbea512 Binary files /dev/null and b/docs/_static/photos/33888714601_a1f7d020a2_k_d.jpg differ diff --git a/docs/_static/photos/33907143624_cd621b535c_k_d.jpg b/docs/_static/photos/33907143624_cd621b535c_k_d.jpg new file mode 100644 index 000000000..d7604c1a7 Binary files /dev/null and b/docs/_static/photos/33907143624_cd621b535c_k_d.jpg differ diff --git a/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg b/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg new file mode 100644 index 000000000..85bb549c8 Binary files /dev/null and b/docs/_static/photos/33907149294_82d7535a6c_k_d.jpg differ diff --git a/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg b/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg new file mode 100644 index 000000000..93e98f476 Binary files /dev/null and b/docs/_static/photos/33907150054_5ee79e8940_k_d.jpg differ diff --git a/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg b/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg new file mode 100644 index 000000000..480d6e153 Binary files /dev/null and b/docs/_static/photos/33907150594_9abba7ad0a_k_d.jpg differ diff --git a/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg b/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg new file mode 100644 index 000000000..ae0136d82 Binary files /dev/null and b/docs/_static/photos/33907151034_e0a9e53402_k_d.jpg differ diff --git a/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg b/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg new file mode 100644 index 000000000..cf218c710 Binary files /dev/null and b/docs/_static/photos/33907151224_0574e7dfc2_k_d.jpg differ diff --git a/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg b/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg new file mode 100644 index 000000000..91bfebbb0 Binary files /dev/null and b/docs/_static/photos/33907152464_a99fdcc8de_k_d.jpg differ diff --git a/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg b/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg new file mode 100644 index 000000000..7b3151fd5 Binary files /dev/null and b/docs/_static/photos/33907152824_bf91078cc1_k_d.jpg differ diff --git a/docs/_static/photos/33925223870_97e44f5629_k_d.jpg b/docs/_static/photos/33925223870_97e44f5629_k_d.jpg new file mode 100644 index 000000000..b271f261a Binary files /dev/null and b/docs/_static/photos/33925223870_97e44f5629_k_d.jpg differ diff --git a/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg b/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg new file mode 100644 index 000000000..8bdd9082c Binary files /dev/null and b/docs/_static/photos/33928819683_97b5c6a184_k_d.jpg differ diff --git a/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg b/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg new file mode 100644 index 000000000..995212043 Binary files /dev/null and b/docs/_static/photos/33928823133_2f3d32cf32_k_d.jpg differ diff --git a/docs/_static/photos/34018729885_002ced9b54_k_d.jpg b/docs/_static/photos/34018729885_002ced9b54_k_d.jpg new file mode 100644 index 000000000..5420bb6a1 Binary files /dev/null and b/docs/_static/photos/34018729885_002ced9b54_k_d.jpg differ diff --git a/docs/_static/photos/34018732105_f0e6758859_k_d.jpg b/docs/_static/photos/34018732105_f0e6758859_k_d.jpg new file mode 100644 index 000000000..1a4c3dd03 Binary files /dev/null and b/docs/_static/photos/34018732105_f0e6758859_k_d.jpg differ diff --git a/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg b/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg new file mode 100644 index 000000000..21fada7a6 Binary files /dev/null and b/docs/_static/photos/34151833832_6bdfd930af_k_d.jpg differ diff --git a/docs/_static/photos/34268661876_442428e122_k_d.jpg b/docs/_static/photos/34268661876_442428e122_k_d.jpg new file mode 100644 index 000000000..f6ce0be5c Binary files /dev/null and b/docs/_static/photos/34268661876_442428e122_k_d.jpg differ diff --git a/docs/_static/photos/34309496175_b82d104282_k_d.jpg b/docs/_static/photos/34309496175_b82d104282_k_d.jpg new file mode 100644 index 000000000..a09fd0a3d Binary files /dev/null and b/docs/_static/photos/34309496175_b82d104282_k_d.jpg differ diff --git a/docs/_static/photos/34364815780_bea6614025_k_d.jpg b/docs/_static/photos/34364815780_bea6614025_k_d.jpg new file mode 100644 index 000000000..ab05248ae Binary files /dev/null and b/docs/_static/photos/34364815780_bea6614025_k_d.jpg differ diff --git a/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg b/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg new file mode 100644 index 000000000..e765c7cf2 Binary files /dev/null and b/docs/_static/photos/34435687940_8f73fc1fa6_k_d.jpg differ diff --git a/docs/_static/photos/34435688380_b5a740762b_k_d.jpg b/docs/_static/photos/34435688380_b5a740762b_k_d.jpg new file mode 100644 index 000000000..baa1f17fc Binary files /dev/null and b/docs/_static/photos/34435688380_b5a740762b_k_d.jpg differ diff --git a/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg b/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg new file mode 100644 index 000000000..fe4c1aa40 Binary files /dev/null and b/docs/_static/photos/34435688560_4cc2a7bcbb_k_d.jpg differ diff --git a/docs/_static/photos/34435689480_2e6f358510_k_d.jpg b/docs/_static/photos/34435689480_2e6f358510_k_d.jpg new file mode 100644 index 000000000..87e278159 Binary files /dev/null and b/docs/_static/photos/34435689480_2e6f358510_k_d.jpg differ diff --git a/docs/_static/photos/34435690330_11930b5987_k_d.jpg b/docs/_static/photos/34435690330_11930b5987_k_d.jpg new file mode 100644 index 000000000..74b44e067 Binary files /dev/null and b/docs/_static/photos/34435690330_11930b5987_k_d.jpg differ diff --git a/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg b/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg new file mode 100644 index 000000000..4a00c547e Binary files /dev/null and b/docs/_static/photos/34435690580_3afec7d4cd_k_d.jpg differ diff --git a/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg b/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg new file mode 100644 index 000000000..8a667d23a Binary files /dev/null and b/docs/_static/photos/34484834733_5b80f65ab1_k_d.jpg differ diff --git a/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg b/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg new file mode 100644 index 000000000..88c760e87 Binary files /dev/null and b/docs/_static/photos/34575689432_3de8e9a348_k_d.jpg differ diff --git a/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg b/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg new file mode 100644 index 000000000..50554cfa6 Binary files /dev/null and b/docs/_static/photos/34689432801_78d97ecec9_k_d.jpg differ diff --git a/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg b/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg new file mode 100644 index 000000000..ab2ae0735 Binary files /dev/null and b/docs/_static/photos/34689452831_93d7fd0571_k_d.jpg differ diff --git a/docs/_static/photos/34725946825_0f85497e60_k_d.jpg b/docs/_static/photos/34725946825_0f85497e60_k_d.jpg new file mode 100644 index 000000000..5d58e91d3 Binary files /dev/null and b/docs/_static/photos/34725946825_0f85497e60_k_d.jpg differ diff --git a/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg b/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg new file mode 100644 index 000000000..c982f1fe8 Binary files /dev/null and b/docs/_static/photos/34725951345_c8f5959a2e_k_d.jpg differ diff --git a/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg b/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg new file mode 100644 index 000000000..c25560701 Binary files /dev/null and b/docs/_static/photos/35254379756_c9fe23f843_k_d.jpg differ diff --git a/docs/_static/photos/35294660055_42c02b2316_k_d.jpg b/docs/_static/photos/35294660055_42c02b2316_k_d.jpg new file mode 100644 index 000000000..f7cc6b936 Binary files /dev/null and b/docs/_static/photos/35294660055_42c02b2316_k_d.jpg differ diff --git a/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg b/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg new file mode 100644 index 000000000..e3a1b74a9 Binary files /dev/null and b/docs/_static/photos/35620636012_f66aa88f93_k_d.jpg differ diff --git a/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg b/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg new file mode 100644 index 000000000..ed1364a28 Binary files /dev/null and b/docs/_static/photos/36137232412_fdcb0f84eb_k_d.jpg differ diff --git a/docs/_static/photos/36137234682_be6898bf57_k_d.jpg b/docs/_static/photos/36137234682_be6898bf57_k_d.jpg new file mode 100644 index 000000000..fed85141d Binary files /dev/null and b/docs/_static/photos/36137234682_be6898bf57_k_d.jpg differ diff --git a/docs/_static/test b/docs/_static/test deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/dev/env.rst b/docs/dev/env.rst index bc6d68cbd..de67a9ae9 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -1,7 +1,7 @@ Your Development Environment ============================ -.. image:: https://farm3.staticflickr.com/2930/33175624924_7febc46cc4_k_d.jpg +.. image:: /_static/photos/33175624924_7febc46cc4_k_d.jpg Text Editors @@ -164,8 +164,8 @@ MIT licensed. Enthought Canopy ---------------- `Enthought Canopy `_ is a Python -IDE which is focused towards Scientists and Engineers as it provides pre -installed libraries for data analysis. +IDE which is focused towards Scientists and Engineers as it provides pre +installed libraries for data analysis. Eclipse ------- diff --git a/docs/dev/pip-virtualenv.rst b/docs/dev/pip-virtualenv.rst index 50b69034c..6971be876 100644 --- a/docs/dev/pip-virtualenv.rst +++ b/docs/dev/pip-virtualenv.rst @@ -3,7 +3,7 @@ Further Configuration of Pip and Virtualenv =========================================== -.. image:: https://farm4.staticflickr.com/3934/34018732105_f0e6758859_k_d.jpg +.. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg Requiring an active virtual environment for ``pip`` --------------------------------------------------- diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 06f20dde4..11f924882 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -3,7 +3,7 @@ Pipenv & Virtual Environments ============================= -.. image:: https://farm5.staticflickr.com/4290/35294660055_42c02b2316_k_d.jpg +.. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg This tutorial walks you through installing and using Python packages. diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 472c6d546..2e54be330 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -3,7 +3,7 @@ The Community ============= -.. image:: https://farm5.staticflickr.com/4225/34689432801_78d97ecec9_k_d.jpg +.. image:: /_static/photos/34689432801_78d97ecec9_k_d.jpg BDFL ---- diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst index a75aa3c03..ea247ce4f 100644 --- a/docs/intro/documentation.rst +++ b/docs/intro/documentation.rst @@ -1,7 +1,7 @@ Documentation ============= -.. image:: https://farm5.staticflickr.com/4178/33928823133_2f3d32cf32_k_d.jpg +.. image:: /_static/photos/33928823133_2f3d32cf32_k_d.jpg Official Documentation ---------------------- diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 8e9cc6f0f..4a6772d79 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -1,7 +1,7 @@ Introduction ============ -.. image:: https://farm5.staticflickr.com/4180/34725946825_0f85497e60_k_d.jpg +.. image:: /_static/photos/34725946825_0f85497e60_k_d.jpg From the `official Python website `_: diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 8e71cfce7..22935e6d6 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -1,7 +1,7 @@ Learning Python =============== -.. image:: https://farm3.staticflickr.com/2840/32800783863_11a00db52c_k_d.jpg +.. image:: /_static/photos/32800783863_11a00db52c_k_d.jpg Beginner -------- diff --git a/docs/intro/news.rst b/docs/intro/news.rst index c3a019551..37c144a15 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -1,7 +1,7 @@ News ==== -.. image:: https://farm4.staticflickr.com/3804/33573767786_eececc5d27_k_d.jpg +.. image:: /_static/photos/33573767786_eececc5d27_k_d.jpg Planet Python ~~~~~~~~~~~~~ @@ -35,7 +35,7 @@ A short-form Python podcast covering recent developer headlines. Pycoder's Weekly ~~~~~~~~~~~~~~~~ -Pycoder's Weekly is a free weekly Python newsletter for Python developers +Pycoder's Weekly is a free weekly Python newsletter for Python developers by Python developers (Projects, Articles, News, and Jobs). `Pycoder's Weekly `_ diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index b75f55926..4045fb102 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -1,7 +1,7 @@ Contribute ~~~~~~~~~~ -.. image:: https://farm3.staticflickr.com/2858/33573769116_49c1ef51e7_k_d.jpg +.. image:: /_static/photos/33573769116_49c1ef51e7_k_d.jpg Python-guide is under active development, and contributors are welcome. diff --git a/docs/notes/license.rst b/docs/notes/license.rst index 6df4ee6b8..407e17358 100644 --- a/docs/notes/license.rst +++ b/docs/notes/license.rst @@ -2,6 +2,6 @@ License ======= -.. image:: https://farm4.staticflickr.com/3762/32800805573_568d6b72fd_k_d.jpg +.. image:: /_static/photos/32800805573_568d6b72fd_k_d.jpg The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license `_. diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index c2d4034ec..619c6daff 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -4,7 +4,7 @@ The Guide Style Guide ===================== -.. image:: https://farm4.staticflickr.com/3684/33573755856_7f43d43adf_k_d.jpg +.. image:: /_static/photos/33573755856_7f43d43adf_k_d.jpg As with all documentation, having a consistent format helps make the document more understandable. In order to make The Guide easier to digest, diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index ee7b5127b..1fe3b5358 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -1,7 +1,7 @@ Systems Administration ====================== -.. image:: https://farm5.staticflickr.com/4179/34435690580_3afec7d4cd_k_d.jpg +.. image:: /_static/photos/34435690580_3afec7d4cd_k_d.jpg Fabric ------ @@ -234,37 +234,37 @@ The Ansible playbook will ping all of the servers in the :file:`hosts.yml` file. You can also select groups of servers using Ansible. For more information about Ansible, read the `Ansible Docs `_. -`An Ansible tutorial `_ is also a +`An Ansible tutorial `_ is also a great and detailed introduction to getting started with Ansible. Chef ---- -`Chef `_ is a systems and cloud infrastructure automation -framework that makes it easy to deploy servers and applications to any physical, -virtual, or cloud location. In case this is your choice for configuration management, -you will primarily use Ruby to write your infrastructure code. - -Chef clients run on every server that is part of your infrastructure and these regularly -check with your Chef server to ensure your system is always aligned and represents the -desired state. Since each individual server has its own distinct Chef client, each server +`Chef `_ is a systems and cloud infrastructure automation +framework that makes it easy to deploy servers and applications to any physical, +virtual, or cloud location. In case this is your choice for configuration management, +you will primarily use Ruby to write your infrastructure code. + +Chef clients run on every server that is part of your infrastructure and these regularly +check with your Chef server to ensure your system is always aligned and represents the +desired state. Since each individual server has its own distinct Chef client, each server configures itself and this distributed approach makes Chef a scalable automation platform. -Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically -packages for infrastructure choices, are usually stored in your Chef server. -Read the `Digital Ocean tutorial series -`_ +Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically +packages for infrastructure choices, are usually stored in your Chef server. +Read the `Digital Ocean tutorial series +`_ on chef to learn how to create a simple Chef Server. To create a simple cookbook the `knife `_ command is used: -.. code-block:: console +.. code-block:: console knife cookbook create cookbook_name -`Getting started with Chef `_ -is a good starting point for Chef Beginners and many community maintained cookbooks that can -serve as a good reference or tweaked to serve your infrastructure configuration needs can be +`Getting started with Chef `_ +is a good starting point for Chef Beginners and many community maintained cookbooks that can +serve as a good reference or tweaked to serve your infrastructure configuration needs can be found on the `Chef Supermarket `_. - `Chef Documentation `_ @@ -304,7 +304,7 @@ your Puppet modules. .. code-block:: console $ facter operatingsystem - Ubuntu + Ubuntu Writing Modules in Puppet is pretty straight forward. Puppet Manifests together form Puppet Modules. Puppet manifest end with an extension of ``.pp``. @@ -374,7 +374,7 @@ Buildout -------- `Buildout `_ is an open source software build tool. -Buildout is created using the Python programming language. It implements a +Buildout is created using the Python programming language. It implements a principle of separation of configuration from the scripts that do the setting up. Buildout is primarily used to download and set up dependencies in Python eggs format of the software being developed or deployed. Recipes for build tasks in any diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 457f2321f..676f0b805 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -1,7 +1,7 @@ Continuous Integration ====================== -.. image:: https://farm5.staticflickr.com/4173/33907150594_9abba7ad0a_k_d.jpg +.. image:: /_static/photos/33907150594_9abba7ad0a_k_d.jpg .. note:: For advice on writing your tests, see :doc:`/writing/tests`. diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index b6c7e7376..50bbbbc09 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -1,7 +1,7 @@ Command-line Applications ========================= -.. image:: https://farm5.staticflickr.com/4272/34435690330_11930b5987_k_d.jpg +.. image:: /_static/photos/34435690330_11930b5987_k_d.jpg Command-line applications, also referred to as `Console Applications `_, @@ -68,9 +68,9 @@ sub-command to do the work. Cement ------ -`Cement `_ is an advanced CLI Application Framework. +`Cement `_ is an advanced CLI Application Framework. Its goal is to introduce a standard, and feature-full platform for both simple and complex command line applications as well -as support rapid development needs without sacrificing quality. -Cement is flexible, and it's use cases span from the simplicity of a micro-framework -to the complexity of a meg-framework. +as support rapid development needs without sacrificing quality. +Cement is flexible, and it's use cases span from the simplicity of a micro-framework +to the complexity of a meg-framework. diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 712d7f88e..dba7d7127 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -1,7 +1,7 @@ Interfacing with C/C++ Libraries ================================ -.. image:: https://farm5.staticflickr.com/4173/34725951345_c8f5959a2e_k_d.jpg +.. image:: /_static/photos/34725951345_c8f5959a2e_k_d.jpg C Foreign Function Interface ---------------------------- @@ -105,20 +105,20 @@ Example: Overloading __repr__ :linenos: %include "string.i" - + %module myclass %{ #include #include "MyClass.h" %} - + %extend MyClass { std::string __repr__() { return $self->getName(); } } - + %include "MyClass.h" diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst index 99c7ac08d..459feb243 100644 --- a/docs/scenarios/client.rst +++ b/docs/scenarios/client.rst @@ -1,7 +1,7 @@ Network Applications ==================== -.. image:: https://farm5.staticflickr.com/4251/34364815780_bea6614025_k_d.jpg +.. image:: /_static/photos/34364815780_bea6614025_k_d.jpg HTTP :::: diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst index 1d61c1a9a..35330821c 100644 --- a/docs/scenarios/crypto.rst +++ b/docs/scenarios/crypto.rst @@ -1,13 +1,13 @@ Cryptography ============ -.. image:: https://farm5.staticflickr.com/4220/33907152824_bf91078cc1_k_d.jpg +.. image:: /_static/photos/33907152824_bf91078cc1_k_d.jpg Cryptography ------------ `Cryptography `_ is an actively developed -library that provides cryptographic recipes and primitives. It supports +library that provides cryptographic recipes and primitives. It supports Python 2.6-2.7, Python 3.3+ and PyPy. @@ -60,7 +60,7 @@ Example .. code-block:: python3 import gpg - + # Encryption to public key specified in rkey. a_key = input("Enter the fingerprint or key ID to encrypt to: ") filename = input("Enter the filename to encrypt: ") diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 8da9a203e..af610e0f7 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -1,7 +1,7 @@ Databases ========= -.. image:: https://farm5.staticflickr.com/4225/33907152464_a99fdcc8de_k_d.jpg +.. image:: /_static/photos/33907152464_a99fdcc8de_k_d.jpg DB-API ------ diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index ed683d62e..28f1a9cd8 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -1,7 +1,7 @@ GUI Applications ================ -.. image:: https://farm5.staticflickr.com/4250/33907143624_cd621b535c_k_d.jpg +.. image:: /_static/photos/33907143624_cd621b535c_k_d.jpg Alphabetical list of GUI Applications. diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst index bcd02e6da..ff620808e 100644 --- a/docs/scenarios/imaging.rst +++ b/docs/scenarios/imaging.rst @@ -2,7 +2,7 @@ Image Manipulation ================== -.. image:: https://farm5.staticflickr.com/4157/34575689432_3de8e9a348_k_d.jpg +.. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg Most image processing and manipulation techniques can be carried out effectively using two libraries: Python Imaging Library (PIL) and OpenSource diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst index 55de04ef7..d555067db 100644 --- a/docs/scenarios/json.rst +++ b/docs/scenarios/json.rst @@ -1,7 +1,7 @@ JSON ==== -.. image:: https://farm5.staticflickr.com/4174/33928819683_97b5c6a184_k_d.jpg +.. image:: /_static/photos/33928819683_97b5c6a184_k_d.jpg The `json `_ library can parse JSON from strings or files. The library parses JSON into a Python dictionary @@ -60,7 +60,7 @@ You can start using simplejson when the json library is not available by importing simplejson under a different name: .. code-block:: python - + import simplejson as json After importing simplejson as json, the above examples will all work as if you diff --git a/docs/scenarios/ml.rst b/docs/scenarios/ml.rst index fde454276..30eefcbdf 100644 --- a/docs/scenarios/ml.rst +++ b/docs/scenarios/ml.rst @@ -2,9 +2,9 @@ Machine Learning ================ -.. image:: https://farm4.staticflickr.com/3954/34018729885_002ced9b54_k_d.jpg +.. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg -Python has a vast number of libraries for data analysis, statistics and Machine Learning itself, making it a language of choice for many data scientists. +Python has a vast number of libraries for data analysis, statistics and Machine Learning itself, making it a language of choice for many data scientists. Some widely used packages for Machine Learning and other Data Science applications are enlisted below. @@ -45,7 +45,7 @@ Installation Through PyPI: .. code-block:: python - + pip install -U scikit-learn Through conda: @@ -61,28 +61,28 @@ Example For this example, we train a simple classifier on the `Iris dataset `_, which comes bundled in with scikit-learn. -The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica). +The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica). We shuffle the Iris dataset, and divide it into separate training and testing sets: keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set, and predict on the testing set. .. code-block:: python - from sklearn.datasets import load_iris + from sklearn.datasets import load_iris from sklearn import tree from sklearn.metrics import accuracy_score import numpy as np #loading the iris dataset - iris = load_iris() + iris = load_iris() x = iris.data #array of the data y = iris.target #array of labels (i.e answers) of each data entry #getting label names i.e the three flower species - y_names = iris.target_names + y_names = iris.target_names #taking random indices to split the dataset into train and test - test_ids = np.random.permutation(len(x)) + test_ids = np.random.permutation(len(x)) #splitting data and labels into train and test #keeping last 10 entries for testing, rest for training diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index 0aa5860c9..1cea42dd5 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -1,7 +1,7 @@ Networking ========== -.. image:: https://farm3.staticflickr.com/2892/34151833832_6bdfd930af_k_d.jpg +.. image:: /_static/photos/34151833832_6bdfd930af_k_d.jpg Twisted ------- @@ -35,4 +35,4 @@ gevent `gevent `_ is a coroutine-based Python networking library that uses greenlets to provide a high-level synchronous API on top of -the libev event loop. +the libev event loop. diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index f81ecef1b..7276420d3 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -2,7 +2,7 @@ Scientific Applications ======================= -.. image:: https://farm3.staticflickr.com/2890/33925223870_97e44f5629_k_d.jpg +.. image:: /_static/photos/33925223870_97e44f5629_k_d.jpg Context ::::::: diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 7a8e94412..01d56f4a3 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -1,7 +1,7 @@ HTML Scraping ============= -.. image:: https://farm3.staticflickr.com/2900/34268661876_442428e122_k_d.jpg +.. image:: /_static/photos/34268661876_442428e122_k_d.jpg Web Scraping ------------ diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index 8a950bad9..5d5f41517 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -2,41 +2,41 @@ Data Serialization ================== -.. image:: https://farm3.staticflickr.com/2927/33467946364_3e59bd376a_k_d.jpg +.. image:: /_static/photos/33467946364_3e59bd376a_k_d.jpg What is data serialization? --------------------------- -Data serialization is the concept of converting structured data into a format -that allows it to be shared or stored in such a way that its original -structure to be recovered. In some cases, the secondary intention of data -serialization is to minimize the size of the serialized data which then +Data serialization is the concept of converting structured data into a format +that allows it to be shared or stored in such a way that its original +structure to be recovered. In some cases, the secondary intention of data +serialization is to minimize the size of the serialized data which then minimizes disk space or bandwidth requirements. Pickle ------ -The native data serialization module for Python is called `Pickle -`_. +The native data serialization module for Python is called `Pickle +`_. Here's an example: .. code-block:: python - + import pickle - + #Here's an example dict grades = { 'Alice': 89, 'Bob': 72, 'Charles': 87 } - + #Use dumps to convert the object to a serialized string serial_grades = pickle.dumps( grades ) - - #Use loads to de-serialize an object + + #Use loads to de-serialize an object received_grades = pickle.loads( serial_grades ) Protobuf -------- -If you're looking for a serialization module that has support in multiple -languages, Google's `Protobuf -`_ library is an option. +If you're looking for a serialization module that has support in multiple +languages, Google's `Protobuf +`_ library is an option. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 18e84ec92..dcb141a71 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -1,7 +1,7 @@ Speed ===== -.. image:: https://farm3.staticflickr.com/2826/33175625804_e225b90f3e_k_d.jpg +.. image:: /_static/photos/33175625804_e225b90f3e_k_d.jpg CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast. @@ -234,14 +234,14 @@ Concurrent.futures The `concurrent.futures`_ module is a module in the standard library that provides a "high-level interface for asynchronously executing callables". It abstracts away a lot of the more complicated details about using multiple -threads or processes for concurrency, and allows the user to focus on +threads or processes for concurrency, and allows the user to focus on accomplishing the task at hand. The `concurrent.futures`_ module exposes two main classes, the `ThreadPoolExecutor` and the `ProcessPoolExecutor`. The ThreadPoolExecutor will create a pool of worker threads that a user can submit jobs to. These jobs will then be executed in another thread when the next worker thread becomes -available. +available. The ProcessPoolExecutor works in the same way, except instead of using multiple threads for its workers, it will use multiple processes. This makes it possible @@ -275,7 +275,7 @@ everything in parallel. : # Do something with the result print(page.text) -For even more control, the `submit(func, *args, **kwargs)` method will schedule +For even more control, the `submit(func, *args, **kwargs)` method will schedule a callable to be executed ( as `func(*args, **kwargs)`) and returns a `Future`_ object that represents the execution of the callable. @@ -389,9 +389,9 @@ still alive (because the join call timed out): Because multiple threads have access to the same section of memory, sometimes there might be situations where two or more threads are trying to write to the same resource at the same time or where the output is dependent on the sequence -or timing of certain events. This is called a `data race`_ or race condition. +or timing of certain events. This is called a `data race`_ or race condition. When this happens, the output will be garbled or you may encounter problems -which are difficult to debug. A good example is this `stackoverflow post`_. +which are difficult to debug. A good example is this `stackoverflow post`_. The way this can be avoided is by using a `Lock`_ that each thread needs to acquire before writing to a shared resource. Locks can be acquired and released @@ -412,7 +412,7 @@ through either the contextmanager protocol (`with` statement), or by using def monitor_website(some_website): """ - Monitor a website and then if there are any changes, + Monitor a website and then if there are any changes, log them to disk. """ while True: @@ -429,7 +429,7 @@ Here, we have a bunch of threads checking for changes on a list of sites and whenever there are any changes, they attempt to write those changes to a file by calling `log(changes)`. When `log()` is called, it will wait to acquire the lock with `with file_lock:`. This ensures that at any one time, only one -thread is writing to the file. +thread is writing to the file. Spawning Processes ------------------ diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 9ec6bdfef..923c9423b 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -2,7 +2,7 @@ Web Applications & Frameworks ============================= -.. image:: https://farm3.staticflickr.com/2891/34309496175_b82d104282_k_d.jpg +.. image:: /_static/photos/34309496175_b82d104282_k_d.jpg As a powerful scripting language adapted to both fast prototyping and bigger projects, Python is widely used in web application @@ -99,7 +99,7 @@ to build RESTful API microservices that are fast and scalable. It is a reliable, high-performance Python web framework for building large-scale app backends and microservices. Falcon encourages the REST architectural style of -mapping URIs to resources, trying to do as little as possible while remaining highly effective. +mapping URIs to resources, trying to do as little as possible while remaining highly effective. Falcon highlights four main focuses: speed, reliability, flexibility and debuggability. It implements HTTP through "responders" such as ``on_get()``, ``on_put()``, etc. @@ -120,9 +120,9 @@ Pyramid `Pyramid `_ is a very flexible framework with a heavy focus on modularity. It comes with a small number of libraries ("batteries") -built-in, and encourages users to extend its base functionality. A set of +built-in, and encourages users to extend its base functionality. A set of provided cookiecutter templates helps making new project decisions for users. -It poweres one of the most important parts of python infrastucture +It poweres one of the most important parts of python infrastucture `PyPI `_. Pyramid does not have a large user base, unlike Django and Flask. It's a diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index 8af9e416c..51a784d20 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -1,7 +1,7 @@ XML parsing =========== -.. image:: https://farm3.staticflickr.com/2808/33888714601_a1f7d020a2_k_d.jpg +.. image:: /_static/photos/33888714601_a1f7d020a2_k_d.jpg untangle -------- diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index f0b73b41d..8545ab295 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -4,27 +4,27 @@ Freezing Your Code ================== -.. image:: https://farm5.staticflickr.com/4227/33907151034_e0a9e53402_k_d.jpg +.. image:: /_static/photos/33907151034_e0a9e53402_k_d.jpg -"Freezing" your code is creating a single-file executable file to distribute -to end-users, that contains all of your application code as well as the +"Freezing" your code is creating a single-file executable file to distribute +to end-users, that contains all of your application code as well as the Python interpreter. Applications such as 'Dropbox', 'Eve Online', 'Civilization IV', and BitTorrent clients do this. The advantage of distributing this way is that your application will "just work", -even if the user doesn't already have the required version of Python (or any) +even if the user doesn't already have the required version of Python (or any) installed. On Windows, and even on many Linux distributions and OS X, the right version of Python will not already be installed. -Besides, end-user software should always be in an executable format. Files -ending in ``.py`` are for software engineers and system administrators. +Besides, end-user software should always be in an executable format. Files +ending in ``.py`` are for software engineers and system administrators. -One disadvantage of freezing is that it will increase the size of your +One disadvantage of freezing is that it will increase the size of your distribution by about 2–12MB. Also, you will be responsible for shipping -updated versions of your application when security vulnerabilities to -Python are patched. +updated versions of your application when security vulnerabilities to +Python are patched. Alternatives to Freezing ------------------------ @@ -75,34 +75,34 @@ Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Wi 1. Install :code:`bbfreeze`: .. code-block:: console - + $ pip install bbfreeze - + 2. Write most basic :file:`bb_setup.py` .. code-block:: python from bbfreeze import Freezer - + freezer = Freezer(distdir='dist') freezer.addScript('foobar.py', gui_only=True) freezer() - + .. note:: - + This will work for the most basic one file scripts. For more advanced freezing you will have to provide include and exclude paths like so - + .. code-block:: python - + freezer = Freezer(distdir='dist', includes=['my_code'], excludes=['docs']) 3. (Optionally) include icon .. code-block:: python - + freezer.setIcon('my_awesome_icon.ico') - + 4. Provide the Microsoft Visual C runtime DLL for the freezer. It might be possible to append your :code:`sys.path` with Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script resides. @@ -110,7 +110,7 @@ resides. 5. Freeze! .. code-block:: console - + $ python bb_setup.py py2exe @@ -204,7 +204,7 @@ To create a standalone windowed OS X application, use the :code:`--windowed` opt This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt `_ or `PySide `_, to control the graphical parts of the app. -There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option. +There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option. Linux diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 7e55d4207..79d2cc0c7 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -4,7 +4,7 @@ Packaging Your Code =================== -.. image:: https://farm5.staticflickr.com/4325/36137234682_be6898bf57_k_d.jpg +.. image:: /_static/photos/36137234682_be6898bf57_k_d.jpg Package your code to share it with other developers. For example to share a library for other developers to use in their application, diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index de831b6e0..65cff2abe 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -3,7 +3,7 @@ Installing Python 2 on Linux ============================= -.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg +.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg .. note:: Check out our :ref:`guide for installing Python 3 on Linux`. diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 9d2424236..5cd3db300 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -3,7 +3,7 @@ Installing Python 2 on Mac OS X =============================== -.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg +.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg .. note:: Check out our :ref:`guide for installing Python 3 on OS X`. diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index e930b4683..113a1740c 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -3,7 +3,7 @@ Installing Python 2 on Windows ============================== -.. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg +.. image:: /_static/photos/34435688560_4cc2a7bcbb_k_d.jpg .. note:: Check out our :ref:`guide for installing Python 3 on Windows`. diff --git a/docs/starting/install3/linux.rst b/docs/starting/install3/linux.rst index 1c6d67d35..fa1b01c2e 100644 --- a/docs/starting/install3/linux.rst +++ b/docs/starting/install3/linux.rst @@ -3,7 +3,7 @@ Installing Python 3 on Linux ============================ -.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg +.. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg This document describes how to install Python 3.6 on Ubuntu Linux machines. @@ -93,7 +93,7 @@ care about that. Pipenv & Virtual Environments ----------------------------- -The next step is to install Pipenv, so you can install dependencies and manage virtual environments. +The next step is to install Pipenv, so you can install dependencies and manage virtual environments. A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst index 1ffdf4ba9..e330964ac 100644 --- a/docs/starting/install3/osx.rst +++ b/docs/starting/install3/osx.rst @@ -5,7 +5,7 @@ Installing Python 3 on Mac OS X =============================== -.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg +.. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg The latest version of Mac OS X, High Sierra, **comes with Python 2.7 out of the box**. @@ -106,13 +106,13 @@ The rest of the guide will assume that ``python`` references Python 3. # Do I have a Python 3 installed? $ python --version - Python 3.6.4 # Success! + Python 3.6.4 # Success! # If you still see 2.7 ensure in PATH /usr/local/bin/ takes precedence over /usr/bin/ Pipenv & Virtual Environments ----------------------------- -The next step is to install Pipenv, so you can install dependencies and manage virtual environments. +The next step is to install Pipenv, so you can install dependencies and manage virtual environments. A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the diff --git a/docs/starting/install3/win.rst b/docs/starting/install3/win.rst index ddddad5fa..1a93221e4 100644 --- a/docs/starting/install3/win.rst +++ b/docs/starting/install3/win.rst @@ -3,7 +3,7 @@ Installing Python 3 on Windows ============================== -.. image:: https://farm5.staticflickr.com/4276/34435689480_2e6f358510_k_d.jpg +.. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg First, follow the installation instructions for `Chocolatey `_. It's a community system packager manager for Windows 7+. (It's very much like Homebrew on OSX.) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index bb84c2715..d48165f78 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -3,7 +3,7 @@ Properly Installing Python ========================== -.. image:: https://farm5.staticflickr.com/4303/36137232412_fdcb0f84eb_k_d.jpg +.. image:: /_static/photos/36137232412_fdcb0f84eb_k_d.jpg There's a good chance that you already have Python on your operating system. @@ -16,8 +16,8 @@ other third-party Python libraries. .. 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. —*Kenneth Reitz* - - + + Installation Guides ------------------- diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 155eadb0c..75970b3e1 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -1,7 +1,7 @@ Picking an Python Interpreter (3 vs. 2) ======================================= -.. image:: https://farm5.staticflickr.com/4265/34484834733_5b80f65ab1_k_d.jpg +.. image:: /_static/photos/34484834733_5b80f65ab1_k_d.jpg .. _which-python: diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index d251a0b99..a712db8af 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -1,7 +1,7 @@ Documentation ============= -.. image:: https://farm5.staticflickr.com/4279/35620636012_f66aa88f93_k_d.jpg +.. image:: /_static/photos/35620636012_f66aa88f93_k_d.jpg Readability is a primary focus for Python developers, in both project and code documentation. Following some simple best practices can save @@ -67,10 +67,10 @@ There is also **great**, **free** hosting for your Sphinx_ docs: your source repository so that rebuilding your documentation will happen automatically. -When run, Sphinx_ will import your code and using Python's introspection +When run, Sphinx_ will import your code and using Python's introspection features it will extract all function, method and class signatures. It will also extract the accompanying docstrings, and compile it all into well -structured and easily readable documentation for your project. +structured and easily readable documentation for your project. .. note:: @@ -146,7 +146,7 @@ their source code, and as a side effect, it also ensures that their code is tested and works. :: - + def my_function(a, b): """ >>> my_function(2, 3) @@ -175,14 +175,14 @@ comment block is a programmer's note. The docstring describes the Unlike block comments, docstrings are built into the Python language itself. This means you can use all of Python's powerful introspection capabilities to access docstrings at runtime, compared with comments which are optimised out. -Docstrings are accessible from both the `__doc__` dunder attribute for almost +Docstrings are accessible from both the `__doc__` dunder attribute for almost every Python object, as well as with the built in `help()` function. While block comments are usually used to explain *what* a section of code is doing, or the specifics of an algorithm, docstrings are more intended for explaining to other users of your code (or you in 6 months time) *how* a -particular function can be used and the general purpose of a function, class, -or module. +particular function can be used and the general purpose of a function, class, +or module. Writing Docstrings ~~~~~~~~~~~~~~~~~~ @@ -196,19 +196,19 @@ really obvious cases, such as:: return a + b The docstring should describe the function in a way that is easy to understand. -For simple cases like trivial functions and classes, simply embedding the -function's signature (i.e. `add(a, b) -> result`) in the docstring is -unnecessary. This is because with Python's `inspect` module, it is already +For simple cases like trivial functions and classes, simply embedding the +function's signature (i.e. `add(a, b) -> result`) in the docstring is +unnecessary. This is because with Python's `inspect` module, it is already quite easy to find this information if needed, and it is also readily available -by reading the source code. +by reading the source code. -In larger or more complex projects however, it is often a good idea to give -more information about a function, what it does, any exceptions it may raise, +In larger or more complex projects however, it is often a good idea to give +more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters. For more detailed documentation of code a popular style is the one used for the Numpy project, often called `Numpy style`_ docstrings. While it can take up more -lines than the previous example, it allows the developer to include a lot +lines than the previous example, it allows the developer to include a lot more information about a method, function, or class. :: def random_number_generator(arg1, arg2): diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 76af6263c..b230640af 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -1,7 +1,7 @@ Common Gotchas ============== -.. image:: https://farm5.staticflickr.com/4163/34435688380_b5a740762b_k_d.jpg +.. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg For the most part, Python aims to be a clean and consistent language that avoids surprises. However, there are a few cases that can be confusing to diff --git a/docs/writing/license.rst b/docs/writing/license.rst index dd5fe3bb8..c48194ecb 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -1,7 +1,7 @@ Choosing a License ================== -.. image:: https://farm5.staticflickr.com/4228/33907149294_82d7535a6c_k_d.jpg +.. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg Your source publication *needs* a license. In the US, if no license is specified, users have no legal right to download, modify, or distribute. diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst index 184e9e8b6..21623594b 100644 --- a/docs/writing/logging.rst +++ b/docs/writing/logging.rst @@ -1,7 +1,7 @@ Logging ======= -.. image:: https://farm5.staticflickr.com/4246/35254379756_c9fe23f843_k_d.jpg +.. image:: /_static/photos/35254379756_c9fe23f843_k_d.jpg The :mod:`logging` module has been a part of Python's Standard Library since version 2.3. It is succinctly described in :pep:`282`. The documentation @@ -37,14 +37,14 @@ Other reasons why logging is better than ``print``: Logging in a Library -------------------- -Notes for `configuring logging for a library`_ are in the +Notes for `configuring logging for a library`_ are in the `logging tutorial`_. Because the *user*, not the library, should dictate what happens when a logging event occurs, one admonition bears repeating: .. note:: It is strongly advised that you do not add any handlers other than - NullHandler to your library’s loggers. + NullHandler to your library’s loggers. Best practice when instantiating loggers in a library is to only create them @@ -100,23 +100,23 @@ section of the `logging tutorial`_. [loggers] keys=root - + [handlers] keys=stream_handler - + [formatters] keys=formatter - + [logger_root] level=DEBUG handlers=stream_handler - + [handler_stream_handler] class=StreamHandler level=DEBUG formatter=formatter args=(sys.stderr,) - + [formatter_formatter] format=%(asctime)s %(name)-12s %(levelname)-8s %(message)s @@ -131,7 +131,7 @@ Then use :meth:`logging.config.fileConfig` in the code: fileConfig('logging_config.ini') logger = logging.getLogger() logger.debug('often makes a very good meal of %s', 'visiting tourists') - + Example Configuration via a Dictionary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst index 4e6a59c38..a74b64b9c 100644 --- a/docs/writing/reading.rst +++ b/docs/writing/reading.rst @@ -1,7 +1,7 @@ Reading Great Code ================== -.. image:: https://farm5.staticflickr.com/4221/34689452831_93d7fd0571_k_d.jpg +.. image:: /_static/photos/34689452831_93d7fd0571_k_d.jpg One of the core tenets behind the design of Python is creating readable code. The motivation behind this design is simple: The number diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index a2d531652..c59f4dd00 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -1,7 +1,7 @@ Structuring Your Project ======================== -.. image:: https://farm5.staticflickr.com/4203/33907151224_0574e7dfc2_k_d.jpg +.. image:: /_static/photos/33907151224_0574e7dfc2_k_d.jpg By "structure" we mean the decisions you make concerning how your project best meets its objective. We need to consider how to @@ -395,9 +395,9 @@ folder named :file:`my` which is not the case. There is an dot notation should be used in the Python docs. If you'd like you could name your module :file:`my_spam.py`, but even our -friend the underscore should not be seen often in module names. However, using other -characters (spaces or hyphens) in module names will prevent importing -(- is the subtract operator), so try to keep module names short so there is +friend the underscore should not be seen often in module names. However, using other +characters (spaces or hyphens) in module names will prevent importing +(- is the subtract operator), so try to keep module names short so there is no need to separate words. And, most of all, don't namespace with underscores, use submodules instead. .. code-block:: python @@ -799,7 +799,7 @@ its parts, it is much more efficient to accumulate the parts in a list, which is mutable, and then glue ('join') the parts together when the full string is needed. One thing to notice, however, is that list comprehensions are better and faster than constructing a list in a loop -with calls to ``append()``. +with calls to ``append()``. One other option is using the map function, which can 'map' a function ('str') to an iterable ('range(20)'). This results in a map object, @@ -833,14 +833,14 @@ The map function can be even faster than a list comprehension in some cases. # create a concatenated string from 0 to 19 (e.g. "012..1819") nums = [str(n) for n in range(20)] print "".join(nums) - + **Best** .. code-block:: python # create a concatenated string from 0 to 19 (e.g. "012..1819") nums = map(str, range(20)) - print "".join(nums) + print "".join(nums) One final thing to mention about strings is that using ``join()`` is not always best. In the instances where you are creating a new string from a pre-determined diff --git a/docs/writing/style.rst b/docs/writing/style.rst index abd0af49f..59781c6ee 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -3,7 +3,7 @@ Code Style ========== -.. image:: https://farm5.staticflickr.com/4223/33907150054_5ee79e8940_k_d.jpg +.. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg If you ask Python programmers what they like most about Python, they will often cite its high readability. Indeed, a high level of readability diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 32c6e552e..7da42e788 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -1,11 +1,11 @@ Testing Your Code ================= -.. image:: https://farm5.staticflickr.com/4166/34435687940_8f73fc1fa6_k_d.jpg +.. image:: /_static/photos/34435687940_8f73fc1fa6_k_d.jpg Testing your code is very important. -Getting used to writing testing code and running this code in parallel is now +Getting used to writing testing code and running this code in parallel is now considered a good habit. Used wisely, this method helps you define more precisely your code's intent and have a more decoupled architecture. @@ -29,7 +29,7 @@ Some general rules of testing: tests as often as needed. - Learn your tools and learn how to run a single test or a test case. Then, - when developing a function inside a module, run this function's tests + when developing a function inside a module, run this function's tests frequently, ideally automatically when you save the code. - Always run the full test suite before a coding session, and run it again @@ -65,10 +65,10 @@ Some general rules of testing: - Another use of the testing code is as an introduction to new developers. When someone will have to work on the code base, running and reading the related - testing code is often the best thing that they can do to start. They will - or should discover the hot spots, where most difficulties arise, and the - corner cases. If they have to add some functionality, the first step should - be to add a test to ensure that the new functionality is not already a + testing code is often the best thing that they can do to start. They will + or should discover the hot spots, where most difficulties arise, and the + corner cases. If they have to add some functionality, the first step should + be to add a test to ensure that the new functionality is not already a working path that has not been plugged into the interface. The Basics