[Python-ideas] More Metadata for Variable Annotations
wes.turner at gmail.com
Fri Aug 18 17:23:50 EDT 2017
PyContracts supports things like numpy array constraints
> You can specify that the value must be a list, and specify optional
constraints for its length and for its elements.
You mentioned JSONschema. For RDF (e.g. JSONLD, #CSVW), there are a number
of relevant variable annotations that should be useful as schema:
> A data table with 7 metadata header rows (column label, property URI
path, DataType, unit, accuracy, precision, significant figures):
On Friday, August 18, 2017, Bagrat Aznauryan <bagrat at aznauryan.org> wrote:
> # Abstract
> Before the holly PEP-526 the only option for type hints were comments. And
> before PEP-484 the docstrings were the main place where variable metadata
> would go. That variable metadata would include:
> * the type
> * the human-readable description
> * some value constraints (e.g. a range for integer variable)
> PEP-526 introduced the awesome syntax sugar, which made the first part of
> the metadata - the type, easily introspectable during the runtime. However,
> if you still need to add the description and the value constraints to the
> variable metadata, you still need to fallback to the docstring option.
> The idea is to make it possible to be able to include all of the mentioned
> metadata in the variable annotations.
> # Rationale
> Having the type specified using the supported annotation syntax and the
> rest of the metadata in the docstrings, adds duplication and complexity for
> further maintenance. Moreover, if you need the docstring-contained metadata
> to be used in the runtime, you need to implement a parser or pick one from
> existing ones which adds another dependency to your application.
> The need for the rest of the metadata other than the type, might be proven
> to be common. A typical example is generating the JSON Schema for a class,
> e.g. to be used for OpenAPI definition of your API.
> # Possible Solutions
> ## A wrapper
> The proposal is to introduce a new wrapper (probably a function), that
> will accept the type as the first positional argument and additional
> keyword arguments for metadata. The wrapper will map the keyword arguments
> to the type object as attributes and return it. The code would look like
> foo: wrapper(
> Later, the metadata can be accessed as the annotation attributes, like
> ## Annotation as a tuple
> This solution does not require any code change in Python, but will force
> other tools change the parsing (e.g. mypy). The proposal is that when the
> annotation is optionally a tuple instance, use the first element as the
> type of the variable, and ignore the rest or treat as additional metadata.
> This will make it possible to add the metadata into a separate dictionary
> as the second element of the annotation tuple. For example:
> foo: (
> The annotation will be stored as is, so to access the metadata in the
> runtime, one would need to explicitly access the second item of the
> annotation tuple.
> # Summary
> This option would help to have a well annotated code which will be
> self-descriptive and provide abilities to generate schemas and other
> definitions (e.g. OpenAPI) automatically and without duplication.
> The proposed solutions are definitely not perfect and not the main point
> of this email. The target is to describe the idea and motivation and start
> a discussion.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-ideas