sfq 0.0.21__tar.gz → 0.0.23__tar.gz

{sfq-0.0.21 → sfq-0.0.23}/.github/workflows/publish.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Sync dependencies with uv
         run: uv sync
 
+      - name: Install pytest
+        run: pip install pytest
+
       - name: Authenticate GitHub CLI
         run: |
           echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token
@@ -75,12 +78,20 @@ jobs:
           sed -i -E "s/(user_agent: str = \"sfq\/)[0-9]+\.[0-9]+\.[0-9]+(\")/\1$VERSION\2/" src/sfq/__init__.py
           sed -i -E "s/(default is \"sfq\/)[0-9]+\.[0-9]+\.[0-9]+(\")/\1$VERSION\2/" src/sfq/__init__.py
 
+      - name: Run tests
+        run: pytest --verbose --strict-config
+        env:
+          SF_INSTANCE_URL: ${{ secrets.SF_INSTANCE_URL }}
+          SF_CLIENT_ID: ${{ secrets.SF_CLIENT_ID }}
+          SF_CLIENT_SECRET: ${{ secrets.SF_CLIENT_SECRET }}
+          SF_REFRESH_TOKEN: ${{ secrets.SF_REFRESH_TOKEN }}
+
       - name: Commit version updates
         run: |
-          git config user.name "github-actions"
-          git config user.email "github-actions@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add pyproject.toml uv.lock src/sfq/__init__.py
-          git commit -m "chore: bump version to ${{ steps.get_version.outputs.version }}"
+          git commit -m "CI: bump version to ${{ steps.get_version.outputs.version }}"
           git push
 
       - name: Create and push git tag
@@ -104,3 +115,48 @@ jobs:
           prerelease: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install pdoc
+        run: pip install pdoc
+
+      - name: Generate docs
+        run: pdoc .\src\sfq\__init__.py -o docs --no-search
+
+      - name: Set sfq.html as default index page
+        run: |
+          rm docs/index.html
+          mv docs/sfq.html docs/index.html
+
+
+      - name: Prepare docs branch (first-time safe)
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git fetch origin
+          rm -rf docs-branch
+
+          if git show-ref --verify --quiet refs/remotes/origin/docs; then
+            echo "Branch 'docs' exists. Checking it out with worktree..."
+            git worktree add -B docs docs-branch origin/docs
+          else
+            echo "Branch 'docs' does not exist. Creating new orphan branch..."
+            mkdir docs-branch
+            cd docs-branch
+            git init
+            git checkout --orphan docs
+            git commit --allow-empty -m "CI: Initial empty commit"
+            git remote add origin https://github.com/${{ github.repository }}.git
+            git push origin docs
+            cd ..
+            git worktree add -B docs docs-branch origin/docs
+          fi
+
+      - name: Push generated docs to docs branch
+        run: |
+          rm -rf docs-branch/*
+          cp -r docs/* docs-branch/
+          cd docs-branch
+          git add .
+          git commit -m "CI: Update documentation" || echo "No changes to commit"
+          git push origin docs --force

{sfq-0.0.21 → sfq-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sfq
-Version: 0.0.21
+Version: 0.0.23
 Summary: Python wrapper for the Salesforce's Query API.
 Author-email: David Moruzzi <sfq.pypi@dmoruzi.com>
 Keywords: salesforce,salesforce query

{sfq-0.0.21 → sfq-0.0.23}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sfq"
-version = "0.0.21"
+version = "0.0.23"
 description = "Python wrapper for the Salesforce's Query API."
 readme = "README.md"
 authors = [{ name = "David Moruzzi", email = "sfq.pypi@dmoruzi.com" }]

{sfq-0.0.21 → sfq-0.0.23}/src/sfq/__init__.py

@@ -1,3 +1,7 @@
+"""
+.. include:: ../../README.md
+"""
+
 import base64
 import http.client
 import json
@@ -10,6 +14,8 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import Any, Dict, Iterable, Literal, Optional, List, Tuple
 from urllib.parse import quote, urlparse
 
+__all__ = ["SFAuth"]  # https://pdoc.dev/docs/pdoc.html#control-what-is-documented
+
 TRACE = 5
 logging.addLevelName(TRACE, "TRACE")
 
@@ -84,7 +90,7 @@ class SFAuth:
         access_token: Optional[str] = None,
         token_expiration_time: Optional[float] = None,
         token_lifetime: int = 15 * 60,
-        user_agent: str = "sfq/0.0.21",
+        user_agent: str = "sfq/0.0.23",
         sforce_client: str = "_auto",
         proxy: str = "_auto",
     ) -> None:
@@ -94,27 +100,145 @@ class SFAuth:
         :param instance_url: The Salesforce instance URL.
         :param client_id: The client ID for OAuth.
         :param refresh_token: The refresh token for OAuth.
-        :param client_secret: The client secret for OAuth (default is "_deprecation_warning").
-        :param api_version: The Salesforce API version (default is "v64.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 in seconds (default is 15 minutes).
-        :param user_agent: Custom User-Agent string (default is "sfq/0.0.21").
-        :param sforce_client: Custom Application Identifier (default is user_agent).
-        :param proxy: The proxy configuration, "_auto" to use environment (default is "_auto").
+        :param client_secret: The client secret for OAuth.
+        :param api_version: The Salesforce API version.
+        :param token_endpoint: The token endpoint.
+        :param access_token: The access token for the current session.
+        :param token_expiration_time: The expiration time of the access token.
+        :param token_lifetime: The lifetime of the access token in seconds.
+        :param user_agent: Custom User-Agent string.
+        :param sforce_client: Custom Application Identifier.
+        :param proxy: The proxy configuration, "_auto" to use environment.
         """
         self.instance_url = self._format_instance_url(instance_url)
+        """
+        ### `instance_url`
+        **The fully qualified Salesforce instance URL.**
+
+        - Should end with `.my.salesforce.com`
+        - No trailing slash
+
+        **Examples:**
+        - `https://sfq-dev-ed.trailblazer.my.salesforce.com`
+        - `https://sfq.my.salesforce.com`
+        - `https://sfq--dev.sandbox.my.salesforce.com`
+        """
+
         self.client_id = client_id
+        """
+        ### `client_id`
+        **The OAuth client ID.**
+
+        - Uniquely identifies your **Connected App** in Salesforce
+        - If using **Salesforce CLI**, this is `"PlatformCLI"`
+        - For other apps, find this value in the **Connected App details**
+        """
+
         self.client_secret = client_secret
+        """
+        ### `client_secret`
+        **The OAuth client secret.**
+
+        - Secret key associated with your Connected App
+        - For **Salesforce CLI**, this is typically an empty string `""`
+        - For custom apps, locate it in the **Connected App settings**
+        """
+
         self.refresh_token = refresh_token
+        """
+        ### `refresh_token`
+        **The OAuth refresh token.**
+
+        - Used to fetch new access tokens when the current one expires
+        - For CLI, obtain via:
+
+          ```bash
+          sf org display --json
+        ````
+
+        * For other apps, this value is returned during the **OAuth authorization flow**
+            * 📖 [Salesforce OAuth Flows Documentation](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_flows.htm&type=5)
+        """
+
         self.api_version = api_version
+        """
+
+        ### `api_version`
+
+        **The Salesforce API version to use.**
+
+        * Must include the `"v"` prefix (e.g., `"v64.0"`)
+        * Periodically updated to align with new Salesforce releases
+        """
+
         self.token_endpoint = token_endpoint
+        """
+
+        ### `token_endpoint`
+
+        **The token URL path for OAuth authentication.**
+
+        * Defaults to Salesforce's `.well-known/openid-configuration` for *token* endpoint
+        * Should start with a **leading slash**, e.g., `/services/oauth2/token`
+        * No customization is typical, but internal designs may use custom ApexRest endpoints
+          """
+
         self.access_token = access_token
+        """
+
+        ### `access_token`
+
+        **The current OAuth access token.**
+
+        * Used to authorize API requests
+        * Does not include Bearer prefix, strictly the token
+        """
+
         self.token_expiration_time = token_expiration_time
+        """
+
+        ### `token_expiration_time`
+
+        **Unix timestamp (in seconds) for access token expiration.**
+
+        * Managed automatically by the library
+        * Useful for checking when to refresh the token
+          """
+
         self.token_lifetime = token_lifetime
+        """
+
+        ### `token_lifetime`
+
+        **Access token lifespan in seconds.**
+
+        * Determined by your Connected App's session policies
+        * Used to calculate when to refresh the token
+          """
+
         self.user_agent = user_agent
+        """
+
+        ### `user_agent`
+
+        **Custom User-Agent string for API calls.**
+
+        * Included in HTTP request headers
+        * Useful for identifying traffic in Salesforce `ApiEvent` logs
+          """
+
         self.sforce_client = str(sforce_client).replace(",", "")
+        """
+
+        ### `sforce_client`
+
+        **Custom application identifier.**
+
+        * Included in the `Sforce-Call-Options` header
+        * Useful for identifying traffic in Event Log Files
+        * Commas are not allowed; will be stripped
+        """
+
         self._auto_configure_proxy(proxy)
         self._high_api_usage_threshold = 80
 

sfq-0.0.23/tests/conftest.py

@@ -0,0 +1,16 @@
+# tests/conftest.py
+
+executed_tests = 0
+
+def pytest_runtest_logreport(report):
+    global executed_tests
+    if report.when == "call" and report.passed:
+        executed_tests += 1
+    elif report.when == "call" and report.failed:
+        executed_tests += 1
+
+def pytest_sessionfinish(session, exitstatus):
+    if session.testscollected > 0 and executed_tests == 0:
+        print()
+        print("❌ Pytest collected tests, but all were skipped. Failing the run.")
+        session.exitstatus = 1

sfq-0.0.23/tests/test_limits_api.py

@@ -0,0 +1,44 @@
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+# --- Setup local import path ---
+project_root = Path(__file__).resolve().parents[1]
+src_path = project_root / "src"
+sys.path.insert(0, str(src_path))
+from sfq import SFAuth  # noqa: E402
+
+
+@pytest.fixture(scope="module")
+def sf_instance():
+    required_env_vars = [
+        "SF_INSTANCE_URL",
+        "SF_CLIENT_ID",
+        "SF_CLIENT_SECRET",
+        "SF_REFRESH_TOKEN",
+    ]
+
+    missing_vars = [var for var in required_env_vars if not os.getenv(var)]
+    if missing_vars:
+        pytest.skip(f"Missing required env vars: {', '.join(missing_vars)}")
+
+    sf = SFAuth(
+        instance_url=os.getenv("SF_INSTANCE_URL"),
+        client_id=os.getenv("SF_CLIENT_ID"),
+        client_secret=os.getenv("SF_CLIENT_SECRET"),
+        refresh_token=os.getenv("SF_REFRESH_TOKEN"),
+    )
+    return sf
+
+
+def test_limits_api(sf_instance):
+    """
+    Test the limits API endpoint.
+    """
+
+    limits = sf_instance.limits()
+
+    assert isinstance(limits, dict)
+    assert "DailyApiRequests" in limits.keys()

sfq-0.0.23/tests/test_log_trace_redact.py

@@ -0,0 +1,79 @@
+import logging
+import os
+import sys
+from io import StringIO
+from pathlib import Path
+
+import pytest
+
+# --- Setup local import path ---
+project_root = Path(__file__).resolve().parents[1]
+src_path = project_root / "src"
+sys.path.insert(0, str(src_path))
+from sfq import SFAuth  # noqa: E402
+
+
+@pytest.fixture(scope="module")
+def sf_instance():
+    required_env_vars = [
+        "SF_INSTANCE_URL",
+        "SF_CLIENT_ID",
+        "SF_CLIENT_SECRET",
+        "SF_REFRESH_TOKEN",
+    ]
+
+    missing_vars = [var for var in required_env_vars if not os.getenv(var)]
+    if missing_vars:
+        pytest.skip(f"Missing required env vars: {', '.join(missing_vars)}")
+
+    sf = SFAuth(
+        instance_url=os.getenv("SF_INSTANCE_URL"),
+        client_id=os.getenv("SF_CLIENT_ID"),
+        client_secret=os.getenv("SF_CLIENT_SECRET"),
+        refresh_token=os.getenv("SF_REFRESH_TOKEN"),
+    )
+    return sf
+
+
+@pytest.fixture
+def capture_logs():
+    """
+    Fixture to capture logs emitted to 'sfq' logger at TRACE level.
+    """
+    log_stream = StringIO()
+    handler = logging.StreamHandler(log_stream)
+    handler.setLevel(5)
+
+    logger = logging.getLogger("sfq")
+    original_level = logger.level
+    original_handlers = logger.handlers[:]
+
+    logger.setLevel(5)
+    for h in original_handlers:
+        logger.removeHandler(h)
+    logger.addHandler(handler)
+
+    yield logger, log_stream
+
+    # Teardown - restore original handlers and level
+    logger.removeHandler(handler)
+    for h in original_handlers:
+        logger.addHandler(h)
+    logger.setLevel(original_level)
+
+
+def test_access_token_redacted_in_logs(sf_instance, capture_logs):
+    """
+    Ensure access tokens are redacted in log output to prevent leakage.
+    """
+    logger, log_stream = capture_logs
+
+    sf_instance._get_common_headers()
+
+    logger.handlers[0].flush()
+    log_contents = log_stream.getvalue()
+
+    assert "access_token" in log_contents, "Expected access_token key in logs"
+    assert "'access_token': '********'," in log_contents in log_contents, (
+        "Access token was not properly redacted in logs"
+    )

{sfq-0.0.21 → sfq-0.0.23}/uv.lock

@@ -3,5 +3,5 @@ requires-python = ">=3.9"
 
 [[package]]
 name = "sfq"
-version = "0.0.21"
+version = "0.0.23"
 source = { editable = "." }