API¶

This part of the document lists full API reference for all public classes and functions

Base Classes¶

class remarking.WriterCommand[source]¶

Base class for defining writer commands.

Writer commands are subcommands instructing remarking how to output the results of extractors.

For example, JSONWriterCommand adds the json subcommand to remarking run and remarking persist.

Placing a concrete implementation of this class in the remarking.cli.commands package will ensure it is automatically picked up by remarking.

abstract name() → str[source]¶

Return the name of the command as referenced on the command line.

Return type: str

abstract options() → List[Callable[[remarking.cli.writer_command.FC], remarking.cli.writer_command.FC]][source]¶

Return a list of click options to use for the command.

The list can be constructed from the return value of click.option().

These options will be added to the default options for the run or persist command.

Return type: List[Callable[[remarking.cli.writer_command.FC], remarking.cli.writer_command.FC]]

abstract long_description() → str[source]¶

The long description for your command. Shown when running --help

Return type: str

abstract short_description() → str[source]¶

The short description of your command.

Return type: str

abstract writer(documents: List[remarking.models.Document], highlights: List[remarking.models.Highlight], **kwargs: Any) → remarking.cli.writer.Writer[source]¶

Parse options and return a configured instance of a concrete Writer class.

Parameters

documents (List[remarking.models.Document]) – The documents that were processed by extractors.
highlights (List[remarking.models.Highlight]) – The highlights resulting from the extractors.
kwargs (Any) – options specified in the options() method are available here.

Returns

Return an instance of the writer implementation for your command.

Return type

remarking.cli.writer.Writer

class remarking.Writer[source]¶

Base class for defining custom writers.

Concrete implementations of a configured Writer instance are returned by WriterCommand.writer() to be excuted by remarking.

For example, JSONWriterCommand.writer() returns a configured instance of JSONWriter which will then have JSONWriter.write() called by remarking.

write(logger: remarking.cli.log.CommandLineLogger) → None[source]¶

Write to output. Invoked by remarking after extraction is ran on documents.

Parameters: logger (remarking.cli.log.CommandLineLogger) – A logger for writing output to.
Return type: None

class remarking.HighlightExtractor[source]¶

Base class for highlight extractors.

Extractors are run after documents are downloaded. remarking calls HighlightExtractor.get_highlights() for each document downloaded.

For example, RemarkableHighlightExtractor is will extract the highlgihts from the built-in reMarkable highlighting functionality.

abstract classmethod get_extractor_instance_data() → List[remarking.highlight_extractor.highlight_extractor.ExtractorData][source]¶

Return a list of ExtractorData instaces representing different run options for the extractor.

Return type: List[remarking.highlight_extractor.highlight_extractor.ExtractorData]

abstract get_highlights(working_path: str, document: remarking.models.Document) → List[remarking.models.Highlight][source]¶

Retrieve all highlights for document.

Parameters

working_path (str) – The path on the operating system where all documents were downloaded. Documents are downloaded from the cloud and unzipped into this repository. For more information on the layout check out https://remarkablewiki.com/tech/filesystem#user_data_directory_structure.
document (remarking.models.Document) – The document to extract highlights for.

Returns

A list of highlights for the document.

Return type

List[remarking.models.Highlight]

Models¶

class remarking.Document(**kwargs)[source]¶

Represents the current state of a document originating from reMarkable cloud

id: str¶: Primary key for document. This is a UUID generated by the reMarkable tablet.

version: int¶: The version of the document according to the reMarkable cloud.

modified_client: datetime.datetime¶: The unix timestamp for the last time this document was modified.

type: str¶: The type of the document.

name: str¶: The name of the document as visible on the reMarkable tablet.

current_page: int¶: The current page the document is opened on.

bookmarked: bool¶: Indicate if the document is bookmarked.

parent: str¶: The parent of the document. This is usually a folder ID.

equal(other: remarking.models.Document) → bool[source]¶

Check for equality with other documents.

Parameters: other (remarking.models.Document) –
Return type: bool

classmethod from_cloud_document(cloud_document: rmapy.document.Document) → remarking.models.Document[source]¶

Create a Document model from a reMarkable cloud document.

Parameters: cloud_document (rmapy.document.Document) –
Return type: remarking.models.Document

to_metadata_dict() → Dict[str, Any][source]¶

Return a dictionary that matches the .content file used by the reMarkable.

Return type: Dict[str, Any]

__init__(**kwargs)¶

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class remarking.Highlight(**kwargs)[source]¶

Represents a single highlight for a Document.

__init__(**kwargs)¶

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

hash: str¶: Primary for a highlight. This is a hash of the document_id and text.

document_id: str¶: The document that the highlight is associated with

text: str¶: The text of the highlight

page_number: int¶: The page number on which the highlight is located.

extracted_at: datetime.datetime¶: A unix timestamp of when the highlight was extracted.

extraction_method: str¶: What method was used to perform the highlight extraction.

classmethod create_highlight(doc_id: str, text: str, page_number: int, extraction_method: str) → remarking.models.Highlight[source]¶

Create a Highlight. This should be used in place of the default constructor as it properly constructs the highlight hash.

Parameters

doc_id (str) – The id of the document this highlight is associated with.
text (str) – The text of the highlight.
page_number (int) – The page number where the highlight is located.
extract_method – The extraction method.
extraction_method (str) –

Returns

An instance of highlight for these values.

Return type

remarking.models.Highlight

equal(other: remarking.models.Highlight) → bool[source]¶

Check for equality with other Highlights.

Parameters: other (remarking.models.Highlight) –
Return type: bool

Extractors¶

class remarking.ExtractorData(extractor_name: str, instance: remarking.highlight_extractor.highlight_extractor.HighlightExtractor, description: str)[source]¶

Represents an extractor mapping entry.

This is used by remarking to generate extractor choices for the end user.

Parameters

extractor_name (str) – The name of the extractor on the command line.
instance (remarking.highlight_extractor.highlight_extractor.HighlightExtractor) – An instance of the extractor.
description (str) – A description for the extractor. This is shown when running remarking list extractors

Return type

None

class remarking.RemarkableHighlightExtractor[source]¶: Extracts highlights from the highlights folder of reMarkable documents.

Writers¶

class remarking.JSONWriter(documents: List[remarking.models.Document], highlights: List[remarking.models.Highlight])[source]¶

Write a JSON string representing the documents and highlights extracted.

The JSON string resembles:

{
  "documents": [
    {
      "id": "235c7b66-c048-4639-ae89-8b2d60e3263b",
      "version": 3,
      "modified_client": 1626731660,
      "type": "DocumentType",
      "name": "Through the Looking Glass",
      "current_page": 0,
      "bookmarked": false,
      "parent": "002de508-09db-4e25-8714-aedf6c484363"
    }
  ],
  "highlights": [
    {
      "hash": "0e0e22dac038605e8ad32d9104525ff767ddf871689fd92a7adcfae4",
      "document_id": "235c7b66-c048-4639-ae89-8b2d60e3263b",
      "text": "Alice was sitting curled up in a corner of the great arm-chair",
      "page_number": 11,
      "extracted_at": 1626976202,
      "extraction_method": "RemarkableHighlightExtractor"
    }
  ]
}

Parameters

documents (List[remarking.models.Document]) – The list of documents to generate a json string for.
highlights (List[remarking.models.Highlight]) – The list of highlights to generate a json string for.

Return type

None

class remarking.CSVWriter(documents: List[remarking.models.Document], highlights: List[remarking.models.Highlight], columns: Optional[List[str]] = None, delimiter: Optional[str] = None)[source]¶

Writes normalized documents and highlights to csv table.

Resembles:

highlight_text,highlight_page_number,document_name
Alice was sitting curled up in a corner of the great arm-chair,11,Through the Looking Glass

Parameters

documents (List[remarking.models.Document]) – The list of documents to generate a csv for.
highlights (List[remarking.models.Highlight]) – The list of highlights to generate a csv for.
columns (Optional[List[str]]) – The columns to print for the csv. A list of columns can be found by running remarking list columns
delimiter (str) – The delimiter to use for the csv.

Return type

None

class remarking.TableWriter(documents: List[remarking.models.Document], highlights: List[remarking.models.Highlight], columns: Optional[List[str]] = None, truncate: bool = True, print_plain: bool = False)[source]¶

Writes normalized documents and highlights to a simple table.

Resembles:

        highlight_text                                                    highlight_page_number  document_name
--------------------------------------------------------------  -----------------------  -------------------------
Alice was sitting curled up in a corner of the great arm-chair                       11  Through the Looking Glass

Parameters

documents (List[remarking.models.Document]) – The list of documents to generate a table for.
highlights (List[remarking.models.Highlight]) – The list of highlights to generate a table for.
columns (Optional[List[str]]) – The columns to print for the table. A list of columns can be found by running remarking list columns
truncate (bool) – If the highligh_text column should be truncated.
print_plain (bool) – If a plain table with only spaces and new lines should be printed.

Return type

None

Writer Commands¶

class remarking.JSONWriterCommand[source]¶: The writer command implementation for the json output writer.

class remarking.CSVWriterCommand[source]¶: The writer command implementaton for the csv output writer.

class remarking.TableWriterCommand[source]¶: The writer command implementation for the table output writer.

Utilities¶

class remarking.CommandLineLogger(spinners_enabled: bool = True, quiet: bool = False, file_output: Optional[IO] = None)[source]¶

A logger used throughout remarking.

The logger is created at the start of a remarking execution and is passed to methods that require logging functionality. By default this logs to stdout and stderr.

Parameters

spinners_enabled (bool) – If refreshing spinners should be used in output. Used to configure the instance of HaloWrapper returned from CommandLineLogger.spinner().
quiet (bool) – If output should be supressed. This will not supress output from calls to CommandLineLogger.output_result()
file_output (Optional[IO]) – When set, this indicates that all logs should go to the given file handle.

spinner(text: str, spinner: str, **kwargs: Any) → remarking.cli.log.HaloWrapper[source]¶

Return a spinner to show the user that something is happening.

The spinner inherits the settings used to initialize the Logger.

Parameters

text (str) – The text to intialize HaloWrapper with.
spinner (str) – The spinner to pass to HaloWrapper.
kwargs (Any) – Any additional kwargs to pass to the Halo library.

Return type

remarking.cli.log.HaloWrapper

output_result(text: str) → None[source]¶

Write text results as output.

This method will ignore the quiet flag. It should be used to signal final output as in a Writer implementation.

Parameters: text (str) – The result to print.
Return type: None

echo(text: str, **kwargs: Any) → None[source]¶

Write text to given output.

By default, echo uses click.echo() to write output. All kwargs are passed to click.echo()

If the logger was constructed with a file for output, then text is written to a file. click.echo() is not used.

self.echo(click.style("This is a red message", fg="red"), err=True)

The above would write the text in red to the stderr.

Parameters

text (str) – The text to echo.
kwargs (Any) – Arguments to be passed to click.echo().

Return type

None

class remarking.HaloWrapper(logger: remarking.cli.log.CommandLineLogger, text: str, spinner: str, spinner_enabled: bool = True, quiet: bool = False, **kwargs: Any)[source]¶

A wrapper for Halo spinners. Should be constructed from CommandLineLogger.spinner().

Example:

spinner = HaloWrapper(logger, "MyText", "bouncingBar")
spinner.start() # prints "MyText"
...
spinner.suceed("Success text") # Prints "Success text"

Parameters

logger (CommandLineLogger) – The logger to write to.
text (str) – Initial text for the spinner
spinner (str) – The spinner to use. Check the Halo documentation for options.
spinner_enabled (bool) – If the spinner should be enabled or not. If false no spinners are used, and only text is printed out on start, fail and succeed.
quiet (bool) – If any output should be written. If true, then all output is suppressed.
kwargs (Any) – Additional arguments to be passed to Halo spinner if spinners are enabled.

start() → None[source]¶

Called when starting a spinner for the first time.

If spinner is disabled then it prints the currently stored text.

Return type: None

property text: str¶

Retrieves the current text of the spinner

When this property is set, the spinner text is changed automatically.

If the spinner is disabled, then the text is printed when it is set.

fail(text: Optional[str] = None) → None[source]¶

Stops the spinner with a failure icon prepended to the current text. If spinner is disabled, then only the stored text is printed.

Parameters: text (Optional[str]) – The text to use for failure. If this is not set, then the stored text is used.
Return type: None

succeed(text: Optional[str] = None) → None[source]¶

Stops the spinner with a success icon prepended to the current text. If spinner is disabled, then only the stored text is printed.

Parameters: text (Optional[str]) – The text to use for success. If this is not set, then the stored text is used.
Return type: None