bifrostsdk 1.0.0__py3-none-any.whl

byfrost/shared/types/dataclass/bridge.py

@@ -0,0 +1,155 @@
+#!usr/bin/env python3
+
+from typing import Optional, Callable, Tuple, List
+from dataclasses import dataclass
+
+from . import file as bfile
+from ...errors.interface import BifrostError
+
+
+@dataclass
+class BridgeConfig:
+    """
+    BridgeConfig is the configuration for the rainbow bridge.
+
+    Attributes:
+
+    provider {str}{required} -- provider is the name of the cloud storage service to use.
+
+    zone {str} -- zone is the service zone to use for storage.
+
+    default_bucket {str} -- default_bucket is the default storage bucket to use for storing.
+    This is only implemented by some providers (e.g. google cloud storage, s3).
+
+    credentials_file {str} -- credentials_file is the path to the credentials file.
+
+    secret_key {str} -- secret_key is the secret key for iam authentication.
+
+    access_key {str} -- access_key is the access key for iam authentication.
+
+    region {str} -- region is the service region to use for storing.
+    This is only implemented by some providers (e.g. s3, google cloud storage).
+
+    default_timeout {int} -- default_timeout is the time-to-live for time-dependent storage operations.
+
+    enable_debug {bool} -- enable_debug enables debug logging.
+
+    project {str} -- project is the cloud project to use for storage.
+    This is only implemented by some providers (e.g. google cloud storage).
+
+    public_read {bool} -- public_read enables public read access to uploaded files.
+
+    use_async {bool} -- use_async enables asynchronous operations with any of asyncio, threads, queue, and multi-processing.
+
+    pinata_jwt {str} -- pinata_jwt is the jwt generated for your pinata cloud account.
+    """
+
+    provider: str
+    """provider is the name of the cloud storage service to use."""
+
+    zone: Optional[str] = ""
+    """zone is the service zone to use for storage."""
+
+    default_bucket: Optional[str] = ""
+    """default_bucket is the default storage bucket to use for storing."""
+
+    credentials_file: Optional[str] = ""
+    """credentials_file is the path to the credentials file."""
+
+    secret_key: Optional[str] = ""
+    """secret_key is the secret key for iam authentication."""
+
+    access_key: Optional[str] = ""
+    """access_key is the access key for iam authentication."""
+
+    region: Optional[str] = ""
+    """region is the service region to use for storing."""
+
+    default_timeout: Optional[int] = 0
+    """default_timeout is the time-to-live for time-dependent storage operations."""
+
+    enable_debug: Optional[bool] = False
+    """enable_debug enables debug logging."""
+
+    project: Optional[str] = ""
+    """project is the cloud project to use for storage. This is only implemented by some providers (e.g. google cloud storage)."""
+
+    public_read: Optional[bool] = False
+    """public_read enables public read access to uploaded files."""
+
+    use_async: Optional[bool] = False
+    """use_async enables asynchronous operations with any of asyncio, threads, queue, and multi-processing."""
+
+    pinata_jwt: Optional[str] = ""
+    """pinata_jwt is the jwt generated for your pinata cloud account."""
+
+
+@dataclass
+class RainbowBridge:
+    """
+    The RainbowBridge interface for Google Cloud Storage. All providers must implement
+    this interface completely.
+
+    Attributes:
+
+    upload_file uploads a file to the provider storage and returns an error if one occurs.
+    Note: for some providers, upload_file requires that a default bucket be set in bifrosbfile.BridgeConfig.
+
+    upload_multi_file uploads mutliple files to the provider storage and returns an error if one occurs. If any of the
+    uploads fail, the error is appended to the []UploadedFile.Error and also logged when debug is enabled while the
+    rest of the uploads continue. Note: for some providers, UploadMultiFile requires that a default bucket be set
+    in bifrosbfile.BridgeConfig.
+
+    disconnect closes the provider client connection and returns an error if one occurs. Disconnect should
+    only be called when the connection is no longer needed.
+
+    config returns the provider configuration.
+
+    is_connected returns true if there is an active connection to the provider.
+
+    upload_folder uploads a folder to the provider storage and returns an error if one occurs.
+    Note: for some providers, upload_folder requires that a default bucket be set in bifrosbfile.BridgeConfig.
+
+    """
+
+    upload_file: Callable[[bfile.File], Tuple[bfile.UploadedFile, BifrostError]]
+    """
+    upload_file uploads a file to the provider storage and returns an error if one occurs.
+
+    Note: for some providers, upload_file requires that a default bucket be set in bifrosbfile.BridgeConfig.
+    """
+
+    upload_multi_file: Callable[
+        [bfile.MultiFile], Tuple[List[bfile.UploadedFile], BifrostError]
+    ]
+    """
+    upload_multi_file uploads mutliple files to the provider storage and returns an error if one occurs. If any of the uploads fail, the error is appended to the []UploadedFile.Error and also logged when debug is enabled while the rest of the uploads continue.
+
+    Note: for some providers, UploadMultiFile requires that a default bucket be set in bifrosbfile.BridgeConfig.
+    """
+
+    disconnect: Callable[[], BifrostError]
+    """
+    disconnect closes the provider client connection and returns an error if one occurs.
+
+    Disconnect should only be called when the connection is no longer needed.
+    """
+
+    config: Callable[[], BridgeConfig]
+    """
+    config returns the provider configuration.
+    """
+
+    is_connected: Callable[[], bool]
+    """
+    is_connected returns true if there is an active connection to the provider.
+    """
+
+    upload_folder: Callable[
+        [bfile.MultiFile], Tuple[List[bfile.UploadedFile], BifrostError]
+    ]
+    """
+    upload_folder uploads a folder to the provider storage and returns an error if one occurs.
+
+    Note: for some providers, upload_folder requires that a default bucket be set in bifrosbfile.BridgeConfig.
+    """

byfrost/shared/types/dataclass/file.py

@@ -0,0 +1,222 @@
+#!usr/bin/env python3
+
+"""
+All type definitions to files in bifrost but using Typed.
+
+This is majorly for end users who want to pass a kwargs dict to the bifrost dataclass when using bifrost functions.
+"""
+
+import queue
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+
+# from shared.errors.interface import BifrostError
+from ...errors.interface import BifrostError
+
+
+@dataclass
+class Options:
+    """
+    Options is a dict of options to store along with each file.
+
+    Attributes:
+        metadata {Dict[str, Any]} -- metadata is a map of metadata to store along with each file.
+        acl {str} -- acl is the access control list to specify the visibility of the file.
+        public: anyone can access the file.
+        private: only authenticated users can access the file.
+    """
+
+    metadata: Optional[Dict[str, Any]] = None
+    """metadata is a map of metadata to store along with each file."""
+
+    acl: Optional[str] = ""
+    """acl is the access control list to specify the visibility of the file
+       public: anyone can access the file.
+       private: only authenticated users can access the file.
+    """
+
+
+@dataclass
+class File:
+    """
+    File is the dict for uploading a single file
+
+    Attributes:
+        path {str}{required} -- path is the path to the file.
+
+        filename {str} -- filename is the name to store the file as with the provider.
+
+        options {Options} -- options is a dict of options to store along with each file.
+    """
+
+    path: str
+    """path is the path to the file."""
+
+    filename: Optional[str] = ""
+    """filename is the name to store the file as with the provider."""
+
+    options: Optional[Options] = None
+    """options is a dict of options to store along with each file."""
+
+    def validate(self):
+        if self.path == "" and self.handle is None:
+            return ValueError("file.path or file.handle is required")
+        if self.path != "" and self.handle is not None:
+            return ValueError("only one of file.path and file.handle can be set")
+        if self.filename == "" and self.handle is not None:
+            return ValueError("file.filename is required when file.handle is set")
+
+
+@dataclass
+class MultiFile:
+    """
+    MultiFile is the dict for uploading multiple files.
+    Along with options, you can also set global options that will be applied to all files.
+
+    Attributes:
+        files {List[File]} -- files is a list of files to upload
+
+        global_options {Options} -- global_options is a map of options to store along with all the files.
+        say 3 of 4 files need to share the same option, you can set globally for those 3 files and set the 4th
+        file's option separately, bifrost won't override the option.
+    """
+
+    files: List[File]
+    """files is a list of files to upload"""
+
+    global_options: Optional[Options] = None
+    """global_options is a map of options to store along with all the files.
+       say 3 of 4 files need to share the same option, you can set globally for those 3 files and set the 4th
+       file's option separately, bifrost won't override the option."""
+
+    def validate(self):
+        if len(self.files) == 0:
+            return ValueError("no files to upload")
+
+        for file in self.files:
+            file.validate()
+
+
+@dataclass
+class ParamFile:
+    """ "
+    ParamFile is the dict for uploading a single file in a multipart request.
+
+    Attributes:
+        name {str}{required} -- name is the name of the file.
+
+        path {str}{required} -- path is the path to the file.
+
+        key {str}{required} -- key is the key to use for the file.
+    """
+
+    name: str
+    """name is the name of the file."""
+
+    path: str
+    """path is the path to the file."""
+
+    key: str
+    """key is the key to use for the file."""
+
+
+@dataclass
+class ParamData:
+    """
+    ParamData is the dict for uploading data along with files in a multipart request.
+
+    Attributes:
+        key {str}{required} -- key is the key to use for the data.
+
+        value {str}{required} -- value is the value to use for the data.
+    """
+
+    key: str
+    """key is the key to use for the data."""
+
+    value: str
+    """value is the value to use for the data."""
+
+
+@dataclass
+class Param:
+    """
+    Param is the dict used to pass parameters to request methods
+
+    Attributes:
+        files {List[ParamFile]} -- files is a list of files to upload.
+
+        data {List[ParamData]} -- data is a list of data to upload along with the files.
+    """
+
+    files: Optional[List[ParamFile]] = None
+    """files is a list of files to upload."""
+
+    data: Optional[List[ParamData]] = None
+    """data is a list of data to upload along with the files."""
+
+
+@dataclass
+class UploadedFile:
+    """
+    UploadedFile is the dict representing a completed file/files upload.
+
+    Attributes:
+        name {str}{required} -- name is the name of the file.
+
+        bucket {str} -- bucket is the bucket the file was uploaded to.
+
+        path {str}{required} -- path is the local path to the file.
+
+        size {int}{required} -- size is the size of the file in bytes.
+
+        url {str}{required} -- url is the location of the file in the cloud.
+
+        preview {str}{required} -- preview is the url to a preview of the file.
+
+        provider_object {Any}{required} -- provider_object is the object returned by the cloud storage provider.
+        you need to cast it to the appropriate type before using it.
+
+        done {queue.Queue} -- done sends a message to signal when an async process is complete.
+
+        quit {queue.Queue} -- quit receives a message to signal for an exit of an async process.
+
+        cid {str} -- cid is the content identifier for the file.
+        this is only implemented by some providers (e.g. Pinata Cloud)
+
+        error {BifrostError} -- error is the error returned by the provider. This is only used for async operations
+        and multi file uploads.
+    """
+
+    name: str
+    """name is the name of the file."""
+
+    path: str
+    """path is the local path to the file."""
+
+    size: int
+    """size is the size of the file in bytes."""
+
+    url: str
+    """url is the location of the file in the cloud."""
+
+    preview: str
+    """preview is the url to a preview of the file."""
+
+    provider_object: Any
+    """provider_object is the object returned by the cloud storage provider."""
+
+    bucket: Optional[str] = ""
+    """bucket is the bucket the file was uploaded to."""
+
+    done: Optional[queue.Queue] = None
+    """done sends a message to signal when an async process is complete."""
+
+    quit: Optional[queue.Queue] = None
+    """quit receives a message to signal for an exit of an async process."""
+
+    cid: Optional[str] = ""
+    """cid is the content identifier for the file."""
+
+    error: Optional[BifrostError] = None
+    """error is the error returned by the provider. This is only used for async operations and multi file uploads."""

byfrost/shared/types/typeddict/__init__.py

@@ -0,0 +1,12 @@
+#!usr/bin/env python3
+
+from .bridge import BridgeConfigDict
+from .file import (
+    OptionsDict,
+    FileDict,
+    MultiFileDict,
+    ParamFileDict,
+    ParamDataDict,
+    ParamDict,
+    UploadedFileDict,
+)

byfrost/shared/types/typeddict/__init__.pyi

@@ -0,0 +1,12 @@
+#!usr/bin/env python3
+
+from .bridge import BridgeConfigDict
+from .file import (
+    OptionsDict,
+    FileDict,
+    MultiFileDict,
+    ParamFileDict,
+    ParamDataDict,
+    ParamDict,
+    UploadedFileDict,
+)

byfrost/shared/types/typeddict/bridge.py

@@ -0,0 +1,85 @@
+#!usr/bin/env python3
+
+import sys
+from typing import TypedDict
+
+if sys.version_info < (3, 11):
+    from typing_extensions import NotRequired
+else:
+    from typing import NotRequired
+
+
+class BridgeConfigDict(TypedDict):
+    """
+    BridgeConfigDict is the configuration for the rainbow bridge.
+
+    Attributes:
+
+    provider {str}{required} -- provider is the name of the cloud storage service to use.
+
+    zone {str} -- zone is the service zone to use for storage.
+
+    default_bucket {str} -- default_bucket is the default storage bucket to use for storing.
+    This is only implemented by some providers (e.g. google cloud storage, s3).
+
+    credentials_file {str} -- credentials_file is the path to the credentials file.
+
+    secret_key {str} -- secret_key is the secret key for iam authentication.
+
+    access_key {str} -- access_key is the access key for iam authentication.
+
+    region {str} -- region is the service region to use for storing.
+    This is only implemented by some providers (e.g. s3, google cloud storage).
+
+    default_timeout {int} -- default_timeout is the time-to-live for time-dependent storage operations.
+
+    enable_debug {bool} -- enable_debug enables debug logging.
+
+    project {str} -- project is the cloud project to use for storage.
+    This is only implemented by some providers (e.g. google cloud storage).
+
+    public_read {bool} -- public_read enables public read access to uploaded files.
+
+    use_async {bool} -- use_async enables asynchronous operations with any of asyncio, threads, queue, and multi-processing.
+
+    pinata_jwt {str} -- pinata_jwt is the jwt generated for your pinata cloud account.
+    """
+
+    provider: str
+    """provider is the name of the cloud storage service to use."""
+
+    zone: NotRequired[str]
+    """zone is the service zone to use for storage."""
+
+    default_bucket: NotRequired[str]
+    """default_bucket is the default storage bucket to use for storing."""
+
+    credentials_file: NotRequired[str]
+    """credentials_file is the path to the credentials file."""
+
+    secret_key: NotRequired[str]
+    """secret_key is the secret key for iam authentication."""
+
+    access_key: NotRequired[str]
+    """access_key is the access key for iam authentication."""
+
+    region: NotRequired[str]
+    """region is the service region to use for storing."""
+
+    default_timeout: NotRequired[int]
+    """default_timeout is the time-to-live for time-dependent storage operations."""
+
+    enable_debug: NotRequired[bool]
+    """enable_debug enables debug logging."""
+
+    project: NotRequired[str]
+    """project is the cloud project to use for storage. This is only implemented by some providers (e.g. google cloud storage)."""
+
+    public_read: NotRequired[bool]
+    """public_read enables public read access to uploaded files."""
+
+    use_async: NotRequired[bool]
+    """use_async enables asynchronous operations with any of asyncio, threads, queue, and multi-processing."""
+
+    pinata_jwt: NotRequired[str]
+    """pinata_jwt is the jwt generated for your pinata cloud account."""

byfrost/shared/types/typeddict/file.py

@@ -0,0 +1,203 @@
+#!usr/bin/env python3
+
+"""
+All type definitions to files in bifrost but using TypedDict.
+
+This is majorly for end users who want to pass a kwargs dict to the bifrost dataclass when using bifrost functions.
+"""
+
+import sys
+from typing import TypedDict, Dict, Any, List
+import queue
+from ...errors.interface import BifrostError
+
+if sys.version_info < (3, 11):
+    from typing_extensions import NotRequired
+else:
+    from typing import NotRequired
+
+
+class OptionsDict(TypedDict):
+    """
+    Options is a dict of options to store along with each file.
+
+    Attributes:
+        metadata {Dict[str, Any]} -- metadata is a map of metadata to store along with each file.
+        acl {str} -- acl is the access control list to specify the visibility of the file.
+        public: anyone can access the file.
+        private: only authenticated users can access the file.
+    """
+
+    metadata: NotRequired[Dict[str, Any]]
+    """metadata is a map of metadata to store along with each file."""
+
+    acl: NotRequired[str]
+    """acl is the access control list to specify the visibility of the file
+       public: anyone can access the file.
+       private: only authenticated users can access the file.
+    """
+
+
+class FileDict(TypedDict):
+    """
+    File is the dict for uploading a single file
+
+    Attributes:
+        path {str}{required} -- path is the path to the file.
+
+        filename {str} -- filename is the name to store the file as with the provider.
+
+        options {OptionsDict} -- options is a dict of options to store along with each file.
+    """
+
+    path: str
+    """path is the path to the file."""
+
+    filemane: NotRequired[str]
+    """filename is the name to store the file as with the provider."""
+
+    options: NotRequired[OptionsDict]
+    """options is a dict of options to store along with each file."""
+
+
+class MultiFileDict(TypedDict):
+    """
+    MultiFile is the dict for uploading multiple files.
+    Along with options, you can also set global options that will be applied to all files.
+
+    Attributes:
+        files {List[FileDict]} -- files is a list of files to upload
+
+        global_options {OptionsDict} -- global_options is a map of options to store along with all the files.
+        say 3 of 4 files need to share the same option, you can set globally for those 3 files and set the 4th
+        file's option separately, bifrost won't override the option.
+    """
+
+    files: List[FileDict]
+    """files is a list of files to upload"""
+
+    global_options: NotRequired[OptionsDict]
+    """global_options is a map of options to store along with all the files.
+       say 3 of 4 files need to share the same option, you can set globally for those 3 files and set the 4th
+       file's option separately, bifrost won't override the option."""
+
+
+class ParamFileDict(TypedDict):
+    """
+    ParamFile is the dict for uploading a single file in a multipart request.
+
+    Attributes:
+        name {str}{required} -- name is the name of the file.
+
+        path {str}{required} -- path is the path to the file.
+
+        key {str}{required} -- key is the key to use for the file.
+    """
+
+    name: str
+    """name is the name of the file."""
+
+    path: str
+    """path is the path to the file."""
+
+    key: str
+    """key is the key to use for the file."""
+
+
+class ParamDataDict(TypedDict):
+    """
+    ParamData is the dict for uploading data along with files in a multipart request.
+
+    Attributes:
+        key {str}{required} -- key is the key to use for the data.
+
+        value {str}{required} -- value is the value to use for the data.
+    """
+
+    key: str
+    """key is the key to use for the data."""
+
+    value: str
+    """value is the value to use for the data."""
+
+
+class ParamDict(TypedDict):
+    """
+    Param is the dict used to pass parameters to request methods
+
+    Attributes:
+        files {List[ParamFile]} -- files is a list of files to upload.
+
+        data {List[ParamData]} -- data is a list of data to upload along with the files.
+    """
+
+    files: NotRequired[List[ParamFileDict]]
+    """files is a list of files to upload."""
+
+    data: NotRequired[List[ParamDataDict]]
+    """data is a list of data to upload along with the files."""
+
+
+class UploadedFileDict(TypedDict):
+    """
+    UploadedFile is the dict representing a completed file/files upload.
+
+    Attributes:
+        name {str}{required} -- name is the name of the file.
+
+        bucket {str} -- bucket is the bucket the file was uploaded to.
+
+        path {str}{required} -- path is the local path to the file.
+
+        size {int}{required} -- size is the size of the file in bytes.
+
+        url {str}{required} -- url is the location of the file in the cloud.
+
+        preview {str}{required} -- preview is the url to a preview of the file.
+
+        provider_object {Any}{required} -- provider_object is the object returned by the cloud storage provider.
+        you need to cast it to the appropriate type before using it.
+
+        done {queue.Queue} -- done sends a message to signal when an async process is complete.
+
+        quit {queue.Queue} -- quit receives a message to signal for an exit of an async process.
+
+        cid {str} -- cid is the content identifier for the file.
+        this is only implemented by some providers (e.g. Pinata Cloud)
+
+        error {BifrostError} -- error is the error returned by the provider. This is only used for async operations
+        and multi file uploads.
+    """
+
+    name: str
+    """name is the name of the file."""
+
+    bucket: NotRequired[str]
+    """bucket is the bucket the file was uploaded to."""
+
+    path: str
+    """path is the local path to the file."""
+
+    size: int
+    """size is the size of the file in bytes."""
+
+    url: str
+    """url is the location of the file in the cloud."""
+
+    preview: str
+    """preview is the url to a preview of the file."""
+
+    provider_object: Any
+    """provider_object is the object returned by the cloud storage provider."""
+
+    done: NotRequired[queue.Queue]
+    """done sends a message to signal when an async process is complete."""
+
+    quit: NotRequired[queue.Queue]
+    """quit receives a message to signal for an exit of an async process."""
+
+    cid: NotRequired[str]
+    """cid is the content identifier for the file."""
+
+    error: NotRequired[BifrostError]
+    """error is the error returned by the provider. This is only used for async operations and multi file uploads."""