The official Python library for the Foundry API

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for palantir-pypi from gravatar.com palantir-pypi

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: Apache Software License (Apache-2.0)
  • Author: Palantir Technologies, Inc.
  • Tags Palantir, Foundry, SDK, Client, API
  • Requires: Python <4.0, >=3.9
Classifiers

Project description

Foundry Platform SDK

Supported Python Versions PyPI Version License

[!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 based on the Foundry API specification.

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 specification file. 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

API Versioning

Every endpoint of the Foundry API is versioned using a version number that appears in the URL. For example, v1 endpoints look like this:

https://<hostname>/api/v1/...

This SDK exposes several clients, one for each major version of the API. For example, the latest major version of the SDK is v2 and is exposed using the FoundryClient located in the foundry.v2 package. To use this SDK, you must choose the specific client (or clients) you would like to use.

More information about how the API is versioned can be found here.

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:

import foundry

foundry_client = foundry.v2.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.

import foundry

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,

import foundry.v2

foundry_client = foundry.v2.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.

from foundry.v1 import FoundryClient
import foundry
from pprint import pprint

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

# DatasetRid | datasetRid
dataset_rid = "ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da"
# BranchId |
branch_id = "my-branch"
# Optional[TransactionRid] |
transaction_rid = None


try:
    api_response = foundry_client.datasets.Dataset.Branch.create(
        dataset_rid,
        branch_id=branch_id,
        transaction_rid=transaction_rid,
    )
    print("The create response:\n")
    pprint(api_response)
except foundry.PalantirRPCException as e:
    print("HTTP error when calling Branch.create: %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
↳ Pagination: Learn how to work with paginated endpoints in the SDK
↳ 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 transaction_rid which should actually be a string type:

foundry_client.datasets.Dataset.Branch.create(
    "ri.foundry.main.dataset.abc",
    name="123",
    transaction_rid=123,
)

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

pydantic_core._pydantic_core.ValidationError: 1 validation error for create
transaction_rid
  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.

from foundry import PalantirRPCException


try:
    api_response = foundry_client.datasets.Transaction.abort(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.

Property Type Description
name str The Palantir error name. See the Foundry API docs.
error_instance_id str The Palantir error instance ID. See the Foundry API docs.
parameters Dict[str, Any] The Palantir error parameters. See the Foundry API docs.

Pagination

When calling any iterator endpoints, we return a Pager class designed to simplify the process of working with paginated API endpoints. This class provides a convenient way to fetch, iterate over, and manage pages of data, while handling the underlying pagination logic.

To iterate over all items, you can simply create a Pager instance and use it in a for loop, like this:

for branch in foundry_client.datasets.Dataset.Branch.list(dataset_rid):
    print(branch)

This will automatically fetch and iterate through all the pages of data from the specified API endpoint. For more granular control, you can manually fetch each page using the associated page methods.

page = foundry_client.datasets.Dataset.Branch.page(dataset_rid)
while page.next_page_token:
    for branch in page.data:
        print(branch)

    page = foundry_client.datasets.Dataset.Branch.page(dataset_rid, page_token=page.next_page_token)

Static type analysis

This library uses Pydantic for creating and validating data models which you will see in the method definitions (see Documentation for Models below for a full list of models). All request parameters with nested models use a TypedDict whereas responses use Pydantic models. For example, here is how Group.search method is defined in the Admin namespace:

    @validate_call
    @handle_unexpected
    def search(
        self,
        *,
        where: GroupSearchFilterDict,
        page_size: Optional[PageSize] = None,
        page_token: Optional[PageToken] = None,
        preview: Optional[PreviewMode] = None,
        request_timeout: Optional[Annotated[StrictInt, Field(gt=0)]] = None,
    ) -> SearchGroupsResponse:
        ...

[!TIP] A Pydantic model can be converted into its TypedDict representation using the to_dict method. For example, if you handle a variable of type Branch and you called to_dict() on that variable you would receive a BranchDict variable.

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 name but name expects a string or if you try to access branchName on the returned Branch object (the property is actually called name), you will get the following errors:

branch = foundry_client.datasets.Dataset.Branch.create(
    "ri.foundry.main.dataset.abc",
    # ERROR: "Literal[123]" is incompatible with "BranchName"
    name=123,
)
# ERROR: Cannot access member "branchName" for type "Branch"
print(branch.branchName)

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 V2 API endpoints

Namespace Resource Operation HTTP request
Admin Group create POST /v2/admin/groups
Admin Group delete DELETE /v2/admin/groups/{groupId}
Admin Group get GET /v2/admin/groups/{groupId}
Admin Group get_batch POST /v2/admin/groups/getBatch
Admin Group list GET /v2/admin/groups
Admin Group page GET /v2/admin/groups
Admin Group search POST /v2/admin/groups/search
Admin GroupMember add POST /v2/admin/groups/{groupId}/groupMembers/add
Admin GroupMember list GET /v2/admin/groups/{groupId}/groupMembers
Admin GroupMember page GET /v2/admin/groups/{groupId}/groupMembers
Admin GroupMember remove POST /v2/admin/groups/{groupId}/groupMembers/remove
Admin GroupMembership list GET /v2/admin/users/{userId}/groupMemberships
Admin GroupMembership page GET /v2/admin/users/{userId}/groupMemberships
Admin User delete DELETE /v2/admin/users/{userId}
Admin User get GET /v2/admin/users/{userId}
Admin User get_batch POST /v2/admin/users/getBatch
Admin User get_current GET /v2/admin/users/getCurrent
Admin User list GET /v2/admin/users
Admin User page GET /v2/admin/users
Admin User profile_picture GET /v2/admin/users/{userId}/profilePicture
Admin User search POST /v2/admin/users/search
Datasets Branch create POST /v2/datasets/{datasetRid}/branches
Datasets Branch delete DELETE /v2/datasets/{datasetRid}/branches/{branchName}
Datasets Branch get GET /v2/datasets/{datasetRid}/branches/{branchName}
Datasets Branch list GET /v2/datasets/{datasetRid}/branches
Datasets Branch page GET /v2/datasets/{datasetRid}/branches
Datasets Dataset create POST /v2/datasets
Datasets Dataset get GET /v2/datasets/{datasetRid}
Datasets Dataset read_table GET /v2/datasets/{datasetRid}/readTable
Datasets File content GET /v2/datasets/{datasetRid}/files/{filePath}/content
Datasets File delete DELETE /v2/datasets/{datasetRid}/files/{filePath}
Datasets File get GET /v2/datasets/{datasetRid}/files/{filePath}
Datasets File list GET /v2/datasets/{datasetRid}/files
Datasets File page GET /v2/datasets/{datasetRid}/files
Datasets File upload POST /v2/datasets/{datasetRid}/files/{filePath}/upload
Datasets Transaction abort POST /v2/datasets/{datasetRid}/transactions/{transactionRid}/abort
Datasets Transaction commit POST /v2/datasets/{datasetRid}/transactions/{transactionRid}/commit
Datasets Transaction create POST /v2/datasets/{datasetRid}/transactions
Datasets Transaction get GET /v2/datasets/{datasetRid}/transactions/{transactionRid}
Filesystem Folder children GET /v2/filesystem/folders/{folderRid}/children
Filesystem Folder children_page GET /v2/filesystem/folders/{folderRid}/children
Filesystem Folder create POST /v2/filesystem/folders
Filesystem Folder get GET /v2/filesystem/folders/{folderRid}
OntologiesV2 Action apply POST /v2/ontologies/{ontology}/actions/{action}/apply
OntologiesV2 Action apply_batch POST /v2/ontologies/{ontology}/actions/{action}/applyBatch
OntologiesV2 ActionTypeV2 get GET /v2/ontologies/{ontology}/actionTypes/{actionType}
OntologiesV2 ActionTypeV2 list GET /v2/ontologies/{ontology}/actionTypes
OntologiesV2 ActionTypeV2 page GET /v2/ontologies/{ontology}/actionTypes
OntologiesV2 Attachment read GET /v2/ontologies/attachments/{attachmentRid}/content
OntologiesV2 Attachment upload POST /v2/ontologies/attachments/upload
OntologiesV2 AttachmentPropertyV2 get_attachment GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}
OntologiesV2 AttachmentPropertyV2 get_attachment_by_rid GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/{attachmentRid}
OntologiesV2 AttachmentPropertyV2 read_attachment GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/content
OntologiesV2 AttachmentPropertyV2 read_attachment_by_rid GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/{attachmentRid}/content
OntologiesV2 LinkedObjectV2 get_linked_object GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType}/{linkedObjectPrimaryKey}
OntologiesV2 LinkedObjectV2 list_linked_objects GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType}
OntologiesV2 LinkedObjectV2 page_linked_objects GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType}
OntologiesV2 ObjectTypeV2 get GET /v2/ontologies/{ontology}/objectTypes/{objectType}
OntologiesV2 ObjectTypeV2 get_outgoing_link_type GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes/{linkType}
OntologiesV2 ObjectTypeV2 list GET /v2/ontologies/{ontology}/objectTypes
OntologiesV2 ObjectTypeV2 list_outgoing_link_types GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes
OntologiesV2 ObjectTypeV2 page GET /v2/ontologies/{ontology}/objectTypes
OntologiesV2 ObjectTypeV2 page_outgoing_link_types GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes
OntologiesV2 OntologyObjectSet aggregate POST /v2/ontologies/{ontology}/objectSets/aggregate
OntologiesV2 OntologyObjectSet load POST /v2/ontologies/{ontology}/objectSets/loadObjects
OntologiesV2 OntologyObjectV2 aggregate POST /v2/ontologies/{ontology}/objects/{objectType}/aggregate
OntologiesV2 OntologyObjectV2 get GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}
OntologiesV2 OntologyObjectV2 list GET /v2/ontologies/{ontology}/objects/{objectType}
OntologiesV2 OntologyObjectV2 page GET /v2/ontologies/{ontology}/objects/{objectType}
OntologiesV2 OntologyObjectV2 search POST /v2/ontologies/{ontology}/objects/{objectType}/search
OntologiesV2 OntologyV2 get GET /v2/ontologies/{ontology}
OntologiesV2 Query execute POST /v2/ontologies/{ontology}/queries/{queryApiName}/execute
OntologiesV2 QueryType get GET /v2/ontologies/{ontology}/queryTypes/{queryApiName}
OntologiesV2 QueryType list GET /v2/ontologies/{ontology}/queryTypes
OntologiesV2 QueryType page GET /v2/ontologies/{ontology}/queryTypes
OntologiesV2 TimeSeriesPropertyV2 get_first_point GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/firstPoint
OntologiesV2 TimeSeriesPropertyV2 get_last_point GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/lastPoint
OntologiesV2 TimeSeriesPropertyV2 stream_points POST /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/streamPoints
Orchestration Build create POST /v2/orchestration/builds/create
Orchestration Build get GET /v2/orchestration/builds/{buildRid}
Orchestration Schedule create POST /v2/orchestration/schedules
Orchestration Schedule delete DELETE /v2/orchestration/schedules/{scheduleRid}
Orchestration Schedule get GET /v2/orchestration/schedules/{scheduleRid}
Orchestration Schedule pause POST /v2/orchestration/schedules/{scheduleRid}/pause
Orchestration Schedule replace PUT /v2/orchestration/schedules/{scheduleRid}
Orchestration Schedule run POST /v2/orchestration/schedules/{scheduleRid}/run
Orchestration Schedule unpause POST /v2/orchestration/schedules/{scheduleRid}/unpause
ThirdPartyApplications Version delete DELETE /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/{versionVersion}
ThirdPartyApplications Version get GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/{versionVersion}
ThirdPartyApplications Version list GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions
ThirdPartyApplications Version page GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions
ThirdPartyApplications Version upload POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/upload
ThirdPartyApplications Website deploy POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/deploy
ThirdPartyApplications Website get GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website
ThirdPartyApplications Website undeploy POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/undeploy

Documentation for V1 API endpoints

Namespace Resource Operation HTTP request
Datasets Branch create POST /v1/datasets/{datasetRid}/branches
Datasets Branch delete DELETE /v1/datasets/{datasetRid}/branches/{branchId}
Datasets Branch get GET /v1/datasets/{datasetRid}/branches/{branchId}
Datasets Branch list GET /v1/datasets/{datasetRid}/branches
Datasets Branch page GET /v1/datasets/{datasetRid}/branches
Datasets Dataset create POST /v1/datasets
Datasets Dataset get GET /v1/datasets/{datasetRid}
Datasets Dataset read GET /v1/datasets/{datasetRid}/readTable
Datasets File delete DELETE /v1/datasets/{datasetRid}/files/{filePath}
Datasets File get GET /v1/datasets/{datasetRid}/files/{filePath}
Datasets File list GET /v1/datasets/{datasetRid}/files
Datasets File page GET /v1/datasets/{datasetRid}/files
Datasets File read GET /v1/datasets/{datasetRid}/files/{filePath}/content
Datasets File upload POST /v1/datasets/{datasetRid}/files:upload
Datasets Transaction abort POST /v1/datasets/{datasetRid}/transactions/{transactionRid}/abort
Datasets Transaction commit POST /v1/datasets/{datasetRid}/transactions/{transactionRid}/commit
Datasets Transaction create POST /v1/datasets/{datasetRid}/transactions
Datasets Transaction get GET /v1/datasets/{datasetRid}/transactions/{transactionRid}
Ontologies Action apply POST /v1/ontologies/{ontologyRid}/actions/{actionType}/apply
Ontologies Action apply_batch POST /v1/ontologies/{ontologyRid}/actions/{actionType}/applyBatch
Ontologies Action validate POST /v1/ontologies/{ontologyRid}/actions/{actionType}/validate
Ontologies ActionType get GET /v1/ontologies/{ontologyRid}/actionTypes/{actionTypeApiName}
Ontologies ActionType list GET /v1/ontologies/{ontologyRid}/actionTypes
Ontologies ActionType page GET /v1/ontologies/{ontologyRid}/actionTypes
Ontologies ObjectType get GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}
Ontologies ObjectType get_outgoing_link_type GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes/{linkType}
Ontologies ObjectType list GET /v1/ontologies/{ontologyRid}/objectTypes
Ontologies ObjectType list_outgoing_link_types GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes
Ontologies ObjectType page GET /v1/ontologies/{ontologyRid}/objectTypes
Ontologies ObjectType page_outgoing_link_types GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes
Ontologies Ontology get GET /v1/ontologies/{ontologyRid}
Ontologies Ontology list GET /v1/ontologies
Ontologies OntologyObject aggregate POST /v1/ontologies/{ontologyRid}/objects/{objectType}/aggregate
Ontologies OntologyObject get GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}
Ontologies OntologyObject get_linked_object GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType}/{linkedObjectPrimaryKey}
Ontologies OntologyObject list GET /v1/ontologies/{ontologyRid}/objects/{objectType}
Ontologies OntologyObject list_linked_objects GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType}
Ontologies OntologyObject page GET /v1/ontologies/{ontologyRid}/objects/{objectType}
Ontologies OntologyObject page_linked_objects GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType}
Ontologies OntologyObject search POST /v1/ontologies/{ontologyRid}/objects/{objectType}/search
Ontologies Query execute POST /v1/ontologies/{ontologyRid}/queries/{queryApiName}/execute
Ontologies QueryType get GET /v1/ontologies/{ontologyRid}/queryTypes/{queryApiName}
Ontologies QueryType list GET /v1/ontologies/{ontologyRid}/queryTypes
Ontologies QueryType page GET /v1/ontologies/{ontologyRid}/queryTypes

Documentation for V2 models

Documentation for V1 models

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.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for palantir-pypi from gravatar.com palantir-pypi

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: Apache Software License (Apache-2.0)
  • Author: Palantir Technologies, Inc.
  • Tags Palantir, Foundry, SDK, Client, API
  • Requires: Python <4.0, >=3.9
Classifiers

Release history Release notifications | RSS feed

0.40.0

0.39.0

0.38.0

0.37.0

0.35.0

0.34.0

0.33.0

0.32.0

0.31.0

0.30.0

0.29.0

0.28.0

0.27.0

0.26.0

0.25.0

This version

0.24.0

0.23.0

0.22.0

0.21.0

0.20.0

0.19.0

0.18.0

0.17.0

0.16.0

0.15.0

0.14.0

0.13.0

0.12.0

0.11.0

0.10.0

0.9.0

0.8.0

0.7.0

0.6.0

0.5.0

0.3.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foundry_platform_sdk-0.24.0.tar.gz (210.3 kB view hashes)

Uploaded Source

Built Distribution

foundry_platform_sdk-0.24.0-py3-none-any.whl (923.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page