Metadata-Version: 2.3
Name: salespyforce
Version: 1.4.0.dev0
Summary: A Python toolset for performing Salesforce API calls
License: MIT License
         
         Copyright (c) 2023 Jeff Shurtliff
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Keywords: salesforce,sfdc,api,rest,tooling,python
Author: Jeff Shurtliff
Author-email: jeffshurtliff@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Dist: PyYAML (>=6.0.3,<7)
Requires-Dist: requests (>=2.32.5)
Project-URL: Documentation, https://salespyforce.readthedocs.io/en/latest/
Project-URL: Homepage, https://github.com/jeffshurtliff/salespyforce
Project-URL: Issue Tracker, https://github.com/jeffshurtliff/salespyforce/issues
Project-URL: Repository, https://github.com/jeffshurtliff/salespyforce
Description-Content-Type: text/markdown

# salespyforce
A Python toolset for performing Salesforce API calls

<table>
    <tr>
        <td>Latest Stable Release</td>
        <td>
            <a href='https://pypi.org/project/salespyforce/'>
                <img alt="PyPI" src="https://img.shields.io/pypi/v/salespyforce">
            </a>
        </td>
    </tr>
    <tr>
        <td>Latest Beta/RC Release</td>
        <td>
            <a href='https://pypi.org/project/salespyforce/#history'>
                <img alt="PyPI" src="https://img.shields.io/badge/pypi-1.3.0rc3-blue">
            </a>
        </td>
    </tr>
    <tr>
        <td>Build Status</td>
        <td>
            <a href="https://github.com/jeffshurtliff/salespyforce/blob/master/.github/workflows/pythonpackage.yml">
                <img alt="GitHub Workflow Status" 
                src="https://img.shields.io/github/actions/workflow/status/jeffshurtliff/salespyforce/pythonpackage.yml?branch=master">
            </a>
        </td>
    </tr>
    <tr>
        <td>Supported Versions</td>
        <td>
            <a href='https://pypi.org/project/salespyforce/'>
                <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/salespyforce">
            </a>
        </td>
    </tr>
    <tr>
        <td>Code Coverage</td>
        <td>
            <a href="https://codecov.io/gh/jeffshurtliff/salespyforce">
                <img src="https://codecov.io/gh/jeffshurtliff/salespyforce/branch/master/graph/badge.svg" />
            </a>
        </td>
    </tr>
    <tr>
        <td>Documentation</td>
        <td>
            <a href='https://salespyforce.readthedocs.io/en/latest/?badge=latest'>
                <img src='https://readthedocs.org/projects/salespyforce/badge/?version=latest' alt='Documentation Status' />
            </a>
        </td>
    </tr>
    <tr>
        <td>Security Audits</td>
        <td>
            <a href="https://github.com/marketplace/actions/python-security-check-using-bandit">
                <img alt="Bandit" src="https://img.shields.io/badge/security-bandit-yellow.svg">
            </a>
        </td>
    </tr>
    <tr>
        <td>License</td>
        <td>
            <a href="https://github.com/jeffshurtliff/salespyforce/blob/master/LICENSE">
                <img alt="License (GitHub)" src="https://img.shields.io/github/license/jeffshurtliff/salespyforce">
            </a>
        </td>
    </tr>
    <tr>
        <td style="vertical-align: top;">Issues</td>
        <td>
            <a href="https://github.com/jeffshurtliff/salespyforce/issues">
                <img style="margin-bottom:5px;" alt="GitHub open issues" src="https://img.shields.io/github/issues-raw/jeffshurtliff/salespyforce"><br />
            </a>
            <a href="https://github.com/jeffshurtliff/salespyforce/issues">
                <img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed-raw/jeffshurtliff/salespyforce">
            </a>
        </td>
    </tr>
    <tr>
        <td style="vertical-align: top;">Pull Requests</td>
        <td>
            <a href="https://github.com/jeffshurtliff/salespyforce/pulls">
                <img style="margin-bottom:5px;" alt="GitHub pull open requests" src="https://img.shields.io/github/issues-pr-raw/jeffshurtliff/salespyforce"><br />
            </a>
            <a href="https://github.com/jeffshurtliff/salespyforce/pulls">
                <img alt="GitHub closed pull requests" src="https://img.shields.io/github/issues-pr-closed-raw/jeffshurtliff/salespyforce">
            </a>
        </td>
    </tr>
</table>

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

```sh
pip install salespyforce --upgrade
```

You may also clone the repository and install from source using below.

```sh
git clone git://github.com/jeffshurtliff/salespyforce.git
cd salespyforce/
python setup.py install
```

## Change Log
The change log can be found in the [documentation](https://salespyforce.readthedocs.io/en/latest/changelog.html).

## 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.

```python
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.

```python
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:

```yaml
# 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.

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

## Documentation
The documentation is located here: [https://salespyforce.readthedocs.io/en/latest/](https://salespyforce.readthedocs.io/en/latest/)

## License
[MIT License](https://github.com/jeffshurtliff/salespyforce/blob/master/LICENSE)

## Reporting Issues
Issues can be reported within the [GitHub repository](https://github.com/jeffshurtliff/salespyforce/issues).

## Donations
If you would like to donate to this project then you can do so using [this PayPal link](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=XDZ8M6UV6EFK6&item_name=SalesPyForce+Python+API&currency_code=USD).

## Disclaimer
This package is considered unofficial and is in no way endorsed or supported by [Salesforce Inc](https://www.salesforce.com).

