Sometimes, you can't install an external dependency with pip and have to include it directly within your project, such as in the following cases:

• When you have a patched third-party app where you yourself fixed a bug or added a feature that did not get accepted by project owners
• When you need to use private apps that are not accessible at the Python Package Index (PyPI) or public version control repositories
• When you need to use legacy versions of dependencies that are not available at PyPI anymore

Including external dependencies in your project ensures that whenever a developer upgrades the dependent modules, all of the other developers will receive the upgraded version in the next update from the version control system.

You should start with a Django project under a virtual environment.

Execute the following steps one by one for a virtual environment project:

1. If you haven't done so already, create an externals directory under your Django project directory, django-myproject.
2. 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, and Whoosh. The apps directory is for third-party Django apps—for example, Django CMS, Django Haystack, and django-storages.
   We highly recommend that you create README.md 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.
3. The directory structure should look something similar to the following:

externals/
 ├── apps/
 │   ├── cms/
 │   ├── haystack/
 │   ├── storages/
 │   └── README.md
 └── libs/
     ├── boto/
     ├── requests/
     ├── twython/
     └── README.md

4. 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/_base.py
import os
import sys
BASE_DIR = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
)
EXTERNAL_BASE = os.path.join(BASE_DIR, "externals")
EXTERNAL_LIBS_PATH = os.path.join(EXTERNAL_BASE, "libs")
EXTERNAL_APPS_PATH = os.path.join(EXTERNAL_BASE, "apps")
sys.path = ["", EXTERNAL_LIBS_PATH, EXTERNAL_APPS_PATH] + sys.path

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, as specified by the settings file, is a list of directories starting with an empty string for the current directory, followed by the directories in the project, and finally the globally shared directories of the Python installation. You can see the value of sys.path in the Python shell, as follows:

(env)$ python manage.py shell
>>> 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 of django-myproject or three levels higher than myproject/settings/_base.py. 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.

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, we would recommend using the pip requirements that were introduced in the Handling project dependencies with pip recipe.

• The Creating a project file structure recipe
• The Working with Docker containers for Django, Gunicorn, Nginx, and PostgreSQL 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