SalesPyForce

A Python toolset for performing Salesforce API calls

Latest Stable Release
Latest Beta/RC Release
Build Status
Supported Versions
Code Coverage
Documentation
Security Audits
License
Issues
Pull Requests

Overview

salespyforce is a Python toolkit focused on interacting with Salesforce APIs, with a primary Salesforce class that centralizes authentication, version selection, and access to helper feature sets (Chatter, Knowledge).

Installation

The package can be installed via pip using the syntax below.

pip install salespyforce --upgrade

Development and Testing

For local development, this repository uses split test directories: tests/unit/ and tests/integration/.

poetry install
poetry run pytest -q

Development Quality Checks

This repository uses Ruff for linting, import sorting, and formatting. The standard maximum line length for this package is 130 characters.

Line-length exceptions should be rare and limited to comments or special cases where wrapping harms readability. When an exception is required, use a targeted per-line # noqa: E501 comment.

poetry run ruff check .
poetry run ruff check . --fix
poetry run ruff format .
poetry run ruff format --check .

These checks are enforced in CI via .github/workflows/ci.yml.

Changelog

The changelog can be found in the documentation for the stable and latest versions.

Usage

This section provides basic usage instructions for the package.

Importing the package

Rather than importing the base package, it is recommended that you import the primary Salesforce class using the syntax below.

from salespyforce import Salesforce

Initializing a Salesforce object instance

The primary Salesforce object serves many purposes, the most important being to establish a connection to the Salesforce environment with which you intend to interact. As such, when initializing an instance of the Salesforce object, you will need to pass it the following information:

• The username and password of the API user
• The Organization ID of the Salesforce environment
• The Base URL and Endpoint URL
• The client ID, client secret, and security token

The Salesforce object can be initiated in two different ways:

• Passing the information directly into the object
• Leveraging a "helper" configuration file

Passing the information directly into the object

The environment and connection information can be passed directly into the Salesforce object when initializing it, as demonstrated in the example below.

sfdc = Salesforce(
    username='admin.user@example.com',
    password='example123',
    org_id='4DJ000000CeMFYA0',
    base_url='https://example-dev-ed.lightning.force.com/',
    endpoint_url='https://example-dev-ed.my.salesforce.com/services/oauth2/token',
    client_id='3MVG9gTv.DiE8cKRIpEtSN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX_TAoy1Zk_AKGukbqa4KbhM6nVYVUu6md',
    client_secret='7536F4A7865559XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX53797BEA88174713CC3C',
    security_token='2muXaXXXXXXXXXXXXXXXoVKxz'
)

Leveraging a "helper" configuration file

As an alternative to passing the connection information to the Salesforce class in the way demonstrated above, a "helper" configuration file in yaml or json format can be leveraged instead and passed to the Salesforce class when initializing the object.

This is an example of how the configuration file would be written in YAML format:

# Helper configuration file for the SalesPyForce package

# Define how to obtain the connection information
connection:
    # Define the credentials
    username: admin.user@example.com
    password: example123

    # Define the org information
    org_id: 4DJ000000CeMFYA0
    base_url: https://example-dev-ed.lightning.force.com/
    endpoint_url: https://example-dev-ed.my.salesforce.com/services/oauth2/token

    # Define the API connection info
    client_key: 3MVG9gTv.DiE8cKRIpEtSN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX_TAoy1Zk_AKGukbqa4KbhM6nVYVUu6md
    client_secret: 7536F4A7865559XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX53797BEA88174713CC3C
    security_token: 2muXaXXXXXXXXXXXXXXXoVKxz

# Define if SSL certificates should be verified when making API calls
ssl_verify: yes

The file can then be referenced using the helper argument when initializing the object instance, as shown below.

HELPER_FILE = '/path/to/helper.yml'
sfdc = Salesforce(helper=HELPER_FILE)

Documentation

The documentation is located here: https://salespyforce.readthedocs.io/en/stable/

License

MIT License

Reporting Issues

Issues can be reported within the GitHub repository.

Donations

If you would like to donate to this project then you can do so using this PayPal link.

Disclaimer

This package is considered unofficial and is in no way endorsed or supported by Salesforce Inc.