**************** Builtin Backends **************** Using a backend, you can convert the data types and routes in your spec into objects in your programming language of choice. Stone includes backends for an assortment of languages, including: * `Python <#python-guide>`_ * Python `Type Stubs `_ * Javascript * Objective-C * Swift * Typescript If you're looking to write your own backend, see `Backend Reference `_. We would love to see a contribution of a PHP or Ruby backend. Compile with the CLI ==================== Compiling a spec and generating code is done using the ``stone`` command-line interface (CLI):: $ stone -h usage: stone [-h] [-v] [--clean-build] [-f FILTER_BY_ROUTE_ATTR] [-w WHITELIST_NAMESPACE_ROUTES | -b BLACKLIST_NAMESPACE_ROUTES] backend output [spec [spec ...]] StoneAPI positional arguments: backend Either the name of a built-in backend or the path to a backend module. Paths to backend modules must end with a .stoneg.py extension. The following backends are built-in: js_client, js_types, tsd_client, tsd_types, python_types, python_client, swift_client output The folder to save generated files to. spec Path to API specifications. Each must have a .stone extension. If omitted or set to "-", the spec is read from stdin. Multiple namespaces can be provided over stdin by concatenating multiple specs together. optional arguments: -h, --help show this help message and exit -v, --verbose Print debugging statements. --clean-build The path to the template SDK for the target language. -f FILTER_BY_ROUTE_ATTR, --filter-by-route-attr FILTER_BY_ROUTE_ATTR Removes routes that do not match the expression. The expression must specify a route attribute on the left- hand side and a value on the right-hand side. Use quotes for strings and bytes. The only supported operators are "=" and "!=". For example, if "hide" is a route attribute, we can use this filter: "hide!=true". You can combine multiple expressions with "and"/"or" and use parentheses to enforce precedence. -w WHITELIST_NAMESPACE_ROUTES, --whitelist-namespace-routes WHITELIST_NAMESPACE_ROUTES If set, backends will only see the specified namespaces as having routes. -b BLACKLIST_NAMESPACE_ROUTES, --blacklist-namespace-routes BLACKLIST_NAMESPACE_ROUTES If set, backends will not see any routes for the specified namespaces. We'll generate code based on an ``calc.stone`` spec with the following contents:: namespace calc route eval(Expression, Result, EvalError) struct Expression "This expression is limited to a binary operation." op Operator = add left Int64 right Int64 union Operator add sub mult div Boolean "If value is true, rounds up. Otherwise, rounds down." struct Result answer Int64 union EvalError overflow Python Guide ============ This section explains how to use the pre-packaged Python backends and work with the Python classes that have been generated from a spec. There are two different Python backends: ``python_types`` and ``python_client``. The former generates Python classes for the data types defined in your spec. The latter generates a single Python class with a method per route, which is useful for building SDKs. We'll use the ``python_types`` backend:: $ stone python_types . calc.stone This runs the backend on the ``calc.stone`` spec. Its output target is ``.`` which is the current directory. A Python module is created for each declared namespace, so in this case only ``calc.py`` is created. Three additional modules are copied into the target directory. The first, ``stone_validators.py``, contains classes for validating Python values against their expected Stone types. You will not need to explicitly import this module, but the auto-generated Python classes depend on it. The second, ``stone_serializers.py``, contains a pair of ``json_encode()`` and ``json_decode()`` functions. You will need to import this module to serialize your objects. The last is ``stone_base.py`` which shouldn't be used directly. In the following sections, we'll interact with the classes generated in ``calc.py``. For simplicity, we'll assume we've opened a Python interpreter with the following shell command:: $ python -i calc.py For non-test projects, we recommend that you set the generation target to a path within a Python package, and use Python's import facility. Primitive Types --------------- The following table shows the mapping between a Stone `primitive type `_ and its corresponding type in Python. ========================== ============== ===================================== Primitive Python 2.x / 3 Notes ========================== ============== ===================================== Bytes bytes Boolean bool Float{32,64} float long type within range is converted. Int{32,64}, UInt{32,64} long List list String unicode / str str type is converted to unicode. Timestamp datetime ========================== ============== ===================================== Struct ------ For each struct in your spec, you will see a corresponding Python class of the same name. In our example, ``Expression``, ``Operator``, ``Answer``, ``EvalError``, and are Python classes. They have an attribute (getter/setter/deleter property) for each field defined in the spec. You can instantiate these classes and specify field values either in the constructor or by assigning to an attribute:: >>> expr = Expression(op=Operator.add, left=1, right=1) If you assign a value that fails validation, an exception is raised:: >>> expr.op = '+' Traceback (most recent call last) ... ValidationError: expected type Operator or subtype, got string Accessing a required field (non-optional with no default) that has not been set raises an error:: >>> res = Result() >>> res.answer Traceback (most recent call last): File "", line 1, in File "calc.py", line 221, in answer raise AttributeError("missing required field 'answer'") AttributeError: missing required field 'answer' Other characteristics: 1. Inheritance in Stone is represented as inheritance in Python. 2. If a field is nullable and was never set, ``None`` is returned. 3. If a field has a default but was never set, the default is returned. Union ----- For each union in your spec, you will see a corresponding Python class of the same name. You do not use a union class's constructor directly. To select a tag with a void type, use the class attribute of the same name:: >>> EvalError.overflow EvalError('overflow', None) To select a tag with a value, use the class method of the same name and pass in an argument to serve as the value:: >>> Operator.div(False) Operator('div', False) To write code that handles the union options, use the ``is_[tag]()`` methods. We recommend you exhaustively check all tags, or include an else clause to ensure that all possibilities are accounted for. For tags that have values, use the ``get_[tag]()`` method to access the value:: >>> # assume that op is an instance of Operator >>> if op.is_add(): ... # handle addition ... elif op.is_sub(): ... # handle subtraction ... elif op.is_mult(): ... # handle multiplication ... elif op.is_div(): ... round_up = op.get_div() ... # handle division Struct Polymorphism ------------------- As with regular structs, structs that enumerate subtypes have corresponding Python classes that behave identically to regular structs. The difference is apparent when a field has a data type that is a struct with enumerated subtypes. Expanding on our example from the language reference, assume the following spec:: struct Resource union file File folder Folder path String struct File extends Resource: size UInt64 struct Folder extends Resource: "No new fields." struct Response rsrc Resource If we instantiate ``Response``, the ``rsrc`` field can only be assigned a ``File`` or ``Folder`` object. It should not be assigned a ``Resource`` object. An exception to this is on deserialization. Because ``Resource`` is specified as a catch-all, it's possible when deserializing a ``Response`` to get a ``Resource`` object in the ``rsrc`` field. This indicates that the returned subtype was unknown because the recipient has an older spec than the sender. To handle catch-alls, you should use an else clause:: >>> print resp.rsrc.path # Guaranteed to work regardless of subtype >>> if isinstance(resp, File): ... # handle File ... elif isinstance(resp, Folder): ... # handle Folder ... else: ... # unknown subtype of Resource Route ----- Routes are represented as instances of a ``Route`` object. The generated Python module for the namespace will have a module-level variable for each route:: >>> eval Route('eval', 1, False, ...) Route attributes specified in the spec are available as a dict in the ``attrs`` member variable. Route deprecation is stored in the ``deprecated`` member variable. The name and version of a route are stored in the ``name`` and ``version`` member variables, respectively. Serialization ------------- We can use ``stone_serializers.json_encode()`` to serialize our objects to JSON:: >>> import stone_serializers >>> stone_serializers.json_encode(eval.result_type, Result(answer=10)) '{"answer": 10}' To deserialize, we can use ``json_decode``:: >>> stone_serializers.json_decode(eval.result_type, '{"answer": 10}') Result(answer=10) There's also ``json_compat_obj_encode`` and ``json_compat_obj_decode`` for converting to and from Python primitive types rather than JSON strings. Route Functions --------------- To generate functions that represent routes, use the ``python_client`` generator:: $ stone python_client . calc.stone -- -m client -c Client -t myservice ``-m`` specifies the name of the Python module to generate, in this case ``client.py``. The important contents of the file look as follows:: class Client(object): __metaclass__ = ABCMeta @abstractmethod def request(self, route, namespace, arg, arg_binary=None): pass # ------------------------------------------ # Routes in calc namespace def calc_eval(self, left, right, op=calc.Operator.add): """ :type op: :class:`myservice.calc.Operator` :type left: long :type right: long :rtype: :class:`myservice.calc.Result` :raises: :class:`.exceptions.ApiError` If this raises, ApiError will contain: :class:`myservice.calc.EvalError` """ arg = calc.Expression(left, right, op) r = self.request( calc.eval, 'calc', arg, None, ) return r ``-c`` specified the name of the abstract class to generate. Using this class, you'll likely want to inherit the class and implement the request function. For example, an API that goes over HTTP might have the following client:: import requests # use the popular HTTP library from .stone_serializers import json_decode, json_encode from .exceptions import ApiError # You must implement this class MyServiceClient(Client): def request(self, route, namespace, arg, arg_binary=None): url = 'https://api.myservice.xyz/{}/{}'.format( namespace, route.name) r = requests.get( url, headers={'Content-Type': 'application/json'}, data=json_encode(route.arg_type, arg)) if r.status_code != 200: raise ApiError(...) return json_decode(route.result_type, r.content) Note that care is taken to ensure that that the return type and exception type match those that were specified in the automatically generated documentation. Routes with Version Numbers --------------------------- There can be multiple versions of routes sharing the same name. For each route with a version numbers other than 1, the generated module-level route variable and route function have a version suffix appended in the form of ``{name}_v{version}``. For example, suppose we add a new version of route ``eval`` in ``calc.stone`` as follows:: ... route eval:2(Expression, ResultV2, EvalError) struct ResultV2 answer String ... The module-level variable for the route will be:: >>> eval_v2 Route('eval', 2, False, ...) And the corresponding route function in ``client.py`` will be ``calc_eval_v2``.