swh.web.api package

Subpackages

• swh.web.api.views package
  • Submodules
  • swh.web.api.views.content module
  • swh.web.api.views.directory module
  • swh.web.api.views.identifiers module
  • swh.web.api.views.origin module
  • swh.web.api.views.origin_save module
  • swh.web.api.views.person module
  • swh.web.api.views.release module
  • swh.web.api.views.revision module
  • swh.web.api.views.snapshot module
  • swh.web.api.views.stat module
  • swh.web.api.views.utils module
  • swh.web.api.views.vault module
  • Module contents

Submodules

swh.web.api.apidoc module

exception swh.web.api.apidoc.APIDocException

Bases: Exception

Custom exception to signal errors in the use of the APIDoc decorators

class swh.web.api.apidoc.api_doc(route, noargs=False, tags=[], handle_response=False, api_version='1')

Bases: object

Decorate an API function to register it in the API doc route index and create the corresponding DRF route.

Parameters:

• route (str) – documentation page’s route
• noargs (boolean) – set to True if the route has no arguments, and its result should be displayed anytime its documentation is requested. Default to False
• tags (list) –

  Further information on api endpoints. Two values are possibly expected:

  • hidden: remove the entry points from the listing
  • upcoming: display the entry point but it is not followable

• handle_response (boolean) – indicate if the decorated function takes care of creating the HTTP response or delegates that task to the apiresponse module
• api_version (str) – api version string

get_doc_data

Build documentation data for the decorated api endpoint function

swh.web.api.apiresponse module

swh.web.api.apiresponse.compute_link_header(rv, options)

Add Link header in returned value results.

Parameters:

• rv (dict) –

  dictionary with keys:

  • headers: potential headers with ‘link-next’ and ‘link-prev’ keys
  • results: containing the result to return
• options (dict) – the initial dict to update with result if any

Returns:

dictionary with optional keys ‘link-next’ and ‘link-prev’

Return type:

dict

swh.web.api.apiresponse.filter_by_fields(request, data)

Extract a request parameter ‘fields’ if it exists to permit the filtering on the data dict’s keys.

If such field is not provided, returns the data as is.

swh.web.api.apiresponse.transform(rv)

Transform an eventual returned value with multiple layer of information with only what’s necessary.

If the returned value rv contains the ‘results’ key, this is the associated value which is returned.

Otherwise, return the initial dict without the potential ‘headers’ key.

swh.web.api.apiresponse.make_api_response(request, data, doc_data={}, options={})

Generates an API response based on the requested mimetype.

Parameters:

• request – a DRF Request object
• data – raw data to return in the API response
• doc_data – documentation data for HTML response
• options – optional data that can be used to generate the response

Returns:

a DRF Response a object

swh.web.api.apiresponse.error_response(request, error, doc_data)

Private function to create a custom error response.

Parameters:

• request – a DRF Request object
• error – the exception that caused the error
• doc_data – documentation data for HTML response

swh.web.api.apiurls module

class swh.web.api.apiurls.APIUrls

Bases: swh.web.common.urlsindex.UrlsIndex

Class to manage API documentation URLs.

• Indexes all routes documented using apidoc’s decorators.
• Tracks endpoint/request processing method relationships for use in generating related urls in API documentation

scope = 'api'

classmethod get_app_endpoints()

classmethod add_route(route, docstring, **kwargs)

Add a route to the self-documenting API reference

class swh.web.api.apiurls.api_route(url_pattern=None, view_name=None, methods=['GET', 'HEAD', 'OPTIONS'], throttle_scope='swh_api', api_version='1')

Bases: object

Decorator to ease the registration of an API endpoint using the Django REST Framework.

Parameters:

• url_pattern – the url pattern used by DRF to identify the API route
• view_name – the name of the API view associated to the route used to reverse the url
• methods – array of HTTP methods supported by the API route

swh.web.api.renderers module

class swh.web.api.renderers.YAMLRenderer

Bases: rest_framework.renderers.BaseRenderer

Renderer which serializes to YAML.

media_type = 'application/yaml'

format = 'yaml'

charset = 'utf-8'

ensure_ascii = False

default_flow_style = False

render(data, accepted_media_type=None, renderer_context=None)

Renders data into serialized YAML.

swh.web.api.urls module

swh.web.api.utils module

swh.web.api.utils.filter_field_keys(data, field_keys)

Given an object instance (directory or list), and a csv field keys to filter on.

Return the object instance with filtered keys.

Note: Returns obj as is if it’s an instance of types not in (dictionary, list)

Parameters:

• data (-) – one object (dictionary, list…) to filter.
• field_keys (-) – csv or set of keys to filter the object on

Returns:

obj filtered on field_keys

swh.web.api.utils.person_to_string(person)

Map a person (person, committer, tagger, etc…) to a string.

swh.web.api.utils.enrich_object(object)

Enrich an object (revision, release) with link to the ‘target’ of type ‘target_type’.

Parameters:

• object – An object with target and target_type keys
• release, revision) ((e.g.) –

Returns:

Object enriched with target_url pointing to the right swh.web.ui.api urls for the pointing object (revision, release, content, directory)

swh.web.api.utils.enrich_release(object)

Enrich an object (revision, release) with link to the ‘target’ of type ‘target_type’.

Parameters:

• object – An object with target and target_type keys
• release, revision) ((e.g.) –

Returns:

Object enriched with target_url pointing to the right swh.web.ui.api urls for the pointing object (revision, release, content, directory)

swh.web.api.utils.enrich_directory(directory, context_url=None)

Enrich directory with url to content or directory.

swh.web.api.utils.enrich_metadata_endpoint(content)

Enrich metadata endpoint with link to the upper metadata endpoint.

swh.web.api.utils.enrich_content(content, top_url=False, query_string=None)

Enrich content with links to:

• data_url: its raw data
• filetype_url: its filetype information
• language_url: its programming language information
• license_url: its licensing information

Parameters:

• content – dict of data associated to a swh content object
• top_url – whether or not to include the content url in the enriched data
• query_string – optional query string of type ‘<algo>:<hash>’ used when requesting the content, it acts as a hint for picking the same hash method when computing the url listed above

Returns:

An enriched content dict filled with additional urls

swh.web.api.utils.enrich_revision(revision)

Enrich revision with links where it makes sense (directory, parents). Keep track of the navigation breadcrumbs if they are specified.

Parameters:revision – the revision as a dict

Module contents