API Reference

Translations

class piccolo_admin.translations.models.Translation(*, language_name: str, language_code: str, translations: Dict[str, str])

Used to provide translations in the UI.

Parameters:

• language_name – A human readable representation of the language. For example 'English'.

• language_code – The IETF language tag. For English it is 'en'. However, it also allows us to specify dialects like 'en-US' for American English, or 'en-GB' for British English.

• translations –

  A mapping of English words / phrases to their translated form. For example:

  Translation(
      language_name='Portuguese',
      language_code='pt',
      translations={
          'Welcome to': 'Bem-vindo ao',
          ...
      }
  )
  

MediaStorage

class piccolo_api.media.base.MediaStorage(column: Union[Text, Varchar, Array], allowed_extensions: Optional[Sequence[str]] = ALLOWED_EXTENSIONS, allowed_characters: Optional[Sequence[str]] = ALLOWED_CHARACTERS)

If you want to implement your own custom storage backend, create a subclass of this class. Override each abstract method.

Typically, just use LocalMediaStorage or S3MediaStorage instead.

abstract async delete_file(file_key: str)

Deletes the file object matching the file_key.

async delete_unused_files(number_shown: int = 10, auto: bool = False)

Over time, you will end up with files stored which are no longer needed. For example, if a row is deleted in the database, which referenced a stored file.

By periodically running this method, it will clean up these unused files.

It’s important that each column uses its own folder for storing files. If multiple columns store data in the same folder, then we could delete some files which are needed by another column.

Parameters:

• number_shown – This number of unused file names are printed out, so you can be sure nothing strange is going on.

• auto – If True, no confirmation is required before deletion takes place.

generate_file_key(file_name: str, user: Optional[BaseUser] = None) → str

Generates a unique file ID. If you have your own strategy for naming files, you can override this method.

By default we add a UUID to the filename, to make it unique:

>>> self.generate_file_key(file_name='my-poster.jpg')
my-poster-3beac950-7721-46c9-9e7d-5e908ef51011.jpg

Raises:

ValueError – If the file_name is invalid.

abstract async generate_file_url(file_key: str, root_url: str, user: Optional[BaseUser] = None)

This retrieves an absolute URL for the file. It might be a signed URL, if using S3 for storage.

Parameters:

• file_key – Get the URL for a file with this file_key.

• root_url – The URL the media is usually served from. The sub class might ignore this argument entirely, if it’s fetching the data from an external source like S3.

• user – The Piccolo BaseUser who requested this.

abstract async get_file(file_key: str) → Optional[IO]

Returns the file object matching the file_key.

abstract async get_file_keys() → List[str]

Returns the file key for each file we have stored.

async get_file_keys_from_db() → List[str]

Returns the file key for each file we have in the database.

async get_unused_file_keys() → List[str]

Compares the file keys we have stored, vs what’s in the database.

abstract async store_file(file_name: str, file: IO, user: Optional[BaseUser] = None) → str

Stores the file in whichever storage you’re using, and returns a key which uniquely identifes the file.

Parameters:

• file_name – The file name with which the file will be stored.

• file – The file to store.

• user – The Piccolo BaseUser who requested this.

validate_file_name(file_name: str)

Raises:

ValueError – If the file name is invalid.

piccolo_api.media.base.ALLOWED_EXTENSIONS = ('mp3', 'wav', 'csv', 'tsv', 'pdf', 'gif', 'jpeg', 'jpg', 'png', 'svg', 'tif', 'webp', 'rtf', 'txt', 'mov', 'mp4', 'webm')

These are the extensions which are allowed by default.

piccolo_api.media.base.AUDIO_EXTENSIONS = ('mp3', 'wav')

Pass into allowed_characters to just allow audio files.

piccolo_api.media.base.DATA_EXTENSIONS = ('csv', 'tsv')

Pass into allowed_characters to just allow data files.

piccolo_api.media.base.DOCUMENT_EXTENSIONS = ('pdf',)

Pass into allowed_characters to just allow document files.

piccolo_api.media.base.IMAGE_EXTENSIONS = ('gif', 'jpeg', 'jpg', 'png', 'svg', 'tif', 'webp')

Pass into allowed_characters to just allow image files.

piccolo_api.media.base.TEXT_EXTENSIONS = ('rtf', 'txt')

Pass into allowed_characters to just allow text files.

piccolo_api.media.base.VIDEO_EXTENSIONS = ('mov', 'mp4', 'webm')

Pass into allowed_characters to just allow video files.

piccolo_api.media.base.ALLOWED_CHARACTERS = ('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ' ', '-', '_', '.', '(', ')')

These are the characters allowed in the file name by default.