lisc.urls.EUtils

class lisc.urls.EUtils(db=None, retmax=None, field=None, retmode=None, usehistory='n', api_key=None, **eutils_kwargs)

URLs for the NCBI EUtils API.

Attributes

basestr

Base URL for the EUtils API.

utilsdict

The EUtil utilities.

urlsdict

URLs for each EUtils utility.

settingsdict

Dictionary of all defined settings and their values.

authenticatedbool

Whether using an API key as an authenticated NCBI user.

__init__(db=None, retmax=None, field=None, retmode=None, usehistory='n', api_key=None, **eutils_kwargs)

Initialize the NCBI EUtils URLs, with provided settings.

Parameters

dbstr, optional

Which database to access from EUtils.

retmaxint, optional

The maximum number of articles to return.

fieldstr, optional

The search field to search within.

retmode{‘lxml’, ‘xml’}, optional

The return format for the results.

usehistory{‘n’, ‘y’}, optional

Whether to use history caching on the EUtils server. ‘n’ indicates ‘no’, do not use history. ‘y’ indicates ‘yes’, to use history.

api_keystr, optional

An API key for authenticated NCBI user account.

**eutils_kwargs

Additional settings for the EUtils API.

Examples

Initialize a EUtils URL object, setting the max number of returned items:

>>> urls = EUtils(db='pubmed', retmax=5)

Methods

__init__([db, retmax, field, retmode, ...])	Initialize the NCBI EUtils URLs, with provided settings.
authenticate(url)	Authenticate a URL for the EUtils 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)

Authenticate a URL for the EUtils API.

Parameters

urlstr

URL to add authentication to.

Returns

str

Authenticated URL.

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.EUtils

URLs and Requests

URLs and Requests