URLs

Proper URL patterns are the backbone of a ResourceModel. URLs are defined in a ResourceModel as a tuple of nap_urls–a thin wrapper around a python-formatted string. These are defined and tied to a ResourceModel through the urls, prepend_urls, and append_urls. These are stored in the ResourceModel’s _meta

By default, ResourceModels have two nap_urls that allow them to make all common calls to a to-spec REST API:

(
    nap_url('%(resource_name)s/', create=True, lookup=False, collection=True),
    nap_url('%(resource_name)s/%(resource_id)s/', update=True),
)

How a URL lookup works

nap_urls contain three parts of information:

  1. The kinds of lookups that this url can be used for.
  2. The URL String itself
  3. The names of variables needed to generate

On calls that are backed by a URL, Nap will iterate through every URL in it’s url list looking for a match. A match is considered a URL where

  1. The URL is valid for the type of request being attempted
  2. The variablres required to generated a valid URL are available.

Let’s dive into each part of a URL to understand this process a bit better.

Lookup Types

Lookup types closely match the kind of operations possible with an API. They are create, lookup, update, collection.

  • create: URLs that can be used to create new resources. Used for the create() method.
  • lookup: URLs that can be used to retreive a single resource. Used for the get() method when using keyword arguments.
  • update: URLs that can be used to create update an existing resource. Used for the update() method.
  • collection: URLs that can be used to retrieve collections of resources. Used for the filter() and all() methods.

Valid URL Strings

A URL string is simply a python string, optionally containing dictionary-format variables.

nap bases it’s required variables partially on any format variables contained in the URL string.

URL Variables

LookupURLs may require variables to fully resolve. Required variables are either

  1. Python string format variables contained in the url_string, or
  2. Any variables named passed into a __init__‘s param parameter. These variables are passed into the URL via a URL query string.

ResourceModel passes in three kinds of variables into the LookupURL’s match function to determine if all required variables are available for URL resolution:

  1. Keyword arguments passed to lookup function (eg, ResourceModel.get(), ResourceModel.update())
  2. The values of fields, where the name of the field is passed as the variable name.
  3. Meta variables specific to the subclass of ResourceModel

The above lists these groups in order of presidence–eg, If update() is called on a ResourceModel with a resource_name of ‘person’, but a keyword argument of resource_name='author', %(resource_name)s will resolve to author.

Meta Variables available for URLs

Currently, there is only one meta variable passed to LookupURL.

resource_name

The resource name of the ResourceModel. Equal to resource_name

URL API

class nap.lookup.LookupURL

Class in charge of resolving variable URLs based on keyword arguments. Used for any dynamic API method on ResourceModel

LookupURL.__init__(url_string[, params=None, create=False, update=False, lookup=False, collection=False])
Parameters:
  • url_string – python-formatted string representing a URL
  • params – an iterable of variables names required by the URL, as passed in a GET query string.
  • create – Designates whether or not the URL is valid for create operations
  • update – Designates whether or not the URL is valid for create operations
  • lookup – Designates whether or not the URL is valid for create operations
  • collection – Designates whether or not the URL is valid for create operations
LookupURL.url_vars

Returns a tuple the names of variables contained within a LookupURL

LookupURL.required_vars

Returns a tuple of the the names of all variables required to successfully resolve a URL.

LookupURL.match(**lookup_vars)

Attempts to resolve a string of a URL, resolving any variables based on lookup_vars.

Returns a two tuple of the matching URL string and extra lookup variables that were passed in but not part of the required values.

If no match is found, a two tuple of (None, None) is returned.

Parameters:lookup_vars – A dict-like variable mapping URL variables names to
Read the Docs v: winter_refactor
Versions
winter_refactor
latest
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.