poelis-sdk 0.3.5__tar.gz → 0.3.6__tar.gz

poelis_sdk-0.3.6/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: poelis-sdk
+Version: 0.3.6
+Summary: Official Python SDK for Poelis
+Project-URL: Homepage, https://poelis.com
+Project-URL: Source, https://github.com/PoelisTechnologies/poelis-python-sdk
+Project-URL: Issues, https://github.com/PoelisTechnologies/poelis-python-sdk/issues
+Author-email: Matteo Braceschi <matteo@poelis.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,client,poelis,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: build>=1.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: twine>=6.2.0
+Description-Content-Type: text/markdown
+
+# Poelis Python SDK
+
+Python SDK for Poelis - explore your data with simple dot notation.
+
+## Installation
+
+```bash
+pip install -U poelis-sdk
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```python
+from poelis_sdk import PoelisClient
+
+# Create client
+poelis = 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
+
+The browser lets you navigate your Poelis data with simple dot notation:
+
+```python
+# Navigate through your data
+poelis = poelis.browser
+
+# List workspaces
+poelis.names()  # ['workspace1', 'workspace2', ...]
+
+# Access workspace
+ws = poelis.workspace1
+
+# List products in workspace  
+ws.names()  # ['product1', 'product2', ...]
+
+# Access product
+product = ws.product1
+
+# List items in product
+product.names()  # ['item1', 'item2', ...]
+
+# Access item and its properties
+item = product.item1
+item_value = item.some_property.value  # Access property values directly
+item_category = item.some_property.category  # Access property categories 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 `names()` at each level to prime autocomplete
+
+## Examples
+
+See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+
+## Requirements
+
+- Python >= 3.11
+- API base URL reachable from your environment
+
+## License
+
+MIT

poelis_sdk-0.3.6/README.md

@@ -0,0 +1,98 @@
+# Poelis Python SDK
+
+Python SDK for Poelis - explore your data with simple dot notation.
+
+## Installation
+
+```bash
+pip install -U poelis-sdk
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```python
+from poelis_sdk import PoelisClient
+
+# Create client
+poelis = 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
+
+The browser lets you navigate your Poelis data with simple dot notation:
+
+```python
+# Navigate through your data
+poelis = poelis.browser
+
+# List workspaces
+poelis.names()  # ['workspace1', 'workspace2', ...]
+
+# Access workspace
+ws = poelis.workspace1
+
+# List products in workspace  
+ws.names()  # ['product1', 'product2', ...]
+
+# Access product
+product = ws.product1
+
+# List items in product
+product.names()  # ['item1', 'item2', ...]
+
+# Access item and its properties
+item = product.item1
+item_value = item.some_property.value  # Access property values directly
+item_category = item.some_property.category  # Access property categories 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 `names()` at each level to prime autocomplete
+
+## Examples
+
+See `notebooks/try_poelis_sdk.ipynb` for complete examples including authentication, data exploration, and search queries.
+
+## Requirements
+
+- Python >= 3.11
+- API base URL reachable from your environment
+
+## License
+
+MIT

{poelis_sdk-0.3.5 → poelis_sdk-0.3.6}/notebooks/try_poelis_sdk.ipynb

@@ -15,9 +15,12 @@
     "## Table of Contents\n",
     "\n",
     "1. [Installation](#Installation)\n",
-    "2. [Authentication Setup](#Authentication-Setup)\n",
-    "3. [Basic Client Setup](#Basic-Client-Setup)\n",
-    "4. [Browser Interface](#Browser-Interface)\n",
+    "2. [IDE Compatibility & Autocomplete](#IDE-Compatibility--Autocomplete)\n",
+    "3. [PyCharm Users: How to Use the SDK](#PyCharm-Users-How-to-Use-the-SDK)\n",
+    "4. [VS Code Users: Perfect Autocomplete Experience](#VS-Code-Users-Perfect-Autocomplete-Experience)\n",
+    "5. [Authentication Setup](#Authentication-Setup)\n",
+    "6. [Basic Client Setup](#Basic-Client-Setup)\n",
+    "7. [Browser Interface](#Browser-Interface)\n",
     "\n"
    ]
   },
@@ -49,17 +52,26 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# Import the SDK\n",
-    "from poelis_sdk import PoelisClient\n",
+    "## IDE Compatibility & Autocomplete\n",
     "\n",
-    "# Check if the SDK is properly installed\n",
-    "print(\"Poelis SDK imported successfully!\")\n",
-    "print(f\"PoelisClient class: {PoelisClient}\")\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"
    ]
   },
   {
@@ -95,8 +107,27 @@
    "source": [
     "## 3. Basic Client Setup\n",
     "\n",
-    "There are two ways to initialize the Poelis client:\n",
+    "There are two ways to initialize the Poelis client:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import the SDK\n",
+    "from poelis_sdk import PoelisClient\n",
     "\n",
+    "# Check if the SDK is properly installed\n",
+    "print(\"Poelis SDK imported successfully!\")\n",
+    "print(f\"PoelisClient class: {PoelisClient}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "### Method 1: Direct Initialization (Simplified)\n"
    ]
   },
@@ -164,6 +195,12 @@
     "- `client.browser.<workspace>.<product>` - Access a specific product\n",
     "- `client.browser.<workspace>.<product>.<item>` - Access a specific item\n",
     "- And so on...\n",
+    "\n",
+    "### IDE Differences\n",
+    "\n",
+    "**VS Code**: Perfect autocomplete works automatically - just press TAB after each dot.\n",
+    "\n",
+    "**PyCharm**: Autocomplete is limited due to static analysis. Use the workarounds shown above (interactive selectors, print helpers, etc.).\n",
     "\n"
    ]
   },
@@ -179,13 +216,46 @@
     "poelis = PoelisClient(\n",
     "    api_key=\"YOUR_API_KEY\",\n",
     "    org_id=\"YOUR_ORG_ID\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## VS Code Users: Perfect Autocomplete Experience\n",
+    "\n",
+    "If you're using VS Code, you get the full autocomplete experience automatically:\n",
+    "\n",
+    "### Step 1: Initialize Client\n",
+    "```python\n",
+    "from poelis_sdk import PoelisClient\n",
+    "\n",
+    "poelis = PoelisClient(\n",
+    "    api_key=\"your_api_key\",\n",
+    "    org_id=\"your_org_id\"\n",
     ")\n",
+    "```\n",
+    "\n",
+    "### Step 2: Use TAB Completion\n",
+    "```python\n",
+    "# Type this and press TAB after the dot:\n",
+    "poelis.browser.  # ← TAB shows all workspaces\n",
+    "\n",
+    "# Select a workspace and continue:\n",
+    "ws = poelis.browser.demoWS\n",
+    "ws.  # ← TAB shows all products\n",
+    "\n",
+    "# Continue navigating:\n",
+    "prod = ws.my_product\n",
+    "prod.  # ← TAB shows all items\n",
     "\n",
-    "# 2) Explore with TAB (completion is installed automatically when accessing client.browser):\n",
-    "# - Type: client.browser. and press TAB to see workspaces\n",
-    "# - Then: client.browser.<workspace>. and TAB to see products\n",
-    "# - Then: client.browser.<workspace>.<product>. and TAB to see items\n",
-    "# - On an item, TAB shows child items and property keys"
+    "# Access properties:\n",
+    "item = prod.demoItem\n",
+    "item.property_name.value  # ← TAB shows all properties\n",
+    "```\n",
+    "\n",
+    "**That's it!** VS Code automatically discovers dynamic attributes and provides perfect autocomplete.\n"
    ]
   },
   {
@@ -196,7 +266,7 @@
    "source": [
     "# 3) Access a property’s value and category via dot paths\n",
     "# Example (replace names with your actual names shown by TAB):\n",
-    "workspace = poelis.browser.UH2_Workspace"
+    "workspace = poelis.browser.demoWS"
    ]
   },
   {
@@ -205,11 +275,75 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "val = workspace.LH2_Tank.cold_box.clv.mass.value\n",
-    "cat = workspace.LH2_Tank.cold_box.clv.mass.category\n",
+    "# 4) Access a property’s value and category via dot paths\n",
+    "mass_value = workspace.demoProduct.demoItem.demoSubItem.demoPropertyMass.value\n",
+    "mass_category = workspace.demoProduct.demoItem.demoSubItem.demoPropertyMass.category\n",
     "\n",
-    "print(\"property value:\", val)\n",
-    "print(\"property category:\", cat)"
+    "print(\"property value:\", mass_value)\n",
+    "print(\"property category:\", mass_category)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## PyCharm Users: How to Use the SDK\n",
+    "\n",
+    "If you're using PyCharm (especially in Jupyter notebooks), here are the best ways to work with the SDK:\n",
+    "\n",
+    "\n",
+    "### Method 1: Print and Copy-Paste\n",
+    "```python\n",
+    "# Print available workspaces\n",
+    "workspaces = poelis.browser.names()\n",
+    "print(workspaces)\n",
+    "```\n",
+    "Output:\n",
+    "\n",
+    "\n",
+    "['demoWS', 'universal_hydrogen']\n",
+    "\n",
+    "```python\n",
+    "# Copy-paste the line you need:\n",
+    "ws = poelis.browser.demoWS  # Works perfectly!\n",
+    "```\n",
+    "\n",
+    "```python\n",
+    "# Print available products\n",
+    "products = ws.names()\n",
+    "print(products)\n",
+    "```\n",
+    "Output:\n",
+    "\n",
+    "\n",
+    "['demoProduct', 'prod1']\n",
+    "\n",
+    "```python\n",
+    "# Copy-paste the line you need:\n",
+    "prod = ws.demoProduct \n",
+    "```\n",
+    "\n",
+    "### Method 2: Dictionary Access (Always Works)\n",
+    "```python\n",
+    "# Always works in any IDE\n",
+    "workspaces = poelis.browser.names()\n",
+    "ws = poelis.browser[workspaces[0]]  # Access by name\n",
+    "\n",
+    "products = ws.names()\n",
+    "prod = ws[products[0]]  # Access by name\n",
+    "```\n",
+    "\n",
+    "**The code works perfectly in PyCharm** - these are just workarounds for when autocomplete doesn't show the dynamic attributes.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "workspaces = poelis.browser.names()\n",
+    "print(workspaces)"
    ]
   },
   {
@@ -218,8 +352,41 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# 4) Go deeper into child items if needed (TAB will suggest only item/property names)\n",
-    "inner = poelis.browser.UH2_Workspace.LH2_Tank.inner_tank"
+    "ws = poelis.browser.demoWS # Replace with your workspace name"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "products = ws.names()\n",
+    "print(products)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "prod = ws.demoProduct # Replace with your product name"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "item = prod.demoItem # Replace with your item name\n",
+    "\n",
+    "property_value = item.demoProperty.value # Replace with your property name\n",
+    "property_category = item.demoProperty.category # Replace with your property name\n",
+    "\n",
+    "print(\"Property value:\", property_value)\n",
+    "print(\"Property category:\", property_category)"
    ]
   }
  ],

{poelis_sdk-0.3.5 → poelis_sdk-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "poelis-sdk"
-version = "0.3.5"
+version = "0.3.6"
 description = "Official Python SDK for Poelis"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,6 +45,10 @@ testpaths = ["tests"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/poelis_sdk"]
+include = [
+  "src/poelis_sdk/**/*.pyi",
+  "src/poelis_sdk/py.typed",
+]
 
 [dependency-groups]
 dev = [

{poelis_sdk-0.3.5 → poelis_sdk-0.3.6}/uv.lock

@@ -538,7 +538,7 @@ wheels = [
 
 [[package]]
 name = "poelis-sdk"
-version = "0.3.5"
+version = "0.3.6"
 source = { editable = "." }
 dependencies = [
     { name = "build" },

poelis_sdk-0.3.5/PKG-INFO

@@ -1,99 +0,0 @@
-Metadata-Version: 2.4
-Name: poelis-sdk
-Version: 0.3.5
-Summary: Official Python SDK for Poelis
-Project-URL: Homepage, https://poelis.com
-Project-URL: Source, https://github.com/PoelisTechnologies/poelis-python-sdk
-Project-URL: Issues, https://github.com/PoelisTechnologies/poelis-python-sdk/issues
-Author-email: Matteo Braceschi <matteo@poelis.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: api,client,poelis,sdk
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.11
-Requires-Dist: build>=1.3.0
-Requires-Dist: httpx>=0.27
-Requires-Dist: pydantic>=2.7
-Requires-Dist: twine>=6.2.0
-Description-Content-Type: text/markdown
-
-# Poelis Python SDK
-
-Python SDK for Poelis.
-
-## Installation
-
-```bash
-pip install -U poelis-sdk
-```
-
-Requires Python 3.11+.
-
-## Quickstart (API key + org ID)
-
-```python
-from poelis_sdk import PoelisClient
-
-client = PoelisClient(
-    api_key="poelis_live_A1B2C3...",    # Organization Settings → API Keys
-    org_id="tenant_uci_001",            # same section
-)
-```
-
-## Configuration
-
-### Getting your API key and org ID
-
-1. Navigate to Organization Settings → API Keys.
-2. Click “Create API key”, choose a name and scopes (read-only by default recommended).
-3. Copy the full key when shown (it will be visible only once). Keep it secret.
-4. The `org_id` for your organization is displayed in the same section.
-5. You can rotate or revoke keys anytime. Prefer storing as env vars:
-
-```bash
-export POELIS_API_KEY=poelis_live_A1B2C3...
-export POELIS_ORG_ID=tenant_id_001
-```
-
-
-### How authentication works
-
-The SDK does not talk to Auth0. It sends your API key directly to the Poelis backend for validation on every request.
-
-- Default headers sent by the SDK:
-
-  - `X-API-Key: <api_key>` (and `X-Poelis-Api-Key` as a compatibility alias)
-  - `Authorization: Api-Key <api_key>` (compatibility for gateways expecting Authorization-only)
-  - `X-Poelis-Org: <org_id>`
-
-You can opt into Bearer mode (legacy) by setting `POELIS_AUTH_MODE=bearer`, which will send:
-
-  - `Authorization: Bearer <api_key>`
-  - `X-Poelis-Org: <org_id>`
-
-The backend validates the API key against your organization, applies authorization and filtering, and returns data.
-
-
-## Dot-path browser (Notebook UX)
-
-The SDK exposes a dot-path browser for easy exploration:
-
-```python
-client.browser  # then use TAB to explore
-# client.browser.<workspace>.<product>.<item>.<child>.properties
-```
-
-See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries). The client defaults to `https://api.poelis.ai` unless `POELIS_BASE_URL` is set.
-
-## Requirements
-
-- Python >= 3.11
-- API base URL reachable from your environment
-
-## License
-
-MIT

poelis_sdk-0.3.5/README.md

@@ -1,76 +0,0 @@
-# Poelis Python SDK
-
-Python SDK for Poelis.
-
-## Installation
-
-```bash
-pip install -U poelis-sdk
-```
-
-Requires Python 3.11+.
-
-## Quickstart (API key + org ID)
-
-```python
-from poelis_sdk import PoelisClient
-
-client = PoelisClient(
-    api_key="poelis_live_A1B2C3...",    # Organization Settings → API Keys
-    org_id="tenant_uci_001",            # same section
-)
-```
-
-## Configuration
-
-### Getting your API key and org ID
-
-1. Navigate to Organization Settings → API Keys.
-2. Click “Create API key”, choose a name and scopes (read-only by default recommended).
-3. Copy the full key when shown (it will be visible only once). Keep it secret.
-4. The `org_id` for your organization is displayed in the same section.
-5. You can rotate or revoke keys anytime. Prefer storing as env vars:
-
-```bash
-export POELIS_API_KEY=poelis_live_A1B2C3...
-export POELIS_ORG_ID=tenant_id_001
-```
-
-
-### How authentication works
-
-The SDK does not talk to Auth0. It sends your API key directly to the Poelis backend for validation on every request.
-
-- Default headers sent by the SDK:
-
-  - `X-API-Key: <api_key>` (and `X-Poelis-Api-Key` as a compatibility alias)
-  - `Authorization: Api-Key <api_key>` (compatibility for gateways expecting Authorization-only)
-  - `X-Poelis-Org: <org_id>`
-
-You can opt into Bearer mode (legacy) by setting `POELIS_AUTH_MODE=bearer`, which will send:
-
-  - `Authorization: Bearer <api_key>`
-  - `X-Poelis-Org: <org_id>`
-
-The backend validates the API key against your organization, applies authorization and filtering, and returns data.
-
-
-## Dot-path browser (Notebook UX)
-
-The SDK exposes a dot-path browser for easy exploration:
-
-```python
-client.browser  # then use TAB to explore
-# client.browser.<workspace>.<product>.<item>.<child>.properties
-```
-
-See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries). The client defaults to `https://api.poelis.ai` unless `POELIS_BASE_URL` is set.
-
-## Requirements
-
-- Python >= 3.11
-- API base URL reachable from your environment
-
-## License
-
-MIT