From b1b92284f496800a4dfd2cea72cb9be07ba8661c Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 16:52:14 -0400 Subject: First cut at import of quick tutorial. --- docs/quick_tutorial/package.rst | 112 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/quick_tutorial/package.rst (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst new file mode 100644 index 000000000..da6624cb1 --- /dev/null +++ b/docs/quick_tutorial/package.rst @@ -0,0 +1,112 @@ +============================================ +02: Python Packages for Pyramid Applications +============================================ + +Most modern Python development is done using Python packages, an approach +Pyramid puts to good use. In this step we re-do "Hello World" as a +minimum Python package inside a minimum Python project. + +Background +========== + +Python developers can organize a collection of modules and files into a +namespaced unit called a :ref:`package `. If a +directory is on ``sys.path`` and has a special file named +``__init__.py``, it is treated as a Python package. + +Packages can be bundled up, made available for installation, +and installed through a (muddled, but improving) toolchain oriented +around a ``setup.py`` file for a +`setuptools project `_. +Explaining it all in this +tutorial will induce madness. For this tutorial, this is all you need to +know: + +- We will have a directory for each tutorial step as a + setuptools *project* + +- This project will contain a ``setup.py`` which injects the features + of the setuptool's project machinery into the directory + +- In this project we will make a ``tutorial`` subdirectory into a Python + *package* using an ``__init__.py`` Python module file + +- We will run ``python setup.py develop`` to install our project in + development mode + +In summary: + +- You'll do your development in a Python *package* + +- That package will be part of a setuptools *project* + +Objectives +========== + +- Make a Python "package" directory with an ``__init__.py`` + +- Get a minimum Python "project" in place by making a ``setup.py`` + +- Install our ``tutorial`` project in development mode + +Steps +===== + +#. Make an area for this tutorial step: + + .. code-block:: bash + + (env27)$ cd ..; mkdir package; cd package + +#. In ``package/setup.py``, enter the following: + + .. literalinclude:: package/setup.py + +#. Make the new project installed for development then make a directory + for the actual code: + + .. code-block:: bash + + (env27)$ python setup.py develop + (env27)$ mkdir tutorial + +#. Enter the following into ``package/tutorial/__init__.py``: + + .. literalinclude:: package/tutorial/__init__.py + +#. Enter the following into ``package/tutorial/app.py``: + + .. literalinclude:: package/tutorial/app.py + +#. Run the WSGI application with: + + .. code-block:: bash + + (env27)$ python tutorial/app.py + +#. Open ``http://localhost:6543/`` in your browser. + +Analysis +======== + +Python packages give us an organized unit of project development. +Python projects, via ``setup.py``, gives us special features when +our package is installed (in this case, in local development mode.) + +In this step we have a Python package called ``tutorial``. We use the +same name in each step of the tutorial, to avoid unnecessary re-typing. + +Above this ``tutorial`` directory we have the files that handle the +packaging of this, well, package. At the moment, all we need is a +bare-bones ``ini/setup.py``. + +Everything else is the same about our application. We simply made a +Python package with a ``setup.py`` and installed it in development mode. + +Note that the way we're running the app (``python tutorial/app.py``) is a bit +of an odd duck. We would never do this unless we were writing a tutorial that +tries to capture how this stuff works a step at a time. It's generally a bad +idea to run a Python module inside a package directly as a script. + +.. seealso:: :ref:`Python Packages `, + `setuptools Entry Points `_ -- cgit v1.2.3 From 0a784868bdbc3a0eb226ed00e8d89cda9d181ec5 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:11:42 -0400 Subject: Fix naming of virtualenv prefix. --- docs/quick_tutorial/package.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst index da6624cb1..11760bda0 100644 --- a/docs/quick_tutorial/package.rst +++ b/docs/quick_tutorial/package.rst @@ -56,7 +56,7 @@ Steps .. code-block:: bash - (env27)$ cd ..; mkdir package; cd package + (env)$ cd ..; mkdir package; cd package #. In ``package/setup.py``, enter the following: @@ -67,8 +67,8 @@ Steps .. code-block:: bash - (env27)$ python setup.py develop - (env27)$ mkdir tutorial + (env)$ python setup.py develop + (env)$ mkdir tutorial #. Enter the following into ``package/tutorial/__init__.py``: @@ -82,7 +82,7 @@ Steps .. code-block:: bash - (env27)$ python tutorial/app.py + (env)$ python tutorial/app.py #. Open ``http://localhost:6543/`` in your browser. -- cgit v1.2.3 From b0b28ede912c817a62a84b97c332e39eda02d166 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:14:53 +0200 Subject: s/env/venv just for sake of consistency --- docs/quick_tutorial/package.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst index 11760bda0..6e0f9d317 100644 --- a/docs/quick_tutorial/package.rst +++ b/docs/quick_tutorial/package.rst @@ -56,7 +56,7 @@ Steps .. code-block:: bash - (env)$ cd ..; mkdir package; cd package + (venv)$ cd ..; mkdir package; cd package #. In ``package/setup.py``, enter the following: @@ -67,8 +67,8 @@ Steps .. code-block:: bash - (env)$ python setup.py develop - (env)$ mkdir tutorial + (venv)$ python setup.py develop + (venv)$ mkdir tutorial #. Enter the following into ``package/tutorial/__init__.py``: @@ -82,7 +82,7 @@ Steps .. code-block:: bash - (env)$ python tutorial/app.py + (venv)$ python tutorial/app.py #. Open ``http://localhost:6543/`` in your browser. -- cgit v1.2.3 From d749bf4c987c4ab90bd5f89326e7d4059e4f47b3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:18:11 +0200 Subject: make example links clickable, for convenience --- docs/quick_tutorial/package.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst index 6e0f9d317..08cd02fc5 100644 --- a/docs/quick_tutorial/package.rst +++ b/docs/quick_tutorial/package.rst @@ -84,7 +84,7 @@ Steps (venv)$ python tutorial/app.py -#. Open ``http://localhost:6543/`` in your browser. +#. Open http://localhost:6543/ in your browser. Analysis ======== -- cgit v1.2.3 From 187104fd81418beeb51592913041d9751bafe08d Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 09:27:43 -0400 Subject: Quick Tutorial: Improve the setup instructions (adapted from Steve Piercy's work), particularly for Windows. Change all the steps to use $VENV/bin prefixes on commands (don't presume that they have done source env/bin/activate). --- docs/quick_tutorial/package.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst index 08cd02fc5..99a83b790 100644 --- a/docs/quick_tutorial/package.rst +++ b/docs/quick_tutorial/package.rst @@ -56,7 +56,7 @@ Steps .. code-block:: bash - (venv)$ cd ..; mkdir package; cd package + $ cd ..; mkdir package; cd package #. In ``package/setup.py``, enter the following: @@ -67,8 +67,8 @@ Steps .. code-block:: bash - (venv)$ python setup.py develop - (venv)$ mkdir tutorial + $ $VENV/bin/python setup.py develop + $ $VENV/bin/mkdir tutorial #. Enter the following into ``package/tutorial/__init__.py``: @@ -82,7 +82,7 @@ Steps .. code-block:: bash - (venv)$ python tutorial/app.py + $ $VENV/bin/python tutorial/app.py #. Open http://localhost:6543/ in your browser. -- cgit v1.2.3 From 34e974e360184baef873da55f31379697e367f32 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 12:08:33 -0400 Subject: Get pyramid_chameleon added to the quick tutorial, plus some other fixes for Python 3. --- docs/quick_tutorial/package.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/package.rst') diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst index 99a83b790..90d022b29 100644 --- a/docs/quick_tutorial/package.rst +++ b/docs/quick_tutorial/package.rst @@ -68,7 +68,7 @@ Steps .. code-block:: bash $ $VENV/bin/python setup.py develop - $ $VENV/bin/mkdir tutorial + $ mkdir tutorial #. Enter the following into ``package/tutorial/__init__.py``: -- cgit v1.2.3