# What Information Does the `Result` Dataclass Store in user-scanner?

> Discover what information the Result dataclass stores in kaifcodec/user-scanner. Learn about its 9 fields including status, username, and URL for scan outcomes.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: api-reference
- Published: 2026-09-02

---

**The `Result` dataclass in `kaifcodec/user-scanner` stores 9 fields capturing scan outcomes: `status`, `reason`, `username`, `site_name`, `category`, `url`, `extra`, `media`, and `is_email`.**

The `Result` dataclass serves as the central data container for all platform scan operations in the user-scanner repository. Every scan module—whether checking username availability on GitHub or verifying email addresses on Gravatar—returns a `Result` instance that encapsulates the complete outcome plus contextual metadata for reporting and export.

## Core Data Fields in the `Result` Dataclass

The `Result` class is defined in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py). Its fields fall into three logical groups: **outcome**, **identity**, and **metadata**.

### Outcome Fields

| Field | Type | Purpose |
|-------|------|---------|
| **`status`** | `Status` (Enum) | `TAKEN`, `AVAILABLE`, `ERROR`, or `SKIPPED`—the definitive result of the check |
| **`reason`** | `str \| Exception \| None` | Human-readable explanation or the exception object for error cases |

### Identity Fields

| Field | Type | Purpose |
|-------|------|---------|
| **`username`** | `str \| None` | The handle examined; `None` for pure email scans |
| **`site_name`** | `str \| None` | Platform identifier such as "GitHub", "Reddit", or "Gravatar" |
| **`category`** | `str \| None` | Logical grouping like "social", "developer", or "email" |

### Metadata and Media Fields

| Field | Type | Purpose |
|-------|------|---------|
| **`url`** | `str` | The actual URL accessed during the check |
| **`extra`** | `dict[str, str \| bool \| int]` | Arbitrary module-specific data: follower counts, bio snippets, account creation dates |
| **`media`** | `dict[str, str]` | Asset URLs—typically avatar or profile picture locations |
| **`is_email`** | `bool` | Rendering flag distinguishing email checks from username checks |

## How Fields Are Populated

The `Result` class provides two primary mechanisms for setting these fields:

1. **Constructor injection** via `__init__`—used when creating results directly
2. **Dynamic updates** via the `update()` method—merges keyword arguments safely into existing instances, including the `url` field

The `update()` method is particularly important for scan modules that discover additional data after initial object creation, such as resolving a redirect to obtain the final profile URL.

## Working with `Result` Data: Code Examples

### Creating a Username Scan Result

```python
from user_scanner.core.result import Result, Status

# Capturing a "found" result for GitHub

res = Result.taken(
    reason="Profile exists",
    username="alice",
    site_name="GitHub",
    category="developer",
    url="https://github.com/alice",
    extra={"followers": 42, "bio": "Engineer"},
    media={"avatar": "https://avatars.githubusercontent.com/u/12345"},
)

print(res)                      # "Profile exists"

print(res.as_dict())            # Dictionary for JSON/CSV export

print(res.to_json())            # Serialized JSON string

print(res.get_console_output()) # Colored terminal line (requires ScanConfig)

```

### Creating an Email Scan Result

```python

# Verifying an available email address on Gravatar

email_res = Result.available(
    reason=None,
    username="bob@example.com",
    site_name="Gravatar",
    category="email",
    url="https://www.gravatar.com/avatar/...",
    is_email=True,  # Affects label rendering in output

)

print(email_res.to_json())

```

## Export Methods for Stored Data

The `Result` dataclass exposes its stored information through multiple format helpers designed for different consumption patterns:

- **`as_dict()`** — Returns a flat dictionary suitable for JSON serialization or CSV row creation
- **`to_json()`** — Produces a JSON string representation
- **`to_csv()`** — Formats data for spreadsheet export
- **`get_console_output()`** — Renders colored terminal output using `ScanConfig` from [`user_scanner/core/helpers.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/helpers.py)

## Source File Locations

| File | Role |
|------|------|
| [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) | `Result` class, `Status` enum, and field definitions |
| [`user_scanner/core/helpers.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/helpers.py) | `ScanConfig` for console output rendering |
| [`user_scanner/core/engine.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/engine.py) | Scan orchestration and `Result` aggregation |

## Summary

- The **`Result` dataclass** stores 9 standardized fields across outcome, identity, and metadata categories
- **Status enumeration** (`TAKEN`, `AVAILABLE`, `ERROR`, `SKIPPED`) provides the primary result classification
- **Flexible `extra` and `media` dictionaries** accommodate platform-specific data without schema changes
- **Multiple export formats** (`as_dict`, `to_json`, `to_csv`) support diverse reporting pipelines
- **Source implementation** resides in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) with field assignments in `__init__` and `update()`

## Frequently Asked Questions

### What is the difference between `extra` and `media` in a `Result` object?

The `extra` field stores arbitrary key-value data as `dict[str, str | bool | int]`—typically numeric metrics like follower counts or text fields like profile bios. The `media` field is specifically typed as `dict[str, str]` and reserved for URL references to visual assets such as avatars, profile pictures, or header images. This separation allows the rendering layer to handle media previews differently from raw metadata.

### How does `is_email` affect `Result` output rendering?

The `is_email` boolean flag signals to output formatters in [`user_scanner/core/helpers.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/helpers.py) whether to apply email-specific labeling in console displays. When `True`, the interface may render "Email:" instead of "Username:" and adjust validation messaging. This distinction matters because email scans often follow different verification patterns than username availability checks.

### Can `Result` store partial data before a scan completes?

Yes. The `update()` method in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) supports incremental population by safely merging new keyword arguments into existing instances. Scan modules frequently create preliminary `Result` objects with basic identity fields, then call `update()` to add discovered data like resolved URLs, follower statistics, or media links as they become available during asynchronous requests.

### What happens to the `reason` field when a scan raises an exception?

The `reason` field accepts `Exception` objects directly, not just strings. When a module encounters a network timeout, HTTP error, or parsing failure, it can pass the caught exception as the `reason` value. The export methods handle this gracefully—typically converting exceptions to their string representation for JSON/CSV output while preserving full traceback information for debug logs.