# python-demo

**Repository Path**: dian/python-demo

## Basic Information

- **Project Name**: python-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI Demo

A modern FastAPI application with MySQL and Redis support, following best practices for scalable API development.

## Features

- **FastAPI** with async/await support
- **SQLAlchemy 2.0** with async MySQL support
- **Redis** for caching and session management
- **JWT Authentication** with secure password hashing
- **Alembic** for database migrations
- **Pydantic v2** for data validation
- **CORS** middleware
- **Logging** middleware
- **Health check** endpoints
- **Modern Python** (3.11+) with type hints
- **uv** for fast dependency management

## Project Structure

```
app/
├── api/                    # API routes
│   ├── dependencies.py    # Shared dependencies
│   └── v1/                # API version 1
│       ├── auth.py        # Authentication endpoints
│       ├── users.py       # User management endpoints
│       ├── health.py      # Health check endpoints
│       └── router.py      # Route aggregation
├── core/                  # Core functionality
│   ├── config.py         # Configuration management
│   ├── database.py       # Database setup
│   ├── redis.py          # Redis client
│   └── security.py       # Security utilities
├── middleware/            # Custom middleware
│   ├── cors.py           # CORS configuration
│   └── logging.py        # Request logging
├── models/               # SQLAlchemy models
│   └── user.py          # User model
├── schemas/              # Pydantic schemas
│   ├── auth.py          # Authentication schemas
│   └── user.py          # User schemas
├── services/             # Business logic
│   └── user_service.py  # User service layer
└── main.py              # Application entry point
```

## Setup

### Prerequisites

- Python 3.11+
- MySQL 8.0+
- Redis 6.0+
- uv (recommended) or pip

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd fastapi-demo
```

2. Install dependencies using uv:
```bash
uv sync
```

Or using pip:
```bash
pip install -e .
```

3. Copy environment variables:
```bash
cp .env.example .env
```

4. Update the `.env` file with your database and Redis configurations:
```env
DATABASE_URL=mysql+aiomysql://username:password@localhost:3306/fastapi_demo
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here
```

### Database Setup

1. Create the database:
```sql
CREATE DATABASE fastapi_demo;
```

2. Run database migrations:
```bash
alembic upgrade head
```

3. Create a superuser:
```bash
python scripts/create_superuser.py
```

## Running the Application

### Development

```bash
python scripts/start.py
```

Or using uvicorn directly:
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### Production

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

## API Documentation

Once the application is running, you can access:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## API Endpoints

### Health Check
- `GET /api/v1/health/` - Basic health check
- `GET /api/v1/health/detailed` - Detailed health check with database and Redis status

### Authentication
- `POST /api/v1/auth/login` - User login

### Users
- `POST /api/v1/users/` - Create user (admin only)
- `GET /api/v1/users/` - List users (admin only)
- `GET /api/v1/users/me` - Get current user info
- `GET /api/v1/users/{user_id}` - Get user by ID (admin only)
- `PUT /api/v1/users/me` - Update current user
- `PUT /api/v1/users/{user_id}` - Update user by ID (admin only)
- `DELETE /api/v1/users/{user_id}` - Delete user (admin only)

## Development

### Code Quality

The project includes configuration for:

- **Black** - Code formatting
- **isort** - Import sorting
- **flake8** - Linting
- **mypy** - Type checking

Run code quality checks:
```bash
black app/
isort app/
flake8 app/
mypy app/
```

### Database Migrations

Create a new migration:
```bash
alembic revision --autogenerate -m "Description of changes"
```

Apply migrations:
```bash
alembic upgrade head
```

Rollback migrations:
```bash
alembic downgrade -1
```

### Testing

Install development dependencies:
```bash
uv sync --group dev
```

Run tests:
```bash
pytest
```

With coverage:
```bash
pytest --cov=app
```

## Docker Support

Create a `Dockerfile`:
```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml .
RUN pip install uv && uv sync --no-dev

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `APP_NAME` | Application name | FastAPI Demo |
| `DEBUG` | Debug mode | False |
| `SECRET_KEY` | Application secret key | Required |
| `DATABASE_URL` | Database connection URL | Required |
| `REDIS_URL` | Redis connection URL | Required |
| `JWT_SECRET_KEY` | JWT signing key | Required |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Token expiration time | 30 |

## License

MIT License