Merge branch 'main' into omar/automate-wheel-build

Author: MOmarMiraj

.github/workflows/validate.yml

@@ -13,13 +13,13 @@ on:
 
 jobs:
 
-  integration-test-trusted:
+  test-trusted:
     # actions that are trusted by default must only be opened from within the repo, and skipped for forks because they'll fail there
     if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -35,7 +35,15 @@ jobs:
           pip install pytest-asyncio &&
           pip install pydantic &&
           python -m pytest src/onepassword/test_client.py
-
+      - name: Example Test
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.9'
+        env:
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.EXAMPLE_TESTS_OP_SERVICE_ACCOUNT_TOKEN }}
+          OP_VAULT_ID: ${{ secrets.EXAMPLE_TESTS_OP_VAULT_ID }}
+        run: |
+          pip install cryptography &&
+          pip install . &&
+          python example/example.py
   lint:
     name: Lint
     runs-on: ubuntu-latest
@@ -84,7 +92,7 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: '3.x'
-          
+
     - name: Integration Test
       env:
         OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.TEST_SERVICE_ACCOUNT_TOKEN }}
@@ -94,8 +102,14 @@ jobs:
         pip install pydantic &&
         python -m pytest src/onepassword/test_client.py
 
-    - run: |
-        echo "Integration tests completed successfully!"
+    - name: Example Test
+      if: matrix.os == 'ubuntu-latest'
+      env:
+        OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.TEST_SERVICE_ACCOUNT_TOKEN }}
+        OP_VAULT_ID: ${{ secrets.TEST_SERVICE_ACCOUNT_VAULT_ID }}
+      run: |
+        pip install . &&
+        python example/example.py
 
     # Update check run called "integration-fork" on the forked PR
     - uses: actions/github-script@v6
@@ -105,7 +119,7 @@ jobs:
         job: ${{ github.job }}
         ref: ${{ github.event.client_payload.pull_request.head.sha }}
         # Conveniently, job.status maps to https://developer.github.com/v3/checks/runs/#update-a-check-run
-        conclusion: ${{ job.status }} 
+        conclusion: ${{ job.status }}
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         script: |

example/README.md

@@ -0,0 +1,48 @@
+# Examples
+This folder contains a code snippet demonstrating how to use the 1Password Python SDK for performing various operations on 1Password vaults and items. Specifically, the example showcases how to:
+
+- Authenticate with the 1Password API using a service account token.
+- List available vaults and items within those vaults.
+- Retrieve a specific secret and resolve a one-time password (TOTP).
+- Create a new item in a vault with multiple fields and tags.
+- Update an existing item by modifying its fields and adding a new website.
+- Generate different types of passwords (PIN, memorable, and random).
+- Share an item with valid recipients and create a shareable link.
+- Archive or delete items from the vault.
+- Create and manage SSH key items.
+- Create and manage document items, including replacing and reading documents.
+- Create and manage file field items by attaching and deleting files.
+
+## Prerequisites
+
+1. Clone the repository and follow the steps to [get started](https://github.com/1Password/onepassword-sdk-python/blob/main/README.md).
+2. Ensure that you have a valid service account token by exporting it as an environment variable:
+    ```bash
+    export OP_SERVICE_ACCOUNT_TOKEN="<your token>"
+    ```
+3. Export the vault UUID you wish to interact with as an environment variable:
+    ```bash
+    export OP_VAULT_ID="<your vault uuid>"
+    ```
+
+## How to Run
+
+To run the example file, navigate to project root directory and run: 
+```bash
+python example/example.py
+```
+
+## Terminal Output
+
+When running the example, the terminal will display:
+
+- A list of vaults and items.
+- Retrieved secrets and TOTP codes.
+- Details of newly created and updated items.
+- Generated passwords (PIN, memorable, random).
+- A shareable link for shared items.
+- SSH key attributes like public key and fingerprint.
+- Document content after replacing the file.
+- A list of file field items and file deletions.
+
+These outputs show the results of vault and item operations, password generation, item sharing, and management of SSH and document items.

example/example.py

@@ -25,17 +25,26 @@ async def main():
     # [developer-docs.sdk.python.client-initialization]-end
 
     # [developer-docs.sdk.python.list-vaults]-start
-    vaults = await client.vaults.list_all()
-    async for vault in vaults:
+    vaults = await client.vaults.list()
+    for vault in vaults:
         print(vault.title)
     # [developer-docs.sdk.python.list-vaults]-end
 
     # [developer-docs.sdk.python.list-items]-start
-    items = await client.items.list_all(vault.id)
-    async for item in items:
-        print(item.title)
+    overviews = await client.items.list(vault.id)
+    for overview in overviews:
+        print(overview.title)
     # [developer-docs.sdk.python.list-items]-end
-
+    # [developer-docs.sdk.python.use-item-filters]-start
+    archived_overviews = await client.items.list(
+        vault.id,
+        ItemListFilterByState(
+            content=ItemListFilterByStateInner(active=False, archived=True)
+        ),
+    )
+    for overview in archived_overviews:
+        print(overview.title)
+        # [developer-docs.sdk.python.use-item-filters]-end
     # [developer-docs.sdk.python.validate-secret-reference]-start
     # Validate secret reference to ensure no syntax errors
     try:
@@ -44,18 +53,16 @@ async def main():
         print(error)
     # [developer-docs.sdk.python.validate-secret-reference]-end
 
-    # [developer-docs.sdk.python.resolve-secret]-start
-    # Retrieves a secret from 1Password. Takes a secret reference as input and returns the secret to which it points.
-    value = await client.secrets.resolve("op://vault/item/field")
-    print(value)
-    # [developer-docs.sdk.python.resolve-secret]-end
+    vault_id= os.getenv("OP_VAULT_ID")
+    if vault_id is None:
+        raise Exception("OP_VAULT_ID environment variable is not set")
 
     # [developer-docs.sdk.python.create-item]-start
     # Create an Item and add it to your vault.
     to_create = ItemCreateParams(
         title="MyName",
         category=ItemCategory.LOGIN,
-        vault_id="7turaasywpymt3jecxoxk5roli",
+        vault_id=vault_id,
         fields=[
             ItemField(
                 id="username",
@@ -95,6 +102,12 @@ async def main():
 
     print(dict(created_item))
 
+    # [developer-docs.sdk.python.resolve-secret]-start
+    # Retrieves a secret from 1Password. Takes a secret reference as input and returns the secret to which it points.
+    value = await client.secrets.resolve(f"op://{created_item.vault_id}/{created_item.id}/username")
+    print(value)
+    # [developer-docs.sdk.python.resolve-secret]-end
+
     # [developer-docs.sdk.python.resolve-totp-code]-start
     # Retrieves a secret from 1Password. Takes a secret reference as input and returns the secret to which it points.
     code = await client.secrets.resolve(
@@ -171,24 +184,22 @@ async def main():
     print(random_password)
     # [developer-docs.sdk.python.generate-random-password]-end
 
-    await share_item(client, created_item.vault_id, updated_item.id)
+    await share_item(client, updated_item.vault_id, updated_item.id)
+
+    await create_ssh_key_item(client, vault_id)
 
-    await create_ssh_key_item(client)
+    await create_and_replace_document_item(client, vault_id)
 
-    await create_and_replace_document_item(client)
+    await create_attach_and_delete_file_field_item(client, vault_id)
 
-    await create_attach_and_delete_file_field_item(client)
+    await archive_item(client, updated_item.vault_id, updated_item.id)
 
     # [developer-docs.sdk.python.delete-item]-start
     # Delete a item from your vault.
     await client.items.delete(created_item.vault_id, updated_item.id)
     # [developer-docs.sdk.python.delete-item]-end
 
 
-## NOTE: this is in a separate function to avoid creating a new item
-## NOTE: just for the sake of archiving it. This is because the SDK
-## NOTE: only works with active items, so archiving and then deleting
-## NOTE: is not yet possible.
 async def archive_item(client: Client, vault_id: str, item_id: str):
     # [developer-docs.sdk.python.archive-item]-start
     # Archive a item from your vault.
@@ -230,7 +241,7 @@ async def share_item(client: Client, vault_id: str, item_id: str):
     # [developer-docs.sdk.python.item-share-create-share]-end
 
 
-async def create_ssh_key_item(client: Client):
+async def create_ssh_key_item(client: Client, vault_id: str):
     # [developer-docs.sdk.python.create-sshkey-item]-start
     # Generate a 2048-bit RSA private key
     private_key = rsa.generate_private_key(
@@ -249,7 +260,7 @@ async def create_ssh_key_item(client: Client):
     to_create = ItemCreateParams(
         title="SSH Key Item Created With Python SDK",
         category=ItemCategory.SSHKEY,
-        vault_id="7turaasywpymt3jecxoxk5roli",
+        vault_id=vault_id,
         fields=[
             ItemField(
                 id="private_key",
@@ -273,13 +284,13 @@ async def create_ssh_key_item(client: Client):
     await client.items.delete(created_item.vault_id, created_item.id)
 
 
-async def create_and_replace_document_item(client: Client):
+async def create_and_replace_document_item(client: Client, vault_id: str):
     # [developer-docs.sdk.python.create-document-item]-start
     # Create a Document Item
     to_create = ItemCreateParams(
         title="Document Item Created with Python SDK",
         category=ItemCategory.DOCUMENT,
-        vault_id="7turaasywpymt3jecxoxk5roli",
+        vault_id=vault_id,
         sections=[
             ItemSection(id="", title=""),
         ],
@@ -312,13 +323,13 @@ async def create_and_replace_document_item(client: Client):
     await client.items.delete(replaced_item.vault_id, replaced_item.id)
 
 
-async def create_attach_and_delete_file_field_item(client: Client):
+async def create_attach_and_delete_file_field_item(client: Client, vault_id: str):
     # [developer-docs.sdk.python.create-item-with-file-field]-start
     # Create a File Field Item
     to_create = ItemCreateParams(
         title="FileField Item created with Python SDK",
         category=ItemCategory.LOGIN,
-        vault_id="7turaasywpymt3jecxoxk5roli",
+        vault_id=vault_id,
         fields=[
             ItemField(
                 id="username",
@@ -388,10 +399,10 @@ async def resolve_all_secrets(
     client: Client, vault_id: str, item_id: str, field_id: str, field_id2: str
 ):
     # [developer-docs.sdk.python.resolve-bulk-secret]-start
-    # Retrieves multiple secret from 1Password.
+    # Retrieves multiple secrets from 1Password.
     secrets = await client.secrets.resolve_all(
         [
-            f"op://{vault_id}//{item_id}/{field_id}",
+            f"op://{vault_id}/{item_id}/{field_id}",
             f"op://{vault_id}/{item_id}/{field_id2}",
         ]
     )

src/onepassword/build_number.py

@@ -1 +1 @@
-SDK_BUILD_NUMBER = "0020101"
+SDK_BUILD_NUMBER = "0030001"

src/onepassword/items.py

@@ -1,12 +1,11 @@
 # Code generated by op-codegen - DO NO EDIT MANUALLY
 
 from .core import _invoke, _invoke_sync
-from .iterator import SDKIterator
 from typing import Optional, List
 from pydantic import TypeAdapter
 from .items_shares import ItemsShares
 from .items_files import ItemsFiles
-from .types import Item, ItemCreateParams, ItemOverview
+from .types import Item, ItemCreateParams, ItemListFilter, ItemOverview
 
 
 class Items:
@@ -113,21 +112,24 @@ async def archive(self, vault_id: str, item_id: str) -> None:
 
         return None
 
-    async def list_all(self, vault_id: str) -> SDKIterator[ItemOverview]:
+    async def list(self, vault_id: str, *filters: ItemListFilter) -> List[ItemOverview]:
         """
-        List all items
+        List items based on filters.
         """
         response = await _invoke(
             {
                 "invocation": {
                     "clientId": self.client_id,
                     "parameters": {
-                        "name": "ItemsListAll",
-                        "parameters": {"vault_id": vault_id},
+                        "name": "ItemsList",
+                        "parameters": {
+                            "vault_id": vault_id,
+                            "filters": [o.model_dump(by_alias=True) for o in filters],
+                        },
                     },
                 }
             }
         )
 
         response = TypeAdapter(List[ItemOverview]).validate_json(response)
-        return SDKIterator(response)
+        return response

src/onepassword/items_files.py

@@ -1,7 +1,6 @@
 # Code generated by op-codegen - DO NO EDIT MANUALLY
 
 from .core import _invoke, _invoke_sync
-from .iterator import SDKIterator
 from typing import Optional, List
 from pydantic import TypeAdapter
 from .types import DocumentCreateParams, FileAttributes, FileCreateParams, Item

src/onepassword/items_shares.py

@@ -1,7 +1,6 @@
 # Code generated by op-codegen - DO NO EDIT MANUALLY
 
 from .core import _invoke, _invoke_sync
-from .iterator import SDKIterator
 from typing import Optional, List
 from pydantic import TypeAdapter
 from .types import Item, ItemShareAccountPolicy, ItemShareParams, ValidRecipient