diff options
Diffstat (limited to 'docs')
32 files changed, 544 insertions, 369 deletions
diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst index eb9b6b395..cd038ea36 100644 --- a/docs/quick_tutorial/authentication.rst +++ b/docs/quick_tutorial/authentication.rst @@ -39,7 +39,7 @@ Steps .. literalinclude:: authentication/setup.py :language: python - :emphasize-lines: 4 + :emphasize-lines: 6 :linenos: #. We can now install our project in development mode: diff --git a/docs/quick_tutorial/authentication/setup.py b/docs/quick_tutorial/authentication/setup.py index 05104b158..64366a2df 100644 --- a/docs/quick_tutorial/authentication/setup.py +++ b/docs/quick_tutorial/authentication/setup.py @@ -1,23 +1,32 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'bcrypt', 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/authorization/setup.py b/docs/quick_tutorial/authorization/setup.py index 05104b158..64366a2df 100644 --- a/docs/quick_tutorial/authorization/setup.py +++ b/docs/quick_tutorial/authorization/setup.py @@ -1,23 +1,32 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'bcrypt', 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst index 5ba23e937..db75d70ce 100644 --- a/docs/quick_tutorial/databases.rst +++ b/docs/quick_tutorial/databases.rst @@ -51,7 +51,7 @@ Steps .. literalinclude:: databases/setup.py :linenos: - :emphasize-lines: 8-9, 11, 25-26 + :emphasize-lines: 9-10, 12, 34-36 .. note:: We aren't yet doing ``$VENV/bin/pip install -e .`` because we need to write a script and update configuration first. diff --git a/docs/quick_tutorial/databases/setup.py b/docs/quick_tutorial/databases/setup.py index 29dede2af..c4e4ae2f2 100644 --- a/docs/quick_tutorial/databases/setup.py +++ b/docs/quick_tutorial/databases/setup.py @@ -1,28 +1,38 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'pyramid_tm', 'sqlalchemy', 'waitress', 'zope.sqlalchemy', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - [console_scripts] - initialize_tutorial_db = tutorial.initialize_db:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + 'console_scripts': [ + 'initialize_tutorial_db = tutorial.initialize_db:main' + ], + }, +) diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst index a13d153d8..2607c83f2 100644 --- a/docs/quick_tutorial/debugtoolbar.rst +++ b/docs/quick_tutorial/debugtoolbar.rst @@ -38,18 +38,19 @@ Steps cd ..; cp -r ini debugtoolbar; cd debugtoolbar -#. Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py``: +#. Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra" for development: .. literalinclude:: debugtoolbar/setup.py :language: python :linenos: - :emphasize-lines: 5 + :emphasize-lines: 10-16, 20-22 #. Install our project and its newly added dependency. + Note that we use the extra specifier ``[dev]`` to install development requirements and surround it and the period with double quote marks. .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e ".[dev]" #. Our ``debugtoolbar/development.ini`` gets a configuration entry for ``pyramid.includes``: @@ -96,14 +97,20 @@ experience otherwise inexplicable client-side weirdness, you can shut it off by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` temporarily. +Finally we've introduced the concept of :term:`Setuptools` extras. +These are optional or recommended features that may be installed with an "extras" specifier, in this case, ``dev``. +The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line, for example, . +The value for the key is a Python list of dependencies. + .. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`. Extra credit ============ -#. We added ``pyramid_debugtoolbar`` to the list of ``install_requires`` dependencies in ``debugtoolbar/setup.py`` because this tutorial is for development and educational purposes only. - In what cases would you *not* want to add ``pyramid_debugtoolbar`` to your dependencies? +#. We added ``pyramid_debugtoolbar`` to the list of ``dev_requires`` dependencies in ``debugtoolbar/setup.py``. + We then installed the dependencies via ``pip install -e ".[dev]"`` by virtue of the Setuptools ``extras_require`` value in the Python dictionary. + Why did we add them there instead of in the ``requires`` list? #. Introduce a bug into your application. Change: diff --git a/docs/quick_tutorial/debugtoolbar/setup.py b/docs/quick_tutorial/debugtoolbar/setup.py index a947e20d8..53bc0f5c7 100644 --- a/docs/quick_tutorial/debugtoolbar/setup.py +++ b/docs/quick_tutorial/debugtoolbar/setup.py @@ -1,15 +1,28 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index 7d759b72d..3cd1e26aa 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -40,7 +40,7 @@ Steps #. Let's edit ``forms/setup.py`` to declare a dependency on Deform, which in turn pulls in Colander as a dependency: .. literalinclude:: forms/setup.py - :emphasize-lines: 4 + :emphasize-lines: 6 :linenos: #. We can now install our project in development mode: diff --git a/docs/quick_tutorial/forms/setup.py b/docs/quick_tutorial/forms/setup.py index e911d5bb8..0e9ea72bc 100644 --- a/docs/quick_tutorial/forms/setup.py +++ b/docs/quick_tutorial/forms/setup.py @@ -1,23 +1,32 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst index d3ada3793..054d03761 100644 --- a/docs/quick_tutorial/functional_testing.rst +++ b/docs/quick_tutorial/functional_testing.rst @@ -42,14 +42,14 @@ Steps .. literalinclude:: functional_testing/setup.py :language: python :linenos: - :emphasize-lines: 14 + :emphasize-lines: 16 #. Install our project and its newly added dependency. - Note that we use the extra specifier ``[test]`` to install testing requirements. + Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks. .. code-block:: bash - $VENV/bin/pip install -e .[test] + $VENV/bin/pip install -e ".[dev]" #. Let's extend ``functional_testing/tutorial/tests.py`` to include a functional test: diff --git a/docs/quick_tutorial/functional_testing/setup.py b/docs/quick_tutorial/functional_testing/setup.py index c0d3dee8f..a0fa8217c 100644 --- a/docs/quick_tutorial/functional_testing/setup.py +++ b/docs/quick_tutorial/functional_testing/setup.py @@ -1,21 +1,30 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 90f66009c..0bb7da1ba 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -32,49 +32,48 @@ Objectives Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the previous step: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r package ini; cd ini + cd ..; cp -r package ini; cd ini -#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function: +#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function: - .. literalinclude:: ini/setup.py - :linenos: + .. literalinclude:: ini/setup.py + :linenos: + :emphasize-lines: 13-17 -#. We can now install our project, thus generating (or re-generating) an "egg" - at ``ini/tutorial.egg-info``: +#. We can now install our project, thus generating (or re-generating) an "egg" at ``ini/tutorial.egg-info``: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e . -#. Let's make a file ``ini/development.ini`` for our configuration: +#. Let's make a file ``ini/development.ini`` for our configuration: - .. literalinclude:: ini/development.ini - :language: ini - :linenos: + .. literalinclude:: ini/development.ini + :language: ini + :linenos: -#. We can refactor our startup code from the previous step's ``app.py`` into - ``ini/tutorial/__init__.py``: +#. We can refactor our startup code from the previous step's ``app.py`` into ``ini/tutorial/__init__.py``: - .. literalinclude:: ini/tutorial/__init__.py - :linenos: + .. literalinclude:: ini/tutorial/__init__.py + :linenos: -#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: +#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: - .. code-block:: bash + .. code-block:: bash - rm tutorial/app.py + rm tutorial/app.py -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/. +#. Open http://localhost:6543/. Analysis ======== diff --git a/docs/quick_tutorial/ini/setup.py b/docs/quick_tutorial/ini/setup.py index 7a2677ebd..f1d06fe75 100644 --- a/docs/quick_tutorial/ini/setup.py +++ b/docs/quick_tutorial/ini/setup.py @@ -1,14 +1,18 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +setup( + name='tutorial', + install_requires=requires, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst index 23a9982d3..ed9acd955 100644 --- a/docs/quick_tutorial/jinja2.rst +++ b/docs/quick_tutorial/jinja2.rst @@ -33,7 +33,7 @@ Steps .. literalinclude:: jinja2/setup.py :language: python :linenos: - :emphasize-lines: 7 + :emphasize-lines: 8 #. Install our project and its newly added dependency. diff --git a/docs/quick_tutorial/jinja2/setup.py b/docs/quick_tutorial/jinja2/setup.py index 86f177866..ea2c59045 100644 --- a/docs/quick_tutorial/jinja2/setup.py +++ b/docs/quick_tutorial/jinja2/setup.py @@ -1,23 +1,32 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'pyramid_jinja2', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/json/setup.py b/docs/quick_tutorial/json/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/json/setup.py +++ b/docs/quick_tutorial/json/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/logging/setup.py b/docs/quick_tutorial/logging/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/logging/setup.py +++ b/docs/quick_tutorial/logging/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/more_view_classes/setup.py b/docs/quick_tutorial/more_view_classes/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/more_view_classes/setup.py +++ b/docs/quick_tutorial/more_view_classes/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/package/setup.py b/docs/quick_tutorial/package/setup.py index a59527bf4..910c552ad 100644 --- a/docs/quick_tutorial/package/setup.py +++ b/docs/quick_tutorial/package/setup.py @@ -1,10 +1,13 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - ) +setup( + name='tutorial', + install_requires=requires, +) diff --git a/docs/quick_tutorial/request_response/setup.py b/docs/quick_tutorial/request_response/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/request_response/setup.py +++ b/docs/quick_tutorial/request_response/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/retail_forms/setup.py b/docs/quick_tutorial/retail_forms/setup.py index 968889e74..dda0a2cc4 100644 --- a/docs/quick_tutorial/retail_forms/setup.py +++ b/docs/quick_tutorial/retail_forms/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', @@ -7,10 +9,12 @@ requires = [ 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +setup( + name='tutorial', + install_requires=requires, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/routing/setup.py b/docs/quick_tutorial/routing/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/routing/setup.py +++ b/docs/quick_tutorial/routing/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/sessions/setup.py b/docs/quick_tutorial/sessions/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/sessions/setup.py +++ b/docs/quick_tutorial/sessions/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/static_assets/setup.py b/docs/quick_tutorial/static_assets/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/static_assets/setup.py +++ b/docs/quick_tutorial/static_assets/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 4d4ccea4f..cef54fb6f 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -42,67 +42,64 @@ Objectives Steps ===== -#. Let's begin by using the previous package as a starting point for a new - project: +#. Let's begin by using the previous package as a starting point for a new project: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r views templating; cd templating + cd ..; cp -r views templating; cd templating -#. This step depends on ``pyramid_chameleon``, so add it as a dependency in - ``templating/setup.py``: +#. This step depends on ``pyramid_chameleon``, so add it as a dependency in ``templating/setup.py``: - .. literalinclude:: templating/setup.py - :linenos: + .. literalinclude:: templating/setup.py + :linenos: + :emphasize-lines: 7 -#. Now we can activate the development-mode distribution: +#. Now we can activate the development-mode distribution: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e . -#. We need to connect ``pyramid_chameleon`` as a renderer by making a call in - the setup of ``templating/tutorial/__init__.py``: +#. We need to connect ``pyramid_chameleon`` as a renderer by making a call in the setup of ``templating/tutorial/__init__.py``: - .. literalinclude:: templating/tutorial/__init__.py - :linenos: + .. literalinclude:: templating/tutorial/__init__.py + :linenos: -#. Our ``templating/tutorial/views.py`` no longer has HTML in it: +#. Our ``templating/tutorial/views.py`` no longer has HTML in it: - .. literalinclude:: templating/tutorial/views.py - :linenos: + .. literalinclude:: templating/tutorial/views.py + :linenos: -#. Instead we have ``templating/tutorial/home.pt`` as a template: +#. Instead we have ``templating/tutorial/home.pt`` as a template: - .. literalinclude:: templating/tutorial/home.pt - :language: html + .. literalinclude:: templating/tutorial/home.pt + :language: html -#. For convenience, change ``templating/development.ini`` to reload templates - automatically with ``pyramid.reload_templates``: +#. For convenience, change ``templating/development.ini`` to reload templates automatically with ``pyramid.reload_templates``: - .. literalinclude:: templating/development.ini - :language: ini + .. literalinclude:: templating/development.ini + :language: ini -#. Our unit tests in ``templating/tutorial/tests.py`` can focus on data: +#. Our unit tests in ``templating/tutorial/tests.py`` can focus on data: - .. literalinclude:: templating/tutorial/tests.py - :linenos: + .. literalinclude:: templating/tutorial/tests.py + :linenos: -#. Now run the tests: +#. Now run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pytest tutorial/tests.py -q - .... - 4 passed in 0.46 seconds + $VENV/bin/pytest tutorial/tests.py -q + .... + 4 passed in 0.46 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. +#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. Analysis diff --git a/docs/quick_tutorial/templating/setup.py b/docs/quick_tutorial/templating/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/templating/setup.py +++ b/docs/quick_tutorial/templating/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst index 7ef28bdb8..a16bce406 100644 --- a/docs/quick_tutorial/tutorial_approach.rst +++ b/docs/quick_tutorial/tutorial_approach.rst @@ -36,11 +36,13 @@ Each of the directories in our ``quick_tutorial`` workspace (e.g., ``request_res project* (except as noted for the ``hello_world`` step). The ``tutorial`` directory is a *Python package*. -For most steps you will copy the previous step's directory to a new directory, and change your working directory to the new directory, then install your project: +For most steps you will copy an earlier step's directory to a new directory, change your working directory to the new directory, then install your project: .. code-block:: bash cd ..; cp -r package ini; cd ini $VENV/bin/pip install -e . -For a few steps, you won't copy the previous step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``. +For a few steps, you won't copy an earlier step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``. + +Finally for a few steps, you might add a dependency to your project in its ``setup.py`` file, and then install both the dependency and the project with either ``$VENV/bin/pip install -e .`` or ``$VENV/bin/pip install -e ".[dev]"``. diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst index 2e58ee8d9..654925347 100644 --- a/docs/quick_tutorial/unit_testing.rst +++ b/docs/quick_tutorial/unit_testing.rst @@ -54,14 +54,14 @@ Steps .. literalinclude:: unit_testing/setup.py :language: python :linenos: - :emphasize-lines: 11-15 + :emphasize-lines: 15 #. Install our project and its newly added dependency. - Note that we use the extra specifier ``[test]`` to install testing requirements. + Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks. .. code-block:: bash - $VENV/bin/pip install -e .[test] + $VENV/bin/pip install -e ".[dev]" #. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``: @@ -102,11 +102,6 @@ Note that our use of ``pyramid.testing.setUp()`` and necessary when your test needs to make use of the ``config`` object (it's a Configurator) to add stuff to the configuration state before calling the view. -Finally we've introduced the concept of :term:`Setuptools` extras. -These are optional or recommended features that may be installed with an "extras" specifier. -The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line. -The value for the key is a Python list of dependencies. - Extra credit ============ diff --git a/docs/quick_tutorial/unit_testing/setup.py b/docs/quick_tutorial/unit_testing/setup.py index 617c806aa..a5f8a250b 100644 --- a/docs/quick_tutorial/unit_testing/setup.py +++ b/docs/quick_tutorial/unit_testing/setup.py @@ -1,20 +1,29 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst index 4b7b78140..1307857b7 100644 --- a/docs/quick_tutorial/view_classes.rst +++ b/docs/quick_tutorial/view_classes.rst @@ -37,41 +37,38 @@ Objectives Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the previous step: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r templating view_classes; cd view_classes - $VENV/bin/pip install -e . + cd ..; cp -r templating view_classes; cd view_classes + $VENV/bin/pip install -e . -#. Our ``view_classes/tutorial/views.py`` now has a view class with our two - views: +#. Our ``view_classes/tutorial/views.py`` now has a view class with our two views: - .. literalinclude:: view_classes/tutorial/views.py - :linenos: + .. literalinclude:: view_classes/tutorial/views.py + :linenos: -#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's - modify them to import the view class, and make an instance before getting a - response: +#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's modify them to import the view class, and make an instance before getting a response: - .. literalinclude:: view_classes/tutorial/tests.py - :linenos: + .. literalinclude:: view_classes/tutorial/tests.py + :linenos: -#. Now run the tests: +#. Now run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pytest tutorial/tests.py -q - .... - 4 passed in 0.34 seconds + $VENV/bin/pytest tutorial/tests.py -q + .... + 4 passed in 0.34 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. +#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. Analysis diff --git a/docs/quick_tutorial/view_classes/setup.py b/docs/quick_tutorial/view_classes/setup.py index 3ad7f004e..e9c068a23 100644 --- a/docs/quick_tutorial/view_classes/setup.py +++ b/docs/quick_tutorial/view_classes/setup.py @@ -1,22 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/views/setup.py b/docs/quick_tutorial/views/setup.py index c0d3dee8f..a0fa8217c 100644 --- a/docs/quick_tutorial/views/setup.py +++ b/docs/quick_tutorial/views/setup.py @@ -1,21 +1,30 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', - 'pyramid_debugtoolbar', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - extras_require={ - 'test': [ - 'pytest', - 'webtest', - ], - }, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, - ) +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) |