Skip to content

Error handling

The sunstone.errors module re-exports everything from pandas.errors, so you can catch pandas exceptions without importing pandas directly:

from sunstone import pandas as pd
from sunstone.errors import ParserError

try:
    df = pd.read_csv("bad_file.csv", project_path=PROJECT_PATH)
except ParserError:
    print("Failed to parse CSV")

All public error and warning classes from pandas.errors are available, including EmptyDataError, MergeError, ParserError, SettingWithCopyWarning, and others.

Note on ChainedAssignmentError

ChainedAssignmentError is not available via from sunstone.errors import ChainedAssignmentError because pandas itself excludes it from its star export. It is still accessible through the module path:

from sunstone import pandas as pd

pd.errors.ChainedAssignmentError

This matches the behavior of plain import pandas as pd — the drop-in replacement works identically.

LicenseCompatibilityError

Raised by to_csv() / to_parquet() (and other writers that go through the lineage path) when the target license declared for the output is incompatible with one or more source licenses collected from the current session lineage.

from sunstone import pandas as pd
from sunstone.licenses import LicenseCompatibilityError

# Source license is CC-BY-NC-4.0 (NonCommercial),
# but we try to publish under CC-BY-4.0 (drops NC):
try:
    result.to_csv(
        "outputs/derived.csv",
        slug="derived",
        name="Derived Data",
        license="CC-BY-4.0",
    )
except LicenseCompatibilityError as e:
    print(e)

Typical output:

License compatibility check failed for output 'derived' (target: CC-BY-4.0).
  - CC-BY-NC-4.0 is NonCommercial: derivatives must also be NonCommercial, not CC-BY-4.0
Suggested compatible target licenses: CC-BY-NC-4.0, CC-BY-NC-SA-4.0, CC-BY-NC-3.0-IGO

The error is also exported from sunstone.exceptions (via the SunstoneError base class) and inherits from it, so a single except SunstoneError handler catches it alongside DatasetNotFoundError, StrictModeError, etc.

Disabling the check at the call site:

result.to_csv(
    "outputs/derived.csv",
    slug="derived",
    name="Derived Data",
    license="CC-BY-4.0",
    check_license=False,  # opt out — use sparingly
)

When no target license is declared for an output that has source licenses, the writer derives one automatically — inheriting a single source's license, or picking the most restrictive license that satisfies every source — and persists it to datasets.yaml. LicenseCompatibilityError is raised only when the sources are mutually incompatible (or contain unknown identifiers among multiples) and no explicit license: has been set.

See License Compatibility for the rule reference and sunstone license check for the equivalent CI-friendly command.