Related Projects

Satellite apps

We use the term "satellite apps" to refer to other CFPB-maintained Python source code repositories and packages that provide functionality or content for https://www.consumerfinance.gov but are not included in cfgov-refresh. Most but not all of these repositories can be run or tested without needing to set up the full website.

We have six satellite apps that are maintained outside of the cfgov-refresh codebase:

These satellite apps are imported into cfgov-refresh as part of the project requirements files.

Thinking about making a new satellite app?

Satellite apps were originally built to be imported into the consumerfinance.gov website before we started using Wagtail to manage site content. We now prefer to build projects as apps inside the cfgov-refresh repo. For more info, refer to the "Setting up new project code for consumerfinance.gov" page on the CFGOV/platform wiki on GHE.

Other Python packages

CFPB also develops and maintains several other Python source code repositories and packages that are used on https://www.consumerfinance.gov but are more general-purpose.

These include:

The cfpb/development repository contains the CFPB development guidelines used on these projects.

Developing Python packages with cfgov-refresh

Developers working on changes to satellite apps or other Python packages often want or need to test their work as part of the larger cfgov-refresh project.

The standard installation process for cfgov-refresh includes whatever versions of these packages are specified in project requirements files. Developers may want to temporarily or permanently replace those with a local copy of package source code.

Using a local virtual environment

When running in a virtual environment local to your developer machine, standard usage of pip install can be used to swap out package versions.

Running pip install -e path/to/local/repo will install local source code in "editable" mode, replacing the satellite app version installed from requirements files with your local copy:

# In a local virtual environment, after installing cfgov-refresh.
# Python packages have been installed from requirements files.
# This includes, for example, the retirement satellite app:
(cfgov-refresh) $ pip freeze | grep retirement
retirement==0.10.0

# Replace this version with an editable install pointing to your local copy.
(cfgov-refresh) $ pip install -e ../retirement/
...
Installing collected packages: retirement
  Found existing installation: retirement 0.10.0
    Uninstalling retirement-0.10.0:
      Successfully uninstalled retirement-0.10.0
  Running setup.py develop for retirement
Successfully installed retirement

# The Python environment is now using the local copy.
(cfgov-refresh) $ pip freeze | grep retirement
-e git+git@github.com:myfork/retirement.git@7d2b8eca86ed33d90b5cd7782e1f90b7ac89f6f9#egg=retirement

Installing a local copy of source code in editable mode ensures that any changes made to files there will take effect immediately.

To switch back to the default version of a Python package, removing the use of a local copy, you can manually install the version specified in the requirements files:

(cfgov-refresh) $ pip install retirement==0.10.0

Re-running the full virtual environment setup script will do the same thing.

Using Docker

Working on Python packages requires a different approach when running cfgov-refresh locally with its Docker setup. This is because while your local cfgov-refresh directory is exposed to the container, sibling directories or other locations where you might clone other repositories are not.

For this reason, the Docker setup provides the ability to use the local cfgov-refresh/develop-apps subdirectory as place to put local copies of Python packages.

Any packages put there (e.g. via a git clone of a satellite apps' repo) will be automatically added to the PYTHONPATH in the Python containers. Apps located within will be importable from Python running in the Docker containers, and will take precedence over any versions installed from requirements files as part of the Docker images.

To switch back to the default version of a Python package, removing the use of a local copy, simply delete the copy from the develop-apps directory.

For any satellite apps that provide front-end assets that need to be built, you will need to run that step seperately:

# Check out the retirement satellite app into develop-apps:
cd develop-apps
git clone git@github.com:cfpb/retirement.git

# Build the front-end:
cd retirement
./frontendbuild.sh

If the satellite app needs any Python requirements that are not specified in the cfgov-refresh requirements, they will need to be installed seperately by accessing the Python containers' shell and using pip:

Python 2.7:

docker-compose exec python2 bash
pip install [PACKAGE NAME]

Python 3.6:

docker-compose exec python3 bash
pip install [PACKAGE NAME]