Including external dependencies in your project

Sometimes, it is better to include external dependencies in your project. This ensures that whenever a developer upgrades third-party modules, all the other developers will receive the upgraded version in the next update from the version control system (Git, Subversion, or others).

Also, it is better to have external dependencies included in your project when the libraries are taken from unofficial sources, that is, somewhere other than Python Package Index (PyPI), or different version control systems.

Getting ready

Start with a virtual environment with a Django project in it.

How to do it…

Execute the following steps one by one:

1. If you haven't done this already, create an externals directory under your Django project django-myproject directory. Then, create the libs and apps directories under it.

   The libs directory is for the Python modules that are required by your project, for example, boto, Requests, Twython, Whoosh, and so on. The apps directory is for third-party Django apps, for example, django-cms, django-haystack, django-storages, and so on.

   Tip

   I highly recommend that you create the README.txt files in the libs and apps directories, where you mention what each module is for, what the used version or revision is, and where it is taken from.

2. The directory structure should look something similar to the following:
   
3. The next step is to put the external libraries and apps under the Python path so that they are recognized as if they were installed. This can be done by adding the following code in the settings:

   # settings.py
   # -*- coding: UTF-8 -*-
   from __future__ import unicode_literals
   import os
   import sys
   
   BASE_DIR = os.path.abspath(os.path.join(
       os.path.dirname(__file__), ".."
   ))
   
   EXTERNAL_LIBS_PATH = os.path.join(
       BASE_DIR, "externals", "libs"
   )
   EXTERNAL_APPS_PATH = os.path.join(
       BASE_DIR, "externals", "apps"
   )
   sys.path = ["", EXTERNAL_LIBS_PATH, EXTERNAL_APPS_PATH] + \
       sys.path

How it works…

A module is meant to be under the Python path if you can run Python and import that module. One of the ways to put a module under the Python path is to modify the sys.path variable before importing a module that is in an unusual location. The value of sys.path is a list of directories starting with an empty string for the current directory, followed by the directories in the virtual environment, and finally the globally shared directories of the Python installation. You can see the value of sys.path in the Python shell, as follows:

(myproject_env)$ python
>>> import sys
>>> sys.path

When trying to import a module, Python searches for the module in this list and returns the first result that is found.

Therefore, we first define the BASE_DIR variable, which is the absolute path to one level higher than the settings.py file. Then, we define the EXTERNAL_LIBS_PATH and EXTERNAL_APPS_PATH variables, which are relative to BASE_DIR. Lastly, we modify the sys.path property, adding new paths to the beginning of the list. Note that we also add an empty string as the first path to search, which means that the current directory of any module should always be checked first before checking other Python paths.

Tip

This way of including external libraries doesn't work cross-platform with the Python packages that have C language bindings, for example, lxml. For such dependencies, I would recommend using the pip requirements that were introduced in the Handling project dependencies with pip recipe.

See also

• The Creating a project file structure recipe
• The Handling project dependencies with pip recipe
• The Defining relative paths in the settings recipe
• The Using the Django shell recipe in Chapter 10, Bells and Whistles