# Timenet.errors

## timenet.errors

TimeNet's exception hierarchy, and the warnings it raises.

Every TimeNet-raised error derives from :class:`TimeNetError`. TimeF validation errors also derive
from :class:`ValueError`, so existing `except ValueError` handlers keep working. TimeNet raises
the builtin `FileNotFoundError` and `FileExistsError` directly for user-supplied paths.

Every TimeNet-raised warning derives from :class:`TimeNetWarning`.

Some errors carry facts as attributes and leave the remedy to the front end that called the lower
layer: the CLI names its flags, the SDK names its keywords. A front end sets `hint` to one or two
full sentences and raises the error again. `str()` adds the hint after the message as its own
sentence.

### CatalogWarning

Bases: `TimeNetWarning`

A dataset listing skips a source without a catalog.

### ConnectorCardWarning

Bases: `TimeNetWarning`

A dataset listing skips a dataset with an unreadable connector card.

### FormatVersionSubject

Bases: `Enum`

A versioned part of a stored TimeF release. The value names it in error messages.

#### CONTROL\_SCHEMA `class-attribute` `instance-attribute`

```
CONTROL_SCHEMA = 'control schema'
```

The schema of `control.duckdb`, given by the `schema_version` key of `control_metadata`.

#### TIMEF\_FORMAT `class-attribute` `instance-attribute`

```
TIMEF_FORMAT = 'TimeF format'
```

The format of `manifest.json`, given by its `timef_format_version`.

### ReleaseDifference

Bases: `Enum`

What differs between two manifests of the same release.

#### CARD `class-attribute` `instance-attribute`

```
CARD = auto()
```

The file records are the same, and the rest of the manifest differs.

#### FILES `class-attribute` `instance-attribute`

```
FILES = auto()
```

The file records differ.

### SpanOutsideWindowWarning

Bases: `TimeNetWarning`

An annotation's span falls outside the window of the series it names, and is kept.

### TimeFEditError

Bases: `TimeFValidationError`

An edit would leave a dataset referentially inconsistent (for example, a dangling reference).

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeFFormatError

Bases: `TimeNetError`

An on-disk TimeF artifact is corrupt or uses an unsupported format version.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeFFormatVersionError

Bases: `TimeFFormatError`

A stored TimeF artifact has a format version that this TimeNet does not read.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `subject` |  | The versioned part of the release. |
| `where` |  | The file of the artifact, or a description of where a registry keeps it. |
| `found` |  | The version that the artifact records, older than `oldest_readable` or newer than `newest_readable`. |
| `oldest_readable` |  | The oldest version that this TimeNet reads. |
| `newest_readable` |  | The newest version that this TimeNet reads. |
| `path` |  | The file of the artifact, or `None` for an artifact that a registry served. |

#### found `instance-attribute`

```
found = found
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### newest\_readable `instance-attribute`

```
newest_readable = newest_readable
```

#### oldest\_readable `instance-attribute`

```
oldest_readable = oldest_readable
```

#### path `instance-attribute`

```
path = path
```

#### subject `instance-attribute`

```
subject = subject
```

#### where `instance-attribute`

```
where = where
```

### TimeFNotFoundError

Bases: `TimeFValidationError`, `LookupError`

An ID, parent alias, or parent release names nothing in the dataset, or the stored object has another kind.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeFNullValuesError

Bases: `TimeFValidationError`

Values contain nulls where the requested form, such as a NumPy array, cannot hold them.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeFReaderError

Bases: `TimeNetError`

A reader could not complete a read, e.g. its connection was closed while the read ran.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeFValidationError

Bases: `TimeNetError`, `ValueError`

A dataset or its arrays violate a TimeF invariant (raised while building or writing).

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetAccessError

Bases: `TimeNetError`

A dataset needs credentialed or restricted access, so only the user's own registry may hold its data.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `dataset` |  | The release. |
| `access` |  | Its effective access level: the strictest level of its card and of the cards in its lineage. See :func:`~timenet.types.access.effective_access`. |
| `requirements` |  | Each card, of the release itself or of an ancestor, whose access is not open, with its access level and its `access_url`. A user needs access at each of them. See :func:`~timenet.types.access.access_requirements`. |

#### access `instance-attribute`

```
access = access
```

#### dataset `instance-attribute`

```
dataset = dataset
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### requirements `instance-attribute`

```
requirements = requirements
```

### TimeNetBuildError

Bases: `TimeNetError`

A build run failed: the connector build, or the environment it needed.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetConnectorError

Bases: `TimeNetError`

A connector found that one of its assumptions does not hold.

Connector code raises this error. For example, the source data has an unknown code, a download
lacks a file, or a parent lacks a value that the connector needs. The message says where, such
as the file and the row. TimeNet's own checks raise their own errors.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetDatasetNotFoundError

Bases: `TimeNetError`

A requested dataset id or version is not present in a registry or on disk.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetDownloadError

Bases: `TimeNetConnectorError`

TimeNet could not fetch a dataset's source data.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetError

Bases: `Exception`

Base class for all TimeNet errors.

String conversion appends `hint` to the error message.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `hint` | `str | None` | A suggested way to resolve the error, or `None`. |

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetFileError

Bases: `TimeFFormatError`

A release file is missing or differs from its manifest record.

A local copy is checked by file size. A transfer is checked by size and checksum.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `release` |  | The release that the file belongs to. |
| `owner` |  | The release, payload source, or transfer that the file belongs to, as text. |
| `path` |  | The relative file path, using the first missing or resized file in manifest order for local checks. |
| `expected` |  | What the manifest records, for example `"1,024 bytes"` or `"sha256:<hex>"`. |
| `actual` |  | What the file holds, in the same form, or `None` if the file is missing. |

#### actual `instance-attribute`

```
actual = actual
```

#### expected `instance-attribute`

```
expected = expected
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### owner `instance-attribute`

```
owner = owner
```

#### path `instance-attribute`

```
path = path
```

#### release `instance-attribute`

```
release = release
```

### TimeNetInvalidCardError

Bases: `TimeNetError`, `ValueError`

A dataset card YAML is malformed or fails schema validation (raised while building).

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetIsolationError

Bases: `TimeNetBuildError`

An isolated build cannot make its environment.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetManifestError

Bases: `TimeFFormatError`

A stored manifest is not a valid manifest.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `where` |  | The file of the manifest, or a description of where a registry keeps it. |
| `detail` |  | The first problem that the parser found. |
| `path` |  | The file of the manifest, or `None` for a manifest that a registry served. |

#### detail `instance-attribute`

```
detail = detail
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### path `instance-attribute`

```
path = path
```

#### where `instance-attribute`

```
where = where
```

### TimeNetMissingParentError

Bases: `TimeNetDatasetNotFoundError`

A required parent release or payload source is missing.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `missing` |  | The absent release. |
| `needed_by` |  | The release that needs it. |
| `payload_source` |  | `True` if `needed_by` reads files of `missing`, `False` for a declared build parent. |
| `searched` |  | The search location. |

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### missing `instance-attribute`

```
missing = missing
```

#### needed\_by `instance-attribute`

```
needed_by = needed_by
```

#### payload\_source `instance-attribute`

```
payload_source = payload_source
```

#### searched `instance-attribute`

```
searched = searched
```

### TimeNetNoCatalogError

Bases: `TimeNetRegistryError`

No source of a dataset listing has a catalog.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetNotBuiltError

Bases: `TimeNetDatasetNotFoundError`

Only an installed connector provides a release, so it has no manifest yet.

Build the release to create its manifest, or read the connector's card for metadata.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `release` |  | The unbuilt release. |
| `card` |  | The connector's card of the release. |

#### card `instance-attribute`

```
card = card
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### release `instance-attribute`

```
release = release
```

### TimeNetOriginError

Bases: `TimeFFormatError`

The provenance record of a release in the local registry is not valid.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `release` |  | The release of the record. |
| `path` |  | The file of the record. |
| `detail` |  | The first problem that the parser found. |

#### detail `instance-attribute`

```
detail = detail
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### path `instance-attribute`

```
path = path
```

#### release `instance-attribute`

```
release = release
```

### TimeNetRegistryError

Bases: `TimeNetError`

TimeNet could not load or reach a registry, or the registry could not serve a request.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetUnreachableError

Bases: `TimeNetRegistryError`

A request to a registry or its storage failed on the network.

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

### TimeNetVersionConflictError

Bases: `TimeNetError`

A registry already holds a release with other files or another card than the copy.

A changed release needs a new version.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `release` |  | The release that differs. |
| `registry` |  | The destination registry, as text. |
| `registry_location` |  | The `location` of the destination registry. |
| `source` |  | The source registry, as text. |
| `difference` |  | What differs. |
| `needed_by` |  | The requested release that needs this payload source, or `None` if `release` is the request. |

#### difference `instance-attribute`

```
difference = difference
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### needed\_by `instance-attribute`

```
needed_by = needed_by
```

#### registry `instance-attribute`

```
registry = registry
```

#### registry\_location `instance-attribute`

```
registry_location = registry_location
```

#### release `instance-attribute`

```
release = release
```

#### source `instance-attribute`

```
source = source
```

### TimeNetVersionUnavailableError

Bases: `TimeNetDatasetNotFoundError`, `TimeFValidationError`

The installed connector cannot build the requested dataset version.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `release` |  | The requested release. |
| `declared` |  | The version that the connector builds. |

#### declared `instance-attribute`

```
declared = declared
```

#### hint `class-attribute` `instance-attribute`

```
hint: str | None = None
```

#### release `instance-attribute`

```
release = release
```

### TimeNetWarning

Bases: `UserWarning`

Base class for all TimeNet warnings.