Skip to content

Local Development Setup

Get FenLiu running locally for development and testing.

Prerequisites

  • Python 3.11+
  • Git
  • uv package manager (recommended) or pip

Clone Repository

git clone https://codeberg.org/marvinsmastodontools/fenliu.git
cd fenliu

Install Dependencies

# Create virtual environment and install
uv sync -U --all-groups

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Using pip

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Initialize Database

# Alembic runs automatically on startup, but you can also run manually
alembic upgrade head

Run Development Server

# With auto-reload and debug logging
fenliu --reload --debug

# Alternative using uv
uv run python -m fenliu --reload --debug

Visit http://localhost:8000 in your browser.

Pre-Commit Hooks

Set up pre-commit to run checks automatically:

# Install pre-commit hooks
pre-commit install

# Or manually run checks
prek run --all-files

Code Quality Tools

Linting and Formatting

# Check code with ruff
ruff check src/fenliu/

# Format code
ruff format src/fenliu/

# Both checks
prek run --all-files

Type Checking

# Check types with ty
ty check

Full Validation

# Run all checks (same as CI)
nox

Running Tests

# All tests
pytest

# With coverage
pytest --cov=src/fenliu tests/

# Specific test file
pytest tests/test_spam_scoring.py

# Watch mode (auto-run on changes)
pytest-watch

Database Migrations

# Apply pending migrations
alembic upgrade head

# Create new migration
alembic revision --autogenerate -m "add column"

# Show current revision
alembic current

# View migration history
alembic history

Project Structure

fenliu/
├── src/fenliu/
│   ├── __init__.py
│   ├── __main__.py           # CLI entry point
│   ├── main.py               # PyView application
│   ├── config.py             # Configuration
│   ├── database.py           # Database setup
│   ├── models.py             # SQLAlchemy models
│   ├── schemas.py            # Pydantic schemas
│   ├── api/                  # REST API endpoints
│   │   ├── curated.py        # Queue API
│   │   ├── reblog_controls.py
│   │   └── ...
│   ├── services/             # Business logic
│   │   ├── spam_scoring.py
│   │   ├── fediverse.py
│   │   └── ...
│   ├── templates/            # HTML templates
│   ├── static/               # CSS, JS, images
│   └── utils/                # Utilities
├── tests/                    # Test suite
├── docs/                     # Documentation
├── alembic/                  # Database migrations
├── pyproject.toml            # Project configuration
└── mkdocs.yml                # Docs configuration

Environment Variables

Create .env file in project root:

# Database
DATABASE_URL=sqlite:///./fenliu.db

# Fediverse
DEFAULT_INSTANCE=mastodon.social
API_TIMEOUT=30
MAX_POSTS_PER_FETCH=20

# Application
DEBUG=true
SECRET_KEY=dev-secret-key-change-in-production
APP_NAME=FenLiu

# Logging
LOG_LEVEL=DEBUG

Development Workflow

  1. Create feature branch: 

    git checkout -b feature/my-feature

  2. Make changes and test: 

    pytest
prek run --all-files
ty check

  3. Commit with pre-commit checks: 

    git add .
git commit -m "Add my feature"
# Pre-commit hooks run automatically

  4. Full validation before pushing: 

    nox

  5. Push and create pull request: 

    git push origin feature/my-feature

IDE Setup

VS Code

Install extensions: - Python (Microsoft) - Pylance - Ruff - Thunder Client (for API testing)

Add to .vscode/settings.json: 

{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  },
  "python.testing.pytestEnabled": true
}

PyCharm

  1. Open project
  2. Python interpreter: Select .venv/bin/python
  3. Settings → Python → Testing → Pytest
  4. Settings → Tools → Python Integrated Tools → Ruff

Debugging

from fenliu.logging import get_logger

logger = get_logger(__name__)
logger.debug(f"Variable value: {variable}")

View logs: 

tail -f logs/fenliu_debug.log

Interactive Debugging

Add breakpoint in code: 

breakpoint()  # Stops here during execution

Run with: 

python -m pdb -m fenliu

Test Debugging

# Run test with output
pytest -s tests/test_example.py

# Run with debugger
pytest --pdb tests/test_example.py

Troubleshooting

Module Not Found

Ensure you're in virtual environment and dependencies installed: 

source .venv/bin/activate
uv sync -U --all-groups

Database Locked

Close other instances of FenLiu or test runners.

Port Already in Use

Use different port: 

fenliu --port 8001

Pre-commit Errors

Update pre-commit: 

pre-commit autoupdate

Test Database Issues

Delete test database and retry: 

rm fenliu.db
pytest

Useful Commands Reference

# Development
fenliu --reload --debug

# Testing
pytest                                    # All tests
pytest --cov=src/fenliu tests/           # With coverage
pytest -s tests/test_file.py             # With output
pytest -k spam_scoring                   # By pattern

# Code quality
prek run --all-files                     # All pre-commit checks
ruff check src/fenliu/                   # Lint
ruff format src/fenliu/                  # Format
ty check                                 # Type check
nox                                      # Full validation

# Database
alembic upgrade head                     # Apply migrations
alembic revision --autogenerate -m ""   # Create migration

# Documentation
mkdocs serve                             # Build and serve docs
mkdocs build                             # Build static site

# Git
git branch -a                            # List branches
git status                               # Show changes
git diff                                 # Show diffs
git log --oneline                        # Show history

Next Steps