zipline package

zipline.client module

class zipline.Client(server_url, token)

Bases: object

A Zipline client.

async with x:

Returns the client itself. Used to gracefully close the client on exit.

async with zipline.Client(server_url, token) as client:
    ...

async get_version()

This function is a coroutine.

Gets the Zipline server version information.

Returns:

The version information for the server.

Return type:

ServerVersionInfo

async get_user_stats()

This function is a coroutine.

Retrieve stats about the current user.

Returns:

Stats for the current user.

Return type:

UserStats

async create_user(*, username, password, role=UserRole.user, avatar=None)

This function is a coroutine.

Creates a user.

Parameters:

• username (str) – The username of the user to create.

• password (str) – The password of the user to create.

• role (UserRole) – The permissions level of the created User. Only available if used by a Super Admin.

• avatar (Optional[Avatar]) –

  If given, an object containing the avatar to be assigned to the created user.

  Example

  with open('avatar.png', 'rb') as fp:
      avatar_bytes = fp.read()
  
  avatar_mime = 'image/png'
  
  avatar = zipline.Avatar(avatar_mime, avatar_bytes)
  
  user = await create_user(
      username='Example',
      password='s0m3th!ngs3cur3',
      avatar=avatar,
  )
  

Returns:

The created user.

Return type:

User

Raises:

• BadRequest – Missing required fields.

• Forbidden – You do not have permission to use this endpoint.

async get_user(id, /)

This function is a coroutine.

Retrieve a user with given id.

Parameters:

id (str) – The id of the user to get.

Returns:

The retrieved user.

Return type:

User

Raises:

NotFound – A user with that id could not be found

async get_all_users()

This function is a coroutine.

Gets all users.

Returns:

The retrieved users.

Return type:

List[User]

Raises:

Forbidden – You are not an administrator and cannot use this method.

async edit_current_user(username=None, password=None, avatar=..., view_settings=None)

This function is a coroutine.

Edit the currently authenticated user.

Note

Only provided parameters will be updated. At least one parameter must be specified.

Added in version 0.28.0.

Parameters:

• username (Optional[str]) – The new username for the user.

• password (Optional[str]) – The new password for the user.

• avatar (Optional[Avatar]) – The new avatar for the user.

• view_settings (Optional[UserViewSettings]) – The new view settings for the user.

Returns:

The newly edited user model.

Return type:

User

Raises:

• ValueError – No parameters were specified.

• BadRequest – username is already taken or any provided argument is invalid.

async delete_user(id, /, *, remove_data=True)

This function is a coroutine.

Delete a user with given id.

Parameters:

• id (str) – The id of the user to delete.

• remove_data (bool) – Whether the user’s files and urls should be removed, by default True.

Returns:

The deleted user.

Return type:

User

Raises:

Forbidden – You are not an administrator and cannot use this method.

async get_all_invites()

This function is a coroutine.

Retrieves all invites.

Warning

This method may retrieve invites for all users, not just the user the token belongs to.

Returns:

The invites on the server.

Return type:

List[Invite]

async create_invite(*, max_uses=1, expires_at=None)

This function is a coroutine.

Creates an invite.

Changed in version 0.21.0: Removed the count parameter as it’s no longer supported. Return type is now a complete Invite object as opposed to a partial model.

Parameters:

• max_uses (Optional[int]) –

  The number of times the created invite can be used, by default 1. If None is passed the invite will have unlimited uses.

  Added in version 0.21.0.

• expires_at (Optional[Union[datetime.datetime, datetime.timedelta]]) –

  When the created invite(s) should expire.

  Changed in version 0.21.0: Default expiration removed. This parameter will now accept a timedelta. If None is passed, the invite will never expire.

Returns:

The created invite.

Return type:

Invite

Raises:

• ValueError – An invalid argument was passed.

• BadRequest – Provided arguments are invalid.

async delete_invite(id, /)

This function is a coroutine.

Deletes an invite with given id.

Parameters:

id (str) – The id of the invite to delete.

Returns:

The deleted invite.

Return type:

Invite

Raises:

NotFound – The id given was invalid or no longer exists.

async get_all_folders(*, with_files=True)

This function is a coroutine.

Returns all folders.

Parameters:

with_files (Optional[bool]) – Whether the retrieved folder should contain file information, by default True.

Returns:

The retrieved Folders.

Return type:

List[Folder]

async create_folder(name, /, files=None, public=False)

This function is a coroutine.

Creates a folder.

Parameters:

• name (str) – The name of the folder to create.

• public (bool) – Whether the created folder should be public, by default False.

• files (Optional[Sequence[Union[File, str]]]) – Files that should be added to the created folder, if given.

Returns:

The created folder.

Return type:

Folder

Raises:

BadRequest – Folder name is missing or invalid. Invalid file(s) or id(s) provided.

async get_folder(id, /)

This function is a coroutine.

Gets a folder with given id.

Parameters:

id (str) – The id of the folder to get.

Returns:

The requested folder.

Return type:

Folder

Raises:

NotFound – A folder with that id could not be found.

async get_all_urls()

This function is a coroutine.

Retrieves all shortened urls for your user.

Returns:

The requested shortened urls.

Return type:

List[URL]

async shorten_url(original_url, *, vanity=None, max_views=None, password=None, enabled=True, override_domain=None, text_only=False)

This function is a coroutine.

Shortens a url.

Parameters:

• original_url (str) – The url to shorten.

• vanity (Optional[str]) – A vanity name to use. None to receive a randomly assigned name.

• max_views (Optional[int]) – The number of times the url can be used before being deleted. None for unlimited uses, by default None.

• password (Optional[str]) –

  The password required to use the URL, if given.

  Added in version 0.21.0.

• enabled (bool) –

  Whether the url should be enabled for use, by default True.

  Added in version 0.21.0.

• override_domain (Optional[Union[str, List[str]]]) –

  The domain to return a url for. Must still be connected to the Zipline instance or it will not work. If a list of domains is passed, a random one will be chosen.

  Added in version 0.28.0.

• text_only (bool) –

  If True, return a plain text response including only the created url, by default False.

  Added in version 0.28.0.

Returns:

If text_only is False, a full URL instance. Otherwise a plain string with the resulting url.

Return type:

Union[URL, str]

Raises:

• ValueError – Invalid value for max views passed.

• BadRequest – Vanity url already taken, max view invalid, destination is missing.

• Forbidden – Creating the URL would exceed your assigned quota.

async delete_url(id, /)

This function is a coroutine.

Delete a url by given id.

Parameters:

id (str) – The id of the URL to delete.

Returns:

The most recent information about the deleted url.

Return type:

URL

Raises:

NotFound – A url with the given id could not be found.

async get_all_tags()

This function is a coroutine.

Get all tags belonging to the current user.

Returns:

The requested tags.

Return type:

List[Tag]

async get_tag(id, /)

This function is a coroutine.

Get a tag with given id.

Parameters:

id (str) – The id of the tag to retrieve.

Returns:

The requested tag.

Return type:

Tag

Raises:

NotFound – A tag with the given id does not exist.

async create_tag(name, *, color=None)

This function is a coroutine.

Create a tag with a given name and color.

Added in version 0.28.0.

Parameters:

• name (str) – The name for the tag.

• color (Optional[Color]) – The color to be associated with the created tag. If not given, defaults to white.

Returns:

The newly created tag.

Return type:

Tag

Raises:

BadRequest – A tag with this name already exists.

async delete_tag(id, /)

This function is a coroutine.

Delete a tag with given id.

Parameters:

id (str) – The id of the tag to delete.

Returns:

The deleted tag.

Return type:

Tag

Raises:

NotFound – A tag with the given id could not be found.

async get_files(*, page=1, per_page=100, filter=RecentFilesFilter.all, favorite=None, sort_by=FileSearchSort.created_at, order=Order.asc, search_field=FileSearchField.file_name, search_query=None)

This function is a coroutine.

Get files belonging to your user.

Parameters:

• page (int) – The page of files to get.

• per_page (int) – How many files should be returned per page.

• filter (RecentFilesFilter) – A filter to apply to the files retrieved.

• favorite (Optional[bool]) – Whether to search for only favorited or unfavorited files. None for all files.

• sort_by (FileSearchSort) – How the results should be sorted. Defaults to creation datetime.

• order (Order) – How the results should be ordered. Defaults to ascending.

• search_field (FileSearchField) – What file attribute to search by. Defaults to file name.

• search_query (Optional[str]) – The query to use in the search.

Returns:

The requested search results.

Return type:

UserFilesResponse

Raises:

BadRequest – page or per_page are missing or invalid. sort_by, order or search_field/search_query were invalid.

async iter_files(*, per_page=100, filter=RecentFilesFilter.all, favorite=None, sort_by=FileSearchSort.created_at, order=Order.asc, search_field=FileSearchField.file_name, search_query=None)

Retrieves an asynchronous generator of the files owned by the current user that meet the defined criteria.

This method behaves in a similar fashion to get_files().

Added in version 0.25.0.

Example

async for file in client.iter_files():
    if file.deletes_at:
        print(f"{file.full_url} will be removed at: {file.deletes_at:%Y-%m-%d %H:%M:%S})

Parameters:

• per_page (int) – The number of results returned by each iteration, by default 100.

• filter (RecentFilesFilter) – A filter to apply to the files retrieved.

• favorite (Optional[bool]) – Whether to search for only favorited or unfavorited files. None for all files.

• sort_by (FileSearchSort) – How the results should be sorted. Defaults to creation datetime.

• order (Order) – How the results should be ordered. Defaults to ascending.

• search_field (FileSearchField) – What file attribute to search by. Defaults to file name.

• search_query (Optional[str]) – The query to use in the search.

Yields:

File – Files that meet the search criteria.

async get_recent_files(*, amount=10, filter=RecentFilesFilter.all)

This function is a coroutine.

Gets recent files uploaded by the current user.

Parameters:

• amount (Optional[int]) – The number of results to return, by default 10.

• filter (RecentFilesFilter) –

  What files to get.

  Changed in version 0.21.0: This is now controlled by an enum.

Returns:

The requested Files.

Return type:

List[File]

Raises:

• ValueError – An invalid amount was passed.

• BadRequest – An invalid amount was passed.

async delete_files(*files, delete_datasource=False)

This function is a coroutine.

Delete many files from Zipline.

Added in version 0.28.0.

Parameters:

• files (Union[zipline.models.File, str]) – The files to be removed. May either be File objects or a file ids.

• delete_datasource (bool) – Whether to delete the files from the underlying datasource as well. Defaults to False.

Returns:

The number of deleted files.

Return type:

int

Raises:

BadRequest – Invalid file(s) or id(s) provided.

async bulk_file_favorite(*files, favorite)

This function is a coroutine.

Update the favorite status for many files.

Note

For bulk additions to folders, see add_files().

Added in version 0.28.0.

Parameters:

• files (Union[File, str]) – The files to update favorite status for. These can be either File instances or strings representing the ids of the files.

• favorite (bool) – The new favorite status.

Returns:

The number of updated files.

Return type:

int

Raises:

• BadRequest – Invalid file(s) or id(s) provided.

• NotFound – Specified files do not exist.

async upload_file(*payload, format=None, compression_percent=0, expiry=None, password=None, max_views=None, override_name=None, original_name=None, folder=None, override_extension=None, override_domain=None, text_only=False)

This function is a coroutine.

Upload a file to Zipline.

Parameters:

• payload (*FileData) –

  Data regarding the file to upload.

  Changed in version 0.28.0: It is now possible to pass multiple FileData objects.

• format (Optional[NameFormat]) –

  The format of the name to assign to the uploaded file, uses Zipline’s configured name formatting by default.

  Changed in version 0.27.0: This parameter’s default is now None. Previously, it was uuid.

• compression_percent (Optional[int]) – How compressed should the uploaded file be, by default 0.

• expiry (Optional[Union[datetime.datetime, datetime.timedelta]]) –

  When the uploaded file should expire, by default None.

  Changed in version 0.25.0: This parameter now accepts timedeltas as well as concrete datetimes.

• password (Optional[str]) – The password required to view the uploaded file, by default None.

• max_views (Optional[int]) – The number of times the uploaded file can be viewed before it is deleted, by default None.

• override_name (Optional[str]) – A name to give the uploaded file. If provided this will override the server generated name, by default None.

• original_name (Optional[bool]) – Whether to preserve the original name of the file when downloaded.

• folder (Optional[Union[Folder, str]]) –

  The folder (or it’s ID) to place this upload into automatically upon completion.

  Added in version 0.15.0.

• override_extension (Optional[str]) –

  The extension to use for this file instead of the original.

  Added in version 0.21.0.

• override_domain (Optional[Union[str, List[str]]]) –

  The domain to return a url for. Must still be connected to the Zipline instance or it will not work. If a list of domains is passed, a random one will be chosen.

  Added in version 0.25.0.

  Changed in version 0.27.0: It is now possible to pass a list of domains to select one at random from the list given.

• text_only (bool) –

  If True this method returns a simple string containing the url of the uploaded file, by default False.

  Added in version 0.25.0.

Returns:

Information about the file uploaded.

Changed in version 0.25.0: This now returns a str if text_only is True.

Return type:

Union[UploadResponse, str]

Raises:

• ValueError – compression_percent was not in 0 <= compression_percent <= 100. max_views was less than 0. Type of folder is invalid.

• BadRequest – Provided folder does not exist.

• Forbidden – Folder upload not allowed for anonymous user.

• PayloadTooLarge – Processing this upload would exceed the quota assigned to the currently authenticated user.

• ServerError – An unexpected error occurred while processing the upload.

async close()

This function is a coroutine.

Gracefully close the client.

zipline.models module

class zipline.models.File(_http, id, created_at, updated_at, deletes_at, favorite, original_name, name, size, type, views, max_views, password, folder_id, thumbnail, tags, url)

Bases: object

Represents a file stored on Zipline.

str(x)

Returns the full url of the file.

id

The internal id of the file in Zipline.

Type:

str

created_at

When the file was created.

Type:

datetime.datetime

updated_at

When the file was last updated.

Type:

datetime.datetime

deletes_at

The scheduled deletion time of the file, if applicable.

Type:

Optional[datetime.datetime]

favorite

Whether the file is favorited.

Type:

bool

original_name

The original name of the file, if stored.

Type:

Optional[str]

name

The name of the file.

Type:

str

size

The size of the file in bytes.

Type:

int

type

The MIME type of the file.

Type:

str

views

The number of times the file has been viewed.

Type:

int

max_views

The maximum number of times the file can be viewed before being removed, if applicable.

Type:

Optional[int]

password

Whether the file is password protected.

Type:

Optional[Union[str, bool]]

folder_id

The id of the Folder that this file resides in, if applicable.

Type:

Optional[str]

thumbnail

The thumbnail of the file, if available.

Type:

Optional[Thumbnail]

tags

The tags applied to the file.

Type:

List[Tag]

url

The url of this file, if given.

Type:

Optional[str]

property full_url

returns: The full url of this file. :rtype: str

property thumbnail_url

returns: The full url for the thumbnail image, if available. :rtype: Optional[str]

is_password_protected()

Returns the password protection status of this file.

Return type:

bool

async download_password_protected(password)

This function is a coroutine.

Download this file if password protected.

Parameters:

password (str) – The password to use when accessing this file.

Returns:

The content of this file.

Return type:

bytes

Raises:

• Forbidden – Provided password is incorrect.

• NotFound – This file no longer exists or does not have a password.

async refresh()

This function is a coroutine.

Retrieve an updated instance of this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

NotFound – This file no longer exists.

async delete()

This function is a coroutine.

Delete this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

NotFound – This file no longer exists.

async edit(*, favorite=None, tags=None, max_views=None, original_name=None, password=None, type=None)

This function is a coroutine.

Update this file.

Parameters:

• favorite (Optional[bool]) – The new favorite status of the file, if given.

• tags (Optional[Sequence[Tag]]) – Tag to apply to this file, if given.

• max_views (Optional[int]) – The new maximum views of the file, if given.

• original_name (Optional[str]) – The new original name of the file, if given.

• password (Optional[str]) – The new password for the file, if given.

• type (Optional[str]) –

  The new MIME type for the file, if given.

  Warning

  Misuse of this parameter can cause files to display incorrectly or fail outright.

Returns:

The updated file.

Return type:

File

Raises:

• BadRequest – Required fields missing or invalid, numeric fields are invalid, or tags provided are invalid or no longer exist.

• NotFound – This file no longer exists.

async add_favorite()

This function is a coroutine.

Favorite this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

• ValueError – The file is already favorited.

• NotFound – This file no longer exists.

async add_tag(tag, /)

This function is a coroutine.

Add a tag to this file.

Added in version 0.28.0.

Note

This method should not be used for bulk updates. Please use edit() instead.

Equivalent to:

tag = ...

current_tags = file.tags or []
current_tags.append(tag)

await file.edit(tags=current_tags)

Parameters:

tag (Tag) – The tag to be added to this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

• ValueError – The tag is already applied to this file.

• NotFound – This file no longer exists or the provided tag could not be found.

async remove_tag(tag, /)

This function is a coroutine.

Remove a tag from this file.

Added in version 0.28.0.

Note

This method should not be used for bulk updates. Please use edit() instead.

Equivalent to:

tag = ...

current_tags = file.tags or []
current_tags.remove(tag)

await file.edit(tags=current_tags)

Parameters:

tag (Tag) – The tag to be removed from this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

• ValueError – The file does not have the given tag.

• NotFound – This file no longer exists or the tag provided does not exist.

async remove_favorite()

This function is a coroutine.

Unfavorite this file.

Returns:

A new instance with the latest information about this file.

Return type:

File

Raises:

ValueError – The file is already not favorited.

async remove_from_folder()

This function is a coroutine.

Remove this file from it’s current Folder.

Raises:

• BadRequest – This file is not in a folder.

• NotFound – This file no longer exists.

async read()

This function is a coroutine.

Read the content of this file into memory.

Returns:

The content of this file.

Return type:

bytes

class zipline.models.Folder(_http, id, created_at, updated_at, name, public, files, user, user_id)

Bases: object

Represents a folder on Zipline.

str(x)

Returns the full url of the folder.

id

The id of the folder.

Type:

str

created_at

When the folder was created.

Type:

datetime.datetime

updated_at

When the folder was last updated.

Type:

datetime.datetime

name

The name of the folder.

Type:

str

public

Whether the folder is public.

Type:

bool

files

The files contained in the folder, if available.

Type:

Optional[List[File]]

user

The user this folder belongs to, if available.

Type:

Optional[User]

user_id

The id of the user this folder belongs to.

Type:

str

property full_url

A str with the URL of the folder.

async refresh()

This function is a coroutine.

Retrieve an updated instance of this object.

Returns:

A new instance with the latest information about this folder.

Return type:

Folder

Raises:

NotFound – This folder no longer exists.

async delete()

This function is a coroutine.

Delete this folder.

Returns:

A new instance with the latest information about this folder.

Return type:

Folder

Raises:

NotFound – This folder no longer exists.

async edit(*, name=None, public=None, allow_uploads=None)

This function is a coroutine.

Edit this folder.

Parameters:

• name (Optional[str]) –

  The new name of this folder, if given.

  Changed in version 0.28.0: This field is no longer required.

• public (Optional[bool]) –

  Whether this folder should be public.

  Added in version 0.28.0.

• allow_uploads (Optional[bool]) –

  Whether this folder should allow unauthenticated uploads.

  Added in version 0.28.0.

Returns:

The updated folder.

Return type:

Folder

Raises:

• BadRequest – At least one field must be provided.

• NotFound – This folder no longer exists.

async remove_file(file, /)

This function is a coroutine.

Remove a file from this folder.

Parameters:

file (Union[File, str]) – The file or file id to remove from this folder.

Returns:

A new instance with the latest information about this folder.

Return type:

Folder

Raises:

• BadRequest – Provided file not in folder.

• NotFound – This folder no longer exists or the provided file no longer exists.

• Forbidden – The authenticated user does not own the provided file or does not own this folder.

async add_file(file, /)

This function is a coroutine.

Add a file to this folder.

Parameters:

file (Union[File, str]) – The file or file id to add to this folder.

Returns:

A new instance with the latest information about this folder.

Return type:

Folder

Raises:

NotFound – This folder no longer exists.

async add_files(files, /)

This function is a coroutine.

Add multiple files to this folder.

Parameters:

files (Sequence[Union[File, str]]) – The files or file ids to add to this folder.

Returns:

A new instance with the latest information about this folder.

Return type:

Folder

Raises:

• BadRequest – Invalid file(s) or id(s) provided.

• NotFound – Any of the specified files do not exist, this folder no longer exists, or this folder is not owned by the authenticated user.

class zipline.models.User(_http, id, username, created_at, updated_at, role, view, sessions, oauth_providers, totp_secret, passkeys, quota, avatar, password, token)

Bases: object

Represents a Zipline user.

str(x)

Returns the username of this user.

id

The id of this user.

Type:

str

username

The username of this user.

Type:

str

created_at

When this user was created or registered.

Type:

datetime.datetime

updated_at

The last time this user was updated.

Type:

datetime.datetime

role

The role of this user.

Type:

UserRole

view

Custom view info for this user.

Type:

UserViewSettings

sessions

List of session ids this user has open.

Type:

List[str]

oauth_providers

OAuth providers registered for this user.

Type:

List[OAuthProvider]

totp_secret

The user’s timed one-time password secret, if available.

Type:

Optional[str]

passkeys

Passkeys registered for this user.

Type:

List[UserPasskey]

quota

The quota this user has, if applicable.

Type:

Optional[UserQuota]

avatar

The user’s avatar information, if available.

Type:

Optional[Avatar]

password

Password information for this user, if available.

Type:

Optional[str]

token

The user’s token.

Type:

Optional[str]

async refresh()

This function is a coroutine.

Retrieve the latest information about this user.

Returns:

A new instance with the latest information about this user.

Return type:

User

Raises:

NotFound – This user no longer exists.

async edit(*, username=None, password=None, avatar=None, role=None, quota=None)

This function is a coroutine.

Edit this user.

Parameters:

• username (Optional[str]) – The new username for this user, if given.

• password (Optional[str]) – The new password for this user, if given.

• avatar (Optional[Avatar]) – The new avatar for this user, if given.

• role (Optional[UserRole]) – The new role for this user, if given.

• quota (Optional[Union[UserQuota, PartialQuota]]) – The new quota for this user, if given.

Returns:

The updated user.

Return type:

User

Raises:

• BadRequest – Invalid fields, missing required quota properties, invalid role.

• NotFound – If the user with this ID no longer exists.

async delete(*, remove_data=True)

This function is a coroutine.

Delete this user.

Parameters:

remove_data (bool) – Whether this user’s files and urls should be deleted as well, by default True

Returns:

A new instance with the latest information about this user.

Return type:

User

Raises:

• Forbidden – You cannot delete this user.

• NotFound – This user no longer exists.

async get_files(*, page=1, per_page=10, filter=RecentFilesFilter.all, favorite=None, sort_by=FileSearchSort.created_at, order=Order.asc, search_field=FileSearchField.file_name, search_query=None)

This function is a coroutine.

Get files belonging to this user.

Note

This route requires that you have an account with the Super Admin type.

Parameters:

• page (int) – The page of files to get.

• per_page (int) – How many files should be returned per page.

• filter (RecentFilesFilter) – A filter to apply to the files retrieved.

• favorite (Optional[bool]) – Whether to search for only favorited or unfavorited files. None for all files.

• sort_by (FileSearchSort) – How the results should be sorted. Defaults to creation datetime.

• order (Order) – How the results should be ordered. Defaults to ascending.

• search_field (FileSearchField) – What file attribute to search by. Defaults to file name.

• search_query (Optional[str]) – The query to use in the search.

Returns:

The requested search results.

Return type:

UserFilesResponse

class zipline.models.InviteUser(_http, username, id, role)

Bases: object

User information provided with an Invite.

Note

This can be resolved to a User via resolve().

str(x)

Returns the full url of the file.

username

The username of the invite owner.

Type:

str

id

The id of the invite owner.

Type:

str

role

The invite owner’s account type.

Type:

UserRole

async resolve()

This function is a coroutine.

Resolve this object to a full User.

Returns:

The fully fledged user object.

Return type:

User

Raises:

NotFound – The user no longer exists.

class zipline.models.Invite(_http, id, created_at, updated_at, expires_at, code, uses, max_uses, inviter, inviter_id)

Bases: object

Represents an invite to a Zipline instance.

str(x)

Returns the url of the invite.

id

The internal id of the invite.

Type:

str

created_at

When this invite was created.

Type:

datetime.datetime

updated_at

When this invite was last updated.

Type:

datetime.datetime

expires_at

When this invite expires, if applicable.

Type:

Optional[datetime.datetime]

code

The code for this invite.

Type:

str

uses

The number of times this invite has been used.

Type:

int

max_uses

The number of times this invite can be used before it’s no longer valid, if applicable.

Type:

Optional[int]

inviter

The user that is attributed to the creation of this invite.

Type:

InviteUser

inviter_id

The id of the user attributed to the creation of this invite.

Type:

str

property url

returns: The full url of this invite. :rtype: str

async delete()

This function is a coroutine.

Delete this invite.

Returns:

A new instance with the latest information about this invite.

Return type:

Invite

Raises:

NotFound – This invite no longer exists.

async refresh()

This function is a coroutine.

Retreive updated information about this invite.

Returns:

A new instance with the latest information about this invite.

Return type:

Invite

Raises:

NotFound – This invite no longer exists.

class zipline.models.TagFile(http, id)

Bases: object

Partial file given with tags.

Note

This can be resolved to a File via resolve().

id

The internal id of the File represented.

Type:

str

async resolve()

This function is a coroutine.

Retrieve the whole file associated with this partial data.

Returns:

The fully fledged file object.

Return type:

File

Raises:

NotFound – This file no longer exists.

class zipline.models.Tag(_http, id, created_at, updated_at, name, color, files)

Bases: object

Represents a tag on Zipline.

str(x)

Returns the name of this tag.

id

The internal id of the tag.

Type:

str

created_at

When this tag was created.

Type:

datetime.datetime

updated_at

When this tag was last updated.

Type:

datetime.datetime

name

The name of this tag.

Type:

str

color

The color associated with this tag.

Type:

Color

files

Partial files associated with this tag, if available.

Type:

Optional[List[TagFile]]

async edit(color=None, name=None)

This function is a coroutine.

Edit this tag.

Parameters:

• color (Optional[Color]) –

  The new color of the tag, if given.

  Changed in version 0.28.0: This argument now accepts a Color.

• name (Optional[str]) – The new name of the tag, if given.

Returns:

The updated tag.

Return type:

Tag

Raises:

• BadRequest – New name provided is already taken.

• NotFound – This tag no longer exists.

async delete()

This function is a coroutine.

Delete this tag.

Returns:

A new instance with the latest information about this tag.

Return type:

Tag

Raises:

NotFound – This tag no longer exists or does not belong to the currently authenticated user.

async refresh()

This function is a coroutine.

Retrieve the latest information about this tag.

Returns:

A new instance with the latest information about this tag.

Return type:

Tag

Raises:

NotFound – This tag no longer exists.

class zipline.models.URL(_http, id, created_at, updated_at, code, vanity, destination, views, max_views, password, enabled, user, user_id)

Bases: object

Represents a shortened url on Zipline.

str(x)

Returns the link to use the URL.

id

The internal id of the url.

Type:

str

created_at

When this url was created.

Type:

datetime.datetime

updated_at

When this url was last updated.

Type:

datetime.datetime

code

The url code.

Type:

str

vanity

The vanity code of this url, if applicable.

Type:

Optional[str]

destination

The url this url redirects to.

Type:

str

views

The number of times this url has been used.

Type:

int

max_views

The maximum number of times this url can be used, if applicable.

Type:

Optional[int]

password

The password required to use this url.

Type:

Optional[str]

enabled

Whether this url is active for use.

Type:

bool

user

The user this url belongs to.

Type:

Optional[User]

user_id

The id of the user this url belongs to.

Type:

str

property full_url

returns: The full url. :rtype: str

async edit(max_views=None, vanity=None, destination=None, enabled=None, password=None)

This function is a coroutine.

Edit this url.

Parameters:

• max_views (Optional[int]) – The new maximum views, if given.

• vanity (Optional[str]) – The new vanity code this url should have, if given.

• destination (Optional[str]) – The new destination, if given.

• enabled (Optional[bool]) – Whether this url should be usable, if given.

• password (Optional[str]) – The new password required to use this url, if given.

Returns:

The updated url.

Return type:

URL

Raises:

• BadRequest – vanity is already taken, max_views is invalid, or destination is invalid.

• NotFound – This URL no longer exists.

async delete()

This function is a coroutine.

Delete this url.

Returns:

A new instance with the latest information about this url.

Return type:

URL

Raises:

NotFound – This URL no longer exists.

class zipline.models.UploadFile(_http, id, type, url)

Bases: object

File data given by the API when a file is uploaded.

Note

This may be resolved to a full File via resolve().

str(x)

Returns the full url of the uploaded file.

id

The id of the uploaded file.

Type:

str

type

The media type of the uploaded file.

Type:

str

url

The url for the uploaded file.

Type:

str

async resolve()

This function is a coroutine.

Retrieve fully fledged information about this object.

Returns:

The fully fledged file object.

Return type:

File

Raises:

NotFound – This file no longer exists.

class zipline.models.UploadResponse(_http, files, deletes_at)

Bases: object

Response given by the API when a file or multiple files are uploaded.

files

A list of information about the files uploaded.

Type:

List[UploadFile]

class zipline.models.FileData(data, filename=None, *, mimetype=None)

Bases: object

Used to upload a File to Zipline.

data

The file or file like object to open.

Type:

Union[str, bytes, os.PathLike, io.BufferedIOBase]

filename

The name of the file to be uploaded. Defaults to filename of the given path, if applicable.

Type:

Optional[str]

mimetype

The MIME type of the file, if None the lib will attempt to determine it.

Type:

Optional[str]

class zipline.models.PartialQuota(type, value=None, max_urls=...)

Bases: object

A partial quota useful for creating a new quota for a User.

type

The type of this quota.

Type:

QuotaType

value

The value to assign to this quota.

Note

This may only be omitted if type is none

Type:

Optional[int]

max_urls

The url limit for this quota.

Note

This argument may be omitted. If None is passed there will be no limit.

Type:

Optional[int]

class zipline.models.UserQuota(_http, id, created_at, updated_at, files_quota, max_bytes, max_files, max_urls, user, user_id)

Bases: object

Represents a quota assigned to a User in Zipline.

Note

While this class may be used to update a user’s quota this class is not intended to be created manually and should not be used for this purpose.

Usage of PartialQuota is recommended this purpose instead.

id

The id of the quota.

Type:

str

created_at

When this quota was created.

Type:

datetime.datetime

updated_at

When this quota was last updated.

Type:

datetime.datetime

files_quota

The type of this quota.

Type:

QuotaType

max_bytes

The maximum bytes of storage for this quota, if applicable.

Type:

Optional[str]

max_files

The maximum number of files for this quota, if applicable.

Type:

Optional[int]

max_urls

The maximum number of shortened urls for this quota, if applicable.

Type:

Optional[int]

user

The user this quota is assigned to, if given.

Type:

Optional[User]

user_id

The id of the user this quota is assigned to, if given.

Type:

Optional[str]

property type

returns: The type of this quota. :rtype: QuotaType

async resolve_user()

This function is a coroutine.

Resolve the user this quota is assigned to, if possible.

Returns:

The user this quota is assigned to.

Return type:

User

Raises:

• TypeError – The Quota.user_id is None and the user cannot be resolved.

• NotFound – The user associated with this quota no longer exists.

class zipline.models.OAuthProvider(id, created_at, updated_at, user_id, provider, username, access_token, refresh_token, oauth_id)

Bases: object

Represents an OAuth provider being used by a User on Zipline.

id

The internal id of this entry.

Type:

str

created_at

When this entry was created.

Type:

datetime.datetime

updated_at

When this entry was updated.

Type:

datetime.datetime

user_id

The id of the user this provider registration is for.

Type:

str

provider

The service this entry is for.

Type:

OAuthProviderType

username

The username of this entry.

Type:

str

access_token

The access token of this entry.

Type:

str

refresh_token

The refresh token for this entry.

Type:

Optional[str]

oauth_id

The oauth id for this entry.

Type:

Optional[str]

class zipline.models.Thumbnail(path)

Bases: object

Thumbnail data for a Zipline File.

path

The path to this thumbnail.

Type:

str

class zipline.models.UserViewSettings(enabled, align, show_mimetype, show_tags, show_folder, content, embed, embed_title, embed_description, embed_color, embed_site_name)

Bases: object

Represents view settings for a Zipline User.

enabled

Whether the view settings are enabled.

Type:

Optional[bool]

align

How the content should be aligned on the page.

Type:

Optional[Literal[‘left’, ‘center’, ‘right’]]

show_mimetype

Whether the content’s MIME type should be displayed.

Type:

Optional[bool]

show_tags

Whether applied tags should be shown.

Added in version 0.28.0.

Type:

Optional[bool]

show_folder

Whether to show the folder this file is in.

Added in version 0.28.0.

Type:

Optional[bool]

content

Custom content string.

Type:

Optional[str]

embed

Whether embed tags should be present.

Type:

Optional[bool]

embed_title

The title of the embed the content will generate, if applicable.

Type:

Optional[str]

embed_description

The description of the embed the content will generate, if applicable.

Type:

Optional[str]

embed_color

The color of the embed the content will generate, if applicable.

Changed in version 0.28.0: This parameter is now a Color.

Type:

Optional[Color]

embed_site_name

The name of the site the embed will redirect to, if applicable.

Type:

Optional[str]

class zipline.models.ServerVersionInfo(latest_tag, latest_url, latest_commit, is_upstream, is_release, is_latest, version_tag, version_sha, version_url, details_version, details_sha, cached)

Bases: object

Version information for a Zipline instance.

Changed in version 0.28.0: This now only supports the latest versioning scheme in use by Zipline as of 4.1.0.

latest_tag

The latest version tag available.

Type:

str

latest_url

The GitHub link to the latest version tag available.

Type:

str

latest_commit

Information about the latest commit. Only available if the server is running an upstream version. Available keys are: sha, url, pull.

Type:

Optional[Dict[str, Union[str, bool]]]

is_upstream

Whether the server is running an upstream version.

Type:

bool

is_release

Whether the version being run is an official release.

Type:

bool

is_latest

Whether the server is running the latest available version.

Type:

bool

version_tag

The tag of the version the server is running.

Type:

str

version_sha

The SHA of the version the server is running.

Type:

str

version_url

The GitHub link to the current versions commit on GitHub.

Type:

str

details_version

The version currently being run.

Type:

str

details_sha

The SHA of the version currently being run.

Type:

str

cached

Whether the version information retrieved was from the instance cache.

Type:

Optional[bool]

property version

Returns the Zipline version currently in use.

class zipline.models.UserStats(files_uploaded, favorite_files, views, avg_views, storage_used, avg_storage_used, urls_created, url_views, sort_type_count)

Bases: object

Stats for a Zipline User.

files_uploaded

The number of files the user has uploaded.

Type:

int

favorite_files

The number of files the user has favorited.

Type:

int

views

The number of times files uploaded by the user have been viewed.

Type:

int

avg_views

The average number of views a file uploaded by the user has received.

Type:

int

storage_used

The amount of storage the user is using in bytes.

Type:

int

avg_storage_used

The amount of storage a file uploaded by the user takes up in bytes.

Type:

float

urls_created

The number of urls the user has created.

Type:

int

url_views

The number of times urls created by the user have been visited.

Type:

int

sort_type_count

A mapping of MIME type to number of files uploaded.

Type:

Dict[str, int]

class zipline.models.UserFilesResponse(page, search, total, pages)

Bases: object

Represents a response to a file search on Zipline.

page

The files on this page.

Type:

List[File]

search

Search parameters that were passed.

Type:

Optional[Dict[str, Any]]

total

The total number of items matching the search.

Type:

Optional[int]

pages

The number of pages available.

Type:

Optional[int]

property files

Alias for page.

class zipline.models.Avatar(data, mime=None)

Bases: object

Wraps the representation of avatars in Zipline.

str(x)

Returns the encoded data for this Avatar.

data

The avatar data itself.

Type:

bytes

mime

The MIME type of the data. If not given the library will attempt to guess the type.

Type:

Optional[str]

classmethod from_coded_string(coded_str)

Transforms a coded string.

Parameters:

coded_str (str) – The string to transform

to_payload_str()

Returns the base64 encoded string for use in Zipline requests.

Returns:

The string for use in requests.

Return type:

str

Raises:

ZiplineError – MIME type is None.

zipline.enums module

class zipline.enums.NameFormat(value)

Bases: str, Enum

Format for the name of uploaded files.

class zipline.enums.UserRole(value)

Bases: str, Enum

The role of a Zipline user.

class zipline.enums.RecentFilesFilter(value)

Bases: str, Enum

Filters that apply to recent files requests.

class zipline.enums.QuotaType(value)

Bases: str, Enum

The different types of quotas that can be applied to a user.

class zipline.enums.OAuthProviderType(value)

Bases: str, Enum

Supported types of OAuth providers.

class zipline.enums.FileSearchField(value)

Bases: str, Enum

Fields that can be searched by.

class zipline.enums.FileSearchSort(value)

Bases: str, Enum

Fields that files can be ordered by.

zipline.color module

class zipline.color.Color(value)

Bases: object

Represents a color for use on Zipline.

An alias named Colour is also supplied.

str(x)

Returns the hex format of the color.

int(x)

Returns the raw value of the color.

value

The raw integer value of this color.

Type:

int

to_hex()

Returns this Color in hex format as #rrggbb.

to_rgb()

Returns this Color in RGB format as (r, g, b).

classmethod from_rgb(r, g, b)

Construct a Color from given red, green, and blue values.

classmethod from_hsv(h, s, v)

Construct a Color from an HSV tuple.

classmethod from_str(value)

Construct a Color from a given string.

Supported formats:

• RGB: `rgb(rrr, ggg, bbb)`

• HSV: hsv(hh, 0.s, 0.v)

• Hex: #rrggbb or #rgb

Parameters:

value (str) – The correctly formatted input string.

Returns:

The resulting Color.

Return type:

Color

Raises:

ValueError – Input string does not match supported formats.

classmethod default()

The default color, white.

zipline.utils module

zipline.utils.get(iterable, /, **attrs)

A helper that returns the first element in the iterable that meets all the traits passed in attrs.

When multiple attributes are specified, they are checked using logical AND, not logical OR. Meaning they have to meet every attribute passed in and not one of them.

To have a nested attribute search (i.e. search by x.y) then pass in x__y as the keyword argument.

If nothing is found that matches the attributes passed, then None is returned.

Parameters:

• iterable (Union[collections.abc.Iterable, collections.abc.AsyncIterable]) – The iterable to search through. Using a collections.abc.AsyncIterable, makes this function return a coroutine.

• **attrs – Keyword arguments that denote attributes to search with.

zipline.utils.utcnow()

Returns an aware UTC datetime representing the current time.

Returns:

The current time in UTC as an aware datetime.

Return type:

datetime.datetime

zipline.utils.as_chunks(iterable, n)

Batches an iterable into chunks of up to size n.

Parameters:

• iterable (collections.abc.Iterable) – The iterable to batch

• n (int) – The number of elements per generated tuple.

Raises:

ValueError – At least one result must be returned per group.

zipline.utils.slotted_dataclass_to_dict(inst)

Recursively transforms a slotted dataclass instance into a json-like Python object.

Parameters:

inst (Any) – The class instance to convert.

Returns:

A json-like structure representing the given instance.

Return type:

JSON

Raises:

TypeError – An invalid value was given for inst.

zipline.errors module

class zipline.errors.ZiplineError

Bases: Exception

Base class for Zipline related errors.

class zipline.errors.HTTPError(message, code)

Bases: ZiplineError

Base class for HTTP related exceptions. All children implement the attributes of this class.

message

The message returned by the API.

Type:

Any

code

The http status code returned by the API.

Type:

int

class zipline.errors.UnhandledError(message, code)

Bases: HTTPError

Raised by the library if the server returns a status code not handled by the lib.

class zipline.errors.BadRequest(message, code)

Bases: HTTPError

Server returned a 400 response.

class zipline.errors.Forbidden(message, code)

Bases: HTTPError

Server returned a 401 or 403 response.

class zipline.errors.NotFound(message, code)

Bases: HTTPError

Server returned a 404 response.

class zipline.errors.PayloadTooLarge(message, code)

Bases: HTTPError

Server returned a 413 response.

Added in version 0.28.0.

class zipline.errors.RateLimited(message, code)

Bases: HTTPError

Server returned a 429 response.

class zipline.errors.ServerError(message, code)

Bases: HTTPError

Server returned a 5xx response code.

class zipline.errors.NotAuthenticated(message, code)

Bases: HTTPError

Requesting data without an Authorization header.