Bookmark Organizer

Organize and categorize Chrome bookmarks using Python. Parse exported bookmark HTML files, check URL accessibility, use AI for intelligent categorization, and generate reorganized bookmark files.

Installation & Setup

Install the package in development mode:

```bash

pip install -e ".[dev]"

Or using uv

uv sync --dev

```

Configure environment variables for AI classification:

```bash

cp .env.example .env

Edit .env with your OPENAI_API_KEY and other settings

```

Basic Usage

Parse and Organize Bookmarks

```bash

Basic usage

python -m bookmark_organizer --input bookmarks.html --output organized.html

With caching for faster re-runs

python -m bookmark_organizer --cache bookmarks_cache.json --input bookmarks.html --output organized.html

Verbose mode for debugging

python -m bookmark_organizer --verbose --input bookmarks.html --output organized.html

Performance tuning

python -m bookmark_organizer --max-workers 20 --request-timeout 15 --input bookmarks.html

```

Common CLI Commands

```bash

Show help

python -m bookmark_organizer --help

Check version

python -m bookmark_organizer --version

Export cache for sharing

python -m bookmark_organizer --export-cache cache.json --input bookmarks.html

Import existing cache

python -m bookmark_organizer --import-cache cache.json --input bookmarks.html

```

Architecture

The tool follows a pipeline architecture with five core modules:

1. **Parser** (`parser.py`) - Extracts bookmarks from Chrome HTML exports

2. **Checker** (`checker.py`) - Validates URL accessibility with concurrent processing

3. **Classifier** (`classifier.py`) - Categorizes bookmarks using AI or keyword-based rules

4. **Generator** (`generator.py`) - Creates reorganized HTML bookmark files

5. **Models** (`models.py`) - Pydantic data models with validation

Data Flow

```

HTML Input → Parser → Checker → Classifier → Generator → HTML Output

↓

[Cache] ←─────────────────────────┘

```

Development Commands

Running Tests

```bash

Run all tests

python -m pytest tests/

Run with coverage report

python -m pytest tests/ --cov=src/bookmark_organizer --cov-report=html

Run specific test file

python -m pytest tests/test_models.py -v

Run specific test

python -m pytest tests/test_models.py::TestBookmarkItem::test_init_basic

```

Code Quality

```bash

Lint code

ruff check .

Format code

ruff format .

Type checking

mypy src/

All quality checks

ruff check . && ruff format . && mypy src/

```

Configuration

Environment Variables

Set these in `.env` file:

Check configuration:

```bash

python examples/env_usage_example.py

```

Key Features

Concurrent URL Checking

AI-Powered Classification

Caching Mechanism

Adding New Features

Add a New Module

1. Create module in `src/bookmark_organizer/`

2. Add tests in `tests/test_<module>.py`

3. Update exports in `__init__.py`

4. Add CLI options if needed (in `cli.py`)

5. Update documentation

Add Configuration Option

Edit `src/bookmark_organizer/config.py`:

```python

class AppConfig(BaseModel):

new_option: int = Field(default=10, description="Description")

```

Add Test Case

```python

def test_new_feature(self) -> None:

"""Test description"""

# Arrange

input_data = ...

# Act

result = function_under_test(input_data)

# Assert

assert result == expected_value

```

Performance Tuning

Troubleshooting

Import Errors

Test Failures

AI Classification Issues

Important Files

Security Notes