From a624d56914ed9e10e3c0e8bb34a84700e78bcaf6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 10 Apr 2016 03:35:48 -0700 Subject: - update commandline.rst to use pip --- docs/narr/commandline.rst | 90 ++++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 34b12e1e9..bc04f4c7a 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -119,7 +119,7 @@ The Interactive Shell .. seealso:: See also the output of :ref:`pshell --help `. -Once you've installed your program for development using ``setup.py develop``, +Once you've installed your program for development using ``pip install -e .``, you can use an interactive Python shell to execute expressions in a Python environment exactly like the one that will be used when your application runs "for real". To do so, use the ``pshell`` command line utility. @@ -294,7 +294,7 @@ You may use the ``--list-shells`` option to see the available shells. python If you want to use a shell that isn't supported out of the box, you can -introduce a new shell by registering an entry point in your setup.py: +introduce a new shell by registering an entry point in your ``setup.py``: .. code-block:: python @@ -840,12 +840,11 @@ following: distribution which creates a mapping between a script name and a dotted name representing the callable you added to your distribution. -- Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get - your distribution reinstalled. When you reinstall your distribution, a file - representing the script that you named in the last step will be in the - ``bin`` directory of the virtualenv in which you installed the distribution. - It will be executable. Invoking it from a terminal will execute your - callable. +- Run ``pip install -e .`` or ``pip install .`` to get your distribution + reinstalled. When you reinstall your distribution, a file representing the + script that you named in the last step will be in the ``bin`` directory of + the virtualenv in which you installed the distribution. It will be + executable. Invoking it from a terminal will execute your callable. As an example, let's create some code that can be invoked by a console script that prints the deployment settings of a Pyramid application. To do so, we'll @@ -927,16 +926,22 @@ top-level directory, your ``setup.py`` file will look something like this: requires = ['pyramid', 'pyramid_debugtoolbar'] + testing_extras = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] + setup(name='MyProject', version='0.0', description='My project', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Programming Language :: Python", - "Framework :: Pylons", - "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='', @@ -945,20 +950,23 @@ top-level directory, your ``setup.py`` file will look something like this: include_package_data=True, zip_safe=False, install_requires=requires, - tests_require=requires, - test_suite="myproject", + extras_require={ + 'testing': testing_extras, + }, entry_points = """\ [paste.app_factory] main = myproject:main """, ) -We're going to change the setup.py file to add a ``[console_scripts]`` section -within the ``entry_points`` string. Within this section, you should specify a -``scriptname = dotted.path.to:yourfunction`` line. For example:: +We're going to change the ``setup.py`` file to add a ``[console_scripts]`` +section within the ``entry_points`` string. Within this section, you should +specify a ``scriptname = dotted.path.to:yourfunction`` line. For example: + +.. code-block:: ini - [console_scripts] - show_settings = myproject.scripts:settings_show + [console_scripts] + show_settings = myproject.scripts:settings_show The ``show_settings`` name will be the name of the script that is installed into ``bin``. The colon (``:``) between ``myproject.scripts`` and @@ -971,6 +979,7 @@ The result will be something like: .. code-block:: python :linenos: + :emphasize-lines: 43-44 import os @@ -984,16 +993,22 @@ The result will be something like: requires = ['pyramid', 'pyramid_debugtoolbar'] + testing_extras = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] + setup(name='MyProject', version='0.0', description='My project', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Programming Language :: Python", - "Framework :: Pylons", - "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='', @@ -1002,8 +1017,9 @@ The result will be something like: include_package_data=True, zip_safe=False, install_requires=requires, - tests_require=requires, - test_suite="myproject", + extras_require={ + 'testing': testing_extras, + }, entry_points = """\ [paste.app_factory] main = myproject:main @@ -1012,15 +1028,17 @@ The result will be something like: """, ) -Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will -install a file named ``show_settings`` into the ``$somevirtualenv/bin`` -directory with a small bit of Python code that points to your entry point. It -will be executable. Running it without any arguments will print an error and -exit. Running it with a single argument that is the path of a config file will -print the settings. Running it with an ``--omit=foo`` argument will omit the -settings that have keys that start with ``foo``. Running it with two "omit" -options (e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys -that start with either ``foo`` or ``bar``:: +Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a +file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a +small bit of Python code that points to your entry point. It will be +executable. Running it without any arguments will print an error and exit. +Running it with a single argument that is the path of a config file will print +the settings. Running it with an ``--omit=foo`` argument will omit the settings +that have keys that start with ``foo``. Running it with two "omit" options +(e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys that +start with either ``foo`` or ``bar``: + +.. code-block:: bash $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar debug_routematch False -- cgit v1.2.3