gofigr package

Module contents

Copyright (c) 2022, Flagstaff Solutions, LLC All rights reserved.

class gofigr.GoFigr(username=None, password=None, api_key=None, url='https://api.gofigr.io', authenticate=True, anonymous=False)

Bases: object

The GoFigr client. Handles all communication with the API: authentication, figure creation and manipulation, sharing, retrieval of user information, etc.

property api_url

Full URL to the API endpoint.

property app_url

Returns the URL to the GoFigr app

authenticate()

Authenticates with the API.

Returns:

True

create_api_key(name, expiry=None, workspace=None)

Creates an API key

Parameters:

• name – name of the key to create

• expiry – expiration date. If None, the key will not expire.

• workspace – workspace for which the key is to be valid. If None, key will have access to the same

workspaces as the user. :return: ApiKey instance

get_api_key(api_id)

Gets information about a specific API key

heartbeat(throw_exception=True)

Checks whether we can communicate with the API. Currently, this works by polling /api/v1/info.

Parameters:

throw_exception – throw an exception if response code is not 200

Returns:

Response

property jwt_url

Full URL to the JWT endpoint (for authentication).

list_api_keys()

Lists all API keys

property primary_workspace

Returns the primary workspace for this user.

Returns:

Workspace instance

revoke_api_key(api_id)

Revokes an API key

update_user_info(user_info, username=None)

Updates user information for a user.

Parameters:

• user_info – UserInfo instance

• username – optional username. This is for testing only – you will get an error if attempting to update information for anybody other than yourself.

Returns:

refreshed UserInfo from server

user_info(username=None)

Retrieves information about a user.

Parameters:

username – username. Set to None for self.

Returns:

UserInfo object.

property workspaces

Returns a list of all workspaces that the current user is a member of.

exception gofigr.MethodNotAllowedError

Bases: RuntimeError

Thrown if a given REST action is not supported/allowed.

exception gofigr.UnauthorizedError

Bases: RuntimeError

Thrown if user doesn’t have permissions to perform an action.

class gofigr.UserInfo(username, first_name, last_name, email, date_joined, is_active, avatar)

Bases: object

Stores basic information about a user: username, email, etc.

static from_json(obj)

Parses a UserInfo object from JSON

Parameters:

obj – JSON representation

Returns:

UserInfo instance

to_json()

Converts this UserInfo object to json

gofigr.assert_one(elements, error_none=None, error_many=None)

Asserts that a list/tuple contains only a single element (raising an exception if not), and returns that element.

Parameters:

• elements – list/tuple

• error_none – error message if input is empty

• error_many – error message if multiple elements are present

Returns:

the single element in the input

gofigr.load_ipython_extension(ip)

Loads the Jupyter extension. Present here so that we can do “%load_ext gofigr” without having to refer to a subpackage.

Parameters:

ip – IPython shell

Returns:

None

Submodules

gofigr.jupyter module

Copyright (c) 2022, Flagstaff Solutions, LLC All rights reserved.

class gofigr.jupyter.ApiId(api_id)

Bases: tuple

api_id

Alias for field number 0

class gofigr.jupyter.FindByName(name, description=None, create=False)

Bases: object

Used as argument to configure() to specify that we want to find an analysis/workspace by name instead of using an API ID

class gofigr.jupyter.GfDisplayPublisher(pub)

Bases: object

Custom IPython DisplayPublisher which traps all calls to publish() (e.g. when display(…) is called).

clear_output(*args, **kwargs)

IPython’s clear_output. Defers to self.pub

publish(data, *args, **kwargs)

IPython calls this method whenever it needs data displayed. Our function traps the call and calls DISPLAY_TRAP instead, giving it an option to suppress the figure from being displayed.

We use this trap to publish the figure if auto_publish is True. Suppression is useful when we want to show a watermarked version of the figure, and prevents it from being showed twice (once with the watermark inside the trap, and once without in the originating call).

Parameters:

• data – dictionary of mimetypes -> data

• args – implementation-dependent

• kwargs – implementation-dependent

Returns:

None

class gofigr.jupyter.Publisher(gf, annotators, backends, watermark=None, show_watermark=True, image_formats=('png', 'eps', 'svg'), interactive=True, default_metadata=None, clear=True, save_pickle=True, widget_class=<class 'gofigr.widget.DetailedWidget'>)

Bases: object

Publishes revisions to the GoFigr server.

annotate(rev)

Annotates a FigureRevision using self.annotators. :param rev: revision to annotate :return: annotated revision

auto_publish_hook(extension, data, suppress_display=None)

Hook for automatically publishing figures without an explicit call to publish().

Parameters:

• extension – GoFigrExtension instance

• data – data being published. This will usually be a dictionary of mime formats.

• native_publish – callable which will publish the figure using the native backend

Returns:

None

publish(fig=None, target=None, gf=None, dataframes=None, metadata=None, backend=None, image_options=None, suppress_display=None, files=None)

Publishes a revision to the server.

Parameters:

• fig – figure to publish. If None, we’ll use plt.gcf()

• target – Target figure to publish this revision under. Can be a gf.Figure instance, an API ID, or a FindByName instance.

• gf – GoFigure instance

• dataframes – dictionary of dataframes to associate & publish with the figure

• metadata – metadata (JSON) to attach to this revision

usage this will cause Jupyter to print the whole object which we don’t want. :param backend: backend to use, e.g. MatplotlibBackend. If None it will be inferred automatically based on figure type :param image_options: backend-specific params passed to backend.figure_to_bytes :param suppress_display: if used in an auto-publish hook, this will contain a callable which will suppress the display of this figure using the native IPython backend. :param files: either (a) list of file paths or (b) dictionary of name to file path/file obj

Returns:

FigureRevision instance

class gofigr.jupyter.SuppressDisplayTrap

Bases: object

Context manager which temporarily suspends all display traps.

gofigr.jupyter.configure(username=None, password=None, api_key=None, workspace=None, analysis=None, url='https://api.gofigr.io', default_metadata=None, auto_publish=True, watermark=None, annotators=(<class 'gofigr.annotators.NotebookMetadataAnnotator'>, <class 'gofigr.annotators.EnvironmentAnnotator'>, <class 'gofigr.annotators.CellIdAnnotator'>, <class 'gofigr.annotators.CellCodeAnnotator'>, <class 'gofigr.annotators.SystemAnnotator'>, <class 'gofigr.annotators.PipFreezeAnnotator'>, <class 'gofigr.annotators.BackendAnnotator'>, <class 'gofigr.annotators.HistoryAnnotator'>), notebook_name=None, notebook_path=None, backends=(<class 'gofigr.backends.plotnine.PlotnineBackend'>, <class 'gofigr.backends.matplotlib.MatplotlibBackend'>, <class 'gofigr.backends.plotly.PlotlyBackend'>, <class 'gofigr.backends.py3dmol.Py3DmolBackend'>), widget_class=<class 'gofigr.widget.DetailedWidget'>, save_pickle=True, show_watermark=True)

Configures the Jupyter plugin for use.

Parameters:

• username – GoFigr username (if used instead of API key)

• password – GoFigr password (if used instead of API key)

• api_key – API Key (if used instead of username and password)

• url – API URL

• workspace – one of: API ID (string), ApiId instance, or FindByName instance

• analysis – one of: API ID (string), ApiId instance, or FindByName instance

• default_metadata – dictionary of default metadata values to save for each revision

• auto_publish – if True, all figures will be published automatically without needing to call publish()

• watermark – custom watermark instance (e.g. DefaultWatermark with custom arguments)

• annotators – list of annotators to use. Default: DEFAULT_ANNOTATORS

• notebook_name – name of the notebook (if you don’t want it to be inferred automatically)

• notebook_path – path to the notebook (if you don’t want it to be inferred automatically)

• backends – backends to use (e.g. MatplotlibBackend, PlotlyBackend)

• widget_class – Widget type to show, e.g. DetailedWidget or CompactWidget. It will appear below the published figure

• save_pickle – if True, will save the figure in pickle format in addition to any of the image formats

• show_watermark – True to show watermarked figures instead of original. False to always display the unmodified figure. Default True.

Returns:

None

gofigr.jupyter.download_all(api_id, path)

Downloads all files attached to a revision

Parameters:

• api_id – API ID of the revision containing the files

• path – directory where to save the files

Returns:

number of bytes written

gofigr.jupyter.download_file(api_id, file_name, path)

Downloads a file and saves it.

Parameters:

• api_id – API ID of the revision containing the file

• file_name – name of the file to download

• path – where to save the file (either existing directory or full path with the file name)

Returns:

number of bytes written

gofigr.jupyter.find_workspace_by_name(gf, search)

Finds a workspace by name.

Parameters:

• gf – GoFigr client

• search – FindByName instance

Returns:

a Workspace object

gofigr.jupyter.from_config_or_env(env_prefix, config_path)

Decorator that binds function arguments in order of priority (most important first): 1. args/kwargs 2. environment variables 3. config file 4. function defaults

Parameters:

• env_prefix – prefix for environment variables. Variables are assumed to be named <prefix> + <name of function argument in all caps>, e.g. if prefix is MYAPP and function argument is called host_name, we’ll look for an environment variable named MYAPP_HOST_NAME.

• config_path – path to the JSON config file. Function arguments will be looked up using their verbatim names.

Returns:

decorated function

gofigr.jupyter.get_extension()

Returns the GoFigr Jupyter extension instance

gofigr.jupyter.get_gofigr()

Gets the active GoFigr object.

gofigr.jupyter.is_suppressed(fig)

Determines if the figure is suppressed from publication

gofigr.jupyter.load_pickled_figure(api_id)

Unpickles a GoFigr revision and returns it as a backend-specific Python object, e.g. a plt.Figure if the figure was generated with matplotlib. Throws a RuntimeException if the figure is not found or does not have pickle data.

Parameters:

api_id – API ID of the revision

Returns:

backend-dependent figure object, e.g. plt.Figure().

gofigr.jupyter.parse_model_instance(model_class, value, find_by_name)

Parses a model instance from a value, e.g. the API ID or a name.

Parameters:

• model_class – class of the model, e.g. gf.Workspace

• value – value to parse into a model instance

• find_by_name – callable to find the model instance by name

Returns:

model instance

gofigr.jupyter.parse_uuid(val)

Attempts to parse a UUID, returning None if input is not a valid UUID.

Parameters:

val – value to parse

Returns:

UUID (as a string) or None

gofigr.jupyter.proxy_callback(result)

Proxy callback

gofigr.jupyter.publish(fig=None, backend=None, **kwargs)

Publishes a figure. See gofigr.jupyter.Publisher.publish() for a list of arguments. If figure and backend are both None, will publish default figures across all available backends.

Parameters:

• fig – figure to publish

• backend – backend to use

• kwargs

Returns:

gofigr.jupyter.require_configured(func)

Decorator which throws an exception if configure() has not been called yet.

Parameters:

func

Returns:

gofigr.jupyter.suppress(fig)

Suppresses the figure from being auto-published. You can still publish it by calling publish().

gofigr.models module

Copyright (c) 2022, Flagstaff Solutions, LLC All rights reserved.

class gofigr.models.Base64Field(name, parent=None, derived=False)

Bases: Field

Timestamp field

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.CodeLanguage

Bases: ABC

For code data objects, the programming language of the embedded code.

PYTHON = 'Python'

R = 'R'

class gofigr.models.DataField(name, entity_type, many=False, read_only=False, backlink_property=None, parent=None, derived=False, sort_key=None)

Bases: LinkedEntityField

Customizes a LinkedEntityField so that the entity data is fully embedded in the representation

clone()

Creates a clone of this field.

Returns:

cloned field

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.DataType

Bases: ABC

Enum for different types of data we can store inside a FigureRevision.

CODE = 'code'

DATA_FRAME = 'dataframe'

FILE = 'file'

IMAGE = 'image'

TEXT = 'text'

class gofigr.models.Field(name, parent=None, derived=False)

Bases: object

Describes a dynamically created object field, i.e. figure name, revision etc.

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.JSONField(name, parent=None, derived=False)

Bases: Field

Represents a field that stores JSON primitives.

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.LinkSharingStatus(enabled)

Bases: NestedMixin

Stores the status of link sharing for shareable objects.

classmethod from_json(data)

Parses this object from JSON

to_json()

Converts this object to JSON

class gofigr.models.LinkedEntityCollection(entities, read_only=False, backlink_property=None, backlink=None)

Bases: object

Represents a collection of linked entities, i.e. figures inside an analysis

create(new_obj, **kwargs)

Creates a new object and appends it to the collection.

Parameters:

new_obj – object to create

Returns:

created object

find(**kwargs)

Returns the first object whose attributes match the query. E.g. find(name=’hello’, age=21) will return all objects where obj.name == “hello” and obj.age == 21.

Parameters:

kwargs – query

Returns:

first object that matches the query or None

find_or_create(default_obj=None, **kwargs)

Finds an object that matches query parameters. If the object doesn’t exist, it will persist default_obj and return it instead.

Parameters:

• default_obj – object to create/persist if no matches are found

• kwargs – query parameters. See .find()

Returns:

found or created object.

class gofigr.models.LinkedEntityField(name, entity_type, many=False, read_only=False, backlink_property=None, parent=None, derived=False, sort_key=None)

Bases: Field

Represents a linked entity (or a collection of them), e.g. an Analysis inside a Workspace.

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.LogItem(username, timestamp, action, target_id, target_type, deleted_sentinel=None, deleted=False, thumbnail=None, target_name=None, analysis_id=None, analysis_name=None, api_id=None, gf=None, parent=None)

Bases: NestedMixin

Represents an activity item, such as a figure being created or modified.

fetch()

Fetches information about this log item from the server. API ID and parent have to be set.

classmethod from_json(data, gf=None, parent=None)

Parses this object from JSON

to_json()

Converts this object to JSON

class gofigr.models.LogsMixin

Bases: object

Mixin for entities which support the /log/ endpoint.

get_logs()

Retrieves the activity log.

Returns:

list of LogItem objects.

class gofigr.models.MetadataProxyField(name, default=None)

Bases: object

Field which is embedded inside the JSON metadata

class gofigr.models.ModelMixin(api_id=None, parse=False, **kwargs)

Bases: ABC

Base class for GoFigr API entities: workspaces, analyses, figures, etc.

property client

Returns the underlying GoFigr instance

create(update=False)

Creates this object on the server.

Parameters:

update – if True and the object already exists, its properties will be updated on the server. Otherwise

trying to create an object which already exists will throw an exception.

Returns:

self

delete(**kwargs)

Deletes an object on the server. This cannot be undone.

Parameters:

kwargs – specify delete=True to actually delete the object.

Returns:

endpoint = None

fetch()

Updates all fields from the server. Note that any unsaved local changes will be overwritten.

Returns:

self

fields = ['api_id', '_shallow']

classmethod from_json(data)

Parses an instance of this class from JSON data

classmethod list()

Lists all objects from the server.

save(create=False, patch=False, silent=False)

Saves this object to server

Parameters:

• create – will create the object if it doesn’t already exist. Otherwise, saving a non-existing object will throw an exception.

• patch – if True, will submit a partial update where some required properties may be missing. You will almost never use this: it’s only useful if for some reason you can’t/don’t want to fetch the full object before updating properties. However, the web app relies on this functionality so it’s available.

• silent – if True, the server will not generate an activity for this update.

Returns:

self

to_json(include_derived=True, include_none=False)

Serializes this model to JSON primitives.

Parameters:

• include_derived – if True, derived fields will be included in the representation

• include_none – if True, fields set to None will be included in the representation

Returns:

this object (and all nested/referenced fields) serialized to JSON primitives.

class gofigr.models.NestedEntityField(name, entity_type, many=False, read_only=False, derived=False, parent=None)

Bases: Field

Represents a nested entity. Nested entities are embedded fully in the parent object’s JSON representation and cannot be manipulated on their own.

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.NestedMixin

Bases: ABC

Nested objects: these are not standalone (cannot be manipulated based on API ID), but are directly embedded inside other objects.

classmethod from_json(data)

Parses this object from JSON

to_json()

Converts this object to JSON

class gofigr.models.Recents(analyses, figures)

Bases: tuple

analyses

Alias for field number 0

figures

Alias for field number 1

class gofigr.models.ShareableModelMixin(api_id=None, parse=False, **kwargs)

Bases: ModelMixin

Mixins for things we can share: analyses, figures, revisions, etc.

get_link_sharing()

Gets current status of link sharing

Returns:

true if link sharing is enabled, false otherwise.

get_sharing_users()

Gets a list of all users with whom this object has been shared.

Returns:

list of SharingUserData objects.

set_link_sharing(enabled)

Enabled or disables link sharing.

Parameters:

enabled – true to enable, false to disable.

Returns:

confirmation of link sharing status (true or false)

share(username)

Shares this object with a specific user.

Parameters:

username – name of the user to share with.

Returns:

SharingUserData object

unshare(username)

Unshares this object from a user.

Parameters:

username – username of a user from whom to remove access

Returns:

SharingUserData

class gofigr.models.SharingUserData(username, sharing_enabled)

Bases: NestedMixin

Stores information about a user that an object has been shared with

classmethod from_json(data)

Parses this object from JSON

to_json()

Converts this object to JSON

class gofigr.models.ThumbnailMixin

Bases: object

Mixin for entities which support the /log/ endpoint.

get_thumbnail(size)

Retrieves the thumbnail image. :param size: size in pixels

Returns:

PIL.Image if available or None

class gofigr.models.Timestamp(name, parent=None, derived=False)

Bases: Field

Timestamp field

clone()

Creates a clone of this field.

Returns:

cloned field

to_internal_value(gf, data)

Parses the value of this field from JSON primitives.

Parameters:

• gf – GoFigr instance

• data – parsed JSON primitives

Returns:

parsed value

to_representation(value)

Converts the value of this field to a JSON-serializable primitive

class gofigr.models.WorkspaceMember(username, membership_type)

Bases: NestedMixin

Stores information about a member of a workspace

classmethod from_json(data)

Parses this object from JSON

to_json()

Converts this object to JSON

class gofigr.models.WorkspaceMembership

Bases: ABC

Enum for levels of workspace membership: owner, viewer, etc.

ADMIN = 'admin'

ALL_LEVELS = ['owner', 'admin', 'creator', 'viewer']

CREATOR = 'creator'

OWNER = 'owner'

VIEWER = 'viewer'

class gofigr.models.WorkspaceType

Bases: ABC

Enum for workspace type

PRIMARY = 'primary'

SECONDARY = 'secondary'

class gofigr.models.gf_Analysis(api_id=None, parse=False, **kwargs)

Bases: ShareableModelMixin, LogsMixin, ThumbnailMixin

Represents an analysis

endpoint = 'analysis/'

fields = ['api_id', '_shallow', 'name', 'description', 'size_bytes', <gofigr.models.LinkedEntityField object>, <gofigr.models.LinkedEntityField object>, 'created_by', <gofigr.models.Timestamp object>, 'updated_by', <gofigr.models.Timestamp object>, 'child_updated_by', <gofigr.models.Timestamp object>]

get_figure(name, create=True, **kwargs)

Finds a figure by name, optionally creating it.

Parameters:

• name – name of the figure to find

• create – True to create the figure if it doesn’t exist.

• kwargs – parameters to Figure (e.g. description) if it needs to be created

Returns:

Figure instance

class gofigr.models.gf_ApiKey(api_id=None, parse=False, **kwargs)

Bases: ModelMixin

Represents an API key. The field ‘token’ is the actual token used to authenticate, and is always null except at key creation.

endpoint = 'api_key/'

fetch_and_preserve_token()

Like fetch(), but preserves the token if present. This is useful because the token is only available at creation, so calling fetch() will always set it to None.

Returns:

fields = ['api_id', 'name', 'token', <gofigr.models.Timestamp object>, <gofigr.models.Timestamp object>, <gofigr.models.Timestamp object>, <gofigr.models.LinkedEntityField object>]

class gofigr.models.gf_CodeData(contents=None, **kwargs)

Bases: gf_Data

Serialized code data (it’s text, but stored and transmitted as bytes)

DATA_TYPE = 'code'

property contents

Code contents.

Returns:

encoding

Field which is embedded inside the JSON metadata

format

Field which is embedded inside the JSON metadata

language

Field which is embedded inside the JSON metadata

metadata_fields = [<gofigr.models.MetadataProxyField object>, <gofigr.models.MetadataProxyField object>, <gofigr.models.MetadataProxyField object>]

class gofigr.models.gf_Data(*args, **kwargs)

Bases: ModelMixin

Represents binary data (e.g. image data, serialized dataframes, etc.)

DATA_TYPE = None

SPECIALIZED_TYPES = None

endpoint = 'data/'

fields = ['api_id', 'name', 'type', <gofigr.models.JSONField object>, <gofigr.models.Base64Field object>]

property is_shallow

True if this is a shallow data object without the byte payload

property local_id

Reserved for internal API use

metadata_fields = []

specialize()

Creates a specialized data instance, e.g. ImageData, based on the data type

class gofigr.models.gf_Figure(api_id=None, parse=False, **kwargs)

Bases: ShareableModelMixin, ThumbnailMixin

Represents a figure

endpoint = 'figure/'

fields = ['api_id', '_shallow', 'name', 'description', 'size_bytes', <gofigr.models.LinkedEntityField object>, <gofigr.models.LinkedEntityField object>, 'created_by', <gofigr.models.Timestamp object>, 'updated_by', <gofigr.models.Timestamp object>, 'child_updated_by', <gofigr.models.Timestamp object>]

class gofigr.models.gf_FileData(*args, **kwargs)

Bases: gf_Data

Binary file data

DATA_TYPE = 'file'

metadata_fields = [<gofigr.models.MetadataProxyField object>]

path

Field which is embedded inside the JSON metadata

classmethod read(path)

Creates a new FileData object from the contents of a file.

Parameters:

path – path of the file to read

Returns:

FileData object

write(path)

Writes the contents of this file to the given path

class gofigr.models.gf_ImageData(*args, **kwargs)

Bases: gf_Data

Binary image data

DATA_TYPE = 'image'

format

Field which is embedded inside the JSON metadata

property image

Returns this image as a PIL.Image object.

Returns:

PIL.Image

property is_interactive

True if this figure is interactive, false otherwise

is_watermarked

Field which is embedded inside the JSON metadata

metadata_fields = [<gofigr.models.MetadataProxyField object>, <gofigr.models.MetadataProxyField object>]

class gofigr.models.gf_MetadataProxy(api_id=None, parse=False, **kwargs)

Bases: ModelMixin

Represents a proxy object for sharing metadata between the GoFigr extension (server-side) and the Jupyter client.

delete(**kwargs)

Deletes an object on the server. This cannot be undone.

Parameters:

kwargs – specify delete=True to actually delete the object.

Returns:

endpoint = 'metadata/'

fetch()

Updates all fields from the server. Note that any unsaved local changes will be overwritten.

Returns:

self

fields = ['api_id', 'initiator', 'token', <gofigr.models.Timestamp object>, <gofigr.models.Timestamp object>, <gofigr.models.Timestamp object>, <gofigr.models.JSONField object>]

save(*args, **kwargs)

Saves this object to server

Parameters:

• create – will create the object if it doesn’t already exist. Otherwise, saving a non-existing object will throw an exception.

• patch – if True, will submit a partial update where some required properties may be missing. You will almost never use this: it’s only useful if for some reason you can’t/don’t want to fetch the full object before updating properties. However, the web app relies on this functionality so it’s available.

• silent – if True, the server will not generate an activity for this update.

Returns:

self

update_metadata(metadata)

Accepts this invitation

class gofigr.models.gf_Revision(api_id=None, parse=False, **kwargs)

Bases: ShareableModelMixin, ThumbnailMixin

Represents a figure revision

property code_data

Returns only code data (if any)

create(update=False)

Creates a Revision on the server.

Parameters:

update – True to update the object if it already exists

Returns:

self

endpoint = 'revision/'

fetch(fetch_data=True)

Overrides the default fetch to retrieve the data objects (with byte payload) as well. This override is necessary because the API only returns shallow data objects by default.

Parameters:

fetch_data – whether to retrieve full data objects

Returns:

self

fetch_data()

Fetches all data objects

fields = ['api_id', 'revision_index', 'size_bytes', <gofigr.models.JSONField object>, <gofigr.models.LinkedEntityField object>, <gofigr.models.DataField object>, 'created_by', <gofigr.models.Timestamp object>, 'updated_by', <gofigr.models.Timestamp object>]

property file_data

Returns only file data (if any)

property image_data

Returns only image data (if any)

property revision_url

Returns the GoFigr URL for this revision

save(create=False, patch=False, silent=False)

Saves this object to server

Parameters:

• create – will create the object if it doesn’t already exist. Otherwise, saving a non-existing object will throw an exception.

• patch – if True, will submit a partial update where some required properties may be missing. You will almost never use this: it’s only useful if for some reason you can’t/don’t want to fetch the full object before updating properties. However, the web app relies on this functionality so it’s available.

• silent – if True, the server will not generate an activity for this update.

Returns:

self

property table_data

Returns only DataFrame data (if any)

property text_data

Returns only text data (if any)

class gofigr.models.gf_TableData(dataframe=None, **kwargs)

Bases: gf_Data

Serialized data frame

DATA_TYPE = 'dataframe'

property dataframe

Parses the dataframe from the embedded stream of bytes.

Returns:

encoding

Field which is embedded inside the JSON metadata

format

Field which is embedded inside the JSON metadata

metadata_fields = [<gofigr.models.MetadataProxyField object>, <gofigr.models.MetadataProxyField object>]

class gofigr.models.gf_TextData(contents=None, **kwargs)

Bases: gf_Data

Serialized text data (even though it’s text, we store and transmit bytes)

DATA_TYPE = 'text'

property contents

Decoded text (a string)

encoding

Field which is embedded inside the JSON metadata

metadata_fields = [<gofigr.models.MetadataProxyField object>]

class gofigr.models.gf_Workspace(api_id=None, parse=False, **kwargs)

Bases: ModelMixin, LogsMixin

Represents a workspace

add_member(username, membership_type)

Adds a member to this workspace.

Parameters:

• username – username of the person to add

• membership_type – WorkspaceMembership value, e.g. WorkspaceMembership.CREATOR

Returns:

WorkspaceMember instance

change_membership(username, membership_type)

Changes the membership level for a user.

Parameters:

• username – username

• membership_type – new membership type, e.g. WorkspaceMembership.CREATOR

Returns:

WorkspaceMember instance

endpoint = 'workspace/'

fields = ['api_id', '_shallow', 'name', 'description', 'workspace_type', 'size_bytes', <gofigr.models.LinkedEntityField object>, 'created_by', <gofigr.models.Timestamp object>, 'updated_by', <gofigr.models.Timestamp object>, 'child_updated_by', <gofigr.models.Timestamp object>]

get_analysis(name, create=True, **kwargs)

Finds an analysis by name.

Parameters:

• name – name of the analysis

• create – whether to create an analysis if one doesn’t exist

• kwargs – if an Analysis needs to be created, parameters of the Analysis object (such as description)

Returns:

Analysis instance.

get_invitations()

Gets members of this workspace.

Returns:

list of WorkspaceMember objects

get_members()

Gets members of this workspace.

Returns:

list of WorkspaceMember objects

get_recents(limit=100)

Gets the most recently created or modified analyses & figures.

Parameters:

limit – maximum number of elements to retrieve.

Returns:

Instance of the Recents object

remove_member(username)

Removes a member from this workspace.

Parameters:

username – username

Returns:

WorkspaceMember instance

class gofigr.models.gf_WorkspaceInvitation(api_id=None, parse=False, **kwargs)

Bases: ModelMixin

Represents an invitation to join a workspace.

accept()

Accepts this invitation

delete(**kwargs)

Deletes an object on the server. This cannot be undone.

Parameters:

kwargs – specify delete=True to actually delete the object.

Returns:

endpoint = 'invitations/workspace/'

fetch()

Updates all fields from the server. Note that any unsaved local changes will be overwritten.

Returns:

self

fields = ['api_id', 'email', 'initiator', 'token', 'status', <gofigr.models.Timestamp object>, <gofigr.models.Timestamp object>, <gofigr.models.LinkedEntityField object>, 'membership_type']

gofigr.watermarks module

Copyright (c) 2022, Flagstaff Solutions, LLC All rights reserved.

class gofigr.watermarks.DefaultWatermark(show_qr_code=True, margin_px=10, qr_background=(0, 0, 0, 0), qr_foreground=(0, 0, 0, 153), qr_scale=2, font=None)

Bases: object

Draws QR codes + URL watermark on figures.

apply(image, revision)

Adds a QR watermark to an image.

Parameters:

• image – PIL.Image

• revision – instance of FigureRevision

Returns:

PIL.Image containing the watermarked image

draw_identifier(text)

Draws the GoFigr identifier text, returning it as a PIL image

get_watermark(revision)

Generates just the watermark for a revision.

Parameters:

revision – FigureRevision

Returns:

PIL.Image

class gofigr.watermarks.Watermark

Bases: object

Base class for drawing watermaks on figures.

apply(image, revision)

Places a watermark on an image

Parameters:

• image – PIL Image object

• revision – GoFigr revision object

gofigr.watermarks.add_margins(img, margins)

Adds margins to an image

gofigr.watermarks.stack_horizontally(*images, alignment='center')

Stacks images horizontally. Thanks, Stack Overflow!

https://stackoverflow.com/questions/30227466/combine-several-images-horizontally-with-python

gofigr.watermarks.stack_vertically(*images, alignment='center')

Stacks images vertically.

gofigr.annotators module

Copyright (c) 2023, Flagstaff Solutions, LLC All rights reserved.

class gofigr.annotators.Annotator(extension)

Bases: ABC

Annotates figure revisions with pertinent information, such as cell code, variable values, etc.

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.BackendAnnotator(extension)

Bases: Annotator

Annotates revisions with the python version & the kernel info

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.CellCodeAnnotator(extension)

Bases: Annotator

“Annotates revisions with cell contents

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.CellIdAnnotator(extension)

Bases: Annotator

Annotates revisions with the ID of the Jupyter cell

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.EnvironmentAnnotator(extension)

Bases: Annotator

Annotates revisions with the python version & the kernel info

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.HistoryAnnotator(extension)

Bases: Annotator

Annotates revisions with IPython execution history

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.NotebookMetadataAnnotator(extension)

Bases: Annotator

“Annotates revisions with notebook metadata, including filename & path, as well as the full URL

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

parse_metadata()

Infers the notebook path & name from metadata passed through the WebSocket (if available)

class gofigr.annotators.NotebookNameAnnotator(*args, **kwargs)

Bases: NotebookMetadataAnnotator

(Deprecated) Annotates revisions with notebook name & path

class gofigr.annotators.PipFreezeAnnotator(extension, cache=True)

Bases: Annotator

Annotates revisions with the output of pip freeze

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

class gofigr.annotators.SystemAnnotator(extension)

Bases: Annotator

Annotates revisions with the OS version

annotate(revision)

Annotates the figure revision.

Parameters:

revision – FigureRevision

Returns:

annotated FigureRevision

gofigr.widget module

Copyright (c) 2024, Flagstaff Solutions, LLC All rights reserved.

class gofigr.widget.CompactWidget(revision)

Bases: WidgetBase

Generates a compact GoFigr widget

show()

Renders this widget in Jupyter by generating the HTML/JS & calling display()

class gofigr.widget.DetailedWidget(revision)

Bases: WidgetBase

Generates HTML/Javascript for the GoFigr Jupyter widget shown under each figure

show()

Renders this widget in Jupyter by generating the HTML/JS & calling display()

class gofigr.widget.MinimalWidget(revision)

Bases: WidgetBase

Generates a compact GoFigr widget

show()

Renders this widget in Jupyter by generating the HTML/JS & calling display()

class gofigr.widget.WidgetBase(revision)

Bases: ABC

Generates HTML/Javascript for the GoFigr Jupyter widget shown under each figure

get_copy_link(label, watermark, image_format='png')

Generates HTML/JS for the copy image button

get_download_link(label, watermark, image_format='png')

Generates HTML for the download link

get_logo_b64()

Reads the GoFigr logo and returns it as a base64 string

get_text_copy_link(label, text)

Generates HTML/JS for the copy link button

show()

Displays the widget in Jupyter

gofigr.widget.timestamp_to_local_tz(dt_tz)

Converts a datetime to the local timezone

gofigr.backends module

Copyright (c) 2023, Flagstaff Solutions, LLC All rights reserved.

class gofigr.backends.GoFigrBackend

Bases: ABC

Base class for figure backends, e.g. matplotlib or plotly

add_interactive_watermark(fig, rev, watermark)

Adds watermark to a figure using the backend’s native objects (if supported by the backend)

Parameters:

• fig – figure to watermark

• rev – FigureRevision object

• watermark – DefaultWatermark instance

Returns:

modified figure

close(fig)

Closes a figure and prevents it from being displayed. :param fig: figure to close :return: None

figure_to_bytes(fig, fmt, params)

Given a figure and an image format, converts the figure to binary representation in that format.

Parameters:

• fig – figure object

• fmt – format, e.g. png

• params – backend-specific parameters

Returns:

bytes

figure_to_html(fig)

Converts a figure to interactive HTML (if supported by the backend)

Parameters:

fig – figure to convert to HTML

Returns:

figure as HTML string

find_figures(shell, data)

Finds all figures compatible with this backend in the current environment.

Parameters:

shell – IPython shell

Returns:

iterator over available figures

get_backend_name()

Gets a human-readable name of this backend. :return: backend name, a string

get_default_figure(silent=False)

Returns the default/current figure, e.g. plt.gcf() for matplotlib

Parameters:

silent – if True, will suppress warnings/errors if default figure is unavailable

get_supported_image_formats()

Gets a list of supported image formats

get_title(fig)

Extracts figure title

Parameters:

fig – figure to extract title from

Returns:

figure title, or None if not available

is_compatible(fig)

Returns True if this backend is compatible with a figure

is_interactive(fig)

Returns True if the figure supports interactive (HTML) output

is_static(fig)

Returns True if the figure is static (e.g. an image)

gofigr.backends.get_all_function_arguments(frame)

Iterates over all function arguments, including *args and **kwargs

gofigr.backends.get_backend(figure, backends)

Gets the backend compatible with a figure

Parameters:

• figure – figure to find a backend for

• backends – list of backends to search

Returns:

GoFigr backend compatible with the figure, or ValueError if none are compatible.

gofigr.backends.matplotlib module

Copyright (c) 2023, Flagstaff Solutions, LLC All rights reserved.

class gofigr.backends.matplotlib.MatplotlibBackend

Bases: GoFigrBackend

MatplotLib backend for GoFigr.

close(fig)

Closes a figure and prevents it from being displayed. :param fig: figure to close :return: None

figure_to_bytes(fig, fmt, params)

Given a figure and an image format, converts the figure to binary representation in that format.

Parameters:

• fig – figure object

• fmt – format, e.g. png

• params – backend-specific parameters

Returns:

bytes

find_figures(shell, data)

Finds all figures compatible with this backend in the current environment.

Parameters:

shell – IPython shell

Returns:

iterator over available figures

get_backend_name()

Gets a human-readable name of this backend. :return: backend name, a string

get_default_figure(silent=False)

Returns the default/current figure, e.g. plt.gcf() for matplotlib

Parameters:

silent – if True, will suppress warnings/errors if default figure is unavailable

get_supported_image_formats()

Gets a list of supported image formats

get_title(fig)

Extracts figure title

Parameters:

fig – figure to extract title from

Returns:

figure title, or None if not available

is_compatible(fig)

Returns True if this backend is compatible with a figure

is_interactive(fig)

Returns True if the figure supports interactive (HTML) output

static title_to_string(title)

Extracts the title as a string from a title-like object (e.g. Text)

class gofigr.backends.matplotlib.SuppressPltWarnings

Bases: object

Temporarily suppresses matplotlib warnings.

gofigr.backends.plotly module

Copyright (c) 2023, Flagstaff Solutions, LLC All rights reserved.

class gofigr.backends.plotly.PlotlyBackend

Bases: GoFigrBackend

Plotly backend for GoFigr

add_interactive_watermark(fig, rev, watermark)

Adds watermark to a figure using the backend’s native objects (if supported by the backend)

Parameters:

• fig – figure to watermark

• rev – FigureRevision object

• watermark – DefaultWatermark instance

Returns:

modified figure

close(fig)

Closes a figure and prevents it from being displayed. :param fig: figure to close :return: None

figure_to_bytes(fig, fmt, params)

Given a figure and an image format, converts the figure to binary representation in that format.

Parameters:

• fig – figure object

• fmt – format, e.g. png

• params – backend-specific parameters

Returns:

bytes

figure_to_html(fig)

Converts a figure to interactive HTML (if supported by the backend)

Parameters:

fig – figure to convert to HTML

Returns:

figure as HTML string

find_figures(shell, data)

Finds all figures compatible with this backend in the current environment.

Parameters:

shell – IPython shell

Returns:

iterator over available figures

get_backend_name()

Gets a human-readable name of this backend. :return: backend name, a string

get_default_figure(silent=False)

Returns the default/current figure, e.g. plt.gcf() for matplotlib

Parameters:

silent – if True, will suppress warnings/errors if default figure is unavailable

get_supported_image_formats()

Gets a list of supported image formats

get_title(fig)

Extracts figure title

Parameters:

fig – figure to extract title from

Returns:

figure title, or None if not available

is_compatible(fig)

Returns True if this backend is compatible with a figure

is_interactive(fig)

Returns True if the figure supports interactive (HTML) output

gofigr.backends.plotnine module

Copyright (c) 2024, Flagstaff Solutions, LLC All rights reserved.

class gofigr.backends.plotnine.PlotnineBackend

Bases: GoFigrBackend

MatplotLib backend for GoFigr.

close(fig)

Closes a figure and prevents it from being displayed. :param fig: figure to close :return: None

figure_to_bytes(fig, fmt, params)

Given a figure and an image format, converts the figure to binary representation in that format.

Parameters:

• fig – figure object

• fmt – format, e.g. png

• params – backend-specific parameters

Returns:

bytes

find_figures(shell, data)

Finds all figures compatible with this backend in the current environment.

Parameters:

shell – IPython shell

Returns:

iterator over available figures

get_backend_name()

Gets a human-readable name of this backend. :return: backend name, a string

get_default_figure(silent=False)

Returns the default/current figure, e.g. plt.gcf() for matplotlib

Parameters:

silent – if True, will suppress warnings/errors if default figure is unavailable

get_supported_image_formats()

Gets a list of supported image formats

get_title(fig)

Extracts figure title

Parameters:

fig – figure to extract title from

Returns:

figure title, or None if not available

is_compatible(fig)

Returns True if this backend is compatible with a figure

is_interactive(fig)

Returns True if the figure supports interactive (HTML) output

gofigr.backends.py3dmol module

Copyright (c) 2023, Flagstaff Solutions, LLC All rights reserved.

class gofigr.backends.py3dmol.Py3DmolBackend(*args, debug=False, image_size=(1920, 1080), disable_logging=True, **kwargs)

Bases: GoFigrBackend

Plotly backend for GoFigr

add_interactive_watermark(fig, rev, watermark)

Adds watermark to a figure using the backend’s native objects (if supported by the backend)

Parameters:

• fig – figure to watermark

• rev – FigureRevision object

• watermark – DefaultWatermark instance

Returns:

modified figure

close(fig)

Closes a figure and prevents it from being displayed. :param fig: figure to close :return: None

figure_to_bytes(fig, fmt, params)

Given a figure and an image format, converts the figure to binary representation in that format.

Parameters:

• fig – figure object

• fmt – format, e.g. png

• params – backend-specific parameters

Returns:

bytes

figure_to_html(fig)

Converts a figure to interactive HTML (if supported by the backend)

Parameters:

fig – figure to convert to HTML

Returns:

figure as HTML string

find_figures(shell, data)

Finds all figures compatible with this backend in the current environment.

Parameters:

shell – IPython shell

Returns:

iterator over available figures

get_backend_name()

Gets a human-readable name of this backend. :return: backend name, a string

get_default_figure(silent=False)

Returns the default/current figure, e.g. plt.gcf() for matplotlib

Parameters:

silent – if True, will suppress warnings/errors if default figure is unavailable

get_supported_image_formats()

Gets a list of supported image formats

get_title(fig)

Extracts figure title

Parameters:

fig – figure to extract title from

Returns:

figure title, or None if not available

is_compatible(fig)

Returns True if this backend is compatible with a figure

is_interactive(fig)

Returns True if the figure supports interactive (HTML) output

class gofigr.backends.py3dmol.WatermarkedView(wrapped_obj, extra_html)

Bases: view

Overrides py3Dmol.view to include a GoFigr watermark