poelis-sdk 0.4.2__tar.gz → 0.5.3__tar.gz

{poelis_sdk-0.4.2 → poelis_sdk-0.5.3}/.gitignore

@@ -210,6 +210,8 @@ __marimo__/
 
 # Others
 .cursor/
+tmp/
+
 # Allow GitHub workflows
 !/.github/
 !/.github/workflows/

poelis_sdk-0.5.3/.poelis/baseline.json

@@ -0,0 +1,14 @@
+{
+  "baselines": {
+    "prop1": {
+      "value": 150.0,
+      "name": "Price",
+      "first_accessed_at": 1764778693.876765,
+      "updated_at": null,
+      "updated_by": null
+    }
+  },
+  "accessed_items": {},
+  "accessed_properties": {},
+  "last_updated": 1764778693.8768158
+}

{poelis_sdk-0.4.2 → poelis_sdk-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: poelis-sdk
-Version: 0.4.2
+Version: 0.5.3
 Summary: Official Python SDK for Poelis
 Project-URL: Homepage, https://poelis.com
 Project-URL: Source, https://github.com/PoelisTechnologies/poelis-python-sdk
@@ -25,42 +25,46 @@ Description-Content-Type: text/markdown
 
 Python SDK for Poelis - explore your data with simple dot notation.
 
+## IDE Compatibility & Autocomplete
+
+The Poelis SDK works in all Python environments, but autocomplete behavior varies by IDE:
+
+### ✅ VS Code (Recommended for Notebooks)
+- **Autocomplete**: Works perfectly with dynamic attributes
+- **Setup**: No configuration needed
+- **Experience**: Full autocomplete at all levels
+
+### ⚠️ PyCharm (Jupyter Notebooks)
+- **Autocomplete**: Limited - PyCharm uses static analysis and doesn't see dynamic attributes
+- **Code execution**: Works perfectly (attributes are real and functional)
+- **Workaround**: Call the relevant `list_*().names` at each level to prime autocomplete
+
+## Examples
+
+See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+
 ## Installation
 
+- Python >= 3.11
+- API base URL reachable from your environment
+
 ```bash
 pip install -U poelis-sdk
 ```
 
-Requires Python 3.11+.
-
 ## Quick Start
 
+1. Go to **Organization Settings → API Keys**
+2. Click **\"Create API key\"**
+3. Copy the key (shown only once) and store it securely, for example as an environment variable:
+
 ```python
 from poelis_sdk import PoelisClient
 
 # Create client
-poelis = PoelisClient(
+poelis_client = PoelisClient(
     api_key="poelis_live_A1B2C3...",    # Get from Organization Settings → API Keys
-    org_id="tenant_uci_001",            # Same section
 )
-
-# Use the browser for easy exploration
-poelis = poelis.browser  # Now you can use dot notation!
-
-# Explore your data
-poelis.workspace_name.product_name.item_name
-```
-
-## Getting Your Credentials
-
-1. Go to **Organization Settings → API Keys**
-2. Click **"Create API key"** (read-only recommended)
-3. Copy the key (shown only once) and your `org_id`
-4. Store securely as environment variables:
-
-```bash
-export POELIS_API_KEY=poelis_live_A1B2C3...
-export POELIS_ORG_ID=tenant_uci_001
 ```
 
 ## Browser Usage
@@ -69,7 +73,7 @@ The browser lets you navigate your Poelis data with simple dot notation:
 
 ```python
 # Navigate through your data
-poelis = poelis.browser
+poelis = poelis_client.browser
 
 # List workspaces
 poelis.list_workspaces().names  # ['workspace1', 'workspace2', ...]
@@ -97,31 +101,12 @@ item.list_properties().names  # ['Color', 'Weight', ...] - only properties
 item_value = item.some_property.value  # Access property values directly
 item_category = item.some_property.category  # Access property categories directly
 item_unit = item.some_property.unit  # Access property units directly
-
 ```
 
-## IDE Compatibility & Autocomplete
-
-The Poelis SDK works in all Python environments, but autocomplete behavior varies by IDE:
-
-### ✅ VS Code (Recommended for Notebooks)
-- **Autocomplete**: Works perfectly with dynamic attributes
-- **Setup**: No configuration needed
-- **Experience**: Full autocomplete at all levels
-
-### ⚠️ PyCharm (Jupyter Notebooks)
-- **Autocomplete**: Limited - PyCharm uses static analysis and doesn't see dynamic attributes
-- **Code execution**: Works perfectly (attributes are real and functional)
-- **Workaround**: Call the relevant `list_*().names` at each level to prime autocomplete
+## Property Change Detection
 
-## Examples
-
-See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+The SDK can automatically warn you when property values change between script/notebook runs. This is useful when you're using property values for calculations and want to be notified if a colleague changes them in the webapp.
 
-## Requirements
-
-- Python >= 3.11
-- API base URL reachable from your environment
 
 ## License
 

{poelis_sdk-0.4.2 → poelis_sdk-0.5.3}/README.md

@@ -2,42 +2,46 @@
 
 Python SDK for Poelis - explore your data with simple dot notation.
 
+## IDE Compatibility & Autocomplete
+
+The Poelis SDK works in all Python environments, but autocomplete behavior varies by IDE:
+
+### ✅ VS Code (Recommended for Notebooks)
+- **Autocomplete**: Works perfectly with dynamic attributes
+- **Setup**: No configuration needed
+- **Experience**: Full autocomplete at all levels
+
+### ⚠️ PyCharm (Jupyter Notebooks)
+- **Autocomplete**: Limited - PyCharm uses static analysis and doesn't see dynamic attributes
+- **Code execution**: Works perfectly (attributes are real and functional)
+- **Workaround**: Call the relevant `list_*().names` at each level to prime autocomplete
+
+## Examples
+
+See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+
 ## Installation
 
+- Python >= 3.11
+- API base URL reachable from your environment
+
 ```bash
 pip install -U poelis-sdk
 ```
 
-Requires Python 3.11+.
-
 ## Quick Start
 
+1. Go to **Organization Settings → API Keys**
+2. Click **\"Create API key\"**
+3. Copy the key (shown only once) and store it securely, for example as an environment variable:
+
 ```python
 from poelis_sdk import PoelisClient
 
 # Create client
-poelis = PoelisClient(
+poelis_client = PoelisClient(
     api_key="poelis_live_A1B2C3...",    # Get from Organization Settings → API Keys
-    org_id="tenant_uci_001",            # Same section
 )
-
-# Use the browser for easy exploration
-poelis = poelis.browser  # Now you can use dot notation!
-
-# Explore your data
-poelis.workspace_name.product_name.item_name
-```
-
-## Getting Your Credentials
-
-1. Go to **Organization Settings → API Keys**
-2. Click **"Create API key"** (read-only recommended)
-3. Copy the key (shown only once) and your `org_id`
-4. Store securely as environment variables:
-
-```bash
-export POELIS_API_KEY=poelis_live_A1B2C3...
-export POELIS_ORG_ID=tenant_uci_001
 ```
 
 ## Browser Usage
@@ -46,7 +50,7 @@ The browser lets you navigate your Poelis data with simple dot notation:
 
 ```python
 # Navigate through your data
-poelis = poelis.browser
+poelis = poelis_client.browser
 
 # List workspaces
 poelis.list_workspaces().names  # ['workspace1', 'workspace2', ...]
@@ -74,31 +78,12 @@ item.list_properties().names  # ['Color', 'Weight', ...] - only properties
 item_value = item.some_property.value  # Access property values directly
 item_category = item.some_property.category  # Access property categories directly
 item_unit = item.some_property.unit  # Access property units directly
-
 ```
 
-## IDE Compatibility & Autocomplete
-
-The Poelis SDK works in all Python environments, but autocomplete behavior varies by IDE:
-
-### ✅ VS Code (Recommended for Notebooks)
-- **Autocomplete**: Works perfectly with dynamic attributes
-- **Setup**: No configuration needed
-- **Experience**: Full autocomplete at all levels
-
-### ⚠️ PyCharm (Jupyter Notebooks)
-- **Autocomplete**: Limited - PyCharm uses static analysis and doesn't see dynamic attributes
-- **Code execution**: Works perfectly (attributes are real and functional)
-- **Workaround**: Call the relevant `list_*().names` at each level to prime autocomplete
+## Property Change Detection
 
-## Examples
-
-See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+The SDK can automatically warn you when property values change between script/notebook runs. This is useful when you're using property values for calculations and want to be notified if a colleague changes them in the webapp.
 
-## Requirements
-
-- Python >= 3.11
-- API base URL reachable from your environment
 
 ## License
 

poelis_sdk-0.5.3/notebooks/try_poelis_sdk.ipynb

@@ -0,0 +1,286 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Poelis Python SDK Tutorial\n",
+    "\n",
+    "Welcome to the Poelis Python SDK tutorial! This notebook will guide you through setting up and using the SDK to interact with the Poelis API.\n",
+    "\n",
+    "### What is Poelis?\n",
+    "\n",
+    "Poelis is a platform for managing hierarchical data structures, products, items, and their properties. The Python SDK provides a convenient way to interact with the Poelis API from your Python applications.\n",
+    "\n",
+    "### Table of Contents\n",
+    "\n",
+    "1. [Installation](#1-installation)\n",
+    "2. [IDE Compatibility & Autocomplete](#2-ide-compatibility--autocomplete)\n",
+    "3. [Authentication & Client Setup](#3-authentication--client-setup)\n",
+    "4. [Browser Interface](#4-browser-interface)\n",
+    "5. [Product Versions](#5-product-versions)\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Installation\n",
+    "\n",
+    "### Requirements\n",
+    "- Python >= 3.11\n",
+    "- Access to a Poelis API endpoint\n",
+    "- Valid SDK API key (user-bound; org/workspaces derived server-side)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -U poelis-sdk"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. IDE Compatibility & Autocomplete\n",
+    "\n",
+    "The Poelis SDK works great in both **VS Code** and **PyCharm**, but there are some differences in how autocomplete behaves:\n",
+    "\n",
+    "### VS Code (Recommended for Best Experience)\n",
+    "- ✅ **Perfect autocomplete**: Dynamic attributes work automatically\n",
+    "- ✅ **No setup required**: Just start typing and press TAB\n",
+    "- ✅ **Fast and responsive**: Real-time completion suggestions\n",
+    "- ✅ **Works in Jupyter notebooks**: Full autocomplete support\n",
+    "\n",
+    "### PyCharm (Good, but with limitations)\n",
+    "- ⚠️ **Limited autocomplete**: Uses static analysis, not runtime introspection\n",
+    "- ⚠️ **Requires priming**: Call `names()` at each level for autocomplete\n",
+    "- ✅ **Code works perfectly**: All functionality works, just autocomplete is limited\n",
+    "- ✅ **Workarounds available**: Interactive selectors and helper functions\n",
+    "\n",
+    "**Recommendation**: Use **VS Code** for the best autocomplete experience, especially in Jupyter notebooks.\n",
+    "\n",
+    "### Notebooks vs Python Scripts\n",
+    "\n",
+    "**In Jupyter Notebooks**: The browser interface works great! You get autocomplete (especially in VS Code) and can easily explore your data interactively using dot notation like `poelis.demo_workspace.demo_product`.\n",
+    "\n",
+    "**In Python Scripts**: For better reliability and performance, it's recommended to copy IDs from the webapp and use them directly.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Authentication & Client Setup\n",
+    "\n",
+    "Before you can use the SDK, you need to set up authentication and initialize the client.\n",
+    "\n",
+    "### Getting Your Credentials\n",
+    "\n",
+    "1. **Navigate to Organization Settings → API Keys** in the Poelis web interface\n",
+    "2. **Create a new SDK API key**\n",
+    "3. **Important**: SDK keys are **user-bound**; organization and workspace access are derived on the server from the Poelis user behind that key.\n",
+    "4. With this key, you only see the workspaces your Poelis user is assigned to in that org."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import the SDK\n",
+    "from poelis_sdk import PoelisClient\n",
+    "\n",
+    "# Example: Initialize client (replace with your actual API key)\n",
+    "\n",
+    "poelis_client = PoelisClient(\n",
+    "    api_key=\"your_api_key_here\",\n",
+    ")\n",
+    "\n",
+    "poelis = poelis_client.browser"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Browser Interface\n",
+    "\n",
+    "Navigate your data using dot notation: `poelis.<workspace>.<product>.<item>.<property>`\n",
+    "\n",
+    "**IDE Note**: VS Code has perfect autocomplete. PyCharm users should use `list_*().names` to discover available names.\n",
+    "\n",
+    "### Available Functions\n",
+    "\n",
+    "#### 1. `list_workspaces()` - List all workspaces\n",
+    "\n",
+    "#### 2. `list_products()` - List products in a workspace\n",
+    "\n",
+    "#### 3. `list_items()` - List items in a product/item\n",
+    "\n",
+    "#### 4. `list_properties()` - List properties of an item\n",
+    "\n",
+    "#### 5. `get_property(readable_id)` - Get property by readableId\n",
+    "\n",
+    "\n",
+    "## Property Change Detection\n",
+    "\n",
+    "The SDK can automatically warn you when property values change between script/notebook runs. This is useful when you're using property values for calculations and want to be notified if a colleague changes them in the webapp.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: list_workspaces()\n",
+    "workspaces = poelis.list_workspaces().names\n",
+    "print(\"Available workspaces:\", workspaces)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: list_products()\n",
+    "ws = poelis.demo_workspace  # Replace with your workspace name\n",
+    "products = ws.list_products().names\n",
+    "print(\"Products in workspace:\", products)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: list_items()\n",
+    "prod = ws.demo_product\n",
+    "items = prod.list_items().names\n",
+    "print(items)  # ['item1', 'item2', ...]\n",
+    "\n",
+    "# At item level: lists only child items (not properties)\n",
+    "item = prod.demo_item\n",
+    "child_items = item.list_items().names"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: list_properties()\n",
+    "item = prod.demo_item  # Replace with your item name\n",
+    "properties = item.list_properties().names\n",
+    "print(\"Properties:\", properties)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: get_property(readable_id)\n",
+    "property_readable_id = \"demo_property_mass\"  # Replace with your property's readableId\n",
+    "prop = prod.get_property(property_readable_id)\n",
+    "print(f\"Value: {prop.value}, Category: {prop.category}, Unit: {prop.unit}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Product Versions\n",
+    "\n",
+    "Poelis supports **product versioning**, which allows you to create frozen snapshots of your product data at specific points in time. This is useful for tracking changes, maintaining historical records, and ensuring reproducibility.\n",
+    "\n",
+    "### Understanding Versions\n",
+    "\n",
+    "- **Draft**: The current working state of your product (not yet versioned)\n",
+    "- **Versioned snapshots**: Frozen snapshots of your product at specific version numbers (v1, v2, v3, etc.)\n",
+    "- **Baseline**: The latest versioned snapshot (highest version number)\n",
+    "\n",
+    "**Important**: When you access a product without specifying a version (e.g., `product.my_item`), the SDK defaults to the **baseline** version (the latest versioned snapshot). If no versions exist yet, it falls back to the draft.\n",
+    "\n",
+    "### Available Functions\n",
+    "\n",
+    "#### 1. `list_product_versions()` - List all versions of a product\n",
+    "\n",
+    "#### 2. `get_version()` - Access a version of a product by its title"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: List product versions\n",
+    "product = poelis.demo_workspace.demo_product  # Replace with your product\n",
+    "\n",
+    "# List all available versions (including draft)\n",
+    "versions = product.list_product_versions().names\n",
+    "print(\"Available versions:\", versions)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: Access different versions via browser interface\n",
+    "product = poelis.demo_workspace.demo_product  # Replace with your product\n",
+    "\n",
+    "# Access draft version\n",
+    "draft = product.draft\n",
+    "print(\"Draft version items:\", draft.list_items().names[:5])  # First 5 items\n",
+    "\n",
+    "# Access baseline (latest versioned snapshot)\n",
+    "baseline = product.baseline\n",
+    "print(\"Baseline version items:\", baseline.list_items().names[:5])\n",
+    "\n",
+    "# Access a specific version (e.g., v1)\n",
+    "if \"v1\" in product.list_product_versions().names:\n",
+    "    v1 = product.v1\n",
+    "    print(\"Version 1 items:\", v1.list_items().names[:5])\n",
+    "\n",
+    "# Access a version by name\n",
+    "version_prod_2025 = product.get_version(\"PROD 2025\")\n",
+    "print(\"Version items:\", version_prod_2025.list_items().names[:5])"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

{poelis_sdk-0.4.2 → poelis_sdk-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "poelis-sdk"
-version = "0.4.2"
+version = "0.5.3"
 description = "Official Python SDK for Poelis"
 readme = "README.md"
 requires-python = ">=3.11"

{poelis_sdk-0.4.2 → poelis_sdk-0.5.3}/src/poelis_sdk/_transport.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import os
 import random
 import time
 from typing import Any, Dict, Mapping, Optional
@@ -32,26 +31,18 @@ class Transport:
     in the SDK planning document.
     """
 
-    def __init__(self, base_url: str, api_key: str, org_id: str, timeout_seconds: float) -> None:
+    def __init__(self, base_url: str, api_key: str, timeout_seconds: float) -> None:
         """Initialize the transport.
 
         Args:
             base_url: Base API URL.
             api_key: API key provided by backend to authenticate requests.
-            org_id: Organization id for tenant scoping.
             timeout_seconds: Request timeout in seconds.
         """
 
         self._client = httpx.Client(base_url=base_url, timeout=timeout_seconds)
         self._api_key = api_key
-        self._org_id = org_id
         self._timeout = timeout_seconds
-        # Auth mode is intentionally read from environment to keep the public
-        # constructor signature stable for tests and backwards-compatibility.
-        # Supported values:
-        # - "bearer" (default): Authorization: Bearer <api_key>
-        # - "api_key": X-API-Key/X-Poelis-Api-Key headers with no Authorization
-        self._auth_mode = os.environ.get("POELIS_AUTH_MODE", "api_key").strip().lower()
         
 
     def _headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
@@ -59,20 +50,8 @@ class Transport:
             "Accept": "application/json",
             "Content-Type": "application/json",
         }
-        # Resolve auth mode with a safe fallback in case tests monkeypatch __init__
-        auth_mode = getattr(self, "_auth_mode", None) or os.environ.get("POELIS_AUTH_MODE", "api_key").strip().lower()
-        if auth_mode == "api_key":
-            # Some staging environments expect an API key header and reject Bearer
-            # Include common header variants for compatibility; backend may accept either.
-            headers["X-API-Key"] = self._api_key
-            headers["X-Poelis-Api-Key"] = self._api_key
-            # Additionally include Authorization with Api-Key scheme for services
-            # that only read credentials from Authorization.
-            headers["Authorization"] = f"Api-Key {self._api_key}"
-        else:
-            # Default: send API key as Bearer token
-            headers["Authorization"] = f"Bearer {self._api_key}"
-        headers["X-Poelis-Org"] = self._org_id
+        # Always send API key as Bearer token; backend derives org/workspace from key.
+        headers["Authorization"] = f"Bearer {self._api_key}"
         if extra:
             headers.update(dict(extra))
         return headers