rmapy package

Submodules

rmapy.api module

class 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.

static check_response(response)

Check the response from an API Call

Does some sanity checking on the Response

Parameters

response (Response) – A API Response

Returns

True if the response looks ok

Raises

ApiError – When the response contains an error

create_folder(folder)

Create a new folder meta object.

This needs to be done in 3 steps:

  1. Create an upload request for a new CollectionType meta object.

  2. Upload a zipfile with a *.content file containing an empty object.

  3. Update the meta object with the new name.

Parameters

folder (Folder) – A folder instance.

Returns

True if the folder is created.

delete(doc)

Delete a document from the cloud.

Parameters

doc (Union[Document, Folder]) – A Document or folder to delete.

Raises

ApiError – an error occurred while uploading the document.

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.

Parameters

document (Document) – A Document instance we should download

Return type

ZipDocument

Returns

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.

Parameters

docorfolder (Union[Document, Folder]) – A Document or Folder instance.

Return type

int

Returns

the version information.

Raises
  • 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.

Parameters

_id (str) – The id of the meta item.

Return type

Union[Document, Folder, None]

Returns

A Document or Folder instance of the requested ID.

Raises

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.

Returns

a collection of Documents & Folders from the Remarkable

Cloud

Return type

Collection

is_auth()

Is the client authenticated

Returns

True if the client is authenticated

Return type

bool

register_device(code)

Registers a device on the Remarkable Cloud.

This uses a unique code the user gets from https://my.remarkable.com/connect/remarkable to register a new device or client to be able to execute api calls.

Parameters

code (str) – A unique One time code the user can get at https://my.remarkable.com/connect/remarkable .

Returns

True

Raises

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.

Returns

True

Raises

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.

Parameters
  • 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?

Return type

Response

Returns

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.

Parameters

docorfolder (Union[Document, Folder]) – A document or folder to update the meta information from.

upload(zip_doc, to=<rmapy.folder.Folder 43484310-f374-4b43-af1c-297d207ed48d>)

Upload a document to the cloud.

Add a new document to the Remarkable Cloud.

Parameters
  • zip_doc (ZipDocument) – A ZipDocument instance containing the data of a Document.

  • to (Folder) – the parent of the document. (Default root)

Raises

ApiError – an error occurred while uploading the document.

rmapy.collections module

class 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.

Parameters

doc_dict (dict) – A dict representing a document or folder.

Return type

None

add_document(doc_dict)

Add a document to the collection

Parameters

doc_dict (dict) – A dict representing a document.

Return type

None

add_folder(dir_dict)

Add a document to the collection

Parameters

dir_dict (dict) – A dict representing a folder.

Return type

None

children(folder=None)

Get all the children from a folder

Parameters

folder (Optional[Folder]) – A folder where to get the children from. If None, this will get the children in the root.

Return type

List[Union[Document, Folder]]

Returns

a list of documents an folders.

parent(doc_or_folder)

Returns the paren of a Document or Folder

Parameters

doc_or_folder (Union[Document, Folder]) – A document or folder to get the parent from

Return type

Folder

Returns

The parent folder.

rmapy.config module

rmapy.config.dump(config)

Dump config to the .rmapy config file

Parameters

config (dict) – A dict containing data to dump to the .rmapi config file.

Return type

None

rmapy.config.load()

Load the .rmapy config file

Return type

dict

rmapy.const module

rmapy.document module

class 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

class 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

Return type

str

__str__()

String representation of this object

Return type

str

class 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

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.

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.

ID = None
__repr__()

string representation of this class

Return type

str

__str__()

string representation of this class

Return type

str

content = {'extraMetadata': {}, 'lastOpenedPage': 0, 'lineHeight': -1, 'margins': 180, 'pageCount': 0, 'textScale': 1, 'transform': {}}
create_request()
Return type

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.

Parameters

file (~BytesOrString) – Where to save the zipfile

Return type

None

epub = None
load(file)

Load a zipfile into this class.

Extracts the zipfile and reads in the contents.

Parameters

file (~BytesOrString) – A string of a file location or a BytesIO instance of a raw zipfile

Return type

None

metadata = {'VissibleName': 'New Document', 'deleted': False, 'lastModified': '1568368808000', 'metadatamodified': False, 'modified': False, 'parent': '', 'pinned': False, 'synced': True, 'type': 'DocumentType', 'version': 1}
pagedata = "b''"
pdf = None
rm = []
zipfile = <_io.BytesIO object>
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.

Parameters
  • _id (str) – The object ID this zipfile represents.

  • stream (Response) – a stream containing the zipfile.

Return type

ZipDocument

Returns

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.

Parameters
  • _id (str) – The object ID this zipfile represents.

  • file (str) – the filename of the zipfile.

Return type

ZipDocument

Returns

An instance of the supplied zipfile.

rmapy.exceptions module

exception rmapy.exceptions.ApiError(msg, response=None)

Bases: Exception

Could not found a requested document

exception rmapy.exceptions.AuthError(msg)

Bases: Exception

Authentication error

exception rmapy.exceptions.DocumentNotFound(msg)

Bases: Exception

Could not found a requested document

exception rmapy.exceptions.FolderNotFound(msg)

Bases: Exception

Could not found a requested folder

exception rmapy.exceptions.UnsupportedTypeError(msg)

Bases: Exception

Not the expected type

rmapy.folder module

class 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.

Return type

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.

Return type

dict

class 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 module

class 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 = False
CurrentPage = 1
ID = ''
Message = ''
ModifiedClient = ''
Parent = ''
Success = True
Type = ''
Version = 0
VissibleName = ''
to_dict()

Return a dict representation of this object.

Used for API Calls.

Returns

a dict of the current object.

Return type

dict

rmapy.types module

Module contents

Note

This is an unofficial api client for the Remarkable Cloud. Use at your own risk.