posf 0.1.1

A Polars adapter for your Salesforce data

posf

(poh ⋅ sef) A Salesforce client in Python for data engineers. Read from and write to Salesforce with Polars dataframes.

Usage

import posf
import polars as pl

# Connect to Salesforce
pf = posf.Posf.from_cli("prod")

# Describe table

pf.describe("Opportunity")

# Query
df: pl.DataFrame = pf.query("""
    SELECT Id, Name
    FROM Opportunity
""")

# Manipulate data in Polars dataframes
df = df.select(
    [
        pl.col("Id"),
        pl.col("Name").str.to_titlecase()
    ]
)

# Write back to Salesforce
pf.update('Account', df)

Getting Started

First, add posf to your project.

uv add posf

Then, choose from any number of connection options.

from posf import Posf
import simple_salesforce

pf = Posf.from_cli() # Reuse `sf` CLI connection for local dev
pf = Posf.from_security_token() # Use security token for quick start
pf = Posf(simple_salesforce.Salesforce(...)) # Pass in a simple-salesforce
                                             # client directly

Transactions

Use the composite_request API to work with ACID transactions.

tx = pf.composite_request()
tx.insert(df1)
tx.update(df2)
tx.delete(df3)
insert_res, update_res, delete_res = tx.commit()

Working with Notebooks

posf is specially designed with Marimo in mind. All of the non-idempotent actions may be gated behind a Marimo run button. This prevents executing the same action multiple times as cells are autorun. To do this, pass the run button's value property to the run parameter in any method that executes DML. These include insert, update, upsert, delete, and commit.

# Cell 1
import marimo as mo
import posf

# Cell 2
pf = posf.from_cli('prod')
run_button = mo.ui.run_button(label="Commit")

# Cell 3
# insert will not execute until run button is clicked
pf.insert(my_data, 'Account', run=run_button.value)

There are a number of examples available to illustrate this package. These can be loaded as Marimo snippets by saving the contents of examples/marimo-snippets to your snippets directory (snippets.custom_paths in marimo config show).