Python SDK 0.2.0 RC (#156)

* Update core to version 7e6c0600

* Release v0.2.0

* update relaese notes

* update examples

* update readme

* add size checks for invocations

* Clear up SSH key example

* add files for File example and clean up example file

* fix path for file examples

* remove unnecessary semicolon

* update dev doc for snippets

* update comments

* clean up example, update error msg for limit and ensure we are checking for bytes not characaters on invocation size check

* fmt example file and update build number

* decode content correctly and update error msg for invoke sync

---------

Co-authored-by: 1PasswordSDKBot <[email protected]>
Co-authored-by: Horia Culea <[email protected]>

Author: 3 people

README.md

@@ -87,18 +87,18 @@ Operations:
 - [x] [Create items](https://developer.1password.com/docs/sdks/manage-items#create-an-item)
 - [x] [Update items](https://developer.1password.com/docs/sdks/manage-items#update-an-item)
 - [x] [Delete items](https://developer.1password.com/docs/sdks/manage-items#delete-an-item)
-- [x] Archive items
+- [x] [Archive items](https://developer.1password.com/docs/sdks/manage-items/#archive-an-item)
 - [x] [List items](https://developer.1password.com/docs/sdks/list-vaults-items/)
-- [x] Share items
-- [x] Generate PIN, random and memorable passwords
+- [x] [Share items](https://developer.1password.com/docs/sdks/share-items) (items with files cannot be shared)
+- [x] [Generate PIN, random and memorable passwords](https://developer.1password.com/docs/sdks/manage-items#generate-a-password)
 
 Field types:
 - [x] API Keys
 - [x] Passwords
 - [x] Concealed fields
 - [x] Text fields
 - [x] Notes
-- [x] SSH private keys, public keys, fingerprint and key type (partially supported: supported in resolving secret references, not yet supported in item create/get/update)
+- [x] SSH private keys, public keys, fingerprint and key type 
 - [x] One-time passwords
 - [x] URLs
 - [x] Websites (used to suggest and autofill logins)
@@ -108,8 +108,10 @@ Field types:
 - [x] Emails
 - [x] References to other items
 - [ ] Address
-- [ ] Date / MM/YY
-- [ ] Files attachments and Document items
+- [ ] Date
+- [x] MM/YY
+- [x] Files attachments and Document items
+- [x] Menu
 
 ### Vault management
 - [ ] Retrieve vaults

example/example.py

@@ -1,9 +1,13 @@
 import asyncio
 import os
+from pathlib import Path
 
 # [developer-docs.sdk.python.sdk-import]-start
 from onepassword import *
+
 # [developer-docs.sdk.python.sdk-import]-end
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives import serialization
 
 
 async def main():
@@ -167,6 +171,12 @@ async def main():
 
     await share_item(client, created_item.vault_id, updated_item.id)
 
+    await create_ssh_key_item(client)
+
+    await create_and_replace_document_item(client)
+
+    await create_attach_and_delete_file_field_item(client)
+
     # [developer-docs.sdk.python.delete-item]-start
     # Delete a item from your vault.
     await client.items.delete(created_item.vault_id, updated_item.id)
@@ -218,5 +228,151 @@ 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):
+    # Generate a 2048-bit RSA private key
+    private_key = rsa.generate_private_key(
+        public_exponent=65537,
+        key_size=4096,
+    )
+
+    # Serialize the private key in PKCS8 format (PEM)
+    ssh_key_pkcs8_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+    # [developer-docs.sdk.python.create-sshkey-item]-start
+    # Create an Item containing SSH Key and add it to your vault.
+    to_create = ItemCreateParams(
+        title="SSH Key Item Created With Python SDK",
+        category=ItemCategory.SSHKEY,
+        vault_id="7turaasywpymt3jecxoxk5roli",
+        fields=[
+            ItemField(
+                id="private_key",
+                title="private key",
+                field_type=ItemFieldType.SSHKEY,
+                value=ssh_key_pkcs8_pem,
+                sectionId="",
+            ),
+        ],
+        sections=[
+            ItemSection(id="", title=""),
+        ],
+    )
+    created_item = await client.items.create(to_create)
+
+    print(created_item.fields[0].value)
+    print(created_item.fields[0].details.content.public_key)
+    print(created_item.fields[0].details.content.fingerprint)
+    print(created_item.fields[0].details.content.key_type)
+    # [developer-docs.sdk.python.create-sshkey-item]-end
+    await client.items.delete(created_item.vault_id, created_item.id)
+
+
+async def create_and_replace_document_item(client: Client):
+    # [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",
+        sections=[
+            ItemSection(id="", title=""),
+        ],
+        document=DocumentCreateParams(
+            name="file.txt", content=Path("./example/file.txt").read_bytes()
+        ),
+    )
+    created_item = await client.items.create(to_create)
+    # [developer-docs.sdk.python.create-document-item]-end
+
+    # [developer-docs.sdk.python.replace-document-item]-start
+    # Replace the document in the item
+    replaced_item = await client.items.files.replace_document(
+        created_item,
+        DocumentCreateParams(
+            name="file2.txt", content=Path("./example/file2.txt").read_bytes()
+        ),
+    )
+    # [developer-docs.sdk.python.replace-document-item]-end
+
+    # [developer-docs.sdk.python.read-document-item]-start
+    # Read the document in the item
+    content = await client.items.files.read(
+        replaced_item.vault_id, replaced_item.id, replaced_item.document
+    )
+    # [developer-docs.sdk.python.read-document-item]-end
+
+    print(content.decode())
+
+    await client.items.delete(replaced_item.vault_id, replaced_item.id)
+
+
+async def create_attach_and_delete_file_field_item(client: Client):
+    # [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",
+        fields=[
+            ItemField(
+                id="username",
+                title="username",
+                field_type=ItemFieldType.TEXT,
+                value="mynameisjeff",
+            ),
+            ItemField(
+                id="password",
+                title="password",
+                field_type=ItemFieldType.CONCEALED,
+                value="jeff",
+            ),
+        ],
+        sections=[
+            ItemSection(id="", title=""),
+        ],
+        files=[
+            FileCreateParams(
+                name="file.txt",
+                content=Path("./example/file.txt").read_bytes(),
+                sectionId="",
+                fieldId="file_field",
+            )
+        ],
+    )
+
+    created_item = await client.items.create(to_create)
+    # [developer-docs.sdk.python.create-item-with-file-field]-end
+
+    # [developer-docs.sdk.python.attach-file-field-item]-start
+    # Attach a file field to the item
+    attached_item = await client.items.files.attach(
+        created_item,
+        FileCreateParams(
+            name="file2.txt",
+            content=Path("./example/file2.txt").read_bytes(),
+            sectionId="",
+            fieldId="new_file_field",
+        ),
+    )
+    # [developer-docs.sdk.python.attach-file-field-item]-end
+
+    # [developer-docs.sdk.python.delete-file-field-item]-start
+    # Delete a file field from an item
+    deleted_file_item = await client.items.files.delete(
+        attached_item,
+        attached_item.files[1].section_id,
+        attached_item.files[1].field_id,
+    )
+    # [developer-docs.sdk.python.delete-file-field-item]-end
+
+    print(len(deleted_file_item.files))
+
+    await client.items.delete(deleted_file_item.vault_id, deleted_file_item.id)
+
+
 if __name__ == "__main__":
     asyncio.run(main())

example/file.txt

@@ -0,0 +1 @@
+Hello World!

example/file2.txt

@@ -0,0 +1 @@
+Hello again, world!

src/onepassword/build_number.py

@@ -1 +1 @@
-SDK_BUILD_NUMBER = "0010701"
+SDK_BUILD_NUMBER = "0020001"

src/onepassword/core.py

@@ -3,6 +3,10 @@
 
 from onepassword.errors import raise_typed_exception
 
+# In empirical tests, we determined that maximum message size that can cross the FFI boundary 
+# is ~128MB. Past this limit, FFI will throw an error and the program will crash.
+# We set the limit to 50MB to be safe and consistent with the other SDKs (where this limit is 64MB), to be reconsidered upon further testing
+MESSAGE_LIMIT = 50 * 1024 * 1024
 
 machine_arch = platform.machine().lower()
 
@@ -26,16 +30,24 @@ async def _init_client(client_config):
 
 # Invoke calls specified business logic from the SDK core.
 async def _invoke(invoke_config):
+    serialized_config = json.dumps(invoke_config)
+    if len(serialized_config.encode()) > MESSAGE_LIMIT:
+        raise ValueError(
+            f"message size exceeds the limit of {MESSAGE_LIMIT} bytes, please contact 1Password at [email protected] or https://developer.1password.com/joinslack if you need help.")
     try:
-        return await core.invoke(json.dumps(invoke_config))
+        return await core.invoke(serialized_config)
     except Exception as e:
         raise_typed_exception(e)
 
 
 # Invoke calls specified business logic from the SDK core.
 def _invoke_sync(invoke_config):
+    serialized_config = json.dumps(invoke_config)
+    if len(serialized_config.encode()) > MESSAGE_LIMIT:
+        raise ValueError(
+            f"message size exceeds the limit of {MESSAGE_LIMIT} bytes, please contact 1Password at [email protected] or https://developer.1password.com/joinslack if you need help.")
     try:
-        return core.invoke_sync(json.dumps(invoke_config))
+        return core.invoke_sync(serialized_config)
     except Exception as e:
         raise_typed_exception(e)
 

src/onepassword/items.py

@@ -5,6 +5,7 @@
 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
 
 
@@ -17,6 +18,8 @@ def __init__(self, client_id):
         self.client_id = client_id
         self.shares = ItemsShares(client_id)
 
+        self.files = ItemsFiles(client_id)
+
     async def create(self, params: ItemCreateParams) -> Item:
         """
         Create a new item.

src/onepassword/items_files.py

@@ -0,0 +1,104 @@
+# 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
+
+
+class ItemsFiles:
+    def __init__(self, client_id):
+        self.client_id = client_id
+
+    async def attach(self, item: Item, file_params: FileCreateParams) -> Item:
+        """
+        Attach files to Items
+        """
+        response = await _invoke(
+            {
+                "invocation": {
+                    "clientId": self.client_id,
+                    "parameters": {
+                        "name": "ItemsFilesAttach",
+                        "parameters": {
+                            "item": item.model_dump(by_alias=True),
+                            "file_params": file_params.model_dump(by_alias=True),
+                        },
+                    },
+                }
+            }
+        )
+
+        response = TypeAdapter(Item).validate_json(response)
+        return response
+
+    async def read(self, vault_id: str, item_id: str, attr: FileAttributes) -> bytes:
+        """
+        Read file content from the Item
+        """
+        response = await _invoke(
+            {
+                "invocation": {
+                    "clientId": self.client_id,
+                    "parameters": {
+                        "name": "ItemsFilesRead",
+                        "parameters": {
+                            "vault_id": vault_id,
+                            "item_id": item_id,
+                            "attr": attr.model_dump(by_alias=True),
+                        },
+                    },
+                }
+            }
+        )
+
+        response = bytes(TypeAdapter(List[int]).validate_json(response))
+        return response
+
+    async def delete(self, item: Item, section_id: str, field_id: str) -> Item:
+        """
+        Delete a field file from Item using the section and field IDs
+        """
+        response = await _invoke(
+            {
+                "invocation": {
+                    "clientId": self.client_id,
+                    "parameters": {
+                        "name": "ItemsFilesDelete",
+                        "parameters": {
+                            "item": item.model_dump(by_alias=True),
+                            "section_id": section_id,
+                            "field_id": field_id,
+                        },
+                    },
+                }
+            }
+        )
+
+        response = TypeAdapter(Item).validate_json(response)
+        return response
+
+    async def replace_document(
+        self, item: Item, doc_params: DocumentCreateParams
+    ) -> Item:
+        """
+        Replace the document file within a document item
+        """
+        response = await _invoke(
+            {
+                "invocation": {
+                    "clientId": self.client_id,
+                    "parameters": {
+                        "name": "ItemsFilesReplaceDocument",
+                        "parameters": {
+                            "item": item.model_dump(by_alias=True),
+                            "doc_params": doc_params.model_dump(by_alias=True),
+                        },
+                    },
+                }
+            }
+        )
+
+        response = TypeAdapter(Item).validate_json(response)
+        return response

src/onepassword/iterator.py

@@ -1,3 +1,5 @@
+# Code generated by op-codegen - DO NOT EDIT MANUALLY
+
 import asyncio
 from typing import AsyncIterator, Iterable, TypeVar