| commit | author | age | ||
| b1b922 | 1 | ============================================ |
| PE | 2 | 02: Python Packages for Pyramid Applications |
| 3 | ============================================ | |
| 4 | ||
| 5 | Most modern Python development is done using Python packages, an approach | |
| 4e34c5 | 6 | Pyramid puts to good use. In this step we redo "Hello World" as a minimal |
| SP | 7 | Python package inside a minimal Python project. |
| 8 | ||
| b1b922 | 9 | |
| PE | 10 | Background |
| 11 | ========== | |
| 12 | ||
| 13 | Python developers can organize a collection of modules and files into a | |
| 4e34c5 | 14 | namespaced unit called a :ref:`package <python:tut-packages>`. If a directory |
| SP | 15 | is on ``sys.path`` and has a special file named ``__init__.py``, it is treated |
| 16 | as a Python package. | |
| b1b922 | 17 | |
| 7c29ea | 18 | Packages can be bundled up, made available for installation, and installed |
| SP | 19 | through a toolchain oriented around a ``setup.py`` file. For this tutorial, |
| 20 | this is all you need to know: | |
| b1b922 | 21 | |
| 7c29ea | 22 | - We will have a directory for each tutorial step as a *project*. |
| b1b922 | 23 | |
| 7c29ea | 24 | - This project will contain a ``setup.py`` which injects the features of the |
| SP | 25 | project machinery into the directory. |
| b1b922 | 26 | |
| PE | 27 | - In this project we will make a ``tutorial`` subdirectory into a Python |
| 7c29ea | 28 | *package* using an ``__init__.py`` Python module file. |
| b1b922 | 29 | |
| 7c29ea | 30 | - We will run ``pip install -e .`` to install our project in development mode. |
| b1b922 | 31 | |
| PE | 32 | In summary: |
| 33 | ||
| 7c29ea | 34 | - You'll do your development in a Python *package*. |
| b1b922 | 35 | |
| 7c29ea | 36 | - That package will be part of a *project*. |
| b1b922 | 37 | |
| 4e34c5 | 38 | |
| b1b922 | 39 | Objectives |
| PE | 40 | ========== |
| 41 | ||
| 7c29ea | 42 | - Make a Python "package" directory with an ``__init__.py``. |
| b1b922 | 43 | |
| 7c29ea | 44 | - Get a minimum Python "project" in place by making a ``setup.py``. |
| b1b922 | 45 | |
| 7c29ea | 46 | - Install our ``tutorial`` project in development mode. |
| 4e34c5 | 47 | |
| b1b922 | 48 | |
| PE | 49 | Steps |
| 50 | ===== | |
| 51 | ||
| 52 | #. Make an area for this tutorial step: | |
| 53 | ||
| 54 | .. code-block:: bash | |
| 55 | ||
| 187104 | 56 | $ cd ..; mkdir package; cd package |
| b1b922 | 57 | |
| PE | 58 | #. In ``package/setup.py``, enter the following: |
| 59 | ||
| 60 | .. literalinclude:: package/setup.py | |
| 61 | ||
| 4e34c5 | 62 | #. Make the new project installed for development then make a directory for the |
| SP | 63 | actual code: |
| b1b922 | 64 | |
| PE | 65 | .. code-block:: bash |
| 66 | ||
| 7c29ea | 67 | $ $VENV/bin/pip install -e . |
| 34e974 | 68 | $ mkdir tutorial |
| b1b922 | 69 | |
| PE | 70 | #. Enter the following into ``package/tutorial/__init__.py``: |
| 71 | ||
| 72 | .. literalinclude:: package/tutorial/__init__.py | |
| 73 | ||
| 74 | #. Enter the following into ``package/tutorial/app.py``: | |
| 75 | ||
| 76 | .. literalinclude:: package/tutorial/app.py | |
| 77 | ||
| 78 | #. Run the WSGI application with: | |
| 79 | ||
| 80 | .. code-block:: bash | |
| 81 | ||
| 187104 | 82 | $ $VENV/bin/python tutorial/app.py |
| b1b922 | 83 | |
| d749bf | 84 | #. Open http://localhost:6543/ in your browser. |
| b1b922 | 85 | |
| 4e34c5 | 86 | |
| b1b922 | 87 | Analysis |
| PE | 88 | ======== |
| 89 | ||
| 4e34c5 | 90 | Python packages give us an organized unit of project development. Python |
| SP | 91 | projects, via ``setup.py``, give us special features when our package is |
| 92 | installed (in this case, in local development mode, also called local editable | |
| 93 | mode as indicated by ``-e .``). | |
| b1b922 | 94 | |
| 4e34c5 | 95 | In this step we have a Python package called ``tutorial``. We use the same name |
| SP | 96 | in each step of the tutorial, to avoid unnecessary retyping. |
| b1b922 | 97 | |
| 4e34c5 | 98 | Above this ``tutorial`` directory we have the files that handle the packaging |
| SP | 99 | of this project. At the moment, all we need is a bare-bones ``setup.py``. |
| b1b922 | 100 | |
| 4e34c5 | 101 | Everything else is the same about our application. We simply made a Python |
| SP | 102 | package with a ``setup.py`` and installed it in development mode. |
| b1b922 | 103 | |
| PE | 104 | Note that the way we're running the app (``python tutorial/app.py``) is a bit |
| 105 | of an odd duck. We would never do this unless we were writing a tutorial that | |
| 4e34c5 | 106 | tries to capture how this stuff works one step at a time. It's generally a bad |
| b1b922 | 107 | idea to run a Python module inside a package directly as a script. |
| PE | 108 | |
| 186b72 | 109 | .. seealso:: :ref:`Python Packages <python:tut-packages>` and `Working in |
| 7c29ea | 110 | "Development Mode" |
| 7b1612 | 111 | <https://packaging.python.org/tutorials/distributing-packages/#working-in-development-mode>`_. |
