Python OSDK migration guide (1.x to 2.x)

This guide is intended to help you migrate applications using Python OSDK 1.x to Python OSDK 2.x. The sections below explain the differences between the two versions and highlight relevant changes in syntax and structure.

Why upgrade from Python OSDK 1.x to 2.x?

There are three main reasons to upgrade from Python OSDK 1.x to 2.x:

• Shared client used for both Python Platform SDK and OSDK
• Improved return types for queries, links, and aggregations
• Ability to edit your client configuration

Shared client used for both Python Platform SDK and OSDK

Developing with both the OSDK and Platform SDK no longer requires users to manage two separate clients. Users can now access both the Python Platform SDK and OSDK in the same client.

Improved return types for queries, links, and aggregations

• Queries can return Objects, ObjectSets, and Attachments
  • In Python OSDK v1, function queries whose return types were objects, object sets, and Attachments would return the object identifiers for each of these types. For example, if a query returns an Object, in v1, the query would actually return the object primary key as opposed to an instance of said object. Now, queries return an instance of said type.
• Links return ObjectSets or Optional[Objects]
  • One-to-many / many-to-many type links now return ObjectSets and one-to-one / many-to-one type links return Optional[Objects].
  • For one-to-one / many-to-one type links, users no longer need to use .get to retrieve the linked object. The link itself will be the object.
  • For one-to-many / many-to-many type links, all methods available to object sets (such as .page, .where, or .group_by) are now available to these links. In Python OSDK v1, only the methods .iterate and .get were available.
• Aggregations return an AggregateObjectsResponse
  • In Python OSDK v1, aggregation responses were of type dict[str, Any], where the keys were fields such as excluded items, accuracy, data, and so on. With Python OSDK v2, Aggregations now return an instance of AggregateObjectsResponse, whose fields are the same as the v1 dict type, but with improved type safety. The AggregateObjectsResponse in Python OSDK v2 has a .to_dict method, which will return the same response as in v1.

Ability to edit your client configuration

In Python OSDK v1, there was no easy way to edit the client configuration when sending requests. For example, if a user wanted to edit the user-agent of their requests, they would have to access the reserved ._session method on their client in order to do so. To avoid this issue, Python OSDK v2 provides a Config class that users can import and pass into their clients.

This new Config class has the following structure:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class Config:

# Configuration for the HTTP session.


    default_headers: Optional[Dict[str, str]] = ...
    # HTTP headers to include with all requests.

    proxies: Optional[Dict[Literal["http", "https"], str]] = None
    # Proxies to use for HTTP and HTTPS requests.

    timeout: Optional[Union[int, float]] = None
    # The default timeout for all requests in seconds.

    verify: Optional[Union[bool, str]] = True
    # SSL verification, can be a boolean or a path to a CA bundle.

    default_params: Optional[Dict[str, Any]] = None
    # URL query parameters to include with all requests.

    scheme: Literal["http", "https"] = "https"
    # URL scheme to use ('http' or 'https'). Defaults to 'https'.

Python OSDK 1.x (legacy)

Copied!
1
2
3
4
from ontology_sdk import FoundryClient

client = FoundryClient()
client._session._user_agent += "something_new"

Python OSDK 2.x

Copied!
1
2
3
4
5
6
from ontology_sdk import FoundryClient, Config

config = Config()
config.default_headers["User-Agent"] += "something_new"

client = FoundryClient(config=config)

How to upgrade from Python OSDK 1.x to 2.x

You can generate a new SDK version for an existing Developer Console application using the Python OSDK 2.x generator (accessed via the Generate new version button) in the SDK versions tab of your application.

Existing applications must also have the required dependencies to use the newly generated SDK. New applications created in Developer Console will generate SDKs using the Python OSDK 2.x generator by default, and developers can quickly get started by following the instructions in the Start developing tab.

Syntax translations and return type changes from Python OSDK 1.x to 2.x

This section contains simple examples that illustrate how to map between Python OSDK 1.x and 2.x.

Filtering

• Users must include .object_type in the where expression when referencing the property that is being filtered on.
• .is_member_of has been renamed to .in_.
• .starts_with has been renamed to .contains_all_terms_in_order_prefix_last_term.

Filtering with Python OSDK 1.x (legacy)

Copied!
1
client.ontology.object.where(Object.id.is_member_of([1, 2, 3])).take(1)

Filtering with Python OSDK 2.x

Copied!
1
client.ontology.object.where(Object.object_type.id.in_([1, 2, 3])).take(1)

Links

Return type changes

One-to-one or many-to-one links with Python OSDK 1.x (legacy)

In Python OSDK v1, users need to use .get to retrieve the linked object.

Copied!
1
linked_obj: Optional[LinkedObject] = client.ontology.object.linked_object.get()

One-to-many or many-to-many links with Python OSDK 1.x (legacy)

In Python OSDK v1, the only methods available are .iterate and .get.

Copied!
1
2
3
4
linked_obj: ObjectLinkType = client.ontology.object.linked_object

linked_obj.iterate() → Iterable[LinkedObject]
linked_obj.get(1) → Optional[LinkedObject]

One-to-one or many-to-one links with Python OSDK 2.x

In Python OSDK v2, the link itself is a method that returns an instance of the linked object.

Copied!
1
linked_obj: Optional[LinkedObject] = client.ontology.object.linked_object()

One-to-many or many-to-many links with Python OSDK 2.x

In Python OSDK v2, any method available to object sets are now available on links, including .take, .where, and .group_by; this makes it easier to filter, aggregate, and iterate over links.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
linked_obj: LinkedObjectSet = client.ontology.object.linked_object()

# All v1 methods are available

linked_obj.iterate() → Iterable[LinkedObject]
linked_obj.get(1) → Optional[LinkedObject]

# Search, aggregation, iteration is now available

from ontology_sdk.ontology.objects import LinkedObject

result: float = linked_obj.where(LinkedObject.object_type.id > 5).count().compute()

Queries

Return type changes

Object queries with Python OSDK 1.x (legacy)

Copied!
1
2
3
result: float = client.ontology.queries.query_object_output(object_id = 1)
> result
1.0

Object set queries with Python OSDK 1.x (legacy)

Copied!
1
2
3
result: str = client.ontology.queries.query_object_set_output(object_id = 1)
> result
"ri.object-set.main.object-set.e5c05475-8766-4804-9be0-66cf7854de5c"

Attachment queries with Python OSDK 1.x (legacy)

Copied!
1
2
3
result: str = client.ontology.queries.query_attachment_output(object_id = 1)
> result
"ri.attachments.main.attachment.2c1432f8-0378-45f2-8280-55d858cb71fc"

Object queries with Python OSDK 2.x

Copied!
1
2
3
result: Object = client.ontology.queries.query_object_output(object_id = 1)
> result
Object(id = 1)

Object set queries with Python OSDK 2.x

Copied!
1
2
3
result: ObjectSet = client.ontology.queries.query_object_set_output(object_id = 1)
> result
ObjectSet(object_set_definition=...)

Attachment queries with Python OSDK 2.x

Copied!
1
2
3
result: Attachment = client.ontology.queries.query_attachment_output(object_id = 1)
> result
Attachment(rid="ri.attachments.main.attachment.2c1432f8-0378-45f2-8280-55d858cb71fc")

Aggregations

Aggregations that return more than a single value (that is, those derived from .group_by and .aggregate) return AggregateObjectsResponse as opposed to Dict[str, Any]. If you would like to have the Python OSDK v1 response, the AggregateObjectsResponse has a .to_dict method on it, which returns a dictionary representation of the response.

Aggregations with Python OSDK 1.x (legacy)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
result: dict[str, Any] = client.ontology.objects.Object.aggregate({
                             "min_id": Object.object_type.id.min(),
                             "max_id": Object.object_type.id.max()
                         }).compute()
> result

{'accuracy': 'ACCURATE',
 'data': [
    {'group': {},
     'metrics': [
        {'name': 'min_id', 'value': 1.0},
        {'name': 'max_id', 'value': 99.0}
     ]
    }
  ]
}

Aggregations with Python OSDK 2.x

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
result: dict[str, Any] = client.ontology.objects.Object.aggregate({
    "min_id": Object.object_type.id.min(),
    "max_id": Object.object_type.id.max()
}).compute()
> result

AggregateObjectsResponse(
    excluded_items=None,
    accuracy='ACCURATE',
    data=[
        AggregateObjectsResponseItem(
            group={},
            metrics=[
                AggregationMetricResult(name='min_id', value=1.0),
                AggregationMetricResult(name='max_id', value=99.0)
            ]
        )
    ]
)

Property type changes from Python OSDK 1.x to 2.x

• GeoTypes: Point has been renamed GeoPoint.

Error handling

Request exceptions are now imported directly from the python-platform-sdk as opposed to from foundry_sdk_runtime.errors. This includes exceptions such as

• PalantirRPCException
• NotAuthenticated
• EnvironmentNotConfigured

Error handling with Python OSDK 1.x (legacy)

Copied!
1
from foundry_sdk_runtime.errors import PalantirRPCException

Error handling with Python OSDK 2.x

Copied!
1
from foundry import PalantirRPCException

Other differences

ActionResponse

• ActionResponse has been renamed to SyncApplyActionResponse
• BatchActionResponse has been renamed to BatchApplyActionResponse