atomiq.heros ============ .. py:module:: atomiq.heros Attributes ---------- .. autoapisummary:: atomiq.heros.heros atomiq.heros.LocalHERO Classes ------- .. autoapisummary:: atomiq.heros.AtomiqHERO Functions --------- .. autoapisummary:: atomiq.heros.get_heros atomiq.heros.stringify_component Module Contents --------------- .. py:function:: get_heros() To import heros, we have to play tricks here. Since the artiq worker calls our code in the artiq.master.worker_impl.examine function and afterwards removes the imported modules from sys.modules. The PyO3 used for the python zenoh bindings does not like this since then every subsequent `import heros` will reinitialize the PyO3 rust extension, leading to the error PyO3 modules compiled for CPython 3.8 or older may only be initialized once per interpreter process To work around this, we save a reference to the heros module in the sys module and use this reference if it exists. We use the sys module since it should always exist. .. py:data:: heros .. py:data:: LocalHERO .. py:function:: stringify_component(component) Get a stringified version of the component. If just a component is supplied, we return the name, if it is a tuple or list, we assume the first key to be the name and the second one to be the type. .. py:class:: AtomiqHERO(experiment, realm='heros') Bases: :py:obj:`LocalHERO` Base class for objects exposed through HEROS. Any object that should be able to be accessed remotely must be based off this class. :param name: name/identifier under which the object is available. Make sure this name is unique in the realm. :param realm: realm the HERO should exist in. default is "heros" :param implements: list of interfaces that are implemented by the hero :param tags: list of tags to identify and classify the hero .. py:attribute:: name :type: str :value: '' .. py:attribute:: rid :type: int :value: -1 .. py:attribute:: chunksize :value: -1 .. py:attribute:: components :type: tuple[str, ...] :value: () .. py:attribute:: blocks :type: tuple[str, ...] :value: () .. py:attribute:: default_arguments :type: dict[str, dict] | None :value: None .. py:attribute:: git_rev :type: str | None :value: None .. py:attribute:: experiment .. py:property:: step_counter .. py:property:: identifier .. py:property:: steps_total Return the total number of steps. Since this is only available after the prepare stage of the experiment, the method returns -1 if the prepare was not yet run. .. py:method:: terminate() .. py:method:: _set_dataset(*args, **kwargs) Exposes the ARTIQ experiment `set_dataset` function. Note, that using this function is discuraged as using native HEROS data archiving and distribution is more powerful. This function exists to provide compatibility for existing setups to migrate to atomiq more smoothly. .. py:method:: _mutate_dataset(*args, **kwargs) Exposes the ARTIQ experiment `mutate_dataset` function. Note, that using this function is discuraged as using native HEROS data archiving and distribution is more powerful. This function exists to provide compatibility for existing setups to migrate to atomiq more smoothly. .. py:method:: _append_to_dataset(*args, **kwargs) Exposes the ARTIQ experiment `append_to_dataset` function. Note, that using this function is discuraged as using native HEROS data archiving and distribution is more powerful. This function exists to provide compatibility for existing setups to migrate to atomiq more smoothly. .. py:method:: _get_dataset(*args, **kwargs) Exposes the ARTIQ experiment `get_dataset` function. Note, that using this function is discuraged as using native HEROS data archiving and distribution is more powerful. This function exists to provide compatibility for existing setups to migrate to atomiq more smoothly. .. py:method:: _get_dataset_metadata(*args, **kwargs) Exposes the ARTIQ experiment `get_dataset_metadata` function. Note, that using this function is discuraged as using native HEROS data archiving and distribution is more powerful. This function exists to provide compatibility for existing setups to migrate to atomiq more smoothly. .. py:method:: emit_data(data) .. py:attribute:: liveliness_token .. py:method:: _capabilities() Analyze ourself (i.e. the current object) and automatically generate the capabilities of the HERO from this. For every method that doesn't start with _ a method capability is announced. Every defined class attribute becomes an attribute capability. Every method that is defined in the class with the @event decorator becomes an event. While scanning for the capabilities, this method directly creates the necessary callbacks and defines the zenoh queryables for the capabilities. .. py:method:: _destroy_hero() .. py:method:: _connect_local_hero_callback(event, remote_hero_method, origin = None) Connect a method of `RemoteHERO` as a callback to an event of the `LocalHERO`. This leads to a new, direct P2P connection between the `RemoteHERO` and the `LocalHERO` to call the method. :param event: the event `callable`, i.e. a method that is decorated with `@event` in the `LocalHERO`. :param remote_hero_method: `callable` to connect as a callback. :param origin: optional `str` indicating the semantic origin of the connection. :returns: name of the callback. :rtype: str .. py:method:: _disconnect_local_hero_callback(event, remote_hero_method) Disconnect a method of `RemoteHERO` from an event of the `LocalHERO`. :param event: the event `callable`, i.e. a method that is decorated with `@event` in the `LocalHERO`. :param remote_hero_method: `callable` to connect as a callback. :returns: truth value if the remote method was indeed a callback. :rtype: bool .. py:method:: _get_local_hero_callbacks(event) Get a list of dictionary representations of the callbacks of an event of the `LocalHERO`. :param event: the event `callable`, i.e. a method that is decorated with `@event` in the `LocalHERO`. :returns: dictionary representations of the callbacks. :rtype: list .. py:attribute:: _name .. py:attribute:: _endpoint_base_path .. py:attribute:: _endpoints .. py:method:: _query_endpoint(endpoint, *args, **kwargs) Send a query to an endpoint. This is a wrapper for _query_selector that enforces to talk to the endpoint of the remote object. :param endpoint: endpoint within this HERO. If the given endpoint does not start with the endpoint base path, the endpoint base path is prepended to generate a zenoh selector. .. py:method:: _subscribe_endpoint(endpoint, callback, *args, **kwargs) Subscribe to an endpoint of this HERO. This is a wrapper for _subscribe_selector that enforces to talk to the endpoint of the remote object. :param endpoint: endpoint within this HERO. If the given endpoint does not start with the endpoint base path, the endpoint base path is prepended to generate a zenoh selector. :param callback: method to be called for messages that match the selector. The method needs to accept one argument which is the deserialized payload of the message. .. py:attribute:: _ep_discover :value: '_discover' .. py:attribute:: _ep_capabilities :value: '_capabilities' .. py:attribute:: _ep_health :value: '_health' .. py:attribute:: _ns_objects :value: '@object' .. py:attribute:: _default_encoding .. py:attribute:: _realm :value: 'heros' .. py:attribute:: _session_manager .. py:attribute:: _session .. py:attribute:: _subscriptions :value: [] .. py:attribute:: _queryables :value: [] .. py:method:: _query_selector(*args, **kwargs) Send a query to an endpoint and deserialize the results. This is a low-level function. :param selector: The zenoh selector. :param target: zenoh target for the query :param timeout: timeout for the zenoh get command :returns: list of deserialized results :rtype: list .. py:method:: _subscribe_selector(selector, callback, *args, **kwargs) Subscribe to a zenoh selector and a attach a callback. The callback receives the deserialized payload of the messages published. :param selector: zenoh selector for the subscription. See the zenoh documentation for valid descriptors. :param callback: method to be called for messages that match the selector. The method needs to accept one argument which is the deserialized payload of the message. .. py:method:: _declare_queryable(selector, callback) .. py:method:: _get_object_info(object_name, timeout = 2.0) Retrieve the object information for a HERO in the current realm and with the given name. :param object_name: name of the HERO to get the object info for. This name is inserted into a zenoh key expression and can thus contain the corresponding wildcards. :param timeout: timeout for the discover operation in seconds (default: 2) :returns: {remote_object_descriptor}} :rtype: dict of the form {name .. py:method:: _discover(timeout = 2.0) Send query to discovery endpoint of all HEROs in the current realm. All alive objects will respond and send their remote object descriptor. :param timeout: timeout for the discover operation in seconds (default: 2) :returns: {remote_object_descriptor}} :rtype: dict of the form {name .. py:method:: _serialize(obj) Serialize the given object using the serializer used for this HEROPeer. Currently only CBOR is supported. :param obj: The object to serialized. Currently only built-in types and numpy arrays are supported. .. py:method:: _deserialize(bytes) Deserialize the given byte string using the deserializer used for this HEROPeer. Currently only CBOR is supported. :param bytes: bytearray to deserialize. .. py:method:: __enter__() .. py:method:: __exit__(exc_type, exc_val, exc_tb) .. py:method:: __del__()