UNSET Sentinel and UUID4 Auto-Generation Patterns

# OLD PATTERN - DO NOT USE
scene = Scene(id="new", title="Test Scene")

# NEW PATTERN - RECOMMENDED
from stash_graphql_client.types import Scene

# Create new object - UUID4 auto-generated
scene = Scene(title="Test Scene")
print(scene.id)  # "a1b2c3d4e5f6789012345678901234ab"
print(scene.is_new())  # True

# After save, server assigns real ID
await scene.save(client)
print(scene.id)  # "123" (server-assigned)
print(scene.is_new())  # False

scene = Scene(title="Example")
scene.is_new()  # True - has UUID4

scene.id = "123"  # Manually assign server ID
scene.is_new()  # False - numeric ID from server

scene = Scene(title="Example")
old_id = scene.id  # UUID4 hex string

# Manually update after server returns ID
scene.update_id("456")
print(scene.id)  # "456"

def __init__(self, **data: Any) -> None:
    # Auto-generate UUID4 for new objects without an ID
    if "id" not in data or data.get("id") is None:
        data["id"] = uuid.uuid4().hex
        log.debug(
            f"Auto-generated UUID4 for new {self.__class__.__name__}: {data['id']}"
        )
    super().__init__(**data)

# TWO-LEVEL SYSTEM PROBLEM
scene.title = "Updated Title"
scene.rating100 = None  # Want to set to null
# scene.details = ??? How to say "don't touch this field"?

# to_input() has to include ALL fields to be safe
await scene.save(client)  # Overwrites details even though we didn't touch it!

from stash_graphql_client.types import Scene, UNSET

# Three possible states for each field:
scene.title = "Updated Title"  # 1. Set to value
scene.rating100 = None          # 2. Set to null
scene.details = UNSET           # 3. Never touched (don't include in input)

# to_input() only includes fields that are NOT UNSET
input_dict = await scene.to_input()
# {"id": "123", "title": "Updated Title", "rating100": null}
# "details" is excluded because it's UNSET

class UnsetType:
    """Sentinel value representing an unset field."""

    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __repr__(self) -> str:
        return "UNSET"

    def __bool__(self) -> bool:
        return False  # UNSET is always falsy

    def __eq__(self, other) -> bool:
        return isinstance(other, UnsetType)

    def __hash__(self) -> int:
        return hash("UNSET")

# Singleton instance - use this throughout the codebase
UNSET = UnsetType()

from pydantic import BaseModel
from stash_graphql_client.types import UNSET, UnsetType

class Scene(StashObject):
    """Scene entity with UNSET sentinel support."""

    # Required in schema, but UNSET if not in GraphQL fragment
    title: str | UnsetType = UNSET

    # Optional in schema, can be null, value, or UNSET
    rating100: int | None | UnsetType = UNSET
    details: str | None | UnsetType = UNSET

    # Required fields without defaults (always provided)
    id: str

async def to_input(self) -> dict[str, Any]:
    """Convert to GraphQL input, excluding UNSET fields."""
    input_dict = {}

    # Only include fields that are NOT UNSET
    if self.title is not UNSET:
        input_dict["title"] = self.title

    if self.rating100 is not UNSET:
        input_dict["rating100"] = self.rating100  # Could be None or a value

    if self.details is not UNSET:
        input_dict["details"] = self.details  # Could be None or a value

    return input_dict

# ✅ CORRECT - use identity comparison
if scene.title is UNSET:
    print("Title was never set")

if scene.title is not UNSET:
    print(f"Title is: {scene.title}")  # Could be value or None

# ❌ WRONG - don't use equality comparison
if scene.title == UNSET:  # This works but 'is' is preferred for singletons
    print("Title was never set")

# ❌ WRONG - don't use boolean check
if not scene.title:  # This is True for UNSET, None, and empty string!
    print("Ambiguous - could be UNSET, None, or empty")

# Partial fragment - only loaded id and title
scene_data = {"id": "123", "title": "Test Scene"}
scene = Scene.from_graphql(scene_data)

# How do we know that rating100 wasn't loaded vs was loaded as null?
print(scene.rating100)  # UNSET or None?

from stash_graphql_client.types import Scene

# Load from GraphQL with partial data
scene = Scene.from_graphql({
    "id": "123",
    "title": "Test Scene",
    "rating100": None  # Explicitly null in response
})

print(scene._received_fields)  # {"id", "title", "rating100"}
print(scene.title)  # "Test Scene"
print(scene.rating100)  # None (was in response)
print(scene.details)  # UNSET (not in response)

# From GraphQL - tracks received fields
scene1 = Scene.from_graphql({"id": "123", "title": "Test"})
print(scene1._received_fields)  # {"id", "title"}

# Direct construction - no tracking
scene2 = Scene(id="456", title="Test")
print(scene2._received_fields)  # set() - empty

if "rating100" not in scene._received_fields:
    print("Rating was not loaded - fetch it if needed")
    await scene.populate(client, ["rating100"])

# First query loads basic fields
scene = await client.find_scene("123")  # id, title
print(scene._received_fields)  # {"id", "title", ...}

# Second query loads additional fields
detailed = await client.find_scene_with_files("123")  # id, title, files
# Identity map merges: same object, more fields
print(scene._received_fields)  # {"id", "title", "files", ...}
assert scene is detailed  # Same cached object!

def validate_fields(obj: StashObject, required: set[str]):
    """Ensure all required fields were loaded."""
    missing = required - obj._received_fields
    if missing:
        raise ValueError(f"Missing required fields: {missing}")

scene = await client.find_scene("123")
scene.title = "Updated Title"  # Changed
scene.rating100 = scene.rating100  # Not changed (same value)

# How do we know which fields actually changed?
# We need to compare current state to original state

from stash_graphql_client.types import Scene

# Load from server
scene = await client.find_scene("123")
# _snapshot is automatically created with original values

print(scene.is_dirty())  # False - no changes yet

scene.title = "Updated Title"
print(scene.is_dirty())  # True - title changed

dirty_fields = scene.get_changed_fields()
print(dirty_fields)  # {"title": "Updated Title"}

scene = await client.find_scene("123")
print(scene.is_dirty())  # False

scene.title = "New Title"
print(scene.is_dirty())  # True

await scene.save(client)
print(scene.is_dirty())  # False - save() calls mark_clean()

scene.title = "Updated Title"
scene.rating100 = 90

changed = scene.get_changed_fields()
print(changed)  # {"title": "Updated Title", "rating100": 90}

scene.title = "Updated"
print(scene.is_dirty())  # True

scene.mark_clean()  # Update snapshot
print(scene.is_dirty())  # False
print(scene.get_changed_fields())  # {}

scene = await client.find_scene("123")
print(scene.is_dirty())  # False

scene.mark_dirty()  # Clear snapshot
print(scene.is_dirty())  # True
print(scene.get_changed_fields())  # All tracked fields

class StashObject(BaseModel):
    def model_post_init(self, _context: Any) -> None:
        """Called after Pydantic initialization."""
        # Capture initial state
        self._snapshot = self.model_dump()

    def is_dirty(self) -> bool:
        """Compare current state to snapshot."""
        return self.model_dump() != self._snapshot

    def get_changed_fields(self) -> dict[str, Any]:
        """Find fields that differ from snapshot."""
        current = self.model_dump()
        changed = {}
        for field in self.__tracked_fields__:
            if current.get(field) != self._snapshot.get(field):
                changed[field] = current[field]
        return changed

async def to_input(self) -> dict[str, Any]:
    """Convert to GraphQL input type.

    For new objects: Uses _to_input_all() - all non-UNSET fields
    For existing objects: Uses _to_input_dirty() - only changed fields
    """
    input_obj = (
        await self._to_input_all()   # New object path
        if self.is_new()
        else await self._to_input_dirty()  # Existing object path
    )

    return input_obj.model_dump(exclude_none=True)

scene = Scene.new(
    title="New Scene",
    rating100=85,
    # details left as UNSET
)

input_dict = await scene.to_input()
# {
#   "title": "New Scene",
#   "rating100": 85
#   # "details" excluded (UNSET)
# }

scene = await client.find_scene("123")
# _snapshot = {"id": "123", "title": "Original", "rating100": 70, ...}

scene.title = "Updated Title"  # Changed
# scene.rating100 unchanged

input_dict = await scene.to_input()
# {
#   "id": "123",
#   "title": "Updated Title"
#   # rating100 NOT included (not dirty)
# }

# 1. Load from GraphQL (sets _received_fields and _snapshot)
scene = Scene.from_graphql({
    "id": "123",
    "title": "Original Title",
    "rating100": 70,
    "details": None  # Explicitly null
    # "url" not in fragment
})

print(scene._received_fields)  # {"id", "title", "rating100", "details"}
print(scene._snapshot)  # {"id": "123", "title": "Original Title", ...}
print(scene.url)  # UNSET (not loaded)
print(scene.details)  # None (was null in response)

# 2. Make changes
scene.title = "Updated Title"  # Change tracked field
scene.rating100 = None  # Change to null
scene.url = UNSET  # Explicitly keep as UNSET (don't send)
# scene.details unchanged (still None)

# 3. Check dirty state
print(scene.is_dirty())  # True
print(scene.get_changed_fields())  # {"title": "Updated Title", "rating100": None}

# 4. Generate minimal input (only dirty fields)
input_dict = await scene.to_input()
print(input_dict)
# {
#   "id": "123",
#   "title": "Updated Title",  # Changed
#   "rating100": None          # Changed to null - INCLUDED
#   # details NOT included (unchanged)
#   # url NOT included (UNSET)
# }

# 5. Save and mark clean
await scene.save(client)
print(scene.is_dirty())  # False

from stash_graphql_client import StashClient
from stash_graphql_client.types import Scene, UNSET

# Create new scene - UUID4 auto-generated
scene = Scene(
    title="My New Scene",
    rating100=85,
    # details left as UNSET - will be excluded from create input
)

print(scene.id)        # "a1b2c3d4..." (UUID4)
print(scene.is_new())  # True
print(scene.title)     # "My New Scene"
print(scene.details)   # UNSET

# Save to server
await scene.save(client)

print(scene.id)        # "123" (server-assigned)
print(scene.is_new())  # False

# Fetch existing scene from server
scene = await client.find_scene("123")

print(scene.title)     # "Original Title"
print(scene.rating100) # 70
print(scene.details)   # "Original details"

# Update only one field
scene.title = "Updated Title"

# to_input() only includes changed field + ID
input_dict = await scene.to_input()
# {"id": "123", "title": "Updated Title"}
# rating100 and details are NOT included (not dirty)

# Save sends only the changed field
await scene.save(client)

scene = await client.find_scene("123")

# Set field to null (explicit null in GraphQL)
scene.rating100 = None
input_dict = await scene.to_input()
# {"id": "123", "rating100": null}
# Server will set rating100 to null

# vs. leaving field UNSET (omit from GraphQL input)
scene.details = UNSET
input_dict = await scene.to_input()
# {"id": "123"}
# Server keeps existing details value unchanged

scene = Scene(title="Test")

# Check the three states
if scene.title is not UNSET:
    if scene.title is None:
        print("Title is explicitly null")
    else:
        print(f"Title is set to: {scene.title}")
else:
    print("Title was never touched")

# Using a helper function
def describe_field(field_value):
    if field_value is UNSET:
        return "UNSET (never touched)"
    elif field_value is None:
        return "NULL (explicitly set to null)"
    else:
        return f"VALUE: {field_value}"

print(describe_field(scene.title))     # "VALUE: Test"
print(describe_field(scene.rating100)) # "UNSET (never touched)"

from stash_graphql_client.types import UNSET, UnsetType

class Scene(StashObject):
    title: str | None = None
    rating100: int | None = None

class Scene(StashObject):
    title: str | UnsetType = UNSET
    rating100: int | None | UnsetType = UNSET

async def to_input(self) -> dict[str, Any]:
    data = {"id": self.id}

    # Only include non-UNSET fields
    if self.title is not UNSET:
        data["title"] = self.title

    if self.rating100 is not UNSET:
        data["rating100"] = self.rating100

    return data

def test_unset_field_not_in_input():
    """UNSET fields should be excluded from input."""
    scene = Scene(id="123", title="Test")
    scene.rating100 = UNSET  # Explicitly UNSET

    input_dict = await scene.to_input()

    assert "title" in input_dict
    assert "rating100" not in input_dict  # UNSET fields excluded

def test_null_field_in_input():
    """None fields should be included in input."""
    scene = Scene(id="123", title="Test")
    scene.rating100 = None  # Explicitly null

    input_dict = await scene.to_input()

    assert "title" in input_dict
    assert "rating100" in input_dict
    assert input_dict["rating100"] is None

# Cached objects preserve UNSET state
scene1 = await store.get(Scene, "123")  # Fetched with partial fragment
print(scene1.details)  # UNSET (not in fragment)

# Same object from cache
scene2 = await store.get(Scene, "123")
assert scene1 is scene2  # Same reference
print(scene2.details)  # Still UNSET

# populate() can fetch missing fields
await store.populate(scene1, ["details"])
print(scene1.details)  # "Details from server" (no longer UNSET)

scene = Scene(title="Test")

# mypy knows title could be str or UnsetType
if scene.title is not UNSET:
    # In this block, mypy narrows type to just str
    print(scene.title.upper())  # ✅ OK - mypy knows it's str

# mypy error if you don't check first
print(scene.title.upper())  # ❌ Error - UnsetType has no attribute 'upper'

def test_new_object_gets_uuid():
    """New objects should auto-generate UUID4."""
    scene = Scene(title="Test")

    assert scene.id is not None
    assert len(scene.id) == 32  # UUID4 hex is 32 chars
    assert scene.is_new() is True

def test_existing_object_no_uuid():
    """Objects with server IDs should not be marked as new."""
    scene = Scene(id="123", title="Test")

    assert scene.id == "123"
    assert scene.is_new() is False

def test_update_id_after_save(respx_mock, stash_client):
    """save() should update UUID with server ID."""
    scene = Scene(title="Test")
    original_id = scene.id  # UUID4

    # Mock GraphQL response
    respx.post("http://localhost:9999/graphql").mock(
        return_value=httpx.Response(
            200, json={"data": {"sceneCreate": {"id": "456"}}}
        )
    )

    await scene.save(stash_client)

    assert scene.id == "456"
    assert scene.id != original_id
    assert scene.is_new() is False

def test_unset_field_excluded():
    """UNSET fields should be excluded from to_input()."""
    scene = Scene(id="123", title="Test")
    scene.rating100 = UNSET

    input_dict = await scene.to_input()

    assert "rating100" not in input_dict

def test_null_field_included():
    """None fields should be included in to_input()."""
    scene = Scene(id="123", title="Test")
    scene.rating100 = None

    input_dict = await scene.to_input()

    assert "rating100" in input_dict
    assert input_dict["rating100"] is None

def test_value_field_included():
    """Value fields should be included in to_input()."""
    scene = Scene(id="123", title="Test")
    scene.rating100 = 85

    input_dict = await scene.to_input()

    assert "rating100" in input_dict
    assert input_dict["rating100"] == 85

from pydantic import field_serializer

class Scene(StashObject):
    title: str | UnsetType = UNSET

    @field_serializer("title", when_used="json")
    def serialize_title(self, value):
        if value is UNSET:
            raise ValueError("UNSET should be excluded")
        return value

import msgspec

def dec_hook(type, obj):
    """Custom decoder hook for msgspec."""
    if isinstance(obj, dict) and "id" in obj:
        # Check cache, return cached instance or construct new
        # UNSET is preserved for fields not in response
        pass