sfq 0.0.1__py3-none-any.whl

sfq/__init__.py

@@ -0,0 +1,137 @@
+import http.client
+import logging
+import time
+import json
+from urllib.parse import urlparse, quote
+
+logging.basicConfig(level=logging.INFO)
+
+class SFAuth:
+    def __init__(
+        self,
+        instance_url,
+        client_id,
+        refresh_token,
+        api_version="v62.0",
+        token_endpoint="/services/oauth2/token",
+        access_token=None,
+        token_expiration_time=None,
+        token_lifetime=15 * 60,
+    ):
+        """
+        Initializes the SFAuth with necessary parameters.
+
+        :param instance_url: The Salesforce instance URL.
+        :param client_id: The client ID for OAuth.
+        :param refresh_token: The refresh token for OAuth.
+        :param api_version: The Salesforce API version (default is "v62.0").
+        :param token_endpoint: The token endpoint (default is "/services/oauth2/token").
+        :param access_token: The access token for the current session (default is None).
+        :param token_expiration_time: The expiration time of the access token (default is None).
+        :param token_lifetime: The lifetime of the access token (default is 15 minutes).
+        """
+        self.instance_url = instance_url
+        self.client_id = client_id
+        self.refresh_token = refresh_token
+        self.api_version = api_version
+        self.token_endpoint = token_endpoint
+        self.access_token = access_token
+        self.token_expiration_time = token_expiration_time
+        self.token_lifetime = token_lifetime
+
+    def _prepare_payload(self):
+        """Prepare the payload for the token request."""
+        return {
+            "grant_type": "refresh_token",
+            "client_id": self.client_id,
+            "refresh_token": self.refresh_token,
+        }
+
+    def _send_post_request(self, payload):
+        """Send a POST request to the Salesforce token endpoint using http.client."""
+        parsed_url = urlparse(self.instance_url)
+        conn = http.client.HTTPSConnection(parsed_url.netloc)
+
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        body = "&".join([f"{key}={value}" for key, value in payload.items()])
+
+        try:
+            conn.request("POST", self.token_endpoint, body, headers)
+            response = conn.getresponse()
+            data = response.read().decode("utf-8")
+            if response.status == 200:
+                return json.loads(data)
+            else:
+                logging.error(
+                    f"HTTP error occurred: {response.status} {response.reason}"
+                )
+                logging.error(f"Response content: {data}")
+        except Exception as err:
+            logging.error(f"Other error occurred: {err}")
+        finally:
+            conn.close()
+
+        return None
+
+    def _refresh_token_if_needed(self):
+        """Automatically refresh the token if it has expired or is missing."""
+        _token_expiration = self._is_token_expired
+        if self.access_token and not _token_expiration:
+            return
+        
+        if not self.access_token:
+            logging.debug("No access token available. Requesting a new one.")
+        elif _token_expiration:
+            logging.debug("Access token has expired. Requesting a new one.")
+
+        payload = self._prepare_payload()
+        token_data = self._send_post_request(payload)
+        if token_data:
+            self.access_token = token_data["access_token"]
+            self.token_expiration_time = int(token_data["issued_at"]) + int(self.token_lifetime)
+            logging.debug("Access token refreshed successfully.")
+        else:
+            logging.error("Failed to refresh access token.")
+
+
+    def _is_token_expired(self):
+        """Check if the access token has expired."""
+        return time.time() >= self.token_expiration_time
+
+    def query(self, query, tooling=False):
+        """Query Salesforce using SOQL or Tooling API, depending on the `tooling` parameter."""
+        self._refresh_token_if_needed()
+
+        if not self.access_token:
+            logging.error("No access token available to make the query.")
+            return None
+
+        if tooling:
+            query_endpoint = f"/services/data/{self.api_version}/tooling/query"
+        else:
+            query_endpoint = f"/services/data/{self.api_version}/query"
+
+        headers = {"Authorization": f"Bearer {self.access_token}"}
+
+        # Handle special characters in the query
+        encoded_query = quote(query)
+        params = f"?q={encoded_query}"
+
+        parsed_url = urlparse(self.instance_url)
+        conn = http.client.HTTPSConnection(parsed_url.netloc)
+
+        try:
+            conn.request("GET", query_endpoint + params, headers=headers)
+            response = conn.getresponse()
+            data = response.read().decode("utf-8")
+            if response.status == 200:
+                return json.loads(data)
+            else:
+                logging.error(f"HTTP error occurred during query: {response.status} {response.reason}")
+                logging.error(f"Response content: {data}")
+        except Exception as err:
+            logging.error(f"Other error occurred during query: {err}")
+        finally:
+            conn.close()
+
+        return None

sfq-0.0.1.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.3
+Name: sfq
+Version: 0.0.1
+Summary: Python wrapper for the Salesforce's Query API.
+Author-email: David Moruzzi <sfq.pypi@dmoruzi.com>
+Keywords: salesforce,salesforce query
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sfq (Salesforce Query)
+
+sfq is a lightweight Python wrapper library designed to simplify querying Salesforce, reducing repetitive code for accessing Salesforce data.
+
+For more varied workflows, consider using an alternative like [Simple Salesforce](https://simple-salesforce.readthedocs.io/en/stable/). This library was even referenced on the [Salesforce Developers Blog](https://developer.salesforce.com/blogs/2021/09/how-to-automate-data-extraction-from-salesforce-using-python).
+
+## Features
+
+- Simplified query execution for Salesforce instances.
+- Integration with Salesforce authentication via refresh tokens.
+- Option to interact with Salesforce Tooling API for more advanced queries.
+  
+## Installation
+
+You can install the `sfq` library using `pip`:
+
+```bash
+pip install sfq
+```
+
+## Usage
+
+### Querying Salesforce Data
+
+```python
+from sfq import SFAuth
+
+# Initialize the SFAuth class with authentication details
+sf = SFAuth(
+    instance_url="https://example-dev-ed.trailblaze.my.salesforce.com",
+    client_id="PlatformCLI",
+    refresh_token="your-refresh-token-here"
+)
+
+# Execute a query to fetch account records
+print(sf.query("SELECT Id FROM Account LIMIT 5"))
+
+# Execute a query to fetch Tooling API data
+print(sf.query("SELECT Id, FullName, Metadata FROM SandboxSettings LIMIT 5", tooling=True))
+```
+
+### Querying from Bash
+
+You can easily incorporate this into ad-hoc bash scripts or commands:
+
+```bash
+python -c "from sfq import SFAuth; sf = SFAuth(instance_url='$instance_url', client_id='$client_id', refresh_token='$refresh_token'); print(sf.query('$query'))" | jq -r '.records[].Id'
+```
+
+## How to Obtain Salesforce Tokens
+
+To use the `sfq` library, you'll need a **client ID** and **refresh token**. The easiest way to obtain these is by using the Salesforce CLI:
+
+### Steps to Get Tokens
+
+1. **Install the Salesforce CLI**:  
+   Follow the instructions on the [Salesforce CLI installation page](https://developer.salesforce.com/tools/salesforcecli).
+   
+2. **Authenticate with Salesforce**:  
+   Login to your Salesforce org using the following command:
+   
+   ```bash
+   sf org login web --alias int --instance-url https://corpa--int.sandbox.my.salesforce.com
+   ```
+   
+3. **Display Org Details**:  
+   To get the client ID, refresh token, and instance URL, run:
+   
+   ```bash
+   sf org display --target-org int --verbose --json
+   ```
+
+   The output will look like this:
+
+   ```json
+   {
+     "status": 0,
+     "result": {
+       "id": "00Daa0000000000000",
+       "apiVersion": "62.0",
+       "accessToken": "your-access-token-here",
+       "instanceUrl": "https://example-dev-ed.trailblaze.my.salesforce.com",
+       "username": "user@example.com",
+       "clientId": "PlatformCLI",
+       "connectedStatus": "Connected",
+       "sfdxAuthUrl": "force://PlatformCLI::your-refresh-token-here::https://example-dev-ed.trailblaze.my.salesforce.com",
+       "alias": "int"
+     }
+   }
+   ```
+
+4. **Extract and Use the Tokens**:  
+   The `sfdxAuthUrl` is structured as:
+   
+   ```
+   force://<client_id>::<refresh_token>::<instance_url>
+   ```
+
+   You can extract and use the tokens in a bash script like this:
+
+   ```bash
+   query="SELECT Id FROM User WHERE IsActive = true AND Profile.Name = 'System Administrator'"
+
+   sfdxAuthUrl=$(sf org display --target-org int --verbose --json | jq -r '.result.sfdxAuthUrl' | sed 's/force:\/\///')
+   clientId=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '1p')
+   refreshToken=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '2p')
+   instanceUrl=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '3p')
+
+   pip install sfq && python -c "from sfq import SFAuth; sf = SFAuth(instance_url='$instanceUrl', client_id='$clientId', refresh_token='$refreshToken'); print(sf.query('$query'))" | jq -r '.records[].Id'
+   ```
+
+## Notes
+
+- **Authentication**: Make sure your refresh token is kept secure, as it grants access to your Salesforce instance.
+- **Tooling API**: You can set the `tooling=True` argument in the `query` method to access the Salesforce Tooling API for more advanced metadata queries.

sfq-0.0.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+sfq/__init__.py,sha256=pOOF_qbF_5lWmZCp7Zth_cllmqD9Svr3pOVu01-1h5w,5180
+sfq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sfq-0.0.1.dist-info/METADATA,sha256=tDxHUnStTdh2UrOqI9ItvquS3BHSVANmdhuF2-Sshlo,4585
+sfq-0.0.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+sfq-0.0.1.dist-info/RECORD,,

sfq-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.26.3
+Root-Is-Purelib: true
+Tag: py3-none-any