Foundry Platform SDK

[!WARNING] This SDK is incubating and subject to change.

The Foundry Platform SDK is a Python SDK built on top of the Foundry API. Review Foundry API documentation for more details.

[!NOTE] This Python package is automatically generated using the OpenAPI Generator tool.

Foundry Platform SDK vs. Ontology SDK

Palantir provides two different Python Software Development Kits (SDKs) for interacting with Foundry. Make sure to choose the correct SDK for your use case. As a general rule of thumb, any applications which leverage the Ontology should use the Ontology SDK for a superior development experience.

[!IMPORTANT] Make sure to understand the difference between the Foundry SDK and the Ontology SDK. Review this section before continuing with the installation of this library.

Ontology SDK

The Ontology SDK allows you to access the full power of the Ontology directly from your development environment. You can generate the Ontology SDK using the Developer Console, a portal for creating and managing applications using Palantir APIs. Review the Ontology SDK documentation for more information.

Foundry Platform SDK

The Foundry Platform Software Development Kit (SDK) is generated from the Foundry API's OpenAPI specification file (see openapi.yml). The intention of this SDK is to encompass endpoints related to interacting with the platform itself. Although there are Ontology services included by this SDK, this SDK surfaces endpoints for interacting with Ontological resources such as object types, link types, and action types. In contrast, the OSDK allows you to interact with objects, links and Actions (for example, querying your objects, applying an action).

Installation

You can install the Python package using pip:

pip install foundry-platform-sdk

Then, import the package:

import foundry

Authorization and client initalization

There are two options for authorizing the SDK.

User token

[!WARNING] User tokens are associated with your personal Foundry user account and must not be used in production applications or committed to shared or public code repositories. We recommend you store test API tokens as environment variables during development. For authorizing production applications, you should register an OAuth2 application (see OAuth2 Client below for more details).

You can pass in the hostname and token as keyword arguments when initializing the UserTokenAuth:

foundry_client = foundry.FoundryClient(
    auth=foundry.UserTokenAuth(
        hostname="example.palantirfoundry.com",
        token=os.environ["BEARER_TOKEN"],
    ),
    hostname="example.palantirfoundry.com",
)

OAuth2 Client

OAuth2 clients are the recommended way to connect to Foundry in production applications. Currently, this SDK natively supports the client credentials grant flow. The token obtained by this grant can be used to access resources on behalf of the created service user. To use this authentication method, you will first need to register a third-party application in Foundry by following the guide on third-party application registration.

To use the confidential client functionality, you first need to contstruct a ConfidentialClientAuth object and initiate the sign-in process using the sign_in_as_service_user method. As these service user tokens have a short lifespan, we automatically retry all operations one time if a 401 (Unauthorized) error is thrown after refreshing the token.

auth = foundry.ConfidentialClientAuth(
    client_id=os.environ["CLIENT_ID"],
    client_secret=os.environ["CLIENT_SECRET"],
    hostname="example.palantirfoundry.com",
    scopes=["api:read-data"],
)

auth.sign_in_as_service_user()

[!IMPORTANT] Make sure to select the appropriate scopes when initializating the ConfidentialClientAuth. You can find the relevant scopes in the endpoint documentation.

After creating the ConfidentialClientAuth object, pass it in to the FoundryClient,

foundry_client = foundry.FoundryClient(auth=auth, hostname="example.palantirfoundry.com")

Quickstart

Follow the installation procedure and determine which authentication method is best suited for your instance before following this example. For simplicity, the UserTokenAuth class will be used for demonstration purposes.

import time
import foundry
from foundry.rest import ApiException
from foundry import FoundryClient
from foundry import UserTokenAuth
from pprint import pprint

foundry_client = FoundryClient(auth=UserTokenAuth(...), hostname="example.palantirfoundry.com")

dataset_rid = 'ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da' # str | The Resource Identifier (RID) of the Dataset that contains the Transaction.
transaction_rid = 'ri.foundry.main.transaction.abffc380-ea68-4843-9be1-9f44d2565496' # str | The Resource Identifier (RID) of the Transaction.

try:
    api_response = foundry_client.datasets.abort_transaction(dataset_rid, transaction_rid)
    print("The response of DatasetsApiServiceApi -> abort_transaction:\n")
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DatasetsApiServiceApi -> abort_transaction: %s\n" % e)

Want to learn more about this Foundry SDK library? Review the following sections.

↳ Error handling: Learn more about HTTP & data validation error handling

↳ Static type analysis: Learn about the static type analysis capabilities of this library

Error handling

Data validation

The SDK employs Pydantic for runtime validation of arguments. In the example below, we are passing in a number to transactionRid which should actually be a string type:

foundry_client.datasets.create_branch(
    "ri.foundry.main.dataset.abc",
    # Alternatively, you could have passed in a dict {"branchId": "123", "transactionRid": 123}
    create_branch_request=CreateBranchRequest(branchId="123", transactionRid=123),
)

If you did this, you would receive an error that looks something like:

pydantic_core._pydantic_core.ValidationError: 1 validation error for CreateBranchRequest
transactionRid
    Input should be a valid string [type=string_type, input_value=123, input_type=int]
    For further information visit https://errors.pydantic.dev/2.5/v/string_type

To handle these errors, you can catch pydantic.ValidationError. To learn more, see the Pydantic error documentation.

[!TIP] Pydantic works with static type checkers such as pyright for an improved developer experience. See Static Type Analysis below for more information.

HTTP exceptions

When an HTTP error status is returned, a PalantirRPCException is thrown. All HTTP error exception classes inherit from ApiException.

from foundry import PalantirRPCException


try:
    api_response = foundry_client.datasets.abort_transaction(dataset_rid, transaction_rid)
    ...
except PalantirRPCException as e:
    print("Another HTTP exception occurred: " + str(e))

This exception will have the following properties. See the Foundry API docs for details about the Foundry error information.

Static type analysis

This library uses Pydantic for creating data models which you will see in the method definitions (see Documentation for Models below for a full list of models). For example, here is how create_branch method is defined in the dataset service:

    def create_branch(
        self,
        dataset_rid: Annotated[StrictStr, Field(description="The Resource Identifier (RID) of the Dataset on which to create the Branch.")],
        create_branch_request: CreateBranchRequest,
        ...
    ) -> Branch:
        ...

If you are using a static type checker (for example, mypy, pyright), you get static type analysis for the arguments you provide to the function and with the response. For example, if you pass an int to branchId while calling create_branch and then try to access branchId in returned Branch object (the property is actually called branch_id), you will get the following errors:

branch = foundry_client.datasets.create_branch(
    "ri.foundry.main.dataset.abc",
    create_branch_request=CreateBranchRequest(
        # ERROR: Argument of type "Literal[123]" cannot be assigned to parameter "branchId" of type "StrictStr" in function "__init__"
        branchId=123
    ),
)
# ERROR: Cannot access member "branchId" for type "Branch"
print(branch.branchId)

[!IMPORTANT] For static type analysis to work when passing in a request body, you must use the class instead of passing in a dictionary.

Common errors

This section will document any user-related errors with information on how you may be able to resolve them.

ApiFeaturePreviewUsageOnly

This error indicates you are trying to use an endpoint in public preview and have not set preview=True when calling the endpoint. Before doing so, note that this endpoint is in preview state and breaking changes may occur at any time.

During the first phase of an endpoint's lifecycle, it may be in Public Preview state. This indicates that the endpoint is in development and is not intended for production use.

Documentation for API endpoints

Documentation for models

• ActionParameterArrayType
• ActionParameterType
• ActionParameterV2
• ActionType
• ActionTypeV2
• AnyType
• AttachmentType
• BinaryType
• BooleanType
• Branch
• ByteType
• CreateBranchRequest
• CreateDatasetRequest
• CreateLinkRule
• CreateObjectRule
• CreateTransactionRequest
• Dataset
• DateType
• DecimalType
• DeleteLinkRule
• DeleteObjectRule
• DeploymentApi
• DeploymentListing
• DeploymentMetadata
• DeploymentTransformApi
• DoubleType
• File
• FloatType
• GeoPoint
• GeoPointType
• GeoShapeType
• Geometry
• GeometryCollection
• IntegerType
• LineString
• LinkTypeSide
• LinkTypeSideCardinality
• LinkTypeSideV2
• ListActionTypesResponse
• ListActionTypesResponseV2
• ListBranchesResponse
• ListDeploymentsResponse
• ListFilesResponse
• ListObjectTypesResponse
• ListObjectTypesV2Response
• ListOntologiesResponse
• ListOntologiesV2Response
• ListOutgoingLinkTypesResponse
• ListOutgoingLinkTypesResponseV2
• ListQueryTypesResponse
• ListQueryTypesResponseV2
• LogicRule
• LongType
• ModelApiArrayType
• ModelApiDataType
• ModelApiMapType
• ModelApiStructField
• ModelApiStructType
• ModelApiType
• ModelApiUnionType
• ModelProperty
• ModifyObjectRule
• MultiLineString
• MultiPoint
• MultiPolygon
• NullType
• ObjectPropertyType
• ObjectType
• ObjectTypeV2
• ObjectTypeVisibility
• ObjectTypeWithLink
• Ontology
• OntologyArrayType
• OntologyDataType
• OntologyFullMetadata
• OntologyMapType
• OntologyObjectArrayType
• OntologyObjectSetType
• OntologyObjectType
• OntologySetType
• OntologyStructField
• OntologyStructType
• OntologyV2
• Parameter
• Polygon
• PropertyV2
• QueryAggregationKeyType
• QueryAggregationRangeSubType
• QueryAggregationRangeType
• QueryAggregationValueType
• QueryArrayType
• QueryDataType
• QueryParameterV2
• QuerySetType
• QueryStructField
• QueryStructType
• QueryType
• QueryTypeV2
• QueryUnionType
• ReleaseStatus
• ShortType
• StringType
• TableExportFormat
• ThreeDimensionalAggregation
• TimeSeriesItemType
• TimeseriesType
• TimestampType
• Transaction
• TransactionStatus
• TransactionType
• TwoDimensionalAggregation
• UnsupportedType

Contributions

This repository does not accept code contributions.

If you have any questions, concerns, or ideas for improvements, create an issue with Palantir Support.

License

This project is made available under the Apache 2.0 License.