cce-search-prototype/README.md

# CCE Search Prototype

An unofficial, experimental interface to search records digitized by NYPL's
[Catalog of Copyright Entries project](https://github.com/NYPL/catalog_of_copyright_entries_project).

Forked from Sean Redmond's [original protype](https://github.com/seanredmond/cce-search-prototype).

## 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](https://realpython.com/pipenv-guide/).

## 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 `flask run` within the root directory of the project:

The Flask app will then be running at [localhost:5000](localhost:5000).

Optionally, use `export FLASK_ENV=development` before running the app to enable useful debugging tools.

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.

To see test coverage data, run `python -m pytest --cov`. To generate an HTML coverage report, run `python -m pytest --cov-report html tests/ --cov=./`. Then, run `python -m http.server` and navigate to [localhost:8000](localhost:8000) to view it.

## Troubleshooting

    The 'pipenv==20XX.XX.XX' distribution was not found and is required by the application

Reinstall Pipenv, with the methods specified [above](#Installing-Pipenv).

    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](#Installing-all-dependencies-and-creating-the-virtual-environment).
Add README 2019-07-14 03:35:20 +00:00			`# CCE Search Prototype`

			`An unofficial, experimental interface to search records digitized by NYPL's`
			`[Catalog of Copyright Entries project](https://github.com/NYPL/catalog_of_copyright_entries_project).`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
			`Forked from Sean Redmond's [original protype](https://github.com/seanredmond/cce-search-prototype).`

Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			`## Required software`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			`- Python 3.7`
			`- Pipenv`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`### Why Pipenv?`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			`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](https://realpython.com/pipenv-guide/).`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## Installing Pipenv`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`### Mac`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			`brew install pipenv`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Add note RE differing pip versions 2019-11-12 22:35:05 +00:00			`Note: Mac users can also install through Pip, but using Homebrew is recommended.`
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`### Other systems`
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00
			`pip install --user pipenv`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Add note RE differing pip versions 2019-11-12 22:35:05 +00:00			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`.

Update documentation 2020-01-27 00:33:08 +00:00			`## Installing all dependencies and creating the virtual environment`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			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.
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## Installing new packages`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			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.
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			For example, to install the package requests: `pipenv install requests`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			To specify a specific package version: `pipenv install flask==0.12.1`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			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`.

Update documentation 2020-01-27 00:33:08 +00:00			`## Activating the virtual environment`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			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.
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## "Locking" the virtual environment`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			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.
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## Remove an unneeded package`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			To remove a package from the Pipfile and uninstall it from your virtual environment, use `pipenv uninstall`.
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00			For example, to remove beautifulsoup: `pipenv uninstall beautifulsoup`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## Run a single command in the virtual environment without activating it`
Updated README to add venv instructions 2019-10-25 21:08:09 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`$ pipenv run [command_goes_here]`
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			`## Closing the virtual environment`
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00
			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!`
Added instructions to run gunicorn server 2019-10-26 18:33:13 +00:00
			`## Deploying the project locally`

Added API tests, changed conftest, updated docs 2020-02-26 01:20:27 +00:00			After activating the virtual environment, run `flask run` within the root directory of the project:
Update documentation 2020-01-27 00:33:08 +00:00
			`The Flask app will then be running at [localhost:5000](localhost:5000).`
Added instructions to run gunicorn server 2019-10-26 18:33:13 +00:00
Added API tests, changed conftest, updated docs 2020-02-26 01:20:27 +00:00			Optionally, use `export FLASK_ENV=development` before running the app to enable useful debugging tools.

Added instructions to run gunicorn server 2019-10-26 18:33:13 +00:00			To close the application, end the process with `ctrl-c` in your terminal.

Update documentation 2020-01-27 00:33:08 +00:00			`## Running Tests`

Added API tests, changed conftest, updated docs 2020-02-26 01:20:27 +00:00			`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.

			To see test coverage data, run `python -m pytest --cov`. To generate an HTML coverage report, run `python -m pytest --cov-report html tests/ --cov=./`. Then, run `python -m http.server` and navigate to [localhost:8000](localhost:8000) to view it.
Update documentation 2020-01-27 00:33:08 +00:00
			`## Troubleshooting`

			`The 'pipenv==20XX.XX.XX' distribution was not found and is required by the application`

			`Reinstall Pipenv, with the methods specified [above](#Installing-Pipenv).`

			`Warning: Your Pipfile requires python_version 3.7, but you are using X.X.X (/Users/...).`
			`$ pipenv check will surely fail.`
Updated documentation to reflect Pipenv 2019-11-06 04:58:02 +00:00
Update documentation 2020-01-27 00:33:08 +00:00			This means your Python installation has changed since you first created the venv with `pipenv install`. Delete it using `pipenv --rm`, then [rebuild it](#Installing-all-dependencies-and-creating-the-virtual-environment).