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#
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"