1  # Development Setup
  2  
  3  This guide will help you set up the Sussro Services project for local development.
  4  
  5  ## Prerequisites
  6  
  7  - Python 3.8+
  8  - PostgreSQL 12+
  9  - Redis (for caching and background tasks)
 10  - Git
 11  
 12  ## Installation
 13  
 14  1. **Clone the repository**
 15     ```bash
 16     git clone https://github.com/yourusername/sussro-services.git
 17     cd sussro-services
 18     ```
 19  
 20  2. **Create and activate a virtual environment**
 21     ```bash
 22     python -m venv venv
 23     source venv/bin/activate  # On Windows: venv\Scripts\activate
 24     ```
 25  
 26  3. **Install dependencies**
 27     ```bash
 28     pip install -r requirements/dev.txt
 29     ```
 30  
 31  4. **Set up environment variables**
 32     ```bash
 33     cp .env.example .env
 34     # Edit .env with your configuration
 35     ```
 36  
 37  5. **Set up the database**
 38     ```bash
 39     # Create a new PostgreSQL database
 40     createdb sussro_services
 41     
 42     # Run migrations
 43     alembic upgrade head
 44     ```
 45  
 46  ## Running the Development Server
 47  
 48  ```bash
 49  uvicorn sussro_services.main:app --reload
 50  ```
 51  
 52  The server will be available at `http://localhost:8000`
 53  
 54  ## Running Tests
 55  
 56  ```bash
 57  # Run all tests
 58  pytest
 59  
 60  # Run tests with coverage report
 61  pytest --cov=sussro_services tests/
 62  
 63  # Run a specific test file
 64  pytest tests/test_auth.py -v
 65  ```
 66  
 67  ## Code Style
 68  
 69  We use the following tools to maintain code quality:
 70  
 71  - **Black** for code formatting
 72  - **isort** for import sorting
 73  - **flake8** for linting
 74  - **mypy** for static type checking
 75  
 76  You can run all code quality checks with:
 77  
 78  ```bash
 79  pre-commit run --all-files
 80  ```
 81  
 82  ## Pre-commit Hooks
 83  
 84  Pre-commit hooks are configured to run code quality checks before each commit. To install them:
 85  
 86  ```bash
 87  pre-commit install
 88  ```
 89  
 90  ## Debugging
 91  
 92  For debugging, you can use the built-in Python debugger:
 93  
 94  ```python
 95  import ipdb; ipdb.set_trace()  # Add this line where you want to set a breakpoint
 96  ```
 97  
 98  ## IDE Setup
 99  
100  ### VS Code
101  
102  Recommended extensions:
103  - Python
104  - Pylance
105  - Black Formatter
106  - isort
107  - flake8
108  - mypy
109  
110  ### PyCharm
111  
112  Recommended settings:
113  - Set up Python interpreter to use the virtual environment
114  - Enable "Show line numbers" and "Show method separators"
115  - Configure Black as the default formatter
116  - Enable Pylance type checking
117  
118  ## Database Management
119  
120  ### Migrations
121  
122  To create a new migration:
123  
124  ```bash
125  alembic revision --autogenerate -m "description of changes"
126  ```
127  
128  To apply migrations:
129  
130  ```bash
131  alembic upgrade head
132  ```
133  
134  ### Database Console
135  
136  To access the database console:
137  
138  ```bash
139  psql sussro_services
140  ```
141  
142  ## Common Issues
143  
144  ### Database Connection Issues
145  
146  - Ensure PostgreSQL is running
147  - Verify database credentials in `.env`
148  - Check if the database exists and is accessible
149  
150  ### Dependency Issues
151  
152  If you encounter dependency conflicts:
153  
154  ```bash
155  pip install --upgrade -r requirements/dev.txt
156  ```
157  
158  ### Test Failures
159  
160  If tests are failing:
161  
162  1. Make sure the test database is properly set up
163  2. Check for any pending migrations
164  3. Run tests with `-v` flag for more verbose output