lisc.urls.URLs

class lisc.urls.URLs(base, utils, authenticated=None)

URLs for an API interface.

Attributes

basestr

Base URL for the API.

utilsdict

What utilities are available for the API.

urlsdict

The URLs for each utility.

settingsdict

The available settings for the API.

authenticatedbool

Whether acting as an authenticated user for the API.

__init__(base, utils, authenticated=None)

Initialize a URLs object.

Parameters

basestr

Base URL for the API.

utilsdict

Utilities for the utility, a dictionary with names and URL extensions.

authenticatedbool, optional

Whether acting as an authenticated user for the API.

Examples

Initialize a URLs object for the Github API:

>>> urls = URLs('https://api.github.com', {'search_repos': "search/repositories"})

Methods

__init__(base, utils[, authenticated])	Initialize a URLs object.
authenticate(url)	Method to authenticate a URL for a given API.
build_url(util[, segments, settings])	Build the URL for a specified utility, with provided settings.
check_url(util)	Check the built URL for a specified utility.
fill_settings(**kwargs)	Put all provided settings values into a dictionary object.
get_url(util[, segments, settings])	Get a requested URL, with any additional segments or settings.

authenticate(url)

Method to authenticate a URL for a given API.

Parameters

urlstr

URL to add authentication to.

Returns

str

Authenticated URL.

Notes

This is a placeholder method, on the base URLs object, and should be overloaded by any API object that has authentication.

When overloading this method, it should implement whatever is needed to authenticate a URL request for the specified API.

build_url(util, segments=None, settings=None)

Build the URL for a specified utility, with provided settings.

Parameters

utilstr

Which utility to build the URL for.

segmentslist of str, optional

Segments to add to the URL.

settingsdict or list of str, optional

Settings to use to build the URL. If list, the settings values are taken from the objects settings attribute.

Examples

Build the url for the Github API to search for a repository search:

>>> urls = URLs('https://api.github.com', {'search_repos': "search/repositories"})
>>> urls.fill_settings(q='lisc', sort='stars', order='desc')
>>> urls.build_url('search_repos', settings=['q', 'sort', 'order'])

check_url(util)

Check the built URL for a specified utility.

Parameters

utilstr

Which utility to check the URL for.

Examples

Check the URL that gets built for a Github repository search:

>>> urls = URLs('https://api.github.com', {'search_repos': "search/repositories"})
>>> urls.fill_settings(q='lisc', sort='stars', order='desc')
>>> urls.build_url('search_repos', settings=['q', 'sort', 'order'])
>>> urls.check_url('search_repos')
https://api.github.com/search/repositories?q=lisc&sort=stars&order=desc

fill_settings(**kwargs)

Put all provided settings values into a dictionary object.

Parameters

**kwargs

Keyword arguments for all settings, with their values.

Notes

Potential parameters to this function include all the possible settings for the given API.

Any possible setting that is provided a value as an input to this function is saved out to the dictionary of collected and available settings.

Examples

Provide settings for the query, sort, and order of a Github search:

>>> urls = URLs('https://api.github.com', {'search_repos': "search/repositories"})
>>> urls.fill_settings(q='lisc', sort='stars', order='desc')

get_url(util, segments=None, settings=None)

Get a requested URL, with any additional segments or settings.

Parameters

utilstr

Which utility to get the URL for.

segmentslist of str, optional

Any additional segments to add to the URL.

settingsdict, optional

Any additional settings to add to the URL.

Returns

full_urlstr

The requested URL, with any extra segments and settings added.

Examples

Get the url built for a Github repository search:

>>> urls = URLs('https://api.github.com', {'search_repos': "search/repositories"})
>>> urls.fill_settings(q='lisc', sort='stars', order='desc')
>>> urls.build_url('search_repos', settings=['q', 'sort', 'order'])
>>> urls.get_url('search_repos')
'https://api.github.com/search/repositories?q=lisc&sort=stars&order=desc'

Examples using lisc.urls.URLs

URLs and Requests

URLs and Requests