From f21b2bf0465593f3831bc1d25ef14bed9f0c6fd5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 11 Apr 2016 01:44:05 -0700 Subject: - update narr/project.rst to use pip instead of setup.py - update starter scaffold tests and setup.py (used in `narr/project.rst` and `narr/testing.rst`) - update links to documentation --- docs/narr/MyProject/development.ini | 4 +- .../MyProject/myproject/templates/mytemplate.pt | 6 +- docs/narr/MyProject/myproject/tests.py | 2 +- docs/narr/MyProject/production.ini | 4 +- docs/narr/MyProject/setup.py | 21 ++- docs/narr/project.rst | 146 +++++++++------------ 6 files changed, 84 insertions(+), 99 deletions(-) (limited to 'docs') diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini index 749e574eb..94fece8ce 100644 --- a/docs/narr/MyProject/development.ini +++ b/docs/narr/MyProject/development.ini @@ -1,6 +1,6 @@ ### # app configuration -# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html ### [app:main] @@ -29,7 +29,7 @@ port = 6543 ### # logging configuration -# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html ### [loggers] diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt index 65d7f0609..543663fe8 100644 --- a/docs/narr/MyProject/myproject/templates/mytemplate.pt +++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt @@ -34,15 +34,15 @@

Pyramid Starter scaffold

-

Welcome to ${project}, an application generated by
the Pyramid Web Framework 1.6b2.

+

Welcome to ${project}, an application generated by
the Pyramid Web Framework 1.7.

    -
  • Generated by v1.6b2
    • -
  • Docs
    • +
  • Generated by v1.7
    • +
  • Docs
  • Github Project
  • IRC Channel
  • Pylons Project
    • diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py index 37df08a2a..99303b955 100644 --- a/docs/narr/MyProject/myproject/tests.py +++ b/docs/narr/MyProject/myproject/tests.py @@ -26,4 +26,4 @@ class FunctionalTests(unittest.TestCase): def test_root(self): res = self.testapp.get('/', status=200) - self.assertTrue('Pyramid' in res.body) + self.assertTrue(b'Pyramid' in res.body) \ No newline at end of file diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini index 3ccbe6619..1174b1cc7 100644 --- a/docs/narr/MyProject/production.ini +++ b/docs/narr/MyProject/production.ini @@ -1,6 +1,6 @@ ### # app configuration -# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/environment.html ### [app:main] @@ -23,7 +23,7 @@ port = 6543 ### # logging configuration -# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +# http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/narr/logging.html ### [loggers] diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py index 8c019af51..8d6e243d5 100644 --- a/docs/narr/MyProject/setup.py +++ b/docs/narr/MyProject/setup.py @@ -15,16 +15,22 @@ requires = [ 'waitress', ] +testing_extras = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] + setup(name='MyProject', version='0.0', description='MyProject', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Programming Language :: Python", - "Framework :: Pyramid", - "Topic :: Internet :: WWW/HTTP", - "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", - ], + "Programming Language :: Python", + "Framework :: Pyramid", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], author='', author_email='', url='', @@ -32,9 +38,10 @@ setup(name='MyProject', packages=find_packages(), include_package_data=True, zip_safe=False, + extras_require={ + 'testing': testing_extras, + }, install_requires=requires, - tests_require=requires, - test_suite="myproject", entry_points="""\ [paste.app_factory] main = myproject:main diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 923fde436..355a42d8a 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -90,24 +90,13 @@ Or on Windows: .. code-block:: text > %VENV%\Scripts\pcreate -s starter MyProject - -Here's sample output from a run of ``pcreate`` on UNIX for a project we name -``MyProject``: - -.. code-block:: bash - - $ $VENV/bin/pcreate -s starter MyProject - Creating template pyramid - Creating directory ./MyProject - # ... more output ... - Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info As a result of invoking the ``pcreate`` command, a directory named ``MyProject`` is created. That directory is a :term:`project` directory. The ``setup.py`` file in that directory can be used to distribute your application, or install your application for deployment or development. -A ``.ini`` file named ``development.ini`` will be created in the project +An ``.ini`` file named ``development.ini`` will be created in the project directory. You will use this ``.ini`` file to configure a server, to run your application, and to debug your application. It contains configuration that enables an interactive debugger and settings optimized for development. @@ -152,7 +141,8 @@ Installing your Newly Created Project for Development To install a newly created project for development, you should ``cd`` to the newly created project directory and use the Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` to invoke the -command ``python setup.py develop`` +command ``pip install -e .``, which installs the project in development mode +(``-e`` is for "editable") into the current directory (``.``). The file named ``setup.py`` will be in the root of the pcreate-generated project directory. The ``python`` you're invoking should be the one that lives @@ -165,23 +155,24 @@ On UNIX: .. code-block:: bash $ cd MyProject - $ $VENV/bin/python setup.py develop + $ $VENV/bin/pip install -e . Or on Windows: -.. code-block:: text +.. code-block:: ps1con > cd MyProject - > %VENV%\Scripts\python.exe setup.py develop + > %VENV%\Scripts\pip install -e . Elided output from a run of this command on UNIX is shown below: .. code-block:: bash $ cd MyProject - $ $VENV/bin/python setup.py develop + $ $VENV/bin/pip install -e . ... - Finished processing dependencies for MyProject==0.0 + Successfully installed Chameleon-2.24 Mako-1.0.4 MyProject \ + pyramid-chameleon-0.3 pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 This will install a :term:`distribution` representing your project into the virtual environment interpreter's library set so it can be found by ``import`` @@ -195,65 +186,54 @@ statements and by other console scripts such as ``pserve``, ``pshell``, Running the Tests for Your Application -------------------------------------- -To run unit tests for your application, you should invoke them using the Python -interpreter from the :term:`virtualenv` you created during -:ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` -directory of your virtualenv). +To run unit tests for your application, you must first install the testing +dependencies. On UNIX: .. code-block:: bash - $ $VENV/bin/python setup.py test -q + $ $VENV/bin/pip install -e ".[testing]" -Or on Windows: +On Windows: -.. code-block:: text +.. code-block:: ps1con + + > %VENV%\Scripts\pip install -e ".[testing]" + +Once the testing requirements are installed, then you can run the tests using +the ``py.test`` command that was just installed in the ``bin`` directory of +your virtual environment. + +On UNIX: + +.. code-block:: bash + + $ $VENV/bin/py.test myproject/tests.py -q + +On Windows: + +.. code-block:: ps1con - > %VENV%\Scripts\python.exe setup.py test -q + > %VENV%\Scripts\py.test myproject\tests.py -q Here's sample output from a test run on UNIX: .. code-block:: bash - $ $VENV/bin/python setup.py test -q - running test - running egg_info - writing requirements to MyProject.egg-info/requires.txt - writing MyProject.egg-info/PKG-INFO - writing top-level names to MyProject.egg-info/top_level.txt - writing dependency_links to MyProject.egg-info/dependency_links.txt - writing entry points to MyProject.egg-info/entry_points.txt - reading manifest file 'MyProject.egg-info/SOURCES.txt' - reading manifest template 'MANIFEST.in' - warning: no files found matching '*.cfg' - warning: no files found matching '*.rst' - warning: no files found matching '*.ico' under directory 'myproject' - warning: no files found matching '*.gif' under directory 'myproject' - warning: no files found matching '*.jpg' under directory 'myproject' - warning: no files found matching '*.txt' under directory 'myproject' - warning: no files found matching '*.mak' under directory 'myproject' - warning: no files found matching '*.mako' under directory 'myproject' - warning: no files found matching '*.js' under directory 'myproject' - warning: no files found matching '*.html' under directory 'myproject' - warning: no files found matching '*.xml' under directory 'myproject' - writing manifest file 'MyProject.egg-info/SOURCES.txt' - running build_ext - . - ---------------------------------------------------------------------- - Ran 1 test in 0.008s - - OK + $ $VENV/bin/py.test myproject/tests.py -q + .. + 2 passed in 0.47 seconds The tests themselves are found in the ``tests.py`` module in your ``pcreate`` -generated project. Within a project generated by the ``starter`` scaffold, a -single sample test exists. +generated project. Within a project generated by the ``starter`` scaffold, +only two sample tests exist. .. note:: - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). + The ``-q`` option is passed to the ``py.test`` command to limit the output + to a stream of dots. If you don't pass ``-q``, you'll see verbose test + result output (which normally isn't very useful). .. index:: single: running an application @@ -432,9 +412,8 @@ like this to enable the toolbar when your system contacts Pyramid: # .. other settings ... debugtoolbar.hosts = 192.168.1.1 -For more information about what the debug toolbar allows you to do, see `the -documentation for pyramid_debugtoolbar -`_. +For more information about what the debug toolbar allows you to do, see the +:ref:`documentation for pyramid_debugtoolbar `. The debug toolbar will not be shown (and all debugging will be turned off) when you use the ``production.ini`` file instead of the ``development.ini`` ini file @@ -688,16 +667,16 @@ control system, you may need to install a setuptools add-on such as ~~~~~~~~~~~~ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be -run directly from the command line to perform a variety of functions, such as -testing, packaging, and distributing your application. +used to define requirements for installing dependencies for your package and +testing, as well as distributing your application. .. note:: ``setup.py`` is the de facto standard which Python developers use to distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `Python Packaging - User Guide `_. + and their usage in the `Python Packaging User Guide + `_ and `Setuptools documentation + `_. Our generated ``setup.py`` looks like this: @@ -706,7 +685,7 @@ Our generated ``setup.py`` looks like this: :linenos: The ``setup.py`` file calls the setuptools ``setup`` function, which does -various things depending on the arguments passed to ``setup.py`` on the command +various things depending on the arguments passed to ``pip`` on the command line. Within the arguments to this function call, information about your application @@ -717,8 +696,8 @@ exists in this file in this section. Your application's name can be any string; it is specified in the ``name`` field. The version number is specified in the ``version`` value. A short description is provided in the ``description`` field. The ``long_description`` -is conventionally the content of the README and CHANGES file appended together. -The ``classifiers`` field is a list of `Trove +is conventionally the content of the ``README`` and ``CHANGES`` files appended +together. The ``classifiers`` field is a list of `Trove `_ classifiers describing your application. ``author`` and ``author_email`` are text fields which probably don't need any description. ``url`` is a field that should @@ -726,14 +705,13 @@ point at your application project's URL (if any). ``packages=find_packages()`` causes all packages within the project to be found when packaging the application. ``include_package_data`` will include non-Python files when the application is packaged if those files are checked into version control. -``zip_safe`` indicates that this package is not safe to use as a zipped egg; -instead it will always unpack as a directory, which is more convenient. -``install_requires`` and ``tests_require`` indicate that this package depends -on the ``pyramid`` package. ``test_suite`` points at the package for our -application, which means all tests found in the package will be run when -``setup.py test`` is invoked. We examined ``entry_points`` in our discussion -of the ``development.ini`` file; this file defines the ``main`` entry point -that represents our project's application. +``zip_safe=False`` indicates that this package is not safe to use as a zipped +egg; instead it will always unpack as a directory, which is more convenient. +``install_requires`` indicate that this package depends on the ``pyramid`` +package. ``extras_require`` is a Python dictionary that defines what is +required to be installed for running tests. We examined ``entry_points`` in our +discussion of the ``development.ini`` file; this file defines the ``main`` +entry point that represents our project's application. Usually you only need to think about the contents of the ``setup.py`` file when distributing your application to other people, when adding Python package @@ -745,7 +723,7 @@ you can try this command now: $ $VENV/bin/python setup.py sdist This will create a tarball of your application in a ``dist`` subdirectory named -``MyProject-0.1.tar.gz``. You can send this tarball to other people who want +``MyProject-0.0.tar.gz``. You can send this tarball to other people who want to install and use your application. .. index:: @@ -928,13 +906,13 @@ The ``tests.py`` module includes unit tests for your application. .. literalinclude:: MyProject/myproject/tests.py :language: python - :lines: 1-17 :linenos: -This sample ``tests.py`` file has a single unit test defined within it. This -test is executed when you run ``python setup.py test``. You may add more tests -here as you build your application. You are not required to write tests to use -:app:`Pyramid`. This file is simply provided for convenience and example. +This sample ``tests.py`` file has one unit test and one functional test defined +within it. These tests are executed when you run ``py.test myproject/tests.py +-q``. You may add more tests here as you build your application. You are not +required to write tests to use :app:`Pyramid`. This file is simply provided for +convenience and example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests. -- cgit v1.2.3