HandleClient

class wwt_api_client.constellations.handles.HandleClient(client: CxClient, handle: str)

Bases: object

A client for the WWT Constellations APIs calls related to a specific handle.

Parameters:

clientCxClient

The parent client for making API calls.

handle: :class:`str`

The handle to use for the API calls.

Methods Summary

add_image(image)	Add a new image owned by this handle.
add_image_from_set(imageset, copyright, ...)	Add a new Constellations image derived from a wwt_data_formats.imageset.ImageSet object.
add_scene(scene)	Add a new scene owned by this handle.
add_scene_from_place(place[, publish])	Add a new scene derived from a wwt_data_formats.place.Place object.
get()	Get basic information about this handle.
get_timeline(page_num)	Get information about a group of scenes on this handle's timeline.
image_info(page_num[, page_size])	Get administrative info about images belonging to this handle.
permissions()	Get information about the logged-in user's permissions with regards to this handle.
scene_info(page_num[, page_size])	Get administrative info about scenes belonging to this handle.
stats()	Get some statistics about this handle.
update(updates)	Update various attributes of this handle.

Methods Documentation

add_image(image: AddImageRequest) → str

Add a new image owned by this handle.

Returns:

The Constellations ID of the newly-created image, as a string.

Notes

This method corresponds to the POST /handle/:handle/image API endpoint.

add_image_from_set(imageset: ImageSet, copyright: str, license_spdx_id: str, note: str | None = None, credits: str | None = None, alt_text: str | None = None) → str

Add a new Constellations image derived from a wwt_data_formats.imageset.ImageSet object.

Parameters:

imagesetwwt_data_formats.imageset.ImageSet

The WWT imageset.

copyrightstr

The copyright statement for this image. Preferred form is along the lines of “Copyright 2020 Henrietta Swan Leavitt” or “Public domain”. Please provide support in higher-level applications to allow users to input valid information here — the correct information for this field cannot be determined algorithmically. Note that under the world’s current regime of intellectual property law, virtually every single image in WWT can be presumed to be copyrighted, with the major exception of images produced by employees of the US Federal government in the course of their duties.

license_spdx_idstr

The SPDX License Identifier of the license under which this image is made available through WWT. Use CC-PDDC for images in the public domain. For images with known licenses that are not in the SPDX list, use LicenseRef-$TEXT for some value of $TEXT; see the Other licensing information detected section of the SPDX specification.

noteoptional str, default None

An internal note used to describe this image. This is not shown publicly. If unspecified, a default note is constructed from the imageset name and, if present, the credits URL.

creditsoptional str of restricted HTML text, default None

Credits text for the image. If provided, this field should be encoded as HTML, with a limited set of tags (including <a> for hyperlinks) allowed. If unspecified, the credits field of the imageset is used. It will have HTML special characters (<, >, and &) escaped, under the assumption that its contents do not include any markup.

alt_textoptional str, default None

Optional “alt text” describing this image for visually impaired users. If unspecified, no alt text is provided.

Returns:

The Constellations ID of the newly-created image, as a string.

Notes

Not all of the imageset information is preserved.

add_scene(scene: AddSceneRequest) → str

Add a new scene owned by this handle.

Returns:

The Constellations ID of the newly-created scene, as a string.

Notes

This method corresponds to the POST /handle/:handle/scene API endpoint.

add_scene_from_place(place: Place, publish=True) → str

Add a new scene derived from a wwt_data_formats.place.Place object.

Parameters:

placewwt_data_formats.place.Place

The WWT place

publish: `bool`

Whether or not to publish the newly-created scene

Returns:

The Constellations ID of the newly-created scene, as a string.

Notes

The imagesets referenced by the place must already have been imported into the Constellations framework.

Not all of the Place information is preserved.

get() → HandleInfo

Get basic information about this handle.

Returns:

A HandleInfo object.

Notes

This method corresponds to the GET /handle/:handle API endpoint.

get_timeline(page_num: int) → List[SceneHydrated]

Get information about a group of scenes on this handle’s timeline.

Parameters:

page_numint

Which page to retrieve. Page zero gives the top items on the timeline, page one gives the next set, etc.

Returns:

A list of SceneHydrated

items.

Notes

The page size is not specified externally, nor is it guaranteed to be stable from one page to the next. If you care, look at the length of the list that you get back from an API.

This method corresponds to the GET /handle/:handle/timeline API endpoint.

image_info(page_num: int, page_size: int | None = 10) → List[ImageSummary]

Get administrative info about images belonging to this handle.

Parameters:

page_numint

Which page to retrieve. Page zero gives the most recently-created images, page one gives the next batch, etc.

page_sizeoptinal int, defaults to 10

The number of items per page to retrieve. Valid values are between 1 and 100.

Returns:

A list of ImageSummary

items.

Notes

This method corresponds to the GET /handle/:handle/imageinfo API endpoint. Only administrators of a handle can retrieve the image info. This API returns paginated results.

permissions() → HandlePermissions

Get information about the logged-in user’s permissions with regards to this handle.

Returns:

A HandlePermissions object.

Notes

This method corresponds to the GET /handle/:handle/permissions API endpoint. See that documentation for important guidance about when and how to use this API. In most cases you should not use it, and just go ahead and attempt whatever operation wish to perform.

scene_info(page_num: int, page_size: int | None = 10) → List[SceneInfo]

Get administrative info about scenes belonging to this handle.

Parameters:

page_numint

Which page to retrieve. Page zero gives the most recently-created scenes, page one gives the next batch, etc.

page_sizeoptional int, defaults to 10

The number of items per page to retrieve. Valid values are between 1 and 100.

Returns:

A list of SceneInfo

items.

Notes

This method corresponds to the GET /handle/:handle/sceneinfo API endpoint. Only administrators of a handle can retrieve the scene info. This API returns paginated results.

stats() → HandleStats

Get some statistics about this handle.

Returns:

A HandleStats object.

Notes

This method corresponds to the GET /handle/:handle/stats API endpoint. Only administrators of a handle can retrieve its stats.

update(updates: HandleUpdate)

Update various attributes of this handle.

Returns:

None.

Notes

This method corresponds to the PATCH /handle/:handle API endpoint.