API reference¶

def extract(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Parse URLs into a struct, faithfully reproducing `tldextract`.

    The output mirrors `tldextract.ExtractResult`: parts that do not exist are
    **empty strings**, not nulls. This is the one expression here that keeps
    that convention -- every single-field accessor uses nulls instead, which is
    what a DataFrame wants. Reach for this when porting `tldextract` code and
    wanting the behavior unchanged.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes, matching
        `tldextract`'s `include_psl_private_domains`. With the default,
        `pola-rs.github.io` has suffix `io`; with `True` it has suffix
        `github.io`.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.
        Columns below 100k rows run single-threaded regardless.

    Returns
    -------
    pl.Expr
        Struct of `subdomain` / `domain` / `suffix` / `is_private`. Null input
        yields a null struct.
    """
    return _plugin(
        "tld_extract", expr, include_private=include_private, parallel=parallel
    )

def fqdn(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract the whole hostname, e.g. `"www.bbc.co.uk"`.

    This is the normalized netloc: scheme, userinfo, port, path, query, and
    fragment stripped, trailing root labels dropped, and the three non-ASCII
    IDNA separators folded to `.`. Casing and punycode spelling are preserved.

    Unlike `registrable_domain`, a host with no recognized suffix still has a
    name, so `"localhost"` and `"127.0.0.1"` come back as themselves rather
    than null. Only input with no host at all yields null. A bracketed IPv6
    literal keeps its brackets, matching what `extract` reports as its domain.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes. Does not change
        the result -- the same labels are rejoined either way -- but is taken
        so every expression accepts the same keywords.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column of hostnames, null where the input held no host.
    """
    return _plugin(
        "tld_fqdn", expr, include_private=include_private, parallel=parallel
    )

def registrable_domain(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract `"domain.suffix"`, or null when either half is missing.

    Computed in one pass, without materializing the other parts. Strict on
    purpose: an IP or an unrecognized suffix has no registrable domain, so it
    yields null rather than a half-formed string. Use `fqdn` when you want the
    hostname regardless.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column of registrable domains, null where none could be parsed.
    """
    return _plugin(
        "tld_registrable_domain",
        expr,
        include_private=include_private,
        parallel=parallel,
    )

def subdomain(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract the subdomain, e.g. `"www"` from `"www.bbc.co.uk"`.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column, **null** where there is no subdomain. `extract` reports
        the same absence as an empty string.
    """
    return _plugin(
        "tld_subdomain",
        expr,
        include_private=include_private,
        parallel=parallel,
    )

def domain(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract the registrable label, e.g. `"bbc"` from `"bbc.co.uk"`.

    This is `tldextract`'s `domain` field -- the label you register, not the
    whole hostname. Use `fqdn` for the hostname and `registrable_domain` for
    `"bbc.co.uk"`.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column, **null** where there is no registrable label. `extract`
        reports the same absence as an empty string.
    """
    return _plugin(
        "tld_domain", expr, include_private=include_private, parallel=parallel
    )

def suffix(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract the public suffix, e.g. `"co.uk"` from `"bbc.co.uk"`.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column, **null** where no suffix rule matched. `extract` reports
        the same absence as an empty string.
    """
    return _plugin(
        "tld_suffix", expr, include_private=include_private, parallel=parallel
    )

def load_psl(source: str | Path) -> str:
    """Replace the live Public Suffix List, and return its version.

    Takes effect for every extraction that *starts* after it returns. A query
    already running keeps the list it started with, so no column can be parsed
    against two different lists.

    Parameters
    ----------
    source : str | pathlib.Path
        A path to a `.dat` file, or the list text itself. A `Path` is always
        read as a file; a `str` is treated as list text when it contains a
        newline and as a path otherwise.

    Returns
    -------
    str
        The `VERSION:` stamp of the newly loaded list.

    Raises
    ------
    ValueError
        If the file cannot be read, or the list cannot be parsed, or it is
        missing the ICANN/private section markers. The previously loaded list
        stays in use.

    Examples
    --------
    >>> import polars_tldextract as tld
    >>> path = "/mnt/reference/public_suffix_list.dat"
    >>> tld.load_psl(path)  # doctest: +SKIP
    '2026-07-21_08-00-00_UTC'
    """
    if isinstance(source, Path):
        return load_psl_path(str(source))
    return load_psl_text(source) if "\n" in source else load_psl_path(source)

def refresh_psl(
    url: str = PSL_URL,
    *,
    timeout: float = 60.0,
    save_to: str | Path | None = None,
) -> str:
    """Download the current Public Suffix List and load it.

    This is the only function in the package that touches the network, and only
    when you call it. Call it before the extraction whose results should
    reflect the newer list.

    Parameters
    ----------
    url : str, default `PSL_URL`
        Where to fetch the list from. Point this at an internal mirror if
        outbound access is restricted.
    timeout : float, default 60.0
        Seconds to wait for the download.
    save_to : str | pathlib.Path | None, optional
        If given, also write the downloaded list here, so a later run can
        `load_psl` it (or `POLARS_TLDEXTRACT_PSL` can point at it) without
        going back to the network. Only written once the list has been
        validated and loaded.

    Returns
    -------
    str
        The `VERSION:` stamp of the newly loaded list.

    Raises
    ------
    OSError
        If the download fails. The previously loaded list stays in use.
    ValueError
        If what comes back is not a usable Public Suffix List. The previously
        loaded list stays in use.

    Examples
    --------
    >>> import polars_tldextract as tld
    >>> tld.refresh_psl()  # doctest: +SKIP
    '2026-07-21_08-00-00_UTC'
    """
    with urllib.request.urlopen(url, timeout=timeout) as response:
        text = response.read().decode("utf-8")

    version = load_psl_text(text)

    if save_to is not None:
        Path(save_to).write_text(text, encoding="utf-8")

    return version

def parts(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Build the 0.1 `full_domain` / `sld` / `tld` struct. Deprecated.

    The three fields are `registrable_domain`, `domain`, and `suffix`, which
    now carry the null semantics `parts` existed to provide. `full_domain` was
    a misnomer for the *registrable* domain -- `fqdn` is the actual full
    domain.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Struct of `full_domain`, `sld`, and `tld`, as 0.1 returned it.
    """
    _warn(
        "tld.parts() is deprecated and will be removed in 0.3.0. Its fields "
        "are now separate expressions with the same null semantics: "
        "full_domain -> registrable_domain(), sld -> domain(), "
        "tld -> suffix(). For the whole hostname, use fqdn()."
    )
    kwargs = {"include_private": include_private, "parallel": parallel}
    return pl.struct(
        _expr.registrable_domain(expr, **kwargs).alias("full_domain"),
        _expr.domain(expr, **kwargs).alias("sld"),
        _expr.suffix(expr, **kwargs).alias("tld"),
    )

def top_domain(
    expr: IntoExprColumn,
    *,
    include_private: bool = False,
    parallel: bool = True,
) -> pl.Expr:
    """Extract the registrable label. Deprecated alias for `domain`.

    `top_domain` returned an empty string where there was no registrable label;
    `domain` returns null, like every other single-field expression.

    Parameters
    ----------
    expr : IntoExprColumn
        String column of URLs (or bare hostnames).
    include_private : bool, default False
        Whether to treat the PSL's private section as suffixes.
    parallel : bool, default True
        Whether the plugin may split large columns across rayon threads.

    Returns
    -------
    pl.Expr
        Utf8 column, null where there is no registrable label.
    """
    _warn(
        "tld.top_domain() is deprecated and will be removed in 0.3.0; use "
        "tld.domain(). Note the absent value is now null rather than an "
        "empty string -- extract().struct.field('domain') still gives you "
        "the empty-string form."
    )
    return _expr.domain(
        expr, include_private=include_private, parallel=parallel
    )