# liluo/douban-client architecture

> Architecture diagram of the GitHub repository liluo/douban-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liluo/douban-client
- Repository: https://github.com/liluo/douban-client

## Overview

##### Project type and purpose
- This is a Python library (douban-client) that wraps the Douban API v2, providing:
- OAuth 2.0 authentication (code, password, token flows)
- A uniform interface over all resource endpoints (user, book, movie, music, album, photo, note, discussion, event, online, doumail, miniblog, etc.)
- Automatic JSON handling, error mapping, token refresh
- It is **not** a full‑stack application or microservice, but an SDK / client library designed for easy integration into other Python applications.

##### File structure
- Top‑level:
- `douban_client/` – the library package
- `client.py` – main entrypoint (`DoubanClient`)
- `api/` – one module per resource, plus:
- `base.py` – `BaseAPI` class for common HTTP logic
- `error.py` – exception definitions
- `__init__.py` – imports and version
- `examples/` – three example scripts showing different auth flows
- `tests/` – >90% coverage, exercising each API module via a test framework and mock server
- `requirements.txt` / `setup.py` – packaging and installation
- Architectural hints:
- Single‑process, pure‑Python
- Follows a “one resource = one module/class” pattern
- Delegates all HTTP communication and authentication management to `client.py` and `base.py`

##### Key insights from README
- The library’s purpose is to simplify calls to Douban REST endpoints under OAuth2
- Lists every supported endpoint by resource (user, note, album, etc.)
- Emphasizes JSON transport, standard paging (`start`/`count`), error handling via HTTP codes
- Examples focus on obtaining tokens and then calling `client.<resource>.<action>(…)`

##### Final Recommendations
1. `authorize_url` request/response
2. Token exchange & refresh
3. Resource method HTTP calls
4. Error/exception propagation
- Library internals
- External API
- Consumer code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers
    subgraph "Consumers"
        EX1["Examples: Code Flow"]:::consumer
        EX2["Examples: Password Flow"]:::consumer
        EX3["Examples: Token Flow"]:::consumer
    end

    %% Tests
    subgraph "Tests"
        TF["Test Framework"]:::test
        T_album["tests/test_api_album.py"]:::test
        T_book["tests/test_api_book.py"]:::test
        T_comment["tests/test_api_comment.py"]:::test
        T_discussion["tests/test_api_discussion.py"]:::test
        T_doumail["tests/test_api_doumail.py"]:::test
        T_event["tests/test_api_event.py"]:::test
        T_guess["tests/test_api_guess.py"]:::test
        T_miniblog["tests/test_api_miniblog.py"]:::test
        T_movie["tests/test_api_movie.py"]:::test
        T_music["tests/test_api_music.py"]:::test
        T_note["tests/test_api_note.py"]:::test
        T_online["tests/test_api_online.py"]:::test
        T_photo["tests/test_api_photo.py"]:::test
        T_user["tests/test_api_user.py"]:::test
    end

    %% SDK Library
    subgraph "Douban SDK" 
        DC["DoubanClient"]:::client
        OAuth["OAuth2 Manager"]:::auth
        Err["Error Definitions"]:::http
        BAse["BaseAPI / HTTP Transport"]:::http

        subgraph "Resource APIs"
            UA["UserAPI"]:::resource
            BA["BookAPI"]:::resource
            CA["CommentAPI"]:::resource
            DA["DiscussionAPI"]:::resource
            DMA["DoumailAPI"]:::resource
            EA["EventAPI"]:::resource
            GA["GuessAPI"]:::resource
            MA["MiniblogAPI"]:::resource
            MoA["MovieAPI"]:::resource
            MuA["MusicAPI"]:::resource
            NA["NoteAPI"]:::resource
            OA["OnlineAPI"]:::resource
            PA["PhotoAPI"]:::resource
            RA["ReviewAPI"]:::resource
            SA["SubjectAPI"]:::resource
            AlA["AlbumAPI"]:::resource
        end
    end

    %% External API
    EXT["Douban REST API v2"]:::external

    %% Connections
    EX1 -->|import & calls| DC
    EX2 -->|import & calls| DC
    EX3 -->|import & calls| DC
    TF -->|drives tests| BAse
    T_album -->|tests| AlA
    T_book -->|tests| BA
    T_comment -->|tests| CA
    T_discussion -->|tests| DA
    T_doumail -->|tests| DMA
    T_event -->|tests| EA
    T_guess -->|tests| GA
    T_miniblog -->|tests| MA
    T_movie -->|tests| MoA
    T_music -->|tests| MuA
    T_note -->|tests| NA
    T_online -->|tests| OA
    T_photo -->|tests| PA
    T_user -->|tests| UA

    DC -->|handles auth| OAuth
    OAuth -->|GET authorize_url| EXT
    OAuth -->|POST /oauth2/token| EXT

    DC -->|instantiates| UA
    DC -->|instantiates| BA
    DC -->|instantiates| CA
    DC -->|instantiates| DA
    DC -->|instantiates| DMA
    DC -->|instantiates| EA
    DC -->|instantiates| GA
    DC -->|instantiates| MA
    DC -->|instantiates| MoA
    DC -->|instantiates| MuA
    DC -->|instantiates| NA
    DC -->|instantiates| OA
    DC -->|instantiates| PA
    DC -->|instantiates| RA
    DC -->|instantiates| SA
    DC -->|instantiates| AlA

    UA -->|calls| BAse
    BA -->|calls| BAse
    CA -->|calls| BAse
    DA -->|calls| BAse
    DMA -->|calls| BAse
    EA -->|calls| BAse
    GA -->|calls| BAse
    MA -->|calls| BAse
    MoA -->|calls| BAse
    MuA -->|calls| BAse
    NA -->|calls| BAse
    OA -->|calls| BAse
    PA -->|calls| BAse
    RA -->|calls| BAse
    SA -->|calls| BAse
    AlA -->|calls| BAse

    BAse -->|HTTP requests, JSON parsing| EXT
    BAse -->|raises on error| Err
    Err -->|propagates| EX1
    Err -->|propagates| EX2
    Err -->|propagates| EX3
    Err -->|propagates| T_album

    %% Click Events
    click DC "https://github.com/liluo/douban-client/blob/master/douban_client/client.py"
    click OAuth "https://github.com/liluo/douban-client/blob/master/douban_client/client.py"
    click BAse "https://github.com/liluo/douban-client/blob/master/douban_client/api/base.py"
    click Err "https://github.com/liluo/douban-client/blob/master/douban_client/api/error.py"
    click AlA "https://github.com/liluo/douban-client/blob/master/douban_client/api/album.py"
    click BA "https://github.com/liluo/douban-client/blob/master/douban_client/api/book.py"
    click CA "https://github.com/liluo/douban-client/blob/master/douban_client/api/comment.py"
    click DA "https://github.com/liluo/douban-client/blob/master/douban_client/api/discussion.py"
    click DMA "https://github.com/liluo/douban-client/blob/master/douban_client/api/doumail.py"
    click EA "https://github.com/liluo/douban-client/blob/master/douban_client/api/event.py"
    click GA "https://github.com/liluo/douban-client/blob/master/douban_client/api/guess.py"
    click MA "https://github.com/liluo/douban-client/blob/master/douban_client/api/miniblog.py"
    click MoA "https://github.com/liluo/douban-client/blob/master/douban_client/api/movie.py"
    click MuA "https://github.com/liluo/douban-client/blob/master/douban_client/api/music.py"
    click NA "https://github.com/liluo/douban-client/blob/master/douban_client/api/note.py"
    click OA "https://github.com/liluo/douban-client/blob/master/douban_client/api/online.py"
    click PA "https://github.com/liluo/douban-client/blob/master/douban_client/api/photo.py"
    click RA "https://github.com/liluo/douban-client/blob/master/douban_client/api/review.py"
    click SA "https://github.com/liluo/douban-client/blob/master/douban_client/api/subject.py"
    click UA "https://github.com/liluo/douban-client/blob/master/douban_client/api/user.py"
    click EX1 "https://github.com/liluo/douban-client/blob/master/examples/auth_with_code.py"
    click EX2 "https://github.com/liluo/douban-client/blob/master/examples/auth_with_password.py"
    click EX3 "https://github.com/liluo/douban-client/blob/master/examples/auth_with_token.py"
    click TF "https://github.com/liluo/douban-client/blob/master/tests/framework.py"
    click T_album "https://github.com/liluo/douban-client/blob/master/tests/test_api_album.py"
    click T_book "https://github.com/liluo/douban-client/blob/master/tests/test_api_book.py"
    click T_comment "https://github.com/liluo/douban-client/blob/master/tests/test_api_comment.py"
    click T_discussion "https://github.com/liluo/douban-client/blob/master/tests/test_api_discussion.py"
    click T_doumail "https://github.com/liluo/douban-client/blob/master/tests/test_api_doumail.py"
    click T_event "https://github.com/liluo/douban-client/blob/master/tests/test_api_event.py"
    click T_guess "https://github.com/liluo/douban-client/blob/master/tests/test_api_guess.py"
    click T_miniblog "https://github.com/liluo/douban-client/blob/master/tests/test_api_miniblog.py"
    click T_movie "https://github.com/liluo/douban-client/blob/master/tests/test_api_movie.py"
    click T_music "https://github.com/liluo/douban-client/blob/master/tests/test_api_music.py"
    click T_note "https://github.com/liluo/douban-client/blob/master/tests/test_api_note.py"
    click T_online "https://github.com/liluo/douban-client/blob/master/tests/test_api_online.py"
    click T_photo "https://github.com/liluo/douban-client/blob/master/tests/test_api_photo.py"
    click T_user "https://github.com/liluo/douban-client/blob/master/tests/test_api_user.py"

    %% Styles
    classDef consumer fill:#f9f,stroke:#333,stroke-width:1px
    classDef test fill:#bbf,stroke:#333,stroke-width:1px
    classDef client fill:#afa,stroke:#333,stroke-width:1px
    classDef auth fill:#fea,stroke:#333,stroke-width:1px
    classDef resource fill:#cff,stroke:#333,stroke-width:1px
    classDef http fill:#fcf,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px
```
