Files#

Store and read files and images, which are items of the types File and Image. upload and replace send the file inside a JSON body, and the tus_ methods send it in chunks. For a guide, see Upload and download files.

Each example uses the client from How to read these pages.

client.files#

FilesManager.

Files and images stored in content items.

client.files.upload#

Create a File or Image from a file, in one request.

See upload().

Calls POST /media (plone.restapi documentation).

client.files.upload("/media", "notes.txt", title="Notes")
plone-client upload /media photo.png --title Photo -f @id,@type,title
[
  {
    "@id": "http://localhost:8080/Plone/media/photo.png",
    "@type": "Image",
    "title": "Photo"
  }
]
POST /Plone/++api++/media HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "@type": "File",
  "title": "Notes",
  "file": {
    "data": "TWVldGluZyBub3Rlcy4K",
    "encoding": "base64",
    "filename": "notes.txt",
    "content-type": "text/plain"
  }
}
curl -i -X POST http://localhost:8080/Plone/++api++/media -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"@type":"File","title":"Notes","file":{"data":"TWVldGluZyBub3Rlcy4K","encoding":"base64","filename":"notes.txt","content-type":"text/plain"}}'
{
  "@id": "http://localhost:8080/Plone/media/notes.txt",
  "@type": "File",
  "title": "Notes"
}

This shows only @id, @type, title.

client.files.replace#

Replace the file stored in a field of an item.

See replace().

Calls PATCH /media/readme.txt (plone.restapi documentation).

client.files.replace("/media/readme.txt", b"New text.\n", filename="readme.txt")
PATCH /Plone/++api++/media/readme.txt HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "file": {
    "data": "TmV3IHRleHQuCg==",
    "encoding": "base64",
    "filename": "readme.txt",
    "content-type": "text/plain"
  }
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/media/readme.txt -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"file":{"data":"TmV3IHRleHQuCg==","encoding":"base64","filename":"readme.txt","content-type":"text/plain"}}'

The site answers 204, and the method returns None.

client.files.download#

Contents of a file field (@@download).

See download().

Calls GET /media/readme.txt/@@download/file.

client.files.download("/media/readme.txt")
plone-client download /media/readme.txt -o readme.txt
{
  "path": "readme.txt",
  "size": 10,
  "content-type": "text/plain"
}
GET /Plone/++api++/media/readme.txt/@@download/file HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/media/readme.txt/@@download/file -H 'accept: application/json' -u admin:admin

The method returns the 10 bytes of the file.

client.files.image_scale#

Contents of an image scale (@@images).

See image_scale().

Calls GET /media/logo.png/@@images/image/thumb.

client.files.image_scale("/media/logo.png", scale="thumb")
GET /Plone/++api++/media/logo.png/@@images/image/thumb HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/media/logo.png/@@images/image/thumb -H 'accept: application/json' -u admin:admin

The method returns the 1627 bytes of the file.

client.files.tus_upload#

Create an item from a large file, sent in chunks (@tus-upload).

See tus_upload().

Calls POST /media/@tus-upload, PATCH /media/@tus-upload/3df4921144aa4ae6822ade69c2eabfa9 (plone.restapi documentation).

client.files.tus_upload("/media", b"A large file.\n", filename="large.txt")
plone-client upload /media notes.txt --tus
[
  {
    "@id": "http://localhost:8080/Plone/media/notes.txt"
  }
]
POST /Plone/++api++/media/@tus-upload HTTP/1.1
Host: localhost:8080
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Length: 14
Upload-Metadata: filename bGFyZ2UudHh0,content-type dGV4dC9wbGFpbg==,@type RmlsZQ==,fieldname ZmlsZQ==
Authorization: Basic YWRtaW46YWRtaW4=
PATCH /Plone/++api++/media/@tus-upload/3df4921144aa4ae6822ade69c2eabfa9 HTTP/1.1
Host: localhost:8080
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Type: application/offset+octet-stream
Authorization: Basic YWRtaW46YWRtaW4=

A large file.
curl -i -X POST http://localhost:8080/Plone/++api++/media/@tus-upload -H 'accept: application/json' -H 'tus-resumable: 1.0.0' -H 'upload-length: 14' -H 'upload-metadata: filename bGFyZ2UudHh0,content-type dGV4dC9wbGFpbg==,@type RmlsZQ==,fieldname ZmlsZQ==' -u admin:admin
curl -i -X PATCH http://localhost:8080/Plone/++api++/media/@tus-upload/3df4921144aa4ae6822ade69c2eabfa9 -H 'accept: application/json' -H 'tus-resumable: 1.0.0' -H 'upload-offset: 0' -H 'content-type: application/offset+octet-stream' -u admin:admin --data-raw 'A large file.
'
"http://localhost:8080/Plone/media/large.txt"

client.files.tus_replace#

Replace the file of an item with a large file (@tus-replace).

See tus_replace().

Calls POST /media/readme.txt/@tus-replace, PATCH /media/readme.txt/@tus-upload/3e4be45f149b40fa9266aee8045eaddb (plone.restapi documentation).

client.files.tus_replace(
    "/media/readme.txt",
    b"Sample file.\n",
    filename="readme.txt",
    field="file",
)
POST /Plone/++api++/media/readme.txt/@tus-replace HTTP/1.1
Host: localhost:8080
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Length: 13
Upload-Metadata: filename cmVhZG1lLnR4dA==,content-type dGV4dC9wbGFpbg==,fieldname ZmlsZQ==
Authorization: Basic YWRtaW46YWRtaW4=
PATCH /Plone/++api++/media/readme.txt/@tus-upload/3e4be45f149b40fa9266aee8045eaddb HTTP/1.1
Host: localhost:8080
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Type: application/offset+octet-stream
Authorization: Basic YWRtaW46YWRtaW4=

Sample file.
curl -i -X POST http://localhost:8080/Plone/++api++/media/readme.txt/@tus-replace -H 'accept: application/json' -H 'tus-resumable: 1.0.0' -H 'upload-length: 13' -H 'upload-metadata: filename cmVhZG1lLnR4dA==,content-type dGV4dC9wbGFpbg==,fieldname ZmlsZQ==' -u admin:admin
curl -i -X PATCH http://localhost:8080/Plone/++api++/media/readme.txt/@tus-upload/3e4be45f149b40fa9266aee8045eaddb -H 'accept: application/json' -H 'tus-resumable: 1.0.0' -H 'upload-offset: 0' -H 'content-type: application/offset+octet-stream' -u admin:admin --data-raw 'Sample file.
'
"http://localhost:8080/Plone/media/readme.txt"