4.0 KiB
CCE Search Prototype
An unofficial, experimental interface to search records digitized by NYPL's Catalog of Copyright Entries project.
Forked from Sean Redmond's original protype.
Required software
- Python 3.7
- Pipenv
Why Pipenv?
Using a virtual environment is very important for ensuring that all work is done in a standardized Python environment. In order to simplify using a virtual environment as well as to give us the ability to create deterministic builds, we use Pipenv.
Installing Pipenv
Mac
brew install pipenv
Note: Mac users can also install through Pip, but using Homebrew is recommended.
Other systems
pip install --user pipenv
Note: You may have versions of Pip installed for both Python 2 and 3. If so, your Python 3 Pip will be called pip3. Check if this is the case by running pip --version and pip3 --version.
Installing all dependencies and creating the virtual environment
Run pipenv install in the project's main directory. If installing for development purposes, rather than deployment, add the --dev flag to install required development packages as well.
Installing new packages
In the project directory, use pipenv install the same way you would use pip install. The package will be installed in the virtual environment, and the Pipfile will be updated.
For example, to install the package requests: pipenv install requests
To specify a specific package version: pipenv install flask==0.12.1
To install packages for development purposes (e.g. ones that aren't required to build and run the project, but are useful for working on it), you can use the --dev flag. For example, pipenv install pytest --dev.
Activating the virtual environment
To activate the virtual environment in your current shell, run pipenv shell. The virtual environment will be indicated by a change to your terminal prompt.
"Locking" the virtual environment
To ensure a deterministic build and "lock" the versions of packages and their subdependencies, run pipenv lock. This will ensure Pipfile.lock is up to date. Do this when you intend to push any changes to the production environment.
Remove an unneeded package
To remove a package from the Pipfile and uninstall it from your virtual environment, use pipenv uninstall.
For example, to remove beautifulsoup: pipenv uninstall beautifulsoup
Run a single command in the virtual environment without activating it
$ pipenv run [command_goes_here]
Closing the virtual environment
After you have activated the virtual environment, press ctrl-d to exit. Your terminal prompt should return to its original appearance.
Always do this when you're finished working in the virtual environment, otherwise your other Python work will screw up the project!
Deploying the project locally
After activating the virtual environment, run the following commands from within the root directory of the project:
$ export FLASK_ENV=development
(This is optional, but enables useful debugging tools)
$ flask run
The Flask app will then be running at localhost:5000.
To close the application, end the process with ctrl-c in your terminal.
Running Tests
In the root directory of the project, run python -m pytest. This will run the entire test suite. New test functions and files must be contained in the tests/ directory.
Troubleshooting
The 'pipenv==20XX.XX.XX' distribution was not found and is required by the application
Reinstall Pipenv, with the methods specified above.
Warning: Your Pipfile requires python_version 3.7, but you are using X.X.X (/Users/...).
$ pipenv check will surely fail.
This means your Python installation has changed since you first created the venv with pipenv install. Delete it using pipenv --rm, then rebuild it.