Skip to content

Commit

Permalink
some documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@extreme4all
extreme4all committed May 25, 2024
1 parent 10e2736 commit 030f6de
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 147 deletions.
68 changes: 12 additions & 56 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,50 +37,18 @@ clean-test: ## cleanup pytests leftovers
rm -f test-results.html
rm -f output.xml

docker-clean:
@read -p "Are you sure you want to prune all Docker data (y/n)? " -n 1 -r; \
echo; \
if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
docker system prune -a -f; \
fi

test: clean-test ## Run pytest unit tests
python3 -m pytest --verbosity=1 -s

test-report:
python3 -m pytest --junit-xml=pytest_report.xml

test-debug: ## Run unit tests with debugging enabled
python3 -m pytest --pdb

test-coverage: clean-test ## Run unit tests and check code coverage
PYTHONPATH=src python3 -m pytest --cov=src tests/ --disable-warnings

docker-up: ## Startup docker
docker-compose --verbose up

docker-build: ## Startup docker with build switch
docker-compose --verbose up --build

docker-build-detached: ## Startup docker with build switch
docker-compose up --build -d

docker-restart:
docker-restart: ## restart containers
docker compose down
docker compose up --build -d

docker-test: docker-restart
docker-test: docker-restart ## restart containers & test
pytest -s

setup: test-setup requirements## setup requirements

setup-detached: test-setup docker-build-detached ## setup & run after downloaded repo detached

pre-commit-setup: ## Install pre-commit
python3 -m pip install pre-commit
pre-commit --version

test-setup: pre-commit-setup## installs pytest singular package for local testing
test-setup: ## installs pytest singular package for local testing
python3 -m pip install pytest
python3 -m pip install requests
python3 -m pip install hypothesis
Expand All @@ -89,28 +57,16 @@ test-setup: pre-commit-setup## installs pytest singular package for local testin
requirements: ## installs all requirements
python3 -m pip install -r requirements.txt

docker-down: ## shutdown docker
docker-compose down
create-env: ## create .env file
echo "ENV=DEV" > .env
echo "DATABASE_URL=mysql+aiomysql://root:root_bot_buster@localhost/playerdata" >> .env
echo "KAFKA_HOST=localhost:9094" >> .env
echo "POOL_RECYCLE=60" >> .env
echo "POOL_TIMEOUT=30" >> .env

docker-rebuild: docker-down ## shuts down docker then brings it up and rebuilds
docker-compose --verbose up --build
setup: create-env pre-commit-setup test-setup requirements ## setup requirements

docker-force-rebuild: docker-down ## shuts down docker than brings it up and force rebuilds
docker-compose --verbose up --build --force-recreate

docs: # opens your browser to the webapps testing docs
docs: ## opens your browser to the webapps testing docs
open http://localhost:5000/docs
xdg-open http://localhost:5000/docs
. http://localhost:5000/docs

venv-create: ## creates a venv in the folder .venv
python3 -m venv .venv

venv-remove: ## removes the .venv folder
rm -rf .venv

test-loud: ## runs pytest with verbose output
python3 -m pytest --verbose -s

pre-commit:
pre-commit run --all-files
. http://localhost:5000/docs
111 changes: 20 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ pre-commit install
## Linux
Setup overview:
1. install requirements: python, pip, make, docker
2. create venv `make venv-create` or `python3 -m venv .venv`
2. create venv `python3 -m venv .venv`
3. activate venv `source .venv/bin/activate`
4. run setup `make setup`

Expand Down Expand Up @@ -75,7 +75,7 @@ alias make="gmake"
#### Setup
run the following command to create your venv
```sh
make venv-create
python3 -m venv .venv
```

#### Activate
Expand All @@ -97,22 +97,15 @@ use the `make` command with an `action` when developing on linux. think of `act
```sh
clean-pyc clean python cache files
clean-test cleanup pytests leftovers
test Run pytest unit tests
test-debug Run unit tests with debugging enabled
test-coverage Run unit tests and check code coverage
docker-up Startup docker
docker-build Startup docker with build switch
setup setup & run after downloaded repo
docker-restart restart containers
docker-test restart containers & test
pre-commit-setup Install pre-commit
pre-commit Run pre-commit
test-setup installs pytest singular package for local testing
requirements installs all requirements
docker-down shutdown docker
docker-rebuild shuts down docker then brings it up and rebuilds
docker-force-rebuild shuts down docker than brings it up and force rebuilds
api-setup installs fastapi singular package, for local testing
venv-create cleans the .venv then creates a venv in the folder .venv
venv-remove removes the .venv folder
create-env create .env file
setup setup requirements
docs opens your browser to the webapps testing docs

```

### Docker
Expand All @@ -123,93 +116,29 @@ venv-remove removes the .venv folder
- terminal opened to cloned repos root path


#### Setup Docker Enviornment
run `setup`
#### Setup Docker Environment
With the Makefile we setup our development environment. it is important that you are in your python virtual environment (.venv) when you run this command.
the `make setup` command will
- create a .env file,
- install precommit
- install requirements for testing
- install requirements for the project
```sh
make setup
```
You are now ready to develop code but you may want to read further, to know how to run & debug te code

once complete you will have to open a new terminal as the docker output will be running in the current one. you are looking for the message 'Application startup complete.' to know when the `setup` is done and containers are running.

more explinations of different `make` `actions` that can be run in the other sections below

#### Shutdown Docker Containers
run `docker-down`

```sh
make docker-down
```
the outcome should be like
```sh
docker-compose down
[+] Running 6/6
✔ Container kafdrop Removed 10.2s
✔ Container public_api Removed 0.4s
✔ Container kafka_setup Removed 0.0s
✔ Container database Removed 0.8s
✔ Container kafka Removed 0.9s
✔ Network public-api_botdetector-network Removed 0.0s
```

##### Startup Docker Containers
run `docker-up`. example below is using public-api
```sh
make docker-up
```
the outcome should be like
```sh
docker-compose --verbose up
[+] Building 0.0s (0/0)
[+] Running 7/5
✔ Network public-api_botdetector-Network
✔ Container database kafka_setup
✔ Container kafka
✔ Container kafka_setup
✔ Container kafdrop
...
...
public_api | INFO: Application startup complete.
...
```

##### Force Rebuild of Docker Containers
run `docker-force-rebuild`. usually done if requirements.txt are changed. or if containers are having weird issues and you want to start fresh.
#### Starting / restarting containers
with the Makefile we can easily start & shutdown the containers to a fresh state, under the hood we leverage `docker compose` commands.
```sh
make docker-force-rebuild
make docker-restart
```

### TDD using pytest
#### Verifying Tests Pass
run `test`
```sh
make test
```
the outcome should be like
```sh
python3 -m pytest --verbosity=1 --rootdir=./
=============== test session starts ===============
platform darwin -- Python 3.11.6, pytest-7.4.2, pluggy-1.3.0 -- /opt/homebrew/opt/[email protected]/bin/python3.11
cachedir: .pytest_cache
hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase(PosixPath('./bot-detector/public-api/.hypothesis/examples'))
rootdir: public-api
plugins: hypothesis-6.88.1, anyio-3.7.1
collected 13 items

tests/test_player_api.py::TestPlayerAPI::test_invalid_player_returns_empty PASSED [ 7%]
tests/test_player_api.py::TestPlayerAPI::test_invalid_player_returns_success PASSED [ 15%]
tests/test_player_api.py::TestPlayerAPI::test_valid_player_returns_data PASSED [ 23%]
tests/test_player_api.py::TestPlayerAPI::test_valid_player_returns_success PASSED [ 30%]
tests/test_prediction_api.py::TestPredictionAPI::test_invalid_max_player_name_length_returns_unkonwn PASSED [ 38%]
tests/test_prediction_api.py::TestPredictionAPI::test_invalid_min_player_name_length_returns_unknown PASSED [ 46%]
tests/test_prediction_api.py::TestPredictionAPI::test_invalid_player_breakdown_false_returns_player_not_found PASSED [ 53%]
tests/test_prediction_api.py::TestPredictionAPI::test_invalid_player_breakdown_true_returns_player_not_found PASSED [ 61%]
tests/test_prediction_api.py::TestPredictionAPI::test_invalid_player_breakdown_true_returns_unknown PASSED [ 69%]
tests/test_prediction_api.py::TestPredictionAPI::test_valid_player_breakdown_false_returns_empty_property PASSED [ 76%]
tests/test_prediction_api.py::TestPredictionAPI::test_valid_player_breakdown_false_returns_success PASSED [ 84%]
tests/test_prediction_api.py::TestPredictionAPI::test_valid_player_breakdown_true_returns_populated_property PASSED [ 92%]
tests/test_prediction_api.py::TestPredictionAPI::test_valid_player_breakdown_true_returns_success PASSED [100%]

=============== 13 passed in 1.54s ===============
make docker-test
```

# for admin purposes saving & upgrading
Expand Down

0 comments on commit 030f6de

Please sign in to comment.