snip.snippets.base.BaseSnip

class snip.snippets.base.BaseSnip(book_id: int | None = None, deployment: str | None = None)

Basic Snip class.

You may use this class to create new snippets that can be used in the labbook, they should have an associated schema that defines the structure of the snippet and a view that defines how the snippet is displayed. And every snip should mirror some of the functionality of the traditional snip classes in the (ts) snip package.

Attributes

book_id	The identifier of the book the snippet belongs to
deployment	The deployment URL of the snippet
bounding_box	Bounding box of the snippet on a page.
height	Height of the snippet.
mirror	Mirror the snippet on the x axis.
pos	Position of the snippet on a page.
rotation	Rotation of the snippet on a page in degrees.
schema	Schema to validate the snippet.
size	Size of the snippet.
type	The type identifier of the snippet e.g. 'text', 'image' etc.
width	Width of the snippet.
x	Vertical position of the snippet.
y	Horizontal position of the snippet.

Methods

__init__([book_id, deployment])	Create a new snippet.
as_json([validate])	Return the snippet as a dictionary in basic snippet json format.
preview([token])	Generate a snippet preview.
upload([book_id, token, validate])	Upload the snippet to the labbook.

__init__(book_id: int | None = None, deployment: str | None = None)

Create a new snippet.

Parameters:

• book_id (int, optional) – The book_id of the snippet. Defaults to None. If None, the snippet book_id is derived from the token.

• deployment (str, optional) – The deployment URL of the snippet. Defaults to None. If None, the deployment is set to the default deployment.

as_json(validate=True) → dict

Return the snippet as a dictionary in basic snippet json format.

Returns a dict in the basic snippet structure.

{
    "book_id": 123
    "type": "text"
    "data": {}
    "view": {}
}

If the schema is set in the class it is used to validate the snippet data before returning it.

Parameters:

validate (bool, optional) – If True, the snippet is validated against the schema. Defaults to True.

Raises:

jsonschema.ValidationError – If the snippet does not match the schema.

book_id: int | None

The identifier of the book the snippet belongs to

property bounding_box: Tuple[float, float, float, float]

Bounding box of the snippet on a page.

This is the actual size of the snippet on the page, including potential rotation and mirroring.

Returns:

The left, top, right, bottom coordinates of the snippet.

Return type:

Tuple[float, float, float, float]

deployment: str | None

The deployment URL of the snippet

property height

Height of the snippet.

Ignoring rotation and mirroring. For the actual size of the snippet on the page, use the bounding_box property.

property mirror

Mirror the snippet on the x axis.

property pos: Tuple[float, float] | None

Position of the snippet on a page.

Returns none if the position is not set yet.

preview(token: Token | None = None, **kwargs) → Image | None

Generate a snippet preview.

This requests a server side rendering of the snippet and returns the preview image.

Returns:

• token (Token) – The token to use for the request. If None, the token gets inferred if possible.

• **kwargs (Any) – Additional keyword arguments to pass to the requests function.

property rotation

Rotation of the snippet on a page in degrees.

The rotation origin is the center of the snippet and is defined in degrees.

property schema: dict | None

Schema to validate the snippet.

The schema is used to validate the snippet and should be a valid jsonschema.Draft202012Validator schema.

Returns:

The schema for this snippet class if available. If none is available, None is returned and the schema functionality is disabled.

Return type:

schema

abstract property size: Tuple[float, float]

Size of the snippet.

The width and height of the snippet, ignoring rotation and mirroring. For the actual size of the snippet on the page, use the bounding_box property.

Returns:

The width and height of the snippet.

Return type:

Tuple[float, float]

type: str = 'unknown'

The type identifier of the snippet e.g. ‘text’, ‘image’ etc.

upload(book_id: int | None = None, token: BookToken | None = None, validate=True, **kwargs)

Upload the snippet to the labbook.

This method uploads this snippet to a labbok given the snippets book_id and deployment url.

If no token is provided, the token is inferred from the book_id and deployment.

Parameters:

• book_id (int, optional) – The book_id of the snippet. Defaults to None. If None, the snippet book_id is derived

• token (Token) – The token to use for the request. If None, the token gets inferred if possible.

• validate (bool, optional) – Weather to validate the snippet before uploading. Defaults to True.

• **kwargs (Any) – Additional keyword arguments to pass to the requests function.

property width

Width of the snippet.

Ignoring rotation and mirroring. For the actual size of the snippet on the page, use the bounding_box property.

property x

Vertical position of the snippet.

Returns none if the position is not set yet.

property y

Horizontal position of the snippet.

Returns none if the position is not set yet.