Place¶

class wwt_data_formats.place.Place(**kwargs: Any)[source]¶

Bases: LockedXmlTraits, UrlContainer

A place that can be visited.

Attributes Summary

`angle`	A float trait.
`angular_size`	A float trait.
`annotation`	Annotation metadata for the place.
`background_image_set`	A trait whose value must be an instance of a specified class.
`classification`	Use a Enum class as model for the data type description.
`constellation`	The constellation associated with this place's sky position, if it has one.
`cross_validation_lock`	A contextmanager for running a block with our cross validation lock set to True.
`data_set_type`	Use a Enum class as model for the data type description.
`dec_deg`	A float trait.
`description`	A description of the place, using HTML markup.
`distance`	A float trait.
`dome_alt`	A float trait.
`dome_az`	A float trait.
`foreground_image_set`	A trait whose value must be an instance of a specified class.
`image_set`	A trait whose value must be an instance of a specified class.
`latitude`	A float trait.
`longitude`	A float trait.
`magnitude`	A float trait.
`msr_community_id`	The ID number of the WWT Community that this content came from.
`msr_component_id`	The ID number of this content item on the WWT Communities system.
`name`	A trait for unicode strings.
`opacity`	A float trait.
`permission`	TBD.
`ra_hr`	A float trait.
`rmeta`	Runtime metadata - a namespace object for attaching arbitrary extra information
`rotation_deg`	A float trait.
`thumbnail`	A trait for unicode strings.
`xmeta`	XML metadata - a namespace object for attaching arbitrary text to serialize
`zoom_level`	A float trait.

Methods Summary

`add_traits`(**traits)	Dynamically add trait attributes to the HasTraits instance.
`apply_to_xml`(elem)	Serialize the data of this object to an existing XML tree
`as_imageset`()	Return an ImageSet for this place if one is defined.
`class_own_trait_events`(name)	Get a dict of all event handlers defined on this class, not a parent.
`class_own_traits`(**metadata)	Get a dict of all the traitlets defined on this class, not a parent.
`class_trait_names`(**metadata)	Get a list of all the names of this class' traits.
`class_traits`(**metadata)	Get a `dict` of all the traits of this class.
`from_file`(path[, encoding])	Deserialize an instance of this class from an XML file on local disk.
`from_text`(text)	Deserialize an instance of this class from XML-formatted text.
`from_url`(url[, session])	Deserialize an instance of this class from XML downloaded from the specified URL.
`from_xml`(elem)	Deserialize an instance of this class from XML.
`has_trait`(name)	Returns True if the object has a trait with the specified name.
`hold_trait_notifications`()	Context manager for bundling trait change notifications and cross validation.
`mutate_urls`(mutator)	Visit all URLs inside this container and potentially mutate them.
`notify_change`(change)	Notify observers of a change event
`observe`(handler[, names, type])	Setup a handler to be called when a trait changes.
`on_trait_change`([handler, name, remove])	DEPRECATED: Setup a handler to be called when a trait changes.
`set_ra_dec`(ra_hr, dec_deg)	Update the sky coordinates associated with this Place and associated metadata.
`set_trait`(name, value)	Forcibly sets trait attribute, including read-only attributes.
`setup_instance`(**kwargs)	This is called before self.__init__ is called.
`to_xml`()	Serialize this object to XML.
`to_xml_string`([indent])	Serialize this object to XML text.
`trait_defaults`(names, *metadata)	Return a trait's default value or a dictionary of them
`trait_events`([name])	Get a `dict` of all the event handlers of this class.
`trait_has_value`(name)	Returns True if the specified trait has a value.
`trait_metadata`(traitname, key[, default])	Get metadata values for trait by key.
`trait_names`(**metadata)	Get a list of all the names of this class' traits.
`trait_values`(**metadata)	A `dict` of trait names and their values.
`traits`(**metadata)	Get a `dict` of all the traits of this class.
`unobserve`(handler[, names, type])	Remove a trait change handler.
`unobserve_all`([name])	Remove trait change handlers of any type for the specified name.
`update_constellation`()	Update the constellation associated with this Place to agree with its current RA and declination, if set.
`write_xml`(dest_stream[, dest_wants_bytes, ...])	Serialize this object to XML, writing the data to a stream.

Attributes Documentation

angle¶: A float trait.

angular_size¶: A float trait.

annotation¶

Annotation metadata for the place.

This field is only used in the web engine and web client app. The web client app expects this field to contain a comma-separated list of key-value pairs, where each pair is delimited with colons:

key1:val1,key2:val2,key3:val3

The webclient includes some unfinished support for this field to be used to create circular annotations with YouTube video links. If your WTML file will not be viewed in the webclient, you can use this field to convey arbitrary textual data to the WWT Web Engine JavaScript/TypeScript layer.

background_image_set¶

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

classification¶

Use a Enum class as model for the data type description. Note that if no default-value is provided, the first enum-value is used as default-value.

# -- SINCE: Python 3.4 (or install backport: pip install enum34)
import enum
from traitlets import HasTraits, UseEnum

class Color(enum.Enum):
    red = 1  # -- IMPLICIT: default_value
    blue = 2
    green = 3

class MyEntity(HasTraits):
    color = UseEnum(Color, default_value=Color.blue)

entity = MyEntity(color=Color.red)
entity.color = Color.green  # USE: Enum-value (preferred)
entity.color = "green"  # USE: name (as string)
entity.color = "Color.green"  # USE: scoped-name (as string)
entity.color = 3  # USE: number (as int)
assert entity.color is Color.green

constellation¶: The constellation associated with this place’s sky position, if it has one. Use set_ra_dec() to compute this correctly (according to WWT).

cross_validation_lock¶

A contextmanager for running a block with our cross validation lock set to True.

At the end of the block, the lock’s value is restored to its value prior to entering the block.

data_set_type¶

Use a Enum class as model for the data type description. Note that if no default-value is provided, the first enum-value is used as default-value.

# -- SINCE: Python 3.4 (or install backport: pip install enum34)
import enum
from traitlets import HasTraits, UseEnum

class Color(enum.Enum):
    red = 1  # -- IMPLICIT: default_value
    blue = 2
    green = 3

class MyEntity(HasTraits):
    color = UseEnum(Color, default_value=Color.blue)

entity = MyEntity(color=Color.red)
entity.color = Color.green  # USE: Enum-value (preferred)
entity.color = "green"  # USE: name (as string)
entity.color = "Color.green"  # USE: scoped-name (as string)
entity.color = 3  # USE: number (as int)
assert entity.color is Color.green

dec_deg¶: A float trait.

description¶

A description of the place, using HTML markup.

This field is not actually used in the stock WWT clients, but it is wired up and loaded from the XML.

distance¶: A float trait.

dome_alt¶: A float trait.

dome_az¶: A float trait.

foreground_image_set¶

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

image_set¶

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

latitude¶: A float trait.

longitude¶: A float trait.

magnitude¶: A float trait.

msr_community_id¶: The ID number of the WWT Community that this content came from.

msr_component_id¶: The ID number of this content item on the WWT Communities system.

name¶: A trait for unicode strings.

opacity¶: A float trait.

permission¶: TBD.

ra_hr¶: A float trait.

rmeta¶: Runtime metadata - a namespace object for attaching arbitrary extra information

rotation_deg¶: A float trait.

thumbnail¶: A trait for unicode strings.

xmeta¶: XML metadata - a namespace object for attaching arbitrary text to serialize

zoom_level¶: A float trait.

Methods Documentation

add_traits(**traits: Any) → None¶: Dynamically add trait attributes to the HasTraits instance.

apply_to_xml(elem)¶

Serialize the data of this object to an existing XML tree

Parameters:

elemxml.etree.ElementTree.Element: An XML subtree that will be filled in with data values associated with this instance.

Returns:

self

Notes

This method makes it possible to work with input data that may have additional contents not defined in the WWT specification – by modifying the existing tree, we can preserve those data.

as_imageset()[source]¶

Return an ImageSet for this place if one is defined.

Returns:

Either wwt_data_formats.imageset.ImageSet or None.

Notes

If the foreground_image_set of this Place is not None, it is returned. Otherwise, if its image_set is not None, that is returned. Otherwise, None is returned.

classmethod class_own_trait_events(name: str) → dict[str, EventHandler]¶

Get a dict of all event handlers defined on this class, not a parent.

Works like event_handlers, except for excluding traits from parents.

classmethod class_own_traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]¶

Get a dict of all the traitlets defined on this class, not a parent.

Works like class_traits, except for excluding traits from parents.

classmethod class_trait_names(**metadata: Any) → list[str]¶

Get a list of all the names of this class’ traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]¶

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

classmethod from_file(path, encoding='utf-8-sig')¶

Deserialize an instance of this class from an XML file on local disk.

Parameters:

pathstring: The path of the XML file.
encodingoptional string, default “utf-8-sig”: The encoding of the file text. The default value is basically UTF-8 but will ignore Windows Byte Order Markers (BOMs) if present.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_text(text)¶

Deserialize an instance of this class from XML-formatted text.

Parameters:

textstring: The XML text.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_url(url, session=None, **kwargs)¶

Deserialize an instance of this class from XML downloaded from the specified URL.

Parameters:

urlstring: The URL from which to download the XML.
sessionrequests session or None (the default): The HTTP communications session to use.
kwargs: Extra arguments to pass to requests.get.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_xml(elem)¶

Deserialize an instance of this class from XML.

Parameters:

elemxml.etree.ElementTree.Element: An XML element serializing the object.

Returns:

An instance of the class, initialized with data from the XML.

has_trait(name: str) → bool¶: Returns True if the object has a trait with the specified name.

hold_trait_notifications() → Any¶

Context manager for bundling trait change notifications and cross validation.

Use this when doing multiple trait assignments (init, config), to avoid race conditions in trait notifiers requesting other trait values. All trait notifications will fire after all values have been assigned.

mutate_urls(mutator)[source]¶

Visit all URLs inside this container and potentially mutate them.

Parameters:

mutatorcallable(str) -> str: A function taking a URL string and returning a URL string.

Notes

For each URL inside the container, the URL is updated with the mutator’s return value:

this.some_url = mutator(this.some_url)

If you just want to visit all of the URLs inside this container, you can write a mutator the returns its input unmodified.

Implementors should not call the mutator if the URL is an optional parameter that is None (or otherwise unset).

notify_change(change: Bunch) → None¶: Notify observers of a change event

observe(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None¶

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Parameters:

handlercallable: A callable that is called when a trait changes. Its signature should be handler(change), where change is a dictionary. The change dictionary at least holds a ‘type’ key. * type: the type of notification. Other keys may be passed depending on the value of ‘type’. In the case where type is ‘change’, we also have the following keys: * owner : the HasTraits instance * old : the old value of the modified trait attribute * new : the new value of the modified trait attribute * name : the name of the modified trait attribute.
nameslist, str, All: If names is All, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
typestr, All (default: ‘change’): The type of notification to filter by. If equal to All, then all notifications are passed to the observe handler.

on_trait_change(handler: EventHandler | None = None, name: Sentinel | str | None = None, remove: bool = False) → None¶

DEPRECATED: Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

If remove is True and handler is not specified, all change handlers for the specified name are uninstalled.

Parameters:

handlercallable, None: A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new), handler(name, old, new), or handler(name, old, new, self).
namelist, str, None: If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
removebool: If False (the default), then install the handler. If True then unintall it.

set_ra_dec(ra_hr, dec_deg)[source]¶

Update the sky coordinates associated with this Place and associated metadata.

Parameters:

ra_hrnumber: The right ascension, in hours
dec_degnumber: The declination, in degrees

Returns:

Self, for chaining.

Notes

Beyond simply setting the associated fields, this method will set the data_set_type to Sky, compute the correct setting for constellation, and clear latitude and longitude. The constellation computation is done by emulating WWT’s internal computation, which may give different results than other methods in (literal) corner cases. In cases where precision matters and WWT compatibility does not, astropy.coordinates.get_constellation() should be preferred.

set_trait(name: str, value: Any) → None¶: Forcibly sets trait attribute, including read-only attributes.

setup_instance(**kwargs: Any) → None¶: This is called before self.__init__ is called.

to_xml()¶

Serialize this object to XML.

Returns:

elemxml.etree.ElementTree.Element: An XML element serializing the object.

to_xml_string(indent=True)¶

Serialize this object to XML text.

Parameters:

indentoptional bool, default True: Whether the returned XML text will have user-friendly indentation or not.

Returns:

xml_textstring: A textual serialization of the object as XML.

trait_defaults(*names: str, **metadata: Any) → dict[str, Any] | Sentinel¶

Return a trait’s default value or a dictionary of them

Notes

Dynamically generated default values may depend on the current state of the object.

classmethod trait_events(name: str | None = None) → dict[str, EventHandler]¶

Get a dict of all the event handlers of this class.

Parameters:

namestr (default: None): The name of a trait of this class. If name is None then all the event handlers of this class will be returned instead.

Returns:

The event handlers associated with a trait name, or all event handlers.

trait_has_value(name: str) → bool¶

Returns True if the specified trait has a value.

This will return false even if getattr would return a dynamically generated default value. These default values will be recognized as existing only after they have been generated.

Example

class MyClass(HasTraits):
    i = Int()

mc = MyClass()
assert not mc.trait_has_value("i")
mc.i  # generates a default value
assert mc.trait_has_value("i")

trait_metadata(traitname: str, key: str, default: Any | None = None) → Any¶: Get metadata values for trait by key.

trait_names(**metadata: Any) → list[str]¶: Get a list of all the names of this class’ traits.

trait_values(**metadata: Any) → dict[str, Any]¶

A dict of trait names and their values.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

Returns:

A dict of trait names and their values.

Notes

Trait values are retrieved via getattr, any exceptions raised by traits or the operations they may trigger will result in the absence of a trait value in the result dict.

traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]¶

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

unobserve(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None¶

Remove a trait change handler.

This is used to unregister handlers to trait change notifications.

Parameters:

handlercallable: The callable called when a trait attribute changes.
nameslist, str, All (default: All): The names of the traits for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all changes.
typestr or All (default: ‘change’): The type of notification to filter by. If All, the specified handler is uninstalled from the list of notifiers corresponding to all types.

unobserve_all(name: str | Any = traitlets.All) → None¶: Remove trait change handlers of any type for the specified name. If name is not specified, removes all trait notifiers.

update_constellation()[source]¶

Update the constellation associated with this Place to agree with its current RA and declination, if set.

Returns:

Self, for chaining.

Notes

If this object has a data_set_type of Sky, this method will update constellation to be correct given its ra_hr and dec_deg, and clear latitude and longitude. Otherwise, the constellation, RA, and Dec will be cleared.

The constellation computation is done by emulating WWT’s internal computation, which may give different results than other methods in (literal) corner cases. In cases where precision matters and WWT compatibility does not, astropy.coordinates.get_constellation() should be preferred.

write_xml(dest_stream, dest_wants_bytes=False, indent=True)¶

Serialize this object to XML, writing the data to a stream.

Parameters:

dest_streamwriteable file-like object or None: The destination to which the XML data will be written. If None, standard output is used.
dest_wants_bytesoptional bool, default False: Whether the destination stream expects to be fed bytes data rather than Unicode. If so, the XML text is encoded into UTF-8 before being written.
indentbool, default True: Whether the returned XML text will have user-friendly indentation or not.

Returns:

None

Place¶

Page Contents

Previous topic

Next topic

This Page

Navigation

Place¶