weaver.formats
Module Contents
- class weaver.formats.ContentType[source]
Supported Content-Types.
Media-type nomenclature:
<type> "/" [x- | <tree> "."] <subtype> ["+" suffix] *[";" parameter=value]
- class weaver.formats.OutputFormat[source]
Renderer output formats for CLI, OpenAPI and HTTP response content generation.
- classmethod get(format_or_version: Ellipsis, default: AnyOutputFormat = JSON, allow_version: bool = True) Union[AnyOutputFormat, weaver.base.PropertyDataType] [source]
Resolve the applicable output format.
- Parameters
format_or_version – Either a WPS version, a known value for a
f
/format
query parameter, or anAccept
header that can be mapped to one of the supported output formats.default – Default output format if none could be resolved.
allow_version – Enable WPS version specifiers to infer the corresponding output representation.
- Returns
Resolved output format.
- classmethod convert(data: weaver.typedefs.JSON, to: Union[str, AnyOutputFormat], item_root: str = 'item') Union[str, weaver.typedefs.JSON] [source]
Converts the input data from JSON to another known format.
- Parameters
data – Input data to convert. Must be a literal JSON object, not a JSON-like string.
to – Target format representation. If the output format is not JSON, it is ALWAYS converted to the formatted string of the requested format to ensure the contents are properly represented as intended. In the case of JSON as target format or unknown format, the original object is returned directly.
item_root – When using XML representations, defines the top-most item name. Unused for other representations.
- Returns
Formatted output.
- class weaver.formats.SchemaRole[source]
Constants container that provides similar functionalities to
ExtendedEnum
without explicit Enum membership.
- weaver.formats.get_allowed_extensions() List[str] [source]
Obtain the complete list of extensions that are permitted for processing by the application.
Note
This is employed for security reasons. Files can still be specified with another allowed extension, but it will not automatically inherit properties applicable to scripts and executables. If a specific file type is refused due to its extension, a PR can be submitted to add it explicitly.
- weaver.formats.get_format(mime_type: str, default: Optional[str] = None) Optional[pywps.inout.formats.Format] [source]
Obtains a
Format
with predefined extension and encoding details from known MIME-types.
- weaver.formats.get_extension(mime_type: str, dot: bool = True) str [source]
Retrieves the extension corresponding to
mime_type
if explicitly defined, or by parsing it.
- weaver.formats.get_content_type(extension: str, charset: Optional[str] = None, default: Optional[str] = None) Optional[str] [source]
Retrieves the Content-Type corresponding to the specified extension if it can be matched.
- Parameters
extension – Extension for which to attempt finding a known Content-Type.
charset – Charset to apply to the Content-Type as needed if extension was matched.
default – Default Content-Type to return if no extension is matched.
- Returns
Matched or default Content-Type.
- weaver.formats.add_content_type_charset(content_type: Union[str, ContentType], charset: Optional[str]) str [source]
Apply the specific charset to the content-type with some validation in case of conflicting definitions.
- Parameters
content_type – Desired Content-Type.
charset – Desired charset parameter.
- Returns
updated content-type with charset.
- weaver.formats.get_cwl_file_format(mime_type: str, make_reference: bool = False, must_exist: bool = True, allow_synonym: bool = True) Union[Tuple[Optional[weaver.typedefs.JSON], Optional[str]], Optional[str]] [source]
Obtains the extended schema reference from the media-type identifier.
Obtains the corresponding IANA/EDAM
format
value to be applied under a CWL I/OFile
from themime_type
(Content-Type header) using the first matched one.Lookup procedure is as follows:
- If
make_reference=False
: - If there is a match, returns
tuple({<namespace-name: namespace-url>}, <format>)
with: corresponding namespace mapping to be applied under
$namespaces
in the CWL.value of
format
adjusted according to the namespace to be applied toFile
in the CWL.
- If there is a match, returns
If there is no match but
must_exist=False
, returns a literal and non-existing definition astuple({"iana": <iana-url>}, <format>)
.If there is no match but
must_exist=True
ANDallow_synonym=True
, retry the call with the synonym if available, or move to next step. Skip this step ifallow_synonym=False
.Otherwise, returns
(None, None)
- If
- If
make_reference=True
: If there is a match, returns the explicit format reference as
<namespace-url>/<format>
.If there is no match but
must_exist=False
, returns the literal reference as<iana-url>/<format>
(N.B.: literal non-official MIME-type reference will be returned even if an official synonym exists).If there is no match but
must_exist=True
ANDallow_synonym=True
, retry the call with the synonym if available, or move to next step. Skip this step ifallow_synonym=False
.Returns a single
None
as there is not match (directly or synonym).
- If
- Note:
In situations where
must_exist=False
is used and that the namespace and/or full format URL cannot be resolved to an existing reference, CWL will raise a validation error as it cannot confirm theformat
. You must therefore make sure that the returned reference (or a synonym format) really exists when usingmust_exist=False
before providing it to the CWL I/O definition. Settingmust_exist=False
should be used only for literal string comparison or pre-processing steps to evaluate formats.
- Parameters
mime_type – Some reference, namespace’d or literal (possibly extended) MIME-type string.
make_reference – Construct the full URL reference to the resolved MIME-type. Otherwise return tuple details.
must_exist – Return result only if it can be resolved to an official MIME-type (or synonym if enabled), otherwise
None
. Non-official MIME-type can be enforced if disabled, in which case IANA namespace/URL is used as it preserves the original<type>/<subtype>
format.allow_synonym – Allow resolution of non-official MIME-type to an official MIME-type synonym if available. Types defined as synonym have semantically the same format validation/resolution for CWL. Requires
must_exist=True
, otherwise the non-official MIME-type is employed directly as result.
- Returns
Resolved MIME-type format for CWL usage, accordingly to specified arguments (see description details).
- weaver.formats.clean_mime_type_format(mime_type: str, suffix_subtype: bool = False, strip_parameters: bool = False) Optional[str] [source]
Obtains a generic media-type identifier by cleaning up any additional parameters.
Removes any additional namespace key or URL from
mime_type
so that it corresponds to the generic representation (e.g.:application/json
) instead of the<namespace-name>:<format>
mapping variant used in CWL->inputs/outputs->File->format or the complete URL reference.Removes any leading temporary local file prefix inserted by CWL when resolving namespace mapping. This transforms
file:///tmp/dir/path/package#application/json
to plainapplication/json
.According to provided arguments, it also cleans up additional parameters or extracts sub-type suffixes.
- Parameters
mime_type – MIME-type, full URL to MIME-type or namespace-formatted string that must be cleaned up.
suffix_subtype – Remove additional sub-type specializations details separated by
+
symbol such that an explicit format likeapplication/vnd.api+json
returns only its most basic suffix format defined as``application/json``.strip_parameters – Removes additional MIME-type parameters such that only the leading part defining the
type/subtype
are returned. For example, this will get rid of; charset=UTF-8
or; version=4.0
parameters.
Note
Parameters
suffix_subtype
andstrip_parameters
are not necessarily exclusive.
- weaver.formats.guess_target_format(request: weaver.typedefs.AnyRequestType, default: Optional[Union[ContentType, str]] = ContentType.APP_JSON) ContentType [source]
Guess the best applicable response
Content-Type
header from the request.Considers the request
Accept
header,format
query and alternativelyf
query to parse possible formats. Full Media-Type are expected in the header. Query parameters can use both the full type, or only the sub-type (i.e.: JSON, XML, etc.), with case-insensitive names. Defaults toContentType.APP_JSON
if none was specified.Applies some specific logic to handle automatically added
Accept
headers by many browsers such that sending requests to the API using them will not automatically default back to XML or similar HTML representations. If browsers are used to send requests, but thatformat
/f
queries are used directly in the URL, those will be applied since this is a very intuitive (and easier) approach to request different formats when using browsers.When user-agent clients are identified as another source, such as sending requests from a server or from code, both headers and query parameters are applied directly without question.
- Returns
Matched MIME-type or default.
- weaver.formats.repr_json(data: Any, force_string: bool = True, ensure_ascii: bool = False, indent: Optional[int] = 2, **kwargs: Any) Union[weaver.typedefs.JSON, str, None] [source]
Ensure that the input data can be serialized as JSON to return it formatted representation as such.
If formatting as JSON fails, returns the data as string representation or
None
accordingly.