rmapy.api.Client¶Bases: object
API Client for Remarkable Cloud
This allows you to authenticate & communicate with the Remarkable Cloud and does all the heavy lifting for you.
check_response(response)¶Check the response from an API Call
Does some sanity checking on the Response
response (Response) – A API Response
True if the response looks ok
ApiError – When the response contains an error
create_folder(folder)¶Create a new folder meta object.
This needs to be done in 3 steps:
Create an upload request for a new CollectionType meta object.
Upload a zipfile with a *.content file containing an empty object.
Update the meta object with the new name.
folder (Folder) – A folder instance.
True if the folder is created.
delete(doc)¶Delete a document from the cloud.
download(document)¶Download a ZipDocument
This will download a raw document from the Remarkable Cloud containing the real document. See the documentation for ZipDocument for more information.
document (Document) – A Document instance we should download
A ZipDocument instance, containing the raw data files from a document.
get_current_version(docorfolder)¶Get the latest version info from a Document or Folder
This fetches the latest meta information from the Remarkable Cloud and returns the version information.
docorfolder (Union[Document, Folder]) – A Document or Folder instance.
int
the version information.
DocumentNotFound – cannot find the requested Document or Folder.
ApiError – An error occurred while processing the request.
get_doc(_id)¶Get a meta item by ID
Fetch a meta item from the Remarkable Cloud by ID.
_id (str) – The id of the meta item.
A Document or Folder instance of the requested ID.
DocumentNotFound – When a document cannot be found.
get_meta_items()¶Returns a new collection from meta items.
It fetches all meta items from the Remarkable Cloud and stores them in a collection, wrapping them in the correct class.
Cloud
is_auth()¶Is the client authenticated
True if the client is authenticated
bool
register_device(code)¶Registers a device on the Remarkable Cloud.
This uses a unique code the user gets from https://my.remarkable.com/device/desktop/connect to register a new device or client to be able to execute api calls.
code (str) – A unique One time code the user can get
at https://my.remarkable.com/device/desktop/connect.
True
AuthError – We didn’t recieved an devicetoken from the Remarkable Cloud.
renew_token()¶Fetches a new user_token.
This is the second step of the authentication of the Remarkable Cloud. Before each new session, you should fetch a new user token. User tokens have an unknown expiration date.
True
AuthError – An error occurred while renewing the user token.
request(method, path, data=None, body=None, headers=None, params=None, stream=False)¶Creates a request against the Remarkable Cloud API
This function automatically fills in the blanks of base url & authentication.
method (str) – The request method.
path (str) – complete url or path to request.
data – raw data to put/post/…
body – the body to request with. This will be converted to json.
headers – a dict of additional headers to add to the request.
params – Query params to append to the request.
stream – Should the response be a stream?
Response
A Response instance containing most likely the response from the server.
token_set = {'devicetoken': '', 'usertoken': ''}¶update_metadata(docorfolder)¶Send an update of the current metadata of a meta object
Update the meta item.
upload(zip_doc, to=<rmapy.folder.Folder 8565923c-d4dc-41cc-ba32-3b4087b7d14b>)¶Upload a document to the cloud.
Add a new document to the Remarkable Cloud.
zip_doc (ZipDocument) – A ZipDocument instance containing the data of a Document.
to (Folder) – the parent of the document. (Default root)
ApiError – an error occurred while uploading the document.
rmapy.collections.Collection(*items)¶Bases: object
A collection of meta items
This is basically the content of the Remarkable Cloud.
items¶A list containing the items.
add(doc_dict)¶Add an item to the collection. It wraps it in the correct class based on the Type parameter of the dict.
doc_dict (dict) – A dict representing a document or folder.
None
add_document(doc_dict)¶Add a document to the collection
doc_dict (dict) – A dict representing a document.
None
add_folder(dir_dict)¶Add a document to the collection
dir_dict (dict) – A dict representing a folder.
None
children(folder=None)¶Get all the children from a folder
rmapy.config.dump(config)¶Dump config to the .rmapy config file
config (dict) – A dict containing data to dump to the .rmapi
config file.
None
rmapy.config.load()¶Load the .rmapy config file
dict
rmapy.document.Document(**kwargs)¶Bases: rmapy.meta.Meta
Document represents a real object expected in most calls by the remarkable API
This contains the metadata from a document.
ID¶Id of the meta object.
Version¶The version of this object.
Success¶If the last API Call was a success.
BlobURLGet¶The url to get the data blob from. Can be empty.
BlobURLGetExpires¶The expiration date of the Get url.
BlobURLPut¶The url to upload the data blob to. Can be empty.
BlobURLPutExpires¶The expiration date of the Put url.
ModifiedClient¶When the last change was by the client.
Type¶Currently there are only 2 known types: DocumentType & CollectionType.
VissibleName¶The human name of the object.
CurrentPage¶The current selected page of the object.
Bookmarked¶If the object is bookmarked.
Parent¶If empty, this object is is the root folder. This can be an ID of a CollectionType.
__repr__()¶String representation of this object
__str__()¶String representation of this object
rmapy.document.Highlight(page_id, highlight_data)¶Bases: object
Highlight represents all highlights on a page created using the highligher pen in EPUB documents.
Functionality introduced in Remarkable 2.7 software.
Contains the page_id where the highlights are located and the highlights metadata for the page from the Remarkable Cloud.
Corresponds to single .json file in the .highlights/ folder.
page_id¶The ID of the page where the highlight is located.
highlight_data¶A dictionary containing all highlight data.
__repr__()¶String representation of this object
str
__str__()¶String representation of this object
str
rmapy.document.RmPage(page, metadata=None, order=0, thumbnail=None, _id=None)¶Bases: object
A Remarkable Page
Contains the metadata, the page itself & thumbnail.
__repr__()¶String representation of this object
str
__str__()¶String representation of this object
str
rmapy.document.ZipDocument(_id=None, doc=None, file=None)¶Bases: object
Here is the content of an archive retried on the tablet as example:
384327f5-133e-49c8-82ff-30aa19f3cfa40.content
384327f5-133e-49c8-82ff-30aa19f3cfa40-metadata.json
384326f5-133e-49c8-82ff-30aa19f3cfa40.rm
384327f5-133e-49c8-82ff-30aa19f3cfa40.pagedata
384327f5-133e-49c8-82ff-30aa19f3cfa40.thumbnails/0.jpg
384327f5-133e-49c8-82ff-30aa19f3cfa40.highlights/9b75d8df-1d06-4c59-8f3e-4cf69aa96cd9.json
As the .zip file from remarkable is simply a normal .zip file containing specific file formats, this package is a helper to read and write zip files with the correct format expected by the tablet.
In order to correctly use this package, you will have to understand the format of a Remarkable zip file, and the format of the files that it contains.
You can find some help about the format at the following URL: https://remarkablewiki.com/tech/filesystem
content¶Sane defaults for the .content file in the zip.
metadata¶parameters describing this blob.
highlights¶list of contents of the .highlights folder
pagedata¶the content of the .pagedata file.
zipfile¶The raw zipfile in memory.
pdf¶the raw pdf file if there is one.
epub¶the raw epub file if there is one.
rm¶A list of :class:rmapy.document.RmPage in this zip.
__repr__()¶string representation of this class
str
__str__()¶string representation of this class
str
create_request()¶Tuple[BytesIO, dict]
dump(file)¶Dump the contents of ZipDocument back to a zip file.
This builds a zipfile to upload back to the Remarkable Cloud.
file (~BytesOrString) – Where to save the zipfile
None
load(file)¶Load a zipfile into this class.
Extracts the zipfile and reads in the contents.
file (~BytesOrString) – A string of a file location or a BytesIO instance of a raw zipfile
None
rmapy.document.from_request_stream(_id, stream)¶Return a ZipDocument from a request stream containing a zipfile.
This is used with the BlobGETUrl from a rmapy.document.Document.
_id (str) – The object ID this zipfile represents.
stream (Response) – a stream containing the zipfile.
the object of the downloaded zipfile.
rmapy.document.from_zip(_id, file)¶Return A ZipDocument from a zipfile.
Create a ZipDocument instance from a zipfile.
_id (str) – The object ID this zipfile represents.
file (str) – the filename of the zipfile.
An instance of the supplied zipfile.
rmapy.exceptions.ApiError(msg, response=None)¶Bases: Exception
Could not found a requested document
rmapy.exceptions.AuthError(msg)¶Bases: Exception
Authentication error
rmapy.exceptions.DocumentNotFound(msg)¶Bases: Exception
Could not found a requested document
rmapy.exceptions.FolderNotFound(msg)¶Bases: Exception
Could not found a requested folder
rmapy.exceptions.UnsupportedTypeError(msg)¶Bases: Exception
Not the expected type
rmapy.folder.Folder(name=None, **kwargs)¶Bases: rmapy.meta.Meta
A Meta type of object used to represent a folder.
create_request()¶Prepares the necessary parameters to create this folder.
This creates a ZipFolder & the necessary json body to create an upload request.
Tuple[BytesIO, dict]
update_request()¶Prepares the necessary parameters to update a folder.
This sets some parameters in the data structure to submit to the API.
dict
rmapy.folder.ZipFolder(_id)¶Bases: object
A dummy zipfile to create a folder
This is needed to create a folder on the Remarkable Cloud
rmapy.meta.Meta(**kwargs)¶Bases: object
Meta represents a real object expected in most calls by the remarkable API
This class is used to be subclassed by for new types.
ID¶Id of the meta object.
Version¶The version of this object.
Success¶If the last API Call was a success.
BlobURLGet¶The url to get the data blob from. Can be empty.
BlobURLGetExpires¶The expiration date of the Get url.
BlobURLPut¶The url to upload the data blob to. Can be empty.
BlobURLPutExpires¶The expiration date of the Put url.
ModifiedClient¶When the last change was by the client.
Type¶Currently there are only 2 known types: DocumentType & CollectionType.
VissibleName¶The human name of the object.
CurrentPage¶The current selected page of the object.
Bookmarked¶If the object is bookmarked.
Parent¶If empty, this object is is the root folder. This can be an ID of a CollectionType.
BlobURLGet = ''BlobURLGetExpires = ''BlobURLPut = ''BlobURLPutExpires = ''Bookmarked = FalseCurrentPage = 1ID = ''Message = ''¶ModifiedClient = ''Parent = ''Success = TrueType = ''Version = 0VissibleName = ''to_dict()¶Return a dict representation of this object.
Used for API Calls.
a dict of the current object.
dict
Note
This is an unofficial api client for the Remarkable Cloud. Use at your own risk.