Models

@classmethod
def from_json(cls, data: str, /) -> Self:
    """
    Create an instance of this class from a JSON string.

    Parameters
    ----------
    data : str
        JSON string representing the Paste instance.

    Returns
    -------
    Self

    """
    return msgspec.json.decode(data, type=cls)

def to_json(self) -> str:
    """
    Serialize this instance into a JSON string.

    Returns
    -------
    str
        JSON string representing the Paste.

    """
    jsonified = msgspec.json.encode(self)
    return msgspec.json.format(jsonified, indent=2).decode()

@classmethod
def from_file(cls, file: str | PathLike[str], *, name: str | None = None) -> Self:
    """
    Create an `Attachment` instance from a file path.

    If a name is not provided, the filename from the path is used as the attachment name.

    Parameters
    ----------
    file : str | PathLike[str]
        Path to the file from which to create the attachment.
    name : str | None, optional
        The desired name for the attachment. If `None`, the filename from `file` is used.

    Returns
    -------
    Self

    Raises
    ------
    FileNotFoundError
        If the provided `file` path does not exist or is not a file.

    """
    file = Path(file).expanduser().resolve()

    if not file.is_file():
        raise FileNotFoundError(file)

    filename = name if name else file.name
    content = file.read_bytes()

    return cls(content=content, name=filename)

@classmethod
def from_data_url(cls, *, url: str, name: str) -> Self:
    """
    Create an Attachment from a [data URL][Data URL].

    [Data URL]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data

    Parameters
    ----------
    url : str
        Attachment content as a data URL.
    name : str
        The desired name for the attachment.

    Returns
    -------
    Self

    Raises
    ------
    ValueError
        If the provided `url` is not a data URL.

    """
    # https://regex101.com/r/Wiu431/1
    pattern = r"^data:(?P<mimetype>.+);base64,(?P<data>.+)$"
    match = re.fullmatch(pattern, url)

    if match is None:
        truncated = url[:50] + "... (TRUNCATED)" if len(url) > 50 else url
        msg = (
            "Paste has an invalid or unsupported attachment. "
            f"Expected a data URL: 'data:<mimetype>;base64,<data>', got: {truncated!r}"
        )
        raise ValueError(msg)

    data = match.group("data")
    content = base64.b64decode(data)

    return cls(content=content, name=name)

def to_data_url(self) -> str:
    """
    Convert the Attachment's binary content to a [data URL][Data URL].

    [Data URL]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data

    Returns
    -------
    str
        A data URL representing the attachment content.

    """
    encoded = base64.b64encode(self.content).decode()
    mimetype = guess_mime_type(self.name)
    return f"data:{mimetype};base64,{encoded}"

@classmethod
def from_json(cls, data: str, /) -> Self:
    """
    Create an instance of this class from a JSON string.

    Parameters
    ----------
    data : str
        JSON string representing the Paste instance.

    Returns
    -------
    Self

    """
    return msgspec.json.decode(data, type=cls)

def to_json(self) -> str:
    """
    Serialize this instance into a JSON string.

    Returns
    -------
    str
        JSON string representing the Paste.

    """
    jsonified = msgspec.json.encode(self)
    return msgspec.json.format(jsonified, indent=2).decode()

@classmethod
def from_json(cls, data: str, /) -> Self:
    """
    Create an instance of this class from a JSON string.

    Parameters
    ----------
    data : str
        JSON string representing the Paste instance.

    Returns
    -------
    Self

    """
    return msgspec.json.decode(data, type=cls)

def to_json(self) -> str:
    """
    Serialize this instance into a JSON string.

    Returns
    -------
    str
        JSON string representing the receipt.

    Warnings
    --------
    The serialized JSON contains the delete
    token and the passphrase in plain text.

    """
    return super().to_json()

@classmethod
def from_json(cls, data: str, /) -> Self:
    """
    Create an instance of this class from a JSON string.

    Parameters
    ----------
    data : str
        JSON string representing the Paste instance.

    Returns
    -------
    Self

    """
    return msgspec.json.decode(data, type=cls)

def unmask(self) -> str:
    """
    Explicitly convert this instance into a complete, unmasked URL string.

    This method behaves differently from implicit Python string conversions
    like `print(url)`, or f-strings (`f"{url}"`).

    -  `unmask()` returns the full, unmasked URL with the sensitive passphrase.
    -  Implicit conversions (`print()`, f-strings, etc.) return a masked URL for safety.

    Call `unmask()` when you explicitly need the full, working URL, for example, to:

    -  Open the URL in a browser.
    -  Pass the URL to a function that requires the unmasked passphrase.

    Returns
    -------
    str
        The full, unmasked PrivateBin URL.

    Examples
    --------
    >>> url = PrivateBinUrl(server="https://example.privatebin.com/", id="pasteid", passphrase="secret")
    >>> print(url)  # Implicit string conversion - masked URL
    https://example.privatebin.com/?pasteid#********
    >>> f"{url}"  # Implicit string conversion in f-string - masked URL
    'https://example.privatebin.com/?pasteid#********'
    >>> url.unmask()
    'https://example.privatebin.com/?pasteid#secret'

    """
    return pb_urljoin(self.server, self.id, self.passphrase)

def to_json(self) -> str:
    """
    Serialize this instance into a JSON string.

    Returns
    -------
    str
        JSON string representing the URL.

    Warnings
    --------
    The serialized JSON contains the passphrase in plain text.
    """
    return super().to_json()

@classmethod
def parse(cls, url: str | PrivateBinUrl | PasteReceipt, /) -> Self:
    """
    Parse a URL-like object into a `PrivateBinUrl` instance.

    Parameters
    ----------
    url : str | PrivateBinUrl | PasteReceipt
        The URL-like object to parse.

    Returns
    -------
    Self

    Raises
    ------
    ValueError
        If the provided 'url' string is not in the expected format.
    TypeError
        If the provided 'url' is not in the expected type.

    """
    match url:
        case str():
            try:
                server, id, passphrase = pb_urlsplit(url)
            except ValueError as exc:
                msg = (
                    "Invalid PrivateBin URL: "
                    f"{exc}. Expected '<server>/?<paste-id>#<passphrase>'. "
                    f"Got: {url!r}."
                )
                raise ValueError(msg) from None

            if passphrase is None:
                msg = (
                    "Invalid PrivateBin URL: missing '#<passphrase>' component. "
                    "Expected '<server>/?<paste-id>#<passphrase>'. "
                    f"Got: {url!r}."
                )
                raise ValueError(msg)

            return cls(server=server, id=id, passphrase=passphrase)

        case PrivateBinUrl(server=server, id=id, passphrase=passphrase):
            return cls(server=server, id=id, passphrase=passphrase)

        case PasteReceipt(url=PrivateBinUrl(server=server, id=id, passphrase=passphrase)):
            return cls(server=server, id=id, passphrase=passphrase)

        case _:
            msg = f"Parameter 'url' expected 'str', 'PrivateBinUrl', or 'PasteReceipt', but got {type(url).__name__!r}."
            raise TypeError(msg)