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

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. 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

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

# 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

Source File Locations

File	Role
user_scanner/core/result.py	Result class, Status enum, and field definitions
user_scanner/core/helpers.py	ScanConfig for console output rendering
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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}