1"""
  2# Cave Utilities for the Cave App
  3[![PyPI version](https://badge.fury.io/py/cave_utils.svg)](https://badge.fury.io/py/cave_utils)
  4[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5Basic utilities for the MIT Cave App.
  6This package is intended to be used by the Cave App and the Cave API.
  7
  8## Overview
  9
 10This package is part of the larger [Cave App](https://github.com/MIT-CAVE/cave_app) framework. It provides utilities that are commonly used across different Cave applications, such as validation and logging. It is designed to be an easy to integrate library that can be used in any Cave application. It also serves to provide automated documentation and testing.
 11
 12You can find the low level documentation for this package [here](https://mit-cave.github.io/cave_utils/index.html).
 13
 14
 15
 16## Setup
 17
 18Make sure you have Python 3.11.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
 19
 20### Installation
 21
 22```
 23pip install cave_utils
 24```
 25
 26# cave_utils development
 27
 28## Running Tests, Prettifying Code, and Updating Docs
 29
 30Make sure Docker is installed and running.
 31
 32- Create a docker container and drop into a shell
 33    - `./run.sh`
 34- Run all tests (see ./utils/test.sh)
 35    - `./run.sh test`
 36- Prettify the code (see ./utils/prettify.sh)
 37    - `./run.sh prettify`
 38- Update the docs (see ./utils/docs.sh)
 39    - `./run.sh docs`
 40
 41- Note: You can and should modify the `Dockerfile` to test different python versions.
 42
 43### Using Local Hotloading With a Cave App
 44
 451. In your `cave_app`, update the following file:
 46
 47    `utils/run_server.sh`
 48    ```
 49    #!/bin/bash
 50
 51    SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 52    APP_DIR=$(dirname "$SCRIPT_DIR")
 53
 54    pip install -e /cave_utils
 55
 56    source ./utils/helpers/shell_functions.sh
 57    source ./utils/helpers/ensure_postgres_running.sh
 58    # Check if the app is functional before proceeding
 59    if [ "$(python ./manage.py check --deployment_type development | grep "System check identified no issues" | wc -l)" -eq "0" ]; then
 60    printf "Unable to start the app due to an error in the code. See the stacktrace above." 2>&1 | pipe_log "ERROR"
 61    rm -r "./tmp"
 62    exit 1
 63    fi
 64    source ./utils/helpers/ensure_db_setup.sh
 65
 66    python "$APP_DIR/manage.py" runserver 0.0.0.0:8000 2>&1 | pipe_log "INFO"
 67    ```
 68
 692. Remove `cave_utils` from the root `requirements.txt` file
 70
 713. In your `cave_app`, set `LIVE_API_VALIDATION_PRINT=True` in the `.env` file
 72    - This will validate your data every time an API command is called for each session
 73
 744. Use the following command to run your `cave_app`:
 75    `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils"`
 76    - As you edit `cave_utils`, any changes will be hotloaded into your running `cave_app`
 77
 78### Using interactive mode in your Cave App and running tests
 79
 80- Note: This is for very specific use cases, such as running tests or debugging in an interactive shell.
 81- Note: In general, we copy all included examples from the cave_app to the `cave_utils/test/api_examples` directory, so you can run tests against them without needing to run the cave_app.
 82    - These copied examples can be tested by running `./run.sh test` in the cave_utils directory, which will run all tests in the `cave_utils/test`.
 83        - This includes `test_validator.py` which runs all examples in the `cave_utils/test/api_examples` directory
 84
 85
 861. Run cave_app in interactive mode mounting cave_utils as a volume:
 87    `cave run --docker-args "--volume {local_path_to_cave_utils}/cave_utils:/cave_utils" -it`
 882. Then install cave utils in the docker container:
 89    `pip install -e /cave_utils`
 903. Then run some tests (eg `validate_all_examples.py`):
 91    `python cave_api/tests/validate_all_examples.py`
 92
 93
 94# Generate a New Release
 95
 961. Make sure all tests are passing and the code is prettified.
 972. Make sure the documentation is up to date.
 983. Make sure the version number is updated in `setup.cfg` and `pyproject.toml`.
 994. Set up your virtual environment
100    - `python3 -m virtualenv venv`
101    - `source venv/bin/activate`
102    - `pip install -r requirements.txt`
1035. Update the release
104    - `source venv/bin/activate`
105    - `./publish.sh`"""
106from .log import LogObject, LogHelper
107from .socket import Socket
108from .api_utils.validator import Validator
109from .arguments import Arguments
110from .geo_utils import GeoUtils