report_exports

Report export endpoint handlers.

ReportExportsEndpoint

Bases: BaseEndpoint

Handles report export API endpoints.

An export renders a study or project report server-side into a downloadable artifact (a branded PDF, or a markdown bundle). Exports are created against the project or study whose report they render, then polled and downloaded through the user-scoped export lifecycle:

import asyncio

from yousleep_common.models import ReportExportCreate

export = await client.report_exports.create_for_study(
    study_id=study.id,
    export=ReportExportCreate(format="pdf"),
)
while export.status in ("queued", "running"):
    await asyncio.sleep(2)
    export = await client.report_exports.get(export.id)
print(export.download_url)

Creation is idempotent: an identical export that is still live is returned as-is rather than re-rendered, so a fresh create can already be completed with its download_url set. Check status before polling — see the note on each create method.

create_for_project(project_id, export) async

Create an export of a project's report.

The export renders asynchronously: the returned record is normally queued, and :meth:get is the poll target for its status and download URL. Creation is idempotent — when an identical export is still live, that existing export is returned instead of a new one, and it comes back already completed with its download_url set. Check status before polling rather than polling unconditionally.

The artifact carries the audit appendix (which studies and analyses the numbers came from) and expires after a few days, at which point status becomes expired and the download URL is withheld.

Parameters:

Name	Type	Description	Default
project_id	UUID | str	UUID of the project	required
export	ReportExportCreate	Export request (format, optional section layout, optional project report mode via project_params). Omitting project_params — or omitting its by_group — renders the report BY GROUP over every tag, unlike :meth:ProjectsEndpoint.get_report, which is flat by default	required

Returns:

Type	Description
ReportExportOut	The export record — queued, or an identical live export already
ReportExportOut	completed with its download URL

Raises:

Type	Description
NotFoundError	If project doesn't exist
ValidationError	If the export request is invalid
AuthenticationError	If not authenticated

Example

from yousleep_common.models import (
    ReportExportCreate,
    ReportExportProjectParams,
)

export = await client.report_exports.create_for_project(
    project_id=project.id,
    export=ReportExportCreate(
        format="pdf",
        project_params=ReportExportProjectParams(by_group=True),
    ),
)
if export.status == "completed":
    print(export.download_url)  # reused an existing export

create_for_study(study_id, export) async

Create an export of a study's report.

The export renders asynchronously: the returned record is normally queued, and :meth:get is the poll target for its status and download URL. Creation is idempotent — when an identical export is still live, that existing export is returned instead of a new one, and it comes back already completed with its download_url set. Check status before polling rather than polling unconditionally.

The artifact expires after a few days, at which point status becomes expired and the download URL is withheld.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required
export	ReportExportCreate	Export request (format and optional section layout; project_params applies to project exports only)	required

Returns:

Type	Description
ReportExportOut	The export record — queued, or an identical live export already
ReportExportOut	completed with its download URL

Raises:

Type	Description
NotFoundError	If study doesn't exist
ValidationError	If the export request is invalid
AuthenticationError	If not authenticated

Example

from yousleep_common.models import ReportExportCreate

export = await client.report_exports.create_for_study(
    study_id=study.id,
    export=ReportExportCreate(format="md-bundle"),
)

get(export_id) async

Get one report export — the poll target for a created export.

Parameters:

Name	Type	Description	Default
export_id	UUID | str	UUID of the export	required

Returns:

Type	Description
ReportExportOut	The export record; download_url is present only while the
ReportExportOut	export is completed and its artifact has not expired

Raises:

Type	Description
NotFoundError	If the export doesn't exist or belongs to another user
AuthenticationError	If not authenticated

list(limit=20, offset=0, kind=None, format=None) async

List a page of the authenticated user's report exports, newest first.

Parameters:

Name	Type	Description	Default
limit	int	Maximum exports to return; the server clamps it to 1-100	20
offset	int	How many exports to skip, for paging past the first page	0
kind	ReportExportKind | None	Only study or only project exports; None for both	None
format	ReportExportFormat | None	Only exports of this artifact format; None for every one	None

Returns:

Type	Description
ReportExportListResponse	One page of exports, each with a fresh download URL while
ReportExportListResponse	completed and not expired, and total for everything matching
ReportExportListResponse	— narrowed by the filters, so a filtered history pages correctly

Raises:

Type	Description
AuthenticationError	If not authenticated

Example

page = await client.report_exports.list(limit=50)
while page.offset + len(page.exports) < page.total:
    page = await client.report_exports.list(
        limit=50, offset=page.offset + len(page.exports)
    )