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

class swh.web.api.apidoc._HTTPDomainDocVisitor(document, urls, data)

Bases: docutils.nodes.NodeVisitor

docutils visitor for walking on a parsed rst document containing sphinx httpdomain roles. Its purpose is to extract relevant info regarding swh api endpoints (for instance url arguments) from their docstring written using sphinx httpdomain.

parameter_roles = ('param', 'parameter', 'arg', 'argument')

response_json_object_roles = ('resjsonobj', 'resjson', '>jsonobj', '>json')

response_json_array_roles = ('resjsonarr', '>jsonarr')

query_parameter_roles = ('queryparameter', 'queryparam', 'qparam', 'query')

request_header_roles = ('<header', 'reqheader', 'requestheader')

response_header_roles = ('>header', 'resheader', 'responseheader')

status_code_roles = ('statuscode', 'status', 'code')

__init__(document, urls, data)

Initialize self. See help(type(self)) for accurate signature.

process_paragraph(par)

Process extracted paragraph text before display. Cleanup document model markups and transform the paragraph into a valid raw rst string (as the apidoc documentation transform rst to html when rendering).

visit_field_list(node)

Visit parsed rst field lists to extract relevant info regarding api endpoint.

visit_paragraph(node)

Visit relevant paragraphs to parse

visit_literal_block(node)

Visit literal blocks

visit_bullet_list(node)

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

depart_document(node)

End of parsing extra processing

unknown_departure(node)

Called before exiting unknown Node types.

Raise exception unless overridden.

__module__ = 'swh.web.api.apidoc'

swh.web.api.apidoc._parse_httpdomain_doc(doc, data)

exception swh.web.api.apidoc.APIDocException

Bases: Exception

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

__module__ = 'swh.web.api.apidoc'

__weakref__

list of weak references to the object (if defined)

class swh.web.api.apidoc.api_doc(route, noargs=False, need_params=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
• need_params (boolean) – specify the route requires query parameters otherwise errors will occur. It enables to avoid displaying the invalid response in its HTML documentation. 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

__init__(route, noargs=False, need_params=False, tags=[], handle_response=False, api_version='1')

Initialize self. See help(type(self)) for accurate signature.

__call__(f)

Call self as a function.

get_doc_data

Build documentation data for the decorated api endpoint function

__dict__ = mappingproxy({'__weakref__': <attribute '__weakref__' of 'api_doc' objects>, '__doc__': "\n Decorate an API function to register it in the API doc route index\n and create the corresponding DRF route.\n\n Args:\n route (str): documentation page's route\n noargs (boolean): set to True if the route has no arguments, and its\n result should be displayed anytime its documentation\n is requested. Default to False\n need_params (boolean): specify the route requires query parameters\n otherwise errors will occur. It enables to avoid displaying the\n invalid response in its HTML documentation. Default to False.\n tags (list): Further information on api endpoints. Two values are\n possibly expected:\n\n * hidden: remove the entry points from the listing\n * upcoming: display the entry point but it is not followable\n\n handle_response (boolean): indicate if the decorated function takes\n care of creating the HTTP response or delegates that task to the\n apiresponse module\n api_version (str): api version string\n\n ", '__module__': 'swh.web.api.apidoc', '__init__': <function api_doc.__init__>, '__call__': <function api_doc.__call__>, 'get_doc_data': <functools._lru_cache_wrapper object>, '__dict__': <attribute '__dict__' of 'api_doc' objects>})

__module__ = 'swh.web.api.apidoc'

__weakref__

list of weak references to the object (if defined)

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

_apidoc_routes = {'/content/': {'docstring': '', 'route_view_name': 'api-content', 'tags': {}}, '/content/filetype/': {'docstring': '', 'route_view_name': 'api-content-filetype', 'tags': {}}, '/content/language/': {'docstring': '', 'route_view_name': 'api-content-language', 'tags': {}}, '/content/license/': {'docstring': '', 'route_view_name': 'api-content-license', 'tags': {}}, '/content/raw/': {'docstring': '', 'route_view_name': 'api-content-raw', 'tags': {}}, '/directory/': {'docstring': '', 'route_view_name': 'api-directory', 'tags': {}}, '/origin/': {'docstring': '', 'route_view_name': 'api-origin', 'tags': {}}, '/origin/metadata-search/': {'docstring': '', 'route_view_name': 'api-origin-metadata-search', 'tags': {}}, '/origin/save/': {'docstring': '', 'route_view_name': 'api-origin-save', 'tags': {}}, '/origin/search/': {'docstring': '', 'route_view_name': 'api-origin-search', 'tags': {}}, '/origin/visit/': {'docstring': '', 'route_view_name': 'api-origin-visit', 'tags': {}}, '/origin/visits/': {'docstring': '', 'route_view_name': 'api-origin-visits', 'tags': {}}, '/origins/': {'docstring': '', 'route_view_name': 'api-origins', 'tags': {}}, '/person/': {'docstring': '', 'route_view_name': 'api-person', 'tags': {}}, '/release/': {'docstring': '', 'route_view_name': 'api-release', 'tags': {}}, '/resolve/': {'docstring': '', 'route_view_name': 'api-resolve', 'tags': {}}, '/revision/': {'docstring': '', 'route_view_name': 'api-revision', 'tags': {}}, '/revision/directory/': {'docstring': '', 'route_view_name': 'api-revision-directory', 'tags': {}}, '/revision/log/': {'docstring': '', 'route_view_name': 'api-revision-log', 'tags': {}}, '/revision/origin/': {'docstring': '', 'route_view_name': 'api-revision-origin', 'tags': {}}, '/revision/origin/log/': {'docstring': '', 'route_view_name': 'api-revision-origin-log', 'tags': {}}, '/snapshot/': {'docstring': '', 'route_view_name': 'api-snapshot', 'tags': {}}, '/stat/counters/': {'docstring': '', 'route_view_name': 'api-stat-counters', 'tags': {}}, '/vault/directory/': {'docstring': '', 'route_view_name': 'api-vault-directory', 'tags': {}}, '/vault/directory/raw/': {'docstring': '', 'route_view_name': 'api-vault-directory-raw', 'tags': {}}, '/vault/revision/gitfast/': {'docstring': '', 'route_view_name': 'api-vault-revision-gitfast', 'tags': {}}, '/vault/revision/gitfast/raw/': {'docstring': '', 'route_view_name': 'api-vault-revision-gitfast-raw', 'tags': {}}}

_method_endpoints = {}

scope = 'api'

classmethod get_app_endpoints()

classmethod add_route(route, docstring, **kwargs)

Add a route to the self-documenting API reference

__module__ = 'swh.web.api.apiurls'

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

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

__init__(url_pattern=None, view_name=None, methods=['GET', 'HEAD', 'OPTIONS'], throttle_scope='swh_api', api_version='1', checksum_args=None)

Initialize self. See help(type(self)) for accurate signature.

__call__(f)

Call self as a function.

__dict__ = mappingproxy({'__weakref__': <attribute '__weakref__' of 'api_route' objects>, '__doc__': '\n Decorator to ease the registration of an API endpoint\n using the Django REST Framework.\n\n Args:\n url_pattern: the url pattern used by DRF to identify the API route\n view_name: the name of the API view associated to the route used to\n reverse the url\n methods: array of HTTP methods supported by the API route\n\n ', '__module__': 'swh.web.api.apiurls', '__init__': <function api_route.__init__>, '__call__': <function api_route.__call__>, '__dict__': <attribute '__dict__' of 'api_route' objects>})

__module__ = 'swh.web.api.apiurls'

__weakref__

list of weak references to the object (if defined)

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.

__module__ = 'swh.web.api.renderers'

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