Skip to content

Books#

bookshelf.Book #

Book(client: BookshelfClient, cache: ContentCache, metadata: models.BookListItem, entries: list[models.BookEntryItem])

Bases: _BookBase

A resolved published Book indexed by Entry name.

metadata instance-attribute #

metadata = metadata

The book's record as the platform lists it.

book_id instance-attribute #

book_id = UUID(id)

The platform's id for this book.

entry_names property #

entry_names: tuple[str, ...]

The entries this book indexes, in the order the platform lists them.

__iter__ #

__iter__() -> Iterator[str]

Iterate over entry names in the order the platform lists them.

__getitem__ #

__getitem__(name_in_book: str) -> BookEntry

Look up one entry by name, raising KeyError for a name the book does not index.

bookshelf.AsyncBook #

AsyncBook(client: BookshelfClient, cache: ContentCache, metadata: models.BookListItem, entries: list[models.BookEntryItem])

Bases: _BookBase

An asynchronously resolved published Book indexed by Entry name.

metadata instance-attribute #

metadata = metadata

The book's record as the platform lists it.

book_id instance-attribute #

book_id = UUID(id)

The platform's id for this book.

entry_names property #

entry_names: tuple[str, ...]

The entries this book indexes, in the order the platform lists them.

__iter__ #

__iter__() -> Iterator[str]

Iterate over entry names in the order the platform lists them.

__getitem__ #

__getitem__(name_in_book: str) -> AsyncBookEntry

Look up one entry by name, raising KeyError for a name the book does not index.

bookshelf.BookEntry #

BookEntry(client: BookshelfClient, cache: ContentCache, book_id: str | UUID, entry: models.BookEntryItem)

Bases: Resource

A resource handle with its book scoped exploration capabilities.

tracking_id instance-attribute #

tracking_id = UUID(str(tracking_id))

The platform's id for this resource.

metadata property #

metadata: ResourceRead

Return the generated resource projection.

type property #

type: ResourceType

Return the canonical resource type.

book_id instance-attribute #

book_id = UUID(str(book_id))

The id of the book this entry belongs to.

name_in_book instance-attribute #

name_in_book = name_in_book

The name this entry has in its book.

content_hash #

content_hash() -> str

Return the declared sha256: digest, from memory or disk before the platform.

as_df #

as_df(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pd.DataFrame

Return the whole resource as pandas, using wide indexed form for timeseries.

The year window and column=value filters apply locally, after the download.

as_long_df #

as_long_df(*, year_min: int | None = None, year_max: int | None = None, legacy_columns: bool = False, **filters: str) -> pd.DataFrame

Return tidy pandas timeseries data.

legacy_columns reproduces the 0.4 long format instead: a values column, a year column of YYYY-01-01 00:00:00 strings, and rows sorted by the dimensions and then the year.

as_polars #

as_polars(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pl.DataFrame

Return the resource as a Polars DataFrame.

as_arrow #

as_arrow(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pa.Table

Return the resource as a PyArrow table.

as_scmrun #

as_scmrun(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> ScmRun

Return timeseries data as an scmdata ScmRun.

scmdata rejects rows with duplicate metadata.

fetch #

fetch() -> bytes

Return verified bytes, using memory proportional to the resource size.

Use as_path() to stream large resources without loading them into memory.

as_path #

as_path() -> Path

Stream and verify the resource, then return its cached path.

query #

query(*, select: str | None = None, order: str | None = None, year_min: int | None = None, year_max: int | None = None, drop_constant: bool = False, top_n: int | None = None, limit: int | None = None, offset: int | None = None, **filters: str) -> pd.DataFrame

Return book scoped data filtered and trimmed on the server.

Timeseries go through the book timeseries endpoint, which truncates at its row limit.

as_resource #

as_resource() -> Resource

Drop book context and return the lean resource handle.

facets #

facets(*, max_values: int = _FACET_MAX_VALUES, **filters: str) -> models.FacetsResponse

Return book scoped facet values.

preview #

preview(*, limit: int = 100, offset: int = 0) -> models.PreviewResponse

Return a book scoped tabular preview.

schema #

schema(*, limit: int = 100, offset: int = 0) -> models.TimeseriesMetadataResponse

Return book scoped timeseries schema metadata.

bookshelf.AsyncBookEntry #

AsyncBookEntry(client: BookshelfClient, cache: ContentCache, book_id: str | UUID, entry: models.BookEntryItem)

Bases: AsyncResource

An async resource handle with book scoped exploration capabilities.

tracking_id instance-attribute #

tracking_id = UUID(str(tracking_id))

The platform's id for this resource.

book_id instance-attribute #

book_id = UUID(str(book_id))

The id of the book this entry belongs to.

name_in_book instance-attribute #

name_in_book = name_in_book

The name this entry has in its book.

content_hash async #

content_hash() -> str

Return the declared sha256: digest, from memory or disk before the platform.

as_df async #

as_df(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pd.DataFrame

Return the whole resource as pandas, using wide indexed form for timeseries.

The year window and column=value filters apply locally, after the download.

as_long_df async #

as_long_df(*, year_min: int | None = None, year_max: int | None = None, legacy_columns: bool = False, **filters: str) -> pd.DataFrame

Return tidy pandas timeseries data.

legacy_columns reproduces the 0.4 long format instead: a values column, a year column of YYYY-01-01 00:00:00 strings, and rows sorted by the dimensions and then the year.

as_polars async #

as_polars(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pl.DataFrame

Return the resource as a Polars DataFrame.

as_arrow async #

as_arrow(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> pa.Table

Return the resource as a PyArrow table.

as_scmrun async #

as_scmrun(*, year_min: int | None = None, year_max: int | None = None, **filters: str) -> ScmRun

Return timeseries data as an scmdata ScmRun.

scmdata rejects rows with duplicate metadata.

fetch async #

fetch() -> bytes

Return verified bytes, using memory proportional to the resource size.

Use as_path() to stream large resources without loading them into memory.

as_path async #

as_path() -> Path

Stream and verify the resource, then return its cached path.

query async #

query(*, select: str | None = None, order: str | None = None, year_min: int | None = None, year_max: int | None = None, drop_constant: bool = False, top_n: int | None = None, limit: int | None = None, offset: int | None = None, **filters: str) -> pd.DataFrame

Return book scoped data filtered and trimmed on the server.

Timeseries go through the book timeseries endpoint, which truncates at its row limit.

as_resource #

as_resource() -> AsyncResource

Drop book context and return the lean async resource handle.

facets async #

facets(*, max_values: int = _FACET_MAX_VALUES, **filters: str) -> models.FacetsResponse

Return book scoped facet values.

preview async #

preview(*, limit: int = 100, offset: int = 0) -> models.PreviewResponse

Return a book scoped tabular preview.

schema async #

schema(*, limit: int = 100, offset: int = 0) -> models.TimeseriesMetadataResponse

Return book scoped timeseries schema metadata.