idi-sanmar-sdk 1.0.0__tar.gz

idi_sanmar_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.3
+Name: idi-sanmar-sdk
+Version: 1.0.0
+Summary: A typed Python SDK for SanMar’s web services and SFTP files.
+Author: Bradley Reynolds
+Author-email: Bradley Reynolds <bradley.reynolds@impressdesigns.com>
+License: MIT
+Requires-Dist: paramiko>=4.0,<5
+Requires-Dist: pydantic>=2.12
+Requires-Dist: zeep>=4.3.3
+Requires-Python: >=3.14
+Project-URL: repository, https://github.com/impressdesigns/sanmar-sdk
+Project-URL: documentation, https://impressdesigns.dev/sanmar-sdk/
+Description-Content-Type: text/markdown
+
+# idi-sanmar-sdk
+
+A typed Python SDK for [SanMar](https://www.sanmar.com): its own web services, its
+PromoStandards web services, and the data and order files on its SFTP server.
+
+- **Strict in, typed out.** Orders and lookups are validated Pydantic models, so a bad
+  address or a comma in a PO number fails before anything is sent. Responses come back as
+  typed records, with prices as `Decimal`.
+- **No SOAP or file layouts to learn.** Each call is shaped into SanMar's payload in one
+  place, including the PromoStandards fields SanMar requires and then ignores.
+- **Streams.** SFTP files are parsed row by row as they download, zip archives included.
+
+Documentation: https://impressdesigns.dev/sanmar-sdk/
+
+## Install
+
+```sh
+uv add idi-sanmar-sdk
+```
+
+Python 3.14 or newer. SanMar's web services listen on port 8080, and its SFTP server on
+port 2200; some networks block both.
+
+## Quick start
+
+```python
+from sanmar_sdk import SanMar, ShipMethod, ShipTo
+from sanmar_sdk.promostandards import PromoStandardsOrder, PromoStandardsOrderLine
+
+sanmar = SanMar(123456, "sanmar-username", "sanmar-password")
+
+# Look a style up, and check stock for one of its parts.
+product = sanmar.promostandards.product_data.get("K500")
+[stock] = sanmar.promostandards.inventory.get("K500", part_ids=["208284"])
+
+# Place an order.
+order = PromoStandardsOrder(
+    po_number="85496",
+    ship_to=ShipTo(address1="1404 W MAIN ST", city="CARROLLTON", state="TX", zip_code="75006"),
+    ship_method=ShipMethod.UPS_GROUND,
+    lines=[PromoStandardsOrderLine(part_id="208284", quantity=12)],
+)
+transaction_id = sanmar.promostandards.purchase_orders.send(order)
+```
+
+Reading the catalog over SFTP:
+
+```python
+from sanmar_sdk.ftp import SanMarFTP
+
+with SanMarFTP(123456, "ftp-password", host_key="ssh-rsa AAAA...") as ftp, ftp.catalog() as products:
+    for product in products:
+        print(product.style, product.catalog_color, product.size, product.unique_key)
+```
+
+Colors in requests and orders are SanMar's **catalog** colors (`SANMAR_MAINFRAME_COLOR`),
+not the display names in `COLOR_NAME`. The SDK calls them `catalog_color` everywhere; see
+[Identifiers](https://impressdesigns.dev/sanmar-sdk/identifiers/).
+
+## Sources
+
+Written against these revisions of SanMar's integration guides:
+
+| Guide | Version | Updated |
+|---|---|---|
+| [SanMar Web Services Integration Guide](https://www.sanmar.com/medias/sys_master/pdf/h7a/ha0/33815499964446/SanMar-Web-Services-Integration-Guide-24.6/SanMar-Web-Services-Integration-Guide-24.6.pdf) | 24.6 | August 2026 |
+| [SanMar Purchase Order Integration Guide](https://www.sanmar.com/medias/sys_master/root/h4b/ha7/33815499767838/SanMar-Purchase-Order-Integration-Guide-24.5/SanMar-Purchase-Order-Integration-Guide-24.5.pdf) | 24.5 | August 2026 |
+| [SanMar FTP Integration Guide](https://www.sanmar.com/medias/sys_master/root/h08/hae/33815499571230/SanMar-FTP-Integration-Guide-v23.6/SanMar-FTP-Integration-Guide-v23.6.pdf) | 23.6 | August 2026 |
+
+Where the guides contradict themselves, the SDK follows SanMar's own WSDLs and file
+headers, recorded in `tests/`. The
+[Sources](https://impressdesigns.dev/sanmar-sdk/sources/) page lists each case.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run nox -s lints tests
+```
+
+The live suite calls SanMar's real services, read-only:
+
+```sh
+SANMAR_LIVE=1 SANMAR_CUSTOMER_NUMBER=... SANMAR_USERNAME=... SANMAR_PASSWORD=... \
+  uv run pytest tests/live
+```

idi_sanmar_sdk-1.0.0/README.md

@@ -0,0 +1,86 @@
+# idi-sanmar-sdk
+
+A typed Python SDK for [SanMar](https://www.sanmar.com): its own web services, its
+PromoStandards web services, and the data and order files on its SFTP server.
+
+- **Strict in, typed out.** Orders and lookups are validated Pydantic models, so a bad
+  address or a comma in a PO number fails before anything is sent. Responses come back as
+  typed records, with prices as `Decimal`.
+- **No SOAP or file layouts to learn.** Each call is shaped into SanMar's payload in one
+  place, including the PromoStandards fields SanMar requires and then ignores.
+- **Streams.** SFTP files are parsed row by row as they download, zip archives included.
+
+Documentation: https://impressdesigns.dev/sanmar-sdk/
+
+## Install
+
+```sh
+uv add idi-sanmar-sdk
+```
+
+Python 3.14 or newer. SanMar's web services listen on port 8080, and its SFTP server on
+port 2200; some networks block both.
+
+## Quick start
+
+```python
+from sanmar_sdk import SanMar, ShipMethod, ShipTo
+from sanmar_sdk.promostandards import PromoStandardsOrder, PromoStandardsOrderLine
+
+sanmar = SanMar(123456, "sanmar-username", "sanmar-password")
+
+# Look a style up, and check stock for one of its parts.
+product = sanmar.promostandards.product_data.get("K500")
+[stock] = sanmar.promostandards.inventory.get("K500", part_ids=["208284"])
+
+# Place an order.
+order = PromoStandardsOrder(
+    po_number="85496",
+    ship_to=ShipTo(address1="1404 W MAIN ST", city="CARROLLTON", state="TX", zip_code="75006"),
+    ship_method=ShipMethod.UPS_GROUND,
+    lines=[PromoStandardsOrderLine(part_id="208284", quantity=12)],
+)
+transaction_id = sanmar.promostandards.purchase_orders.send(order)
+```
+
+Reading the catalog over SFTP:
+
+```python
+from sanmar_sdk.ftp import SanMarFTP
+
+with SanMarFTP(123456, "ftp-password", host_key="ssh-rsa AAAA...") as ftp, ftp.catalog() as products:
+    for product in products:
+        print(product.style, product.catalog_color, product.size, product.unique_key)
+```
+
+Colors in requests and orders are SanMar's **catalog** colors (`SANMAR_MAINFRAME_COLOR`),
+not the display names in `COLOR_NAME`. The SDK calls them `catalog_color` everywhere; see
+[Identifiers](https://impressdesigns.dev/sanmar-sdk/identifiers/).
+
+## Sources
+
+Written against these revisions of SanMar's integration guides:
+
+| Guide | Version | Updated |
+|---|---|---|
+| [SanMar Web Services Integration Guide](https://www.sanmar.com/medias/sys_master/pdf/h7a/ha0/33815499964446/SanMar-Web-Services-Integration-Guide-24.6/SanMar-Web-Services-Integration-Guide-24.6.pdf) | 24.6 | August 2026 |
+| [SanMar Purchase Order Integration Guide](https://www.sanmar.com/medias/sys_master/root/h4b/ha7/33815499767838/SanMar-Purchase-Order-Integration-Guide-24.5/SanMar-Purchase-Order-Integration-Guide-24.5.pdf) | 24.5 | August 2026 |
+| [SanMar FTP Integration Guide](https://www.sanmar.com/medias/sys_master/root/h08/hae/33815499571230/SanMar-FTP-Integration-Guide-v23.6/SanMar-FTP-Integration-Guide-v23.6.pdf) | 23.6 | August 2026 |
+
+Where the guides contradict themselves, the SDK follows SanMar's own WSDLs and file
+headers, recorded in `tests/`. The
+[Sources](https://impressdesigns.dev/sanmar-sdk/sources/) page lists each case.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run nox -s lints tests
+```
+
+The live suite calls SanMar's real services, read-only:
+
+```sh
+SANMAR_LIVE=1 SANMAR_CUSTOMER_NUMBER=... SANMAR_USERNAME=... SANMAR_PASSWORD=... \
+  uv run pytest tests/live
+```

idi_sanmar_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,114 @@
+[project]
+name = "idi-sanmar-sdk"
+version = "1.0.0"
+description = "A typed Python SDK for SanMar’s web services and SFTP files."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "paramiko>=4.0,<5",
+    "pydantic>=2.12",
+    "zeep>=4.3.3",
+]
+
+[[project.authors]]
+name = "Bradley Reynolds"
+email = "bradley.reynolds@impressdesigns.com"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+repository = "https://github.com/impressdesigns/sanmar-sdk"
+documentation = "https://impressdesigns.dev/sanmar-sdk/"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "nox>=2026.8.10",
+    "prek>=0.4.14",
+    "ruff>=0.16.3",
+    "mypy>=2.3.1",
+    "ty>=0.0.72",
+    "types-paramiko>=4.0,<5",
+    "types-requests>=2.32",
+]
+docs = [
+    "sphinx>=9.1.0",
+    "furo>=2025.12.19",
+    "sphinx-autoapi>=3.8.0",
+    "releases>=2.1.1",
+]
+tests = [
+    "coverage>=7.15.2",
+    "pytest>=9.1.1",
+    "pytest-randomly>=4.1.0",
+]
+
+[tool.uv]
+required-version = ">=0.11.8"
+exclude-newer = "P7D"
+environments = ["sys_platform == 'linux' and platform_machine == 'x86_64'"]
+
+[tool.uv.build-backend]
+module-name = "sanmar_sdk"
+
+[tool.ruff]
+line-length = 120
+cache-dir = ".cache/ruff"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "CPY001",
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"docs/*" = ["INP001"]
+"scripts/*" = [
+    "INP001",
+    "T201",
+]
+"tests/*" = ["S101"]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = [
+    "pydantic.BaseModel",
+    "sanmar_sdk.base.Model",
+    "sanmar_sdk.base.Record",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sanmar_sdk"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ty.rules]
+unused-ignore-comment = "ignore"
+
+[tool.mypy]
+pretty = true
+num_workers = 4
+native_parser = true
+plugins = ["pydantic.mypy"]
+cache_dir = ".cache/mypy"
+untyped_calls_exclude = ["zeep"]
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["sanmar_sdk"]
+source_dirs = ["tests"]
+data_file = ".cache/coverage/.coverage"
+omit = [
+    "tests/live/*",
+    "src/sanmar_sdk/*/_wire.py",
+]
+
+[tool.pytest]
+strict = true
+cache_dir = ".cache/pytest"
+markers = ["live: calls SanMar's real services; runs only when SANMAR_LIVE=1 (see tests/live/conftest.py)"]

idi_sanmar_sdk-1.0.0/pyproject.toml.orig

@@ -0,0 +1,135 @@
+[project]
+name = "idi-sanmar-sdk"
+version = "1.0.0"
+description = "A typed Python SDK for SanMar’s web services and SFTP files."
+readme = "README.md"
+authors = [
+    { name = "Bradley Reynolds", email = "bradley.reynolds@impressdesigns.com" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.14"
+dependencies = [
+    # 5.0 removed the ssh-rsa host key algorithm, and SanMar's SFTP server offers nothing newer.
+    # That is why 4.x carries GHSA-r374-rxx8-8654 (SHA-1 in rsakey.py), with no fix short of 5.0.
+    "paramiko>=4.0,<5",
+    "pydantic>=2.12",
+    "zeep>=4.3.3",
+]
+
+[project.urls]
+repository = "https://github.com/impressdesigns/sanmar-sdk"
+documentation = "https://impressdesigns.dev/sanmar-sdk/"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    # DX
+    "nox>=2026.8.10",
+    "prek>=0.4.14",
+    # Linters
+    "ruff>=0.16.3",
+    "mypy>=2.3.1",
+    "ty>=0.0.72",
+    # Stubs
+    "types-paramiko>=4.0,<5",
+    "types-requests>=2.32",
+]
+docs = [
+    "sphinx>=9.1.0",
+    # Theme
+    "furo>=2025.12.19",
+    # Extensions
+    "sphinx-autoapi>=3.8.0",
+    "releases>=2.1.1",
+]
+tests = [
+    "coverage>=7.15.2",
+    "pytest>=9.1.1",
+    # Extensions
+    "pytest-randomly>=4.1.0",
+]
+
+[tool.uv]
+# Sync with Dependabot's uv version
+required-version = ">=0.11.8"
+exclude-newer = "P7D"
+environments = [
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+[tool.uv.build-backend]
+module-name = "sanmar_sdk"
+
+[tool.ruff]
+line-length = 120
+cache-dir = ".cache/ruff"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812", # (missing-trailing-comma) - Conflicts with formatter
+    "CPY001", # (Missing copyright notice at top of file) - No license
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"docs/*" = [
+    "INP001", # (File `docs/conf.py` is part of an implicit namespace package. Add an `__init__.py`.) - Docs are not modules
+]
+"scripts/*" = [
+    "INP001", # (File `scripts/*.py` is part of an implicit namespace package. Add an `__init__.py`.) - Scripts are not modules
+    "T201",   # (`print` found) - Scripts report to the terminal
+]
+"tests/*" = [
+    "S101", # (Use of `assert` detected) - Yes, that's the point
+]
+
+[tool.ruff.lint.flake8-type-checking]
+# Pydantic evaluates annotations at runtime to build validators, so imports used only
+# in model annotations must stay at runtime scope. Without this, py314's deferred
+# annotations make TC rules think they are safe to move into a type-checking block.
+# Ruff cannot follow inheritance across modules, so the SDK's own bases are listed too.
+runtime-evaluated-base-classes = [
+    "pydantic.BaseModel",
+    "sanmar_sdk.base.Model",
+    "sanmar_sdk.base.Record",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sanmar_sdk"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+# Still need to tell Mypy to ignore these
+[tool.ty.rules]
+unused-ignore-comment = "ignore"
+
+[tool.mypy]
+pretty = true
+num_workers = 4
+native_parser = true # required by num_workers
+plugins = ["pydantic.mypy"]
+cache_dir = ".cache/mypy"
+# zeep ships py.typed but leaves most of its API unannotated.
+untyped_calls_exclude = ["zeep"]
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["sanmar_sdk"]
+source_dirs = ["tests"]
+data_file = ".cache/coverage/.coverage"
+omit = [
+    "tests/live/*",
+    # TypedDicts for type checkers only; nothing imports them at runtime.
+    "src/sanmar_sdk/*/_wire.py",
+]
+
+[tool.pytest]
+strict = true
+cache_dir = ".cache/pytest"
+markers = [
+    "live: calls SanMar's real services; runs only when SANMAR_LIVE=1 (see tests/live/conftest.py)",
+]

idi_sanmar_sdk-1.0.0/src/sanmar_sdk/__init__.py

@@ -0,0 +1,49 @@
+"""A typed Python SDK for SanMar's web services and SFTP data files."""
+
+from .client import SanMar
+from .common import (
+    Environment,
+    ShipMethod,
+    ShipTo,
+    SkuKey,
+    StyleColorSize,
+    StyleQuery,
+    Warehouse,
+    WarehouseNumber,
+    WillCall,
+)
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    FileFormatError,
+    NotFoundError,
+    RequestError,
+    ResponseError,
+    SanMarConnectionError,
+    SanMarError,
+    ServiceError,
+    SoapFaultError,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "AuthorizationError",
+    "Environment",
+    "FileFormatError",
+    "NotFoundError",
+    "RequestError",
+    "ResponseError",
+    "SanMar",
+    "SanMarConnectionError",
+    "SanMarError",
+    "ServiceError",
+    "ShipMethod",
+    "ShipTo",
+    "SkuKey",
+    "SoapFaultError",
+    "StyleColorSize",
+    "StyleQuery",
+    "Warehouse",
+    "WarehouseNumber",
+    "WillCall",
+]

idi_sanmar_sdk-1.0.0/src/sanmar_sdk/_snapshots.py

@@ -0,0 +1,118 @@
+"""Recording and replaying SanMar's WSDLs, so tests run through zeep without SanMar.
+
+``scripts/snapshot_wsdls.py`` records every WSDL and schema document zeep loads into a
+directory with an ``index.json``. Tests load that directory into :class:`ReplayTransport`,
+which serves the documents back to zeep and answers each call with a queued response, so a
+payload is validated against SanMar's real schema and a response is parsed exactly as it
+would be in production.
+
+Documents are keyed by path and query only, without the host, so one snapshot serves both
+environments and survives SanMar writing an internal hostname into a schema import.
+"""
+
+import json
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+import requests
+from zeep import Transport
+from zeep.wsdl.utils import etree_to_string
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+INDEX_FILE = "index.json"
+
+
+def document_key(url: str) -> str:
+    """Return the host-independent key a document is stored under."""
+    parts = urlsplit(url)
+    return f"{parts.path}?{parts.query}" if parts.query else parts.path
+
+
+@dataclass
+class WsdlSnapshot:
+    """WSDL and schema documents, keyed by :func:`document_key`."""
+
+    documents: dict[str, bytes] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, directory: Path) -> WsdlSnapshot:
+        """Load a snapshot written by :meth:`save`."""
+        index = json.loads((directory / INDEX_FILE).read_text(encoding="utf-8"))
+        return cls({key: (directory / name).read_bytes() for key, name in index["documents"].items()})
+
+    def save(self, directory: Path, **metadata: Any) -> None:  # noqa: ANN401 - free-form, JSON-serializable
+        """Write every document to ``directory``, alongside an index of their keys."""
+        directory.mkdir(parents=True, exist_ok=True)
+        names: dict[str, str] = {}
+        for key in sorted(self.documents):
+            stem = re.sub(r"[^A-Za-z0-9]+", "_", key).strip("_")
+            name = f"{stem}.xml"
+            suffix = 1
+            while name in names.values():
+                suffix += 1
+                name = f"{stem}_{suffix}.xml"
+            names[key] = name
+            (directory / name).write_bytes(self.documents[key])
+        index = {**metadata, "documents": names}
+        (directory / INDEX_FILE).write_text(json.dumps(index, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+class RecordingTransport(Transport):
+    """A transport that keeps a copy of every document zeep loads."""
+
+    def __init__(self, **kwargs: Any) -> None:  # noqa: ANN401 - forwarded to zeep's Transport
+        """Create the transport; keyword arguments go to zeep's :class:`~zeep.Transport`."""
+        super().__init__(**kwargs)  # type: ignore[no-untyped-call]  # mypy's untyped_calls_exclude misses super()
+        self.snapshot = WsdlSnapshot()
+
+    def load(self, url: str) -> bytes:
+        """Load a document as usual, and record it."""
+        content: bytes = super().load(url)  # type: ignore[no-untyped-call]
+        self.snapshot.documents[document_key(url)] = content
+        return content
+
+
+class ReplayTransport(Transport):
+    """A transport that serves recorded documents and answers calls from a queue.
+
+    Every envelope zeep sends is kept in :attr:`sent`, as ``(address, body)``.
+    """
+
+    def __init__(self, snapshot: WsdlSnapshot) -> None:
+        """Serve documents from ``snapshot``; no call is answered until one is queued."""
+        super().__init__()  # type: ignore[no-untyped-call]
+        self.snapshot = snapshot
+        self.sent: list[tuple[str, bytes]] = []
+        self._responses: deque[tuple[int, bytes]] = deque()
+
+    def queue(self, content: bytes | str, status: int = 200) -> None:
+        """Queue the response to the next call."""
+        self._responses.append((status, content.encode() if isinstance(content, str) else content))
+
+    def load(self, url: str) -> bytes:
+        """Serve a recorded document."""
+        try:
+            return self.snapshot.documents[document_key(url)]
+        except KeyError:
+            message = f"No recorded document for {url}; re-run scripts/snapshot_wsdls.py."
+            raise LookupError(message) from None
+
+    def post_xml(self, address: str, envelope: Any, headers: dict[str, str]) -> requests.Response:  # noqa: ANN401, ARG002 - zeep's signature
+        """Record the envelope and answer with the next queued response."""
+        self.sent.append((address, etree_to_string(envelope)))
+        if not self._responses:
+            message = f"No response queued for the call to {address}."
+            raise LookupError(message)
+        status, content = self._responses.popleft()
+        response = requests.Response()
+        response.status_code = status
+        response._content = content  # noqa: SLF001 - building a canned response
+        response.headers["Content-Type"] = "text/xml; charset=utf-8"
+        response.encoding = "utf-8"
+        response.url = address
+        return response