Internal API

A library to allow navigating rest apis easy.

class restnavigator.halnav.APICore(root, nav_class, apiname=None, default_curie=None, session=None, id_map=None)

Shared data between navigators from a single api.

This should contain all state that is generally maintained from one navigator to the next.

authenticate(auth)

Sets the authentication for future requests to the api

cache(link, nav)

Stores a navigator in the identity map for the current api. Can take a link or a bare uri

get_cached(link, default=None)

Retrieves a cached navigator from the id_map.

Either a Link object or a bare uri string may be passed in.

is_cached(link)

Returns whether the current navigator is cached. Intended to be overwritten and customized by subclasses.

class restnavigator.halnav.HALNavigator(link, core, response=None, state=None, curies=None, _links=None, _embedded=None)

The main navigation entity

create(body=None, raise_exc=True, headers=None)

Performs an HTTP POST to the server, to create a subordinate resource. Returns a new HALNavigator representing that resource.

body may either be a string or a dictionary representing json headers are additional headers to send in the request

delete(raise_exc=True, headers=None)

Performs an HTTP DELETE to the server, to delete resource(s).

headers are additional headers to send in the request

fetch(raise_exc=True)

Performs a GET request to the uri of this navigator

patch(body, raise_exc=True, headers=False)

Performs an HTTP PATCH to the server. This is a non-idempotent call that may update all or a portion of the resource this navigator is pointing to. The format of the patch body is up to implementations.

body may either be a string or a dictionary representing json headers are additional headers to send in the request

upsert(body, raise_exc=True, headers=False)

Performs an HTTP PUT to the server. This is an idempotent call that will create the resource this navigator is pointing to, or will update it if it already exists.

body may either be a string or a dictionary representing json headers are additional headers to send in the request

class restnavigator.halnav.HALNavigatorBase(link, core, response=None, state=None, curies=None, _links=None, _embedded=None)

Base class for navigation objects

authenticate(auth)

Authenticate with the api

docsfor(rel)

Obtains the documentation for a link relation. Opens in a webbrowser window

embedded()

Returns a dictionary of navigators representing embedded documents in the current resource. If the navigators have self links they can be fetched as well.

links()

Returns a dictionary of navigators from the current resource. Fetches the resource if necessary.

class restnavigator.halnav.Link(uri, properties=None)

Represents a HAL link. Does not store the link relation

relative_uri(root)

Returns the link of the current uri compared against an api root

class restnavigator.halnav.Navigator

A factory for other navigators. Makes creating them more convenient

static hal(root, apiname=None, default_curie=None, auth=None, headers=None, session=None)

Create a HALNavigator

class restnavigator.halnav.OrphanHALNavigator(link, core, response=None, state=None, curies=None, _links=None, parent=None)

A Special navigator that is the result of a non-GET

This navigator cannot be fetched or created, but has a special property called .parent that refers to the navigator this one was created from. If the result is a HAL document, it will be populated properly

class restnavigator.halnav.PartialNavigator(link, core=None)

A lazy representation of a navigator. Expands to a full navigator when template arguments are given by calling it.

expand_link(**kwargs)

Expands with the given arguments and returns a new untemplated Link object

expand_uri(**kwargs)

Returns the template uri expanded with the current arguments

variables

Returns a set of the template variables in this templated link

exception restnavigator.exc.HALNavigatorError(message, nav=None, status=None, response=None)

Raised when a response is an error

Has all of the attributes of a normal HALNavigator. The error body can be returned by examining response.body

exception restnavigator.exc.NoResponseError

Raised when accessing a field of a navigator that has not fetched a response yet

exception restnavigator.exc.OffTheRailsException(traversal, index, intermediates, e)

Raised when a traversal specified to __getitem__ cannot be satisfied

exception restnavigator.exc.UnexpectedlyNotJSON(uri, response)

Raised when a non-json parseable resource is gotten

exception restnavigator.exc.WileECoyoteException

Raised when a url has a bad scheme

exception restnavigator.exc.ZachMorrisException

Raised when a url has too many schemes

class restnavigator.utils.CurieDict(default_curie, d)

dict subclass that allows specifying a default curie. This enables multiple ways to access an item

class restnavigator.utils.LinkList(items=None)

A list subclass that offers different ways of grabbing the values based on various metadata stored for each entry in the dictionary.

Note: Removing items from this list isn’t really the point, so no attempt has been made to make this convenient. Deleting items will not remove them from the list’s metadata.

append_with(obj, **properties)

Add an item to the dictionary with the given metadata properties

get_by(prop, val, raise_exc=False)

Retrieve an item from the dictionary with the given metadata properties. If there is no such item, None will be returned, if there are multiple such items, the first will be returned.

getall_by(prop, val)

Retrieves all items from the dictionary with the given metadata

named(name)

Returns .get_by(‘name’, name)

serialize

alias of unicode

restnavigator.utils.fix_scheme(url)

Prepends the http:// scheme if necessary to a url. Fails if a scheme other than http is used

restnavigator.utils.getpath(d, json_path, default=None, sep='.')

Gets a value nested in dictionaries containing dictionaries. Returns the default if any key in the path doesn’t exist.

restnavigator.utils.getstate(d)

Deep copies a dict, and returns it without the keys _links and _embedded

restnavigator.utils.namify(root_uri)

Turns a root uri into a less noisy representation that will probably make sense in most circumstances. Used by Navigator’s __repr__, but can be overridden if the Navigator is created with a ‘name’ parameter.

restnavigator.utils.normalize_getitem_args(args)

Turns the arguments to __getitem__ magic methods into a uniform list of tuples and strings

restnavigator.utils.objectify_uri(relative_uri)

Converts uris from path syntax to a json-like object syntax. In addition, url escaped characters are unescaped, but non-ascii characters a romanized using the unidecode library.

Examples:

“/blog/3/comments” becomes “blog[3].comments” “car/engine/piston” becomes “car.engine.piston”

restnavigator.utils.parse_media_type(media_type)

Returns type, subtype, parameter tuple from an http media_type. Can be applied to the ‘Accept’ or ‘Content-Type’ http header fields.