hive-nectar 0.0.11__py3-none-any.whl → 0.1.0__py3-none-any.whl

nectar/imageuploader.py

@@ -5,6 +5,7 @@ from binascii import hexlify
 import requests
 
 from nectar.account import Account
+from nectar.exceptions import MissingKeyError
 from nectargraphenebase.ecdsasig import sign_message
 
 from .instance import shared_blockchain_instance
@@ -13,46 +14,55 @@ from .instance import shared_blockchain_instance
 class ImageUploader(object):
     def __init__(
         self,
-        base_url="https://steemitimages.com",
+        base_url="https://images.hive.blog",
         challenge="ImageSigningChallenge",
         blockchain_instance=None,
-        **kwargs,
     ):
+        """
+        Initialize the ImageUploader.
+
+        Parameters:
+            base_url (str): Base URL of the image upload service (default: "https://images.hive.blog").
+            challenge (str): ASCII string prepended to the image bytes when constructing the signing message; ensures signatures are bound to this uploader's purpose.
+
+        Notes:
+            blockchain_instance is an optional blockchain client; if not provided a shared instance is used.
+        """
         self.challenge = challenge
         self.base_url = base_url
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
-        self.steem = blockchain_instance or shared_blockchain_instance()
-        if self.steem.is_hive and base_url == "https://steemitimages.com":
-            self.base_url = "https://images.hive.blog"
+        self.blockchain = blockchain_instance or shared_blockchain_instance()
 
     def upload(self, image, account, image_name=None):
-        """Uploads an image
+        """
+        Upload an image to the configured image service, signing the upload with the account's posting key.
 
-        :param image: path to the image or image in bytes representation which should be uploaded
-        :type image: str, bytes
-        :param str account: Account which is used to upload. A posting key must be provided.
-        :param str image_name: optional
+        The function accepts a filesystem path (str), raw bytes, or an io.BytesIO for the image. It locates the account's posting private key from the blockchain wallet, signs the image data together with the uploader's challenge string, and POSTs the image under the key `image_name` (defaults to "image") to: <base_url>/<account_name>/<signature_hex>.
 
-        .. code-block:: python
+        Parameters:
+            image (str | bytes | io.BytesIO): Path to an image file, raw image bytes, or an in-memory bytes buffer.
+            account (str | Account): Account identifier (must have posting permission); used to select the signing key.
+            image_name (str, optional): Form field name for the uploaded image (defaults to "image").
 
-            from nectar import Steem
-            from nectar.imageuploader import ImageUploader
-            stm = Steem(keys=["5xxx"]) # private posting key
-            iu = ImageUploader(blockchain_instance=stm)
-            iu.upload("path/to/image.png", "account_name") # "private posting key belongs to account_name
+        Returns:
+            dict: Parsed JSON response from the image service.
 
+        Raises:
+            AssertionError: If the account's posting permission (and therefore a posting key) cannot be accessed.
         """
-        account = Account(account, blockchain_instance=self.steem)
+        account = Account(account, blockchain_instance=self.blockchain)
         if "posting" not in account:
             account.refresh()
         if "posting" not in account:
             raise AssertionError("Could not access posting permission")
+        posting_wif = None
         for authority in account["posting"]["key_auths"]:
-            posting_wif = self.steem.wallet.getPrivateKeyForPublicKey(authority[0])
+            try:
+                posting_wif = self.blockchain.wallet.getPrivateKeyForPublicKey(authority[0])
+                break
+            except MissingKeyError:
+                continue
+        if not posting_wif:
+            raise AssertionError("No local private posting key available to sign the image.")
 
         if isinstance(image, str):
             image_data = open(image, "rb").read()

nectar/instance.py

@@ -3,122 +3,74 @@ import nectar
 
 
 class SharedInstance(object):
-    """Singelton for the Steem Instance"""
+    """Singleton for the shared Blockchain Instance (Hive-only)."""
 
     instance = None
     config = {}
 
 
 def shared_blockchain_instance():
-    """This method will initialize ``SharedInstance.instance`` and return it.
-    The purpose of this method is to have offer single default
-    steem instance that can be reused by multiple classes.
-
-    .. code-block:: python
-
-        from nectar.account import Account
-        from nectar.instance import shared_steem_instance
-
-        account = Account("test")
-        # is equivalent with
-        account = Account("test", blockchain_instance=shared_steem_instance())
+    """Initialize and return the shared Hive instance.
 
+    Hive-only: this always returns a `nectar.Hive` instance, regardless of any
+    legacy configuration that may have referenced other chains.
     """
     if not SharedInstance.instance:
         clear_cache()
-        from nectar.storage import get_default_config_store
-
-        default_chain = get_default_config_store()["default_chain"]
-        if default_chain == "steem":
-            SharedInstance.instance = nectar.Steem(**SharedInstance.config)
-        else:
-            SharedInstance.instance = nectar.Hive(**SharedInstance.config)
+        SharedInstance.instance = nectar.Hive(**SharedInstance.config)
     return SharedInstance.instance
 
 
 def set_shared_blockchain_instance(blockchain_instance):
-    """This method allows us to override default steem instance for all users of
-    ``SharedInstance.instance``.
+    """
+    Override the shared Hive instance used by the module and clear related caches.
 
-    :param Steem blockchain_instance: Steem instance
+    This sets SharedInstance.instance to the provided blockchain instance and calls clear_cache()
+    to invalidate any cached blockchain objects so consumers observe the new instance immediately.
     """
     clear_cache()
     SharedInstance.instance = blockchain_instance
 
 
-def shared_steem_instance():
-    """This method will initialize ``SharedInstance.instance`` and return it.
-    The purpose of this method is to have offer single default
-    steem instance that can be reused by multiple classes.
-
-    .. code-block:: python
-
-        from nectar.account import Account
-        from nectar.instance import shared_steem_instance
+def shared_hive_instance():
+    """Initialize (if needed) and return the shared Hive instance."""
+    return shared_blockchain_instance()
 
-        account = Account("test")
-        # is equivalent with
-        account = Account("test", blockchain_instance=shared_steem_instance())
 
+def set_shared_hive_instance(hive_instance):
     """
-    if not SharedInstance.instance:
-        clear_cache()
-        SharedInstance.instance = nectar.Steem(**SharedInstance.config)
-    return SharedInstance.instance
-
+    Override the global shared Hive instance used by the module.
 
-def set_shared_steem_instance(steem_instance):
-    """This method allows us to override default steem instance for all users of
-    ``SharedInstance.instance``.
+    Replaces the current SharedInstance.instance with the provided hive_instance and clears related caches so subsequent calls return the new instance.
 
-    :param Steem steem_instance: Steem instance
+    Parameters:
+        hive_instance: The nectar.Hive instance to set as the shared global instance.
     """
-    clear_cache()
-    SharedInstance.instance = steem_instance
-
-
-def shared_hive_instance():
-    """This method will initialize ``SharedInstance.instance`` and return it.
-    The purpose of this method is to have offer single default
-    steem instance that can be reused by multiple classes.
+    set_shared_blockchain_instance(hive_instance)
 
-    .. code-block:: python
-
-        from nectar.account import Account
-        from nectar.instance import shared_hive_instance
-
-        account = Account("test")
-        # is equivalent with
-        account = Account("test", blockchain_instance=shared_hive_instance())
 
+def clear_cache():
     """
-    if not SharedInstance.instance:
-        clear_cache()
-        SharedInstance.instance = nectar.Hive(**SharedInstance.config)
-    return SharedInstance.instance
-
-
-def set_shared_hive_instance(hive_instance):
-    """This method allows us to override default steem instance for all users of
-    ``SharedInstance.instance``.
+    Clear cached blockchain object state.
 
-    :param Hive hive_instance: Hive instance
+    Performs a lazy import of BlockchainObject and calls its clear_cache() method to purge any in-memory caches of blockchain objects (used when the shared Hive instance or configuration changes).
     """
-    clear_cache()
-    SharedInstance.instance = hive_instance
-
-
-def clear_cache():
-    """Clear Caches"""
     from .blockchainobject import BlockchainObject
 
     BlockchainObject.clear_cache()
 
 
 def set_shared_config(config):
-    """This allows to set a config that will be used when calling
-    ``shared_steem_instance`` and allows to define the configuration
-    without requiring to actually create an instance
+    """
+    Set configuration for the shared Hive instance without creating the instance.
+
+    Updates the global SharedInstance.config with the provided mapping. If a shared instance already exists, clears internal caches and resets the shared instance to None so the new configuration will take effect on next access.
+
+    Parameters:
+        config (dict): Configuration options to merge into the shared instance configuration.
+
+    Raises:
+        AssertionError: If `config` is not a dict.
     """
     if not isinstance(config, dict):
         raise AssertionError()