diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index b58deb515..13e9a93d7 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -3,6 +3,9 @@ Continuous Integration .. image:: https://farm5.staticflickr.com/4173/33907150594_9abba7ad0a_k_d.jpg +.. note:: + For advice on writing your tests, see :doc:`writing/tests`. + Why? ---- diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index 02fdd2c5f..de831b6e0 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -5,6 +5,9 @@ Installing Python 2 on Linux .. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg +.. note:: + Check out our :ref:`guide for installing Python 3 on Linux`. + The latest versions of CentOS, Red Hat Enterprise Linux (RHEL) and Ubuntu **come with Python 2.7 out of the box**. diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 57bb2058e..e930b4683 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -5,6 +5,9 @@ Installing Python 2 on Windows .. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg +.. note:: + Check out our :ref:`guide for installing Python 3 on Windows`. + First, download the `latest version `_ of Python 2.7 from the official website. If you want to be sure you are installing a fully up-to-date version, click the Downloads > Windows link from the home page of the @@ -50,24 +53,22 @@ makes it much easier for you to use other third-party Python libraries. Setuptools + Pip ---------------- -The most crucial third-party Python software of all is Setuptools, which -extends the packaging and installation facilities provided by the distutils in -the standard library. Once you add Setuptools to your Python system you can -download and install any compliant Python software product with a single -command. It also enables you to add this network installation capability to -your own Python software with very little work. +The two most crucial third-party Python packages are `setuptools `_ and `pip `_. + +Once installed, you can download, install and uninstall any compliant Python software +product with a single command. It also enables you to add this network installation +capability to your own Python software with very little work. -To obtain the latest version of Setuptools for Windows, run the Python script -available here: `ez_setup.py `_ +Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include +pip by default. +To see if pip is installed, open a command prompt and run + +.. code-block:: console -You'll now have a new command available to you: **easy_install**. It is -considered by many to be deprecated, so we will install its replacement: -**pip**. Pip allows for uninstallation of packages, and is actively maintained, -unlike easy_install. + $ command -v pip -To install pip, run the Python script available here: -`get-pip.py `_ +To install pip, `follow the official pip installation guide `_ - this will automatically install the latest version of setuptools. Virtual Environments diff --git a/docs/starting/install3/win.rst b/docs/starting/install3/win.rst index 39acfb592..74fe7d0a4 100644 --- a/docs/starting/install3/win.rst +++ b/docs/starting/install3/win.rst @@ -64,24 +64,14 @@ This will launch the Python 3 interpreter. Setuptools + Pip ---------------- -The most crucial third-party Python software of all is Setuptools, which -extends the packaging and installation facilities provided by the distutils in -the standard library. Once you add Setuptools to your Python system you can -download and install any compliant Python software product with a single -command. It also enables you to add this network installation capability to -your own Python software with very little work. +The two most crucial third-party Python packages are `setuptools `_ and `pip `_, +which let you download, install and uninstall any compliant Python software +product with a single command. It also enables you to add this network installation +capability to your own Python software with very little work. -To obtain the latest version of Setuptools for Windows, run the Python script -available here: `ez_setup.py `_ +All supported versions of Python 3 include pip, so just make sure it's up to date:: - -You'll now have a new command available to you: **easy_install**. It is -considered by many to be deprecated, so we will install its replacement: -**pip**. Pip allows for uninstallation of packages, and is actively maintained, -unlike easy_install. - -To install pip, run the Python script available here: -`get-pip.py `_ + python -m pip install -U pip Pipenv & Virtual Environments diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index a22e35922..bb84c2715 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -24,8 +24,8 @@ Installation Guides These guides go over the proper installation of :ref:`Python ` for development purposes, as well as setuptools, pip and virtualenv. - Python 3 Installation Guides - //////////////////////////// +Python 3 Installation Guides +//////////////////////////// - :ref:`Python 3 on MacOS `. - :ref:`Python 3 on Windows `. diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 1c1bbc191..155eadb0c 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -58,7 +58,9 @@ It is possible to `write code that works on Python 2.6, 2.7, and Python 3 `_. This ranges from trivial to hard depending upon the kind of software you are writing; if you're a beginner there are far more important things to -worry about. +worry about. Note that Python 2.6 is end-of-life upstream, so you shouldn't +try to write 2.6-compatible code unless you're being paid specifically to +do that. Implementations ~~~~~~~~~~~~~~~ diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index befe0277b..b0dc9cadf 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -174,6 +174,8 @@ Test Suite :::::::::: +*For advice on writing your tests, see :doc:`writing/tests`.* + .. csv-table:: :widths: 20, 40 diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index ea86ee8a9..542003b2a 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -190,21 +190,38 @@ the unittest module! `py.test `_ -Nose ----- - -nose extends unittest to make testing easier. +Hypothesis +---------- +Hypothesis is a library which lets you write tests that are parametrized by +a source of examples. It then generates simple and comprehensible examples +that make your tests fail, letting you find more bugs with less work. .. code-block:: console - $ pip install nose + $ pip install hypothesis + +For example, testing lists of floats will try many examples, but report the +minimal example of each bug (distinguished exception type and location): + +.. code-block:: python + + @given(lists(floats(allow_nan=False, allow_infinity=False), min_size=1)) + def test_mean(xs): + mean = sum(xs) / len(xs) + assert min(xs) <= mean(xs) <= max(xs) + +.. code-block:: + + Falsifying example: test_mean( + xs=[1.7976321109618856e+308, 6.102390043022755e+303] + ) -nose provides automatic test discovery to save you the hassle of manually -creating test suites. It also provides numerous plugins for features such as -xUnit-compatible test output, coverage reporting, and test selection. +Hypothesis is practical as well as very powerful, and will often find bugs +that escaped all other forms of testing. It integrates well with py.test, +and has a strong focus on usability in both simple and advanced scenarios. - `nose `_ + `hypothesis `_ tox