syft.core.pointer.pointer¶

A Pointer is the main handler when interacting with remote data. A Pointer object represents an API for interacting with data (of any type) at a specific location. The pointer should never be instantiated, only subclassed.

The relation between pointers and data is many to one, there can be multiple pointers pointing to the same piece of data, meanwhile, a pointer cannot point to multiple data sources.

A pointer is just an object id on a remote location and a set of methods that can be executed on the remote machine directly on that object. One note that has to be made is that all operations between pointers will return a pointer, the only way to have access to the result is by calling .get() on the pointer.

There are two proper ways of receiving a pointer on some data:

When sending that data on a remote machine the user receives a pointer.
When the user searches for the data in an object store it receives a pointer to that data, if it has the correct permissions for that.

After receiving a pointer, one might want to get the data behind the pointer locally. For that the user should:

Request access by calling .request().

Example:

pointer_object.request(name = "Request name", reason = "Request reason")

The data owner has to approve the request (check the domain node docs).
The data user checks if the request has been approved (check the domain node docs).
After the request has been approved, the data user can call .get() on the pointer to get the data locally.

Example:

pointer_object.get()

Pointers are being generated for most types of objects in the data science scene, but what you can do on them is not the pointers job, see the lib module for more details. One can see the pointer as a proxy to the actual data, the filtering and the security being applied where the data is being held.

Example:

# creating the data holder domain
domain_1 = Domain(name="Data holder domain")

# creating dummy data
tensor = th.tensor([1, 2, 3])

# creating the data holder client
domain_1_client = domain_1.get_root_client()

# sending the data to the client and receiving a pointer of that data.
data_ptr_domain_1 = tensor.send(domain_1_client)

# creating the data user domain
domain_2 = Domain(name="Data user domain")

# creating a request to access the data
data_ptr_domain_1.request(
    name="My Request", reason="I'd lke to see this pointer"
)

# getting the remote id of the object
requested_object = data_ptr_domain_1.id_at_location

# getting the request id
message_request_id = domain_1_client.requests.get_request_id_from_object_id(
    object_id=requested_object
)

# the data holder accepts the request
domain_1.requests[0].owner_client_if_available = domain_1_client
domain_1.requests[0].accept()

# the data user checks if the data holder approved his request
response = data_ptr_domain_1.check_access(node=domain_2, request_id=message_request_id)

Classes

Pointer(client[, id_at_location, ...])

The pointer is the handler when interacting with remote data.

class syft.core.pointer.pointer.Pointer(client, id_at_location=None, object_type='', tags=None, description='')[source]¶

Bases: syft.core.common.pointer.AbstractPointer

The pointer is the handler when interacting with remote data.

Automatically generated subclasses of Pointer need to be able to look up the path and name of the object type they point to as a part of serde. For more information on how subclasses are automatically generated, please check the ast module.

Parameters

location (Address) – The location where the data is being held.
id_at_location (UID) – The UID of the object on the remote location.

get_copy(request_block=False, timeout_secs=20, reason='', verbose=False)[source]¶

Method to download a remote object from a pointer object if you have the right permissions. Optionally can block while waiting for approval.

Returns: returns the downloaded data
Return type: Optional[StorableObject]

get(request_block=False, timeout_secs=20, reason='', delete_obj=True, verbose=False)[source]¶

Method to download a remote object from a pointer object if you have the right permissions. Optionally can block while waiting for approval.

Returns: returns the downloaded data
Return type: Optional[StorableObject]

static get_protobuf_schema()[source]¶

Return the type of protobuf object which stores a class of this type

As a part of serialization and deserialization, we need the ability to lookup the protobuf object type directly from the object type. This static method allows us to do this.

Importantly, this method is also used to create the reverse lookup ability within the metaclass of Serializable. In the metaclass, it calls this method and then it takes whatever type is returned from this method and adds an attribute to it with the type of this class attached to it. See the MetaSerializable class for details.

Returns: the type of protobuf object which corresponds to this class.
Return type: GeneratedProtocolMessageType

request(reason='', block=False, timeout_secs=None, verbose=False)[source]¶

Method that requests access to the data on which the pointer points to.

Example:

# data holder domain
domain_1 = Domain(name="Data holder")

# data
tensor = th.tensor([1, 2, 3])

# generating the client for the domain
domain_1_client = domain_1.get_root_client()

# sending the data and receiving a pointer
data_ptr_domain_1 = tensor.send(domain_1_client)

# requesting access to the pointer
data_ptr_domain_1.request(name="My Request", reason="Research project.")

Parameters

name (str) – The title of the request that the data owner is going to see.
reason (str) – The description of the request. This is the reason why you want to have access to the data.

Note

This method should be used when the remote data associated with the pointer wants to be downloaded locally (or use .get() on the pointer).

update_searchability(pointable=True, target_verify_key=None, searchable=None)[source]¶

Make the object pointed at pointable or not for other people. If target_verify_key is not specified, the searchability for the VERIFYALL group will be toggled.

Parameters

pointable – If the target object should be made pointable or not.
target_verify_key (Optional[VerifyKey]) – The verify_key of the client to which we want to give search permission.

check_access(node, request_id)[source]¶

Method that checks the status of an already made request. There are three possible outcomes when requesting access:

RequestStatus.Accepted - your request has been approved, you can not .get() your data.
RequestStatus.Pending - your request has not been reviewed yet.
RequestStatus.Rejected - your request has been rejected.

Parameters

node (AbstractNode) – The node that queries the request status.
request_id (UID) – The request on which you are querying the status.

syft.core.pointer

syft.core.remote_dataloader