pixelbin 4.2.0

Description:

pixelbin 4.2.0

Pixelbin Backend SDK for Python
Pixelbin Backend SDK for python helps you integrate the core Pixelbin features with your application.
Getting Started
Getting started with Pixelbin Backend SDK for Python
Installation
pip install pixelbin


Usage
Quick Example
import asyncio

from pixelbin import PixelbinClient, PixelbinConfig

# create client with your API_TOKEN
config = PixelbinConfig({
"domain": "https://api.pixelbin.io",
"apiSecret": "API_TOKEN",
})

# Create a pixelbin instance
pixelbin:PixelbinClient = PixelbinClient(config=config)

# Sync method call
try:
result = pixelbin.assets.listFiles()
print(result)
except Exception as e:
print(e)

# Async method call
try:
result = asyncio.get_event_loop().run_until_complete(pixelbin.assets.listFilesAsync())
print(result)
except Exception as e:
print(e)

Uploader
upload
Uploads a file to PixelBin with greater control over the upload process.
Arguments



Argument
Type
Required
Description




file
bytes or io.BufferedIOBase
yes
The file to be uploaded.


name
str
no
Name of the file.


path
str
no
Path of the containing folder.


format
str
no
Format of the file.


access
AccessEnum
no
Access level of the asset, can be either 'public-read' or 'private'.


tags
list[str]
no
Tags associated with the file.


metadata
dict
no
Metadata associated with the file.


overwrite
bool
no
Overwrite flag. If set to True, will overwrite any file that exists with the same path, name, and type. Defaults to False.


filenameOverride
bool
no
If set to True, will add unique characters to the name if an asset with the given name already exists. If the overwrite flag is set to True, preference will be given to the overwrite flag. If both are set to False, an error will be raised.


expiry
int
no
Expiry time in seconds for the underlying signed URL. Defaults to 3000 seconds.


uploadOptions
dict
no
Additional options for fine-tuning the upload process. Default: { chunk_size: 10 * 1024 * 1024, max_retries: 2, concurrency: 3, exponential_factor: 2 }.


chunkSize
int
no
Size of each chunk to upload. Default is 10 megabytes.


maxRetries
int
no
Maximum number of retries if an upload fails. Default is 2 retries.


concurrency
int
no
Number of concurrent chunk upload tasks. Default is 3 concurrent chunk uploads.


exponentialFactor
int
no
The exponential factor for retry delay. Default is 2.



Returns
dict: On success, returns a dictionary containing the details of the uploaded file.



Property
Description
Example




orgId
Organization ID
5320086


type
Type of the uploaded entity
file


name
Name of the file
testfile.jpeg


path
Path of the containing folder
/path/to/image.jpeg


fileId
ID of the file
testfile.jpeg


access
Access level of the asset, can be public-read or private
public-read


tags
Tags associated with the file
["tag1", "tag2"]


metadata
Metadata associated with the file
{"source":"", "publicUploadId":""}


format
File format
jpeg


assetType
Type of asset
image


size
File size (in bytes)
37394


width
File width (in pixels)
720


height
File height (in pixels)
450


context
File metadata and additional context
{"steps":[],"req":{"headers":{},"query":{}},"meta":{"format":"png","size":195337,"width":812,"height":500,"space":"srgb","channels":4,"depth":"uchar","density":144,"isProgressive":false,"resolutionUnit":"inch","hasProfile":true,"hasAlpha":true,"extension":"jpeg","contentType":"image/png","assetType":"image","isImageAsset":true,"isAudioAsset":false,"isVideoAsset":false,"isRawAsset":false,"isTransformationSupported":true}}


isOriginal
Flag indicating if the file is original
true


_id
Record ID
a0b0b19a-d526-4xc07-ae51-0xxxxxx


url
URL of the uploaded file
https://cdn.pixelbin.io/v2/user-e26cf3/original/testfile.jpeg



Example Usage
Uploading a Buffer
import asyncio
from pixelbin import PixelbinClient, PixelbinConfig

# Create a config with your API_TOKEN
config = PixelbinConfig(
{
"domain": "https://api.pixelbin.io",
"apiSecret": "API_TOKEN",
}
)

# Create a PixelBin client instance
pixelbin = PixelbinClient(config=config)

# Sync method call
try:
# Read the file into a buffer
with open("myimage.png", "rb") as f:
buffer = f.read()

result = pixelbin.uploader.upload(
file=buffer,
name="myimage",
path="folder",
format="png",
tags=[],
metadata={},
overwrite=False,
filenameOverride=True,
access="public-read",
uploadOptions={
"chunkSize": 5 * 1024 * 1024, # 5MB
"concurrency": 2, # 2 concurrent chunk uploads
"maxRetries": 1, # 1 retry for errors that can be retried
"exponentialFactor": 2, # Exponential factor for retries
}
)
print(result["url"])
# "https://cdn.pixelbin.io/v2/mycloudname/original/folder/myimage.png"
except Exception as e:
print(e)

# Async method call
try:
# Read the file into a buffer
with open("myimage.png", "rb") as f:
buffer = f.read()

result = asyncio.get_event_loop().run_until_complete(pixelbin.uploader.uploadAsync(
file=buffer,
name="myimage",
path="folder",
format="png",
tags=[],
metadata={},
overwrite=False,
filenameOverride=True,
access="public-read",
uploadOptions={
"chunkSize": 5 * 1024 * 1024, # 5MB
"concurrency": 2, # 2 concurrent chunk uploads
"maxRetries": 1, # 1 retry for errors that can be retried
"exponentialFactor": 2, # Exponential factor for retries
}
))
print(result["url"])
# "https://cdn.pixelbin.io/v2/mycloudname/original/folder/myimage.png"
except Exception as e:
print(e)

Uploading a Stream
import asyncio
from pixelbin import PixelbinClient, PixelbinConfig

# Create a config with your API_TOKEN
config = PixelbinConfig(
{
"domain": "https://api.pixelbin.io",
"apiSecret": "API_TOKEN",
}
)

# Create a PixelBin client instance
pixelbin = PixelbinClient(config=config)

# Sync method call
try:
result = pixelbin.uploader.upload(
file=open("myimage.png", "rb"), # Open the file as a stream
name="myimage",
path="folder",
format="png",
tags=[],
metadata={},
overwrite=False,
filenameOverride=True,
access="public-read",
uploadOptions={
"chunkSize": 5 * 1024 * 1024, # 5MB
"concurrency": 2, # 2 concurrent chunk uploads
"maxRetries": 1, # 1 retry for errors that can be retried
"exponentialFactor": 2, # Exponential factor for retries
}
)
print(result["url"])
# "https://cdn.pixelbin.io/v2/mycloudname/original/folder/myimage.png"
except Exception as e:
print(e)

# Async method call
try:
result = asyncio.get_event_loop().run_until_complete(pixelbin.uploader.uploadAsync(
file=open("myimage.png", "rb"), # Open the file as a stream
name="myimage",
path="folder",
format="png",
tags=[],
metadata={},
overwrite=False,
filenameOverride=True,
access="public-read",
uploadOptions={
"chunkSize": 5 * 1024 * 1024, # 5MB
"concurrency": 2, # 2 concurrent chunk uploads
"maxRetries": 1, # 1 retry for errors that can be retried
"exponentialFactor": 2, # Exponential factor for retries
}
))
print(result["url"])
# "https://cdn.pixelbin.io/v2/mycloudname/original/folder/myimage.png"
except Exception as e:
print(e)

Security Utils
For generating Signed URLs
Generate a signed PixelBin url



Parameter
Description
Example




url (string)
A valid Pixelbin URL to be signed
https://cdn.pixelbin.io/v2/dummy-cloudname/original/__playground/playground-default.jpeg


expiry_seconds (int)
Number of seconds the signed URL should be valid for
20


access_key (string)
Access key of the token used for signing
6227274d-92c9-4b74-bef8-2528542516d8


token (string)
Value of the token used for signing
dummy-token



Example:
from pixelbin.utils.security import sign_url

signed_url = sign_url(
"https://cdn.pixelbin.io/v2/dummy-cloudname/original/__playground/playground-default.jpeg", # url
20, # expiry_seconds
"6227274d-92c9-4b74-bef8-2528542516d8", # access_key
"dummy-token", # token
);
# signed_url
# https://cdn.pixelbin.io/v2/dummy-cloudname/original/__playground/playground-default.jpeg?pbs=8eb6a00af74e57967a42316e4de238aa88d92961649764fad1832c1bff101f25&pbe=1695635915&pbt=6227274d-92c9-4b74-bef8-2528542516d8

Usage with custom domain url
from pixelbin.utils.security import sign_url

signed_url = sign_url(
"https://test.example.com/v2/original/__playground/playground-default.jpeg", # url
30, # expirySeconds
22, # tokenId
"dummy-token", # token
);
# signedUrl
# https://test.example.com/v2/original/__playground/playground-default.jpeg?pbs=1aef31c1e0ecd8a875b1d3184f324327f4ab4bce419d81d1eb1a818ee5f2e3eb&pbe=1695705975&pbt=22

URL Utils
Pixelbin provides url utilities to construct and deconstruct Pixelbin urls.
url_to_obj
Deconstruct a pixelbin url



parameter
description
example




url (string)
A valid Pixelbin URL
https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg


opts (Object)
Options for the conversion
Default: { isCustomDomain: False }


opts.is_custom_domain
Indicates if the URL belongs to a custom domain (default: False)




Returns:



Property
Description
Example




baseURL (string)
Base path of the URL
https://cdn.pixelbin.io


filePath (string)
Path to the file on Pixelbin storage
/path/to/image.jpeg


version (string)
Version of the URL
v2


cloudName (string)
Cloud name from the URL
your-cloud-name


transformations (array)
A list of transformation objects
[{ "plugin": "t", "name": "flip" }]


zone (string)
Zone slug from the URL
z-slug


pattern (string)
Transformation pattern extracted from the URL
t.resize(h:100,w:200)~t.flip()


worker (boolean)
Indicates if the URL is a URL Translation Worker URL
False


workerPath (string)
Input path to a URL Translation Worker
resize:w200,h400/folder/image.jpeg


options (Object)
Query parameters added, such as "dpr" and "f_auto"
{ dpr: 2.5, f_auto: True}



Example:
from pixelbin.utils.url import url_to_obj

pixelbinUrl = "https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg?dpr=2.0&f_auto=true"
obj = url_to_obj(pixelbinUrl)
# obj
# {
# "cloudName": "your-cloud-name",
# "zone": "z-slug",
# "version": "v2",
# "options": {
# "dpr": 2.0,
# "f_auto": True,
# },
# "transformations": [
# {
# "plugin": "t",
# "name": "resize",
# "values": [
# {
# "key": "h",
# "value": "100"
# },
# {
# "key": "w",
# "value": "200"
# }
# ]
# },
# {
# "plugin": "t",
# "name": "flip",
# }
# ],
# "filePath": "path/to/image.jpeg",
# "baseUrl": "https://cdn.pixelbin.io"
# }

from pixelbin.utils.url import url_to_obj

customDomainUrl =
"https://xyz.designify.media/v2/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg";
obj = url_to_obj(customDomainUrl, opts={ is_custom_domain: True })
# obj
# {
# "zone": "z-slug",
# "version": "v2",
# "transformations": [
# {
# "plugin": "t",
# "name": "resize",
# "values": [
# {
# "key": "h",
# "value": "100"
# },
# {
# "key": "w",
# "value": "200"
# }
# ]
# },
# {
# "plugin": "t",
# "name": "flip",
# }
# ],
# "filePath": "path/to/image.jpeg",
# "baseUrl": "https://xyz.designify.media",
# "wrkr": False,
# "workerPath": "",
# "options": {}
# }

workerUrl =
"https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/wrkr/resize:h100,w:200/folder/image.jpeg";

obj = url_to_obj(workerUrl)
# obj
# {
# "cloudName": "your-cloud-name",
# "zone": "z-slug",
# "version": "v2",
# "transformations": [],
# "filePath": "",
# "worker": True,
# "workerPath": "resize:h100,w:200/folder/image.jpeg",
# "baseUrl": "https://cdn.pixelbin.io"
# "options": {}
# }

obj_to_url
Converts the extracted url obj to a Pixelbin url.



Property
Description
Example




cloudName (string)
The cloudname extracted from the URL
your-cloud-name


zone (string)
6 character zone slug
z-slug


version (string)
CDN API version
v2


transformations (array)
Extracted transformations from the URL
[{ "plugin": "t", "name": "flip" }]


filePath (string)
Path to the file on Pixelbin storage
/path/to/image.jpeg


baseUrl (string)
Base URL
https://cdn.pixelbin.io/


isCustomDomain (boolean)
Indicates if the URL is for a custom domain
False


worker (boolean)
Indicates if the URL is a URL Translation Worker URL
False


workerPath (string)
Input path to a URL Translation Worker
resize:w200,h400/folder/image.jpeg


options (Object)
Query parameters added, such as "dpr" and "f_auto"
{ "dpr": 2.0, "f_auto": True }



from pixelbin.utils.url import obj_to_url

obj = {
cloudName: "your-cloud-name",
zone: "z-slug",
version: "v2",
options: {
dpr: 2.0,
f_auto: True,
},
transformations: [
{
plugin: "t",
name: "resize",
values: [
{
key: "h",
value: "100",
},
{
key: "w",
value: "200",
},
],
},
{
plugin: "t",
name: "flip",
},
],
filePath: "path/to/image.jpeg",
baseUrl: "https://cdn.pixelbin.io",
}
url = obj_to_url(obj) # obj is as shown above
# url
# https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg?dpr=2.0&f_auto=true

Usage with custom domain
from pixelbin.utils.url import obj_to_url

obj = {
zone: "z-slug",
version: "v2",
transformations: [
{
plugin: "t",
name: "resize",
values: [
{
key: "h",
value: "100",
},
{
key: "w",
value: "200",
},
],
},
{
plugin: "t",
name: "flip",
},
],
filePath: "path/to/image.jpeg",
baseUrl: "https://xyz.designify.media",
isCustomDomain: True,
};
url = Pixelbin.utils.objToUrl(obj); # obj is as shown above
# url
# https://xyz.designify.media/v2/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg

Usage with URL Translation Worker
from pixelbin.utils.url import obj_to_url

obj = {
cloudName: "your-cloud-name",
zone: "z-slug",
version: "v2",
transformations: [],
filePath: "",
worker: True,
workerPath: "resize:h100,w:200/folder/image.jpeg",
baseUrl: "https://cdn.pixelbin.io",
};
url = Pixelbin.utils.objToUrl(obj); # obj is as shown above
# url
# https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/wrkr/resize:h100,w:200/folder/image.jpeg

Usage with proxy
In case you are using a proxy, you can set trust_env to True in the httpClientOptions object in the PixelbinConfig object.
The SDK will trust the environment settings for proxy configuration or ~/.netrc file if present.
Quick Example
import asyncio

from pixelbin import PixelbinClient, PixelbinConfig

# create client with your API_TOKEN
config = PixelbinConfig({
"domain": "https://api.pixelbin.io",
"apiSecret": "API_TOKEN",
"options": {
"httpClientOptions": {
"trust_env": True
}
}
})

# Create a pixelbin instance
pixelbin:PixelbinClient = PixelbinClient(config=config)

# Sync method call
try:
result = pixelbin.assets.listFiles()
print(result)
except Exception as e:
print(e)

# Async method call
try:
result = asyncio.get_event_loop().run_until_complete(pixelbin.assets.listFilesAsync())
print(result)
except Exception as e:
print(e)

Documentation

API docs