adsist-cms/python-detector-worker
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Chore: update md and make command

Browse source
This commit is contained in:
ziesorx 2025-09-12 21:44:09 +07:00
parent f617025e01
commit ea31261bff
3 changed files with 256 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

119
ARCHITECTURE.md
View file

@ -1133,25 +1133,126 @@ def test_yolo_detection_speed(self, sample_frame, performance_config):
## Development Workflow ## Development Workflow
### Cross-Platform Setup
The Makefile automatically detects the correct Python command for your platform:
- **macOS/Linux**: Uses `python3` and `pip3` if available
- **Windows**: Falls back to `python` and `pip`
- **Automatic Detection**: No manual configuration needed
### Step-by-Step Project Setup
#### 1. Clone and Navigate to Project
```bash
git clone <repository-url>
cd python-detector-worker
```
#### 2. Install Dependencies
```bash
# Install production dependencies
make install
# Install development dependencies (includes testing tools)
make install-dev
# Check environment information
make env-info
```
#### 3. Configure Environment (Optional)
```bash
# Copy example configuration (if exists)
cp config.example.json config.json
# Set environment variables for development
export DETECTOR_WORKER_ENV=dev
export DETECTOR_WORKER_PORT=8001
```
#### 4. Run the Application
```bash
# For development (staging port 8001 with auto-reload)
make run-staging
# For production (port 8000)
make run-prod
# For debugging (verbose logging on staging port)
make run-debug
```
#### 5. Verify Installation
```bash
# Check system health
curl http://localhost:8001/health
# Run basic tests
make test-fast
# Check code quality
make lint
```
### Development Commands ### Development Commands
#### Environment Management
```bash ```bash
# Setup make env-info # Show environment information
make install-dev # Install development dependencies make check-deps # Verify dependency integrity
make format # Format code with black & isort make update-deps # List outdated dependencies
make lint # Run code linting make freeze # Generate requirements-frozen.txt
```
# Testing #### Code Development
```bash
# Code quality
make format # Format code with black & isort
make lint # Run code linting (flake8, mypy)
make quality # Run all quality checks
# Application execution
make run # Run production mode (port 8000) with reload
make run-staging # Run staging mode (port 8001) with reload
make run-prod # Run production mode (port 8000) without reload
make run-debug # Run debug mode (port 8001) with verbose logging
```
#### Testing Framework
```bash
# Test execution
make test # Run all tests with coverage make test # Run all tests with coverage
make test-unit # Run unit tests only make test-unit # Run unit tests only
make test-integration # Run integration tests make test-integration # Run integration tests
make test-performance # Run performance benchmarks make test-performance # Run performance benchmarks
make test-fast # Run fast tests only make test-fast # Run fast tests only (skip slow markers)
make test-coverage # Generate detailed coverage report make test-coverage # Generate detailed coverage report
make test-failed # Rerun only failed tests
# Development # CI/CD testing
make run # Run the application make ci-test # Run CI-optimized tests
make clean # Clean build artifacts make ci-quality # Run CI quality checks
```
#### Docker Operations
```bash
# Container management
make docker-build # Build Docker image
make docker-run # Run container (production port 8000)
make docker-run-staging # Run container (staging port 8001)
make docker-dev # Run development container with volume mounts
```
#### Utilities
```bash
# Maintenance
make clean # Clean build artifacts and cache
make monitor # Start system resource monitor
make profile # Run performance profiling
make version # Show application version
# Database utilities (when implemented)
make db-migrate # Run database migrations
make db-reset # Reset database to initial state
``` ```
### Using the Test Runner ### Using the Test Runner

103
CLAUDE.md
View file

@ -375,39 +375,120 @@ make format
## Development & Deployment ## Development & Deployment
### Local Development Setup ### Cross-Platform Development Setup
The project supports cross-platform development with automatic Python command detection:
- **macOS/Linux**: Automatically uses `python3` and `pip3`
- **Windows**: Falls back to `python` and `pip`
- **No manual configuration needed**
### Step-by-Step Setup Guide
#### 1. Clone and Setup
```bash ```bash
# Install dependencies git clone <repository-url>
cd python-detector-worker
# Check environment information
make env-info
```
#### 2. Install Dependencies
```bash
# Install production dependencies
make install
# Install development dependencies (recommended)
make install-dev make install-dev
# Run the application # Verify installation
make check-deps
```
#### 3. Run the Application
```bash
# Development mode (staging port 8001 with auto-reload)
make run-staging
# Production mode (port 8000 with auto-reload)
make run make run
# Run with debug mode # Production mode (port 8000 without auto-reload)
make run-prod
# Debug mode (staging port 8001 with verbose logging)
make run-debug make run-debug
```
# Run tests #### 4. Verify Setup
make test ```bash
# Check application health
curl http://localhost:8001/health # For staging
curl http://localhost:8000/health # For production
# Format code # Run quick tests
make format make test-fast
# Run quality checks # Check code quality
make quality make lint
```
### Local Development Commands
#### Application Execution
```bash
make run # Production mode (port 8000) with reload
make run-staging # Staging mode (port 8001) with reload
make run-prod # Production mode (port 8000) without reload
make run-debug # Debug mode (staging port 8001) with verbose logging
```
#### Code Quality & Testing
```bash
# Code formatting and quality
make format # Format code with black & isort
make lint # Run linting (flake8, mypy)
make quality # Run all quality checks
# Testing
make test # Run all tests with coverage
make test-unit # Run unit tests only
make test-integration # Run integration tests
make test-performance # Run performance benchmarks
make test-fast # Run fast tests only
make test-coverage # Generate detailed coverage report
# Development utilities
make clean # Clean build artifacts
make env-info # Show environment details
make version # Show application version
``` ```
### Docker Deployment ### Docker Deployment
#### Basic Docker Operations
```bash ```bash
# Build container # Build container
make docker-build make docker-build
# Run container # Run container (production port 8000)
make docker-run make docker-run
# Run container (staging port 8001)
make docker-run-staging
# Development container with volume mounts # Development container with volume mounts
make docker-dev make docker-dev
``` ```
#### Docker Environment Variables
```bash
# Run with custom port
docker run -p 8001:8001 -e DETECTOR_WORKER_PORT=8001 detector-worker
# Run with configuration
docker run -v $(PWD)/config.json:/app/config.json detector-worker
```
### Configuration Management ### Configuration Management
- **Environment Variables**: Override default configuration - **Environment Variables**: Override default configuration
- **config.json**: Development and production settings - **config.json**: Development and production settings

81
Makefile
View file

@ -1,7 +1,15 @@
# Detector Worker Makefile # Detector Worker Makefile
# Provides convenient commands for development, testing, and deployment # Provides convenient commands for development, testing, and deployment
.PHONY: help install install-dev test test-unit test-integration test-performance test-all test-fast test-coverage lint format clean run docker-build docker-run # Cross-platform Python command detection
PYTHON := $(shell command -v python3 2> /dev/null || command -v python 2> /dev/null || echo "python")
PIP := $(shell command -v pip3 2> /dev/null || command -v pip 2> /dev/null || echo "pip")
# Environment configuration
PORT_PROD := 8000
PORT_STAGING := 8001
.PHONY: help install install-dev test test-unit test-integration test-performance test-all test-fast test-coverage lint format clean run run-staging run-prod docker-build docker-run
# Default target # Default target
help: help:
@ -25,7 +33,9 @@ help:
@echo " make quality Run all quality checks" @echo " make quality Run all quality checks"
@echo "" @echo ""
@echo "Development:" @echo "Development:"
@echo " make run Run the detector worker" @echo " make run Run the detector worker (production - port 8000)"
@echo " make run-staging Run the detector worker (staging - port 8001)"
@echo " make run-prod Run the detector worker (production - port 8000)"
@echo " make clean Clean build artifacts" @echo " make clean Clean build artifacts"
@echo "" @echo ""
@echo "Docker:" @echo "Docker:"
@ -34,32 +44,32 @@ help:
# Installation targets # Installation targets
install: install:
pip install -r requirements.txt $(PIP) install -r requirements.txt
install-dev: install install-dev: install
pip install -r requirements-dev.txt $(PIP) install -r requirements-dev.txt
# Testing targets # Testing targets
test: test:
python scripts/run_tests.py --all $(PYTHON) scripts/run_tests.py --all
test-unit: test-unit:
python scripts/run_tests.py --unit --verbose $(PYTHON) scripts/run_tests.py --unit --verbose
test-integration: test-integration:
python scripts/run_tests.py --integration --verbose $(PYTHON) scripts/run_tests.py --integration --verbose
test-performance: test-performance:
python scripts/run_tests.py --performance --verbose $(PYTHON) scripts/run_tests.py --performance --verbose
test-fast: test-fast:
python scripts/run_tests.py --fast --verbose $(PYTHON) scripts/run_tests.py --fast --verbose
test-coverage: test-coverage:
python scripts/run_tests.py --coverage --open-browser $(PYTHON) scripts/run_tests.py --coverage --open-browser
test-failed: test-failed:
python scripts/run_tests.py --failed --verbose $(PYTHON) scripts/run_tests.py --failed --verbose
# Code quality targets # Code quality targets
lint: lint:
@ -75,14 +85,24 @@ format:
isort detector_worker tests scripts isort detector_worker tests scripts
quality: lint quality: lint
python scripts/run_tests.py --quality $(PYTHON) scripts/run_tests.py --quality
# Development targets # Development targets
run: run:
python app.py @echo "Running Detector Worker on production port $(PORT_PROD)..."
$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_PROD) --reload
run-staging:
@echo "Running Detector Worker on staging port $(PORT_STAGING)..."
$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_STAGING) --reload
run-prod:
@echo "Running Detector Worker on production port $(PORT_PROD)..."
$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_PROD)
run-debug: run-debug:
python app.py --debug @echo "Running Detector Worker in debug mode on port $(PORT_STAGING)..."
$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_STAGING) --reload --log-level debug
clean: clean:
@echo "Cleaning build artifacts..." @echo "Cleaning build artifacts..."
@ -103,17 +123,20 @@ docker-build:
docker build -t detector-worker . docker build -t detector-worker .
docker-run: docker-run:
docker run -p 8000:8000 detector-worker docker run -p $(PORT_PROD):$(PORT_PROD) detector-worker
docker-run-staging:
docker run -p $(PORT_STAGING):$(PORT_STAGING) -e DETECTOR_WORKER_PORT=$(PORT_STAGING) detector-worker
docker-dev: docker-dev:
docker run -it -v $(PWD):/app -p 8000:8000 detector-worker bash docker run -it -v $(PWD):/app -p $(PORT_PROD):$(PORT_PROD) detector-worker bash
# CI/CD targets # CI/CD targets
ci-test: ci-test:
python scripts/run_tests.py --all --skip-slow $(PYTHON) scripts/run_tests.py --all --skip-slow
ci-quality: ci-quality:
python scripts/run_tests.py --quality $(PYTHON) scripts/run_tests.py --quality
# Documentation targets # Documentation targets
docs: docs:
@ -121,19 +144,19 @@ docs:
# Development utilities # Development utilities
check-deps: check-deps:
pip check $(PIP) check
update-deps: update-deps:
pip list --outdated $(PIP) list --outdated
freeze: freeze:
pip freeze > requirements-frozen.txt $(PIP) freeze > requirements-frozen.txt
# Performance profiling # Performance profiling
profile: profile:
python -m cProfile -o profile_output.prof app.py $(PYTHON) -m cProfile -o profile_output.prof app.py
@echo "Profile saved to profile_output.prof" @echo "Profile saved to profile_output.prof"
@echo "View with: python -m pstats profile_output.prof" @echo "View with: $(PYTHON) -m pstats profile_output.prof"
# Database utilities (if needed) # Database utilities (if needed)
db-migrate: db-migrate:
@ -145,16 +168,20 @@ db-reset:
# Monitor and debug # Monitor and debug
monitor: monitor:
@echo "Starting system monitor..." @echo "Starting system monitor..."
python -c "import psutil; import time; [print(f'CPU: {psutil.cpu_percent()}%, Memory: {psutil.virtual_memory().percent}%') or time.sleep(1) for _ in range(60)]" $(PYTHON) -c "import psutil; import time; [print(f'CPU: {psutil.cpu_percent()}%, Memory: {psutil.virtual_memory().percent}%') or time.sleep(1) for _ in range(60)]"
# Utility targets # Utility targets
version: version:
python -c "import detector_worker; print(f'Detector Worker Version: {getattr(detector_worker, \"__version__\", \"unknown\")}')" $(PYTHON) -c "import detector_worker; print(f'Detector Worker Version: {getattr(detector_worker, \"__version__\", \"unknown\")}')"
env-info: env-info:
@echo "Environment Information:" @echo "Environment Information:"
@echo "Python: $(shell python --version)" @echo "Python: $(shell $(PYTHON) --version)"
@echo "Pip: $(shell pip --version)" @echo "Pip: $(shell $(PIP) --version)"
@echo "Python Command: $(PYTHON)"
@echo "Pip Command: $(PIP)"
@echo "Working Directory: $(PWD)" @echo "Working Directory: $(PWD)"
@echo "Production Port: $(PORT_PROD)"
@echo "Staging Port: $(PORT_STAGING)"
@echo "Git Branch: $(shell git branch --show-current 2>/dev/null || echo 'Not a git repository')" @echo "Git Branch: $(shell git branch --show-current 2>/dev/null || echo 'Not a git repository')"
@echo "Git Commit: $(shell git rev-parse --short HEAD 2>/dev/null || echo 'Not a git repository')" @echo "Git Commit: $(shell git rev-parse --short HEAD 2>/dev/null || echo 'Not a git repository')"