Templates¶
This page provides a description of templates: how to write them, what variables they receive, and so on and so forth.
In many cases, it should be possible to provide alternative Python libraries based on protocol buffers by only editing templates (or authoring new ones), with no requirement to alter the primary codebase itself.
Jinja¶
All templates are implemented in Jinja, Armin Ronacher’s excellent templating library for Python. This document assumes that you are already familiar with the basics of writing Jinja templates, and does not seek to cover that here.
Locating Templates¶
Templates are included in output simply on the basis that they exist. There is no master list of templates; it is assumed that every template should be rendered (unless its name begins with a single underscore).
Note
Files beginning with an underscore (_
) are not rendered by default.
This is to allow them to be used with extends
and include
.
However, __init__.py.j2
is rendered.
The name of the output file is based on the name of the template, with the following string replacements applied:
- The
.j2
suffix is removed. $namespace
is replaced with the namespace specified in the client, converted to appropriate Python module case. If there is no namespace, this segment is dropped. If the namespace has more than one element, this is expanded out in the directory structure. (For example, a namespace of['Acme', 'Manufacturing']
will translate intoacme/manufacturing/
directories.)$name
is replaced with the client name. This is expected to be present.$version
is replaced with the client version (the version of the API). If there is no specified version, this is dropped.$service
is replaced with the service name, converted to appropriate Python module case. There may be more than one service in an API; read on for more about this.
Note
$name_$version
is a special case: It is replaced with the client
name, followed by the version. However, if there is no version, both it
and the underscore are dropped.
Context (Variables)¶
Every template receives one variable, spelled api
. It is the
API
object that was pieced together in the parsing step.
Most APIs also receive one additional variable depending on what piece of the API structure is being iterated over:
- Services. APIs can (and often do) have more than one service. Therefore, templates with
$service
in their name are rendered once per service, with the$service
string changed to the name of the service itself (in snake case, because this is Python). These templates receive aservice
variable (an instance ofService
) corresponding to the service currently being iterated over.- Protos. Similarly, APIs can (and often do) have more than one proto file containing messages. Therefore, templates with
$proto
in their name are rendered once per proto, with the$proto``string changed to the name of the proto file. These templates receive a ``proto
variable (an instance ofProto
) corresponding to the proto currently being iterated over.
Filters¶
Additionally, templates receive a limited number of filters useful for writing properly formatted templates.
These are:
rst
(rst()
): Converts a string to ReStructured Text. If the string appears not to be formatted (contains no obvious Markdown syntax characters), then this method forwards towrap
.sort_lines
(sort_lines()
): Sorts lines of text, optionally de-duplicating if there are duplicates. This works best with the Jinja{% filter sort_lines %}
style syntax.snake_case
(to_snake_case()
): Converts a string in any sane case system to snake case.wrap
(wrap()
): Wraps arbitrary text. Keyword arguments on this method such asoffset
andindent
should make it relatively easy to take an arbitrary string and make it wrap to 79 characters appropriately.
Custom templates¶
It is possible to provide your own templates.
To do so, you need a folder with Jinja templates. Each template must have
a .j2
extension (which will be stripped by this software when writing
the final file; see above). Additionally, when you provide your own templates,
the filename substitutions described above still occur.
Building Locally¶
To specify templates, you need to provide a --python_gapic_opt
argument
to protoc
, with a key-value pair that looks like:
–python_gapic_opt=”python-gapic-templates=/path/to/templates”
It is also possible to specify more than one directory for templates (in which case they are searched in order); to do this, provide the argument multiple times:
–python_gapic_opt=”python-gapic-templates=/path/to/templates” –python_gapic_opt=”python-gapic-templates=/other/path”
If you provide your own templates, the default templates are no longer consulted. If you want to add your own templates on top of the default ones provided by this library, use the special DEFAULT string:
–python_gapic_opt=”python-gapic-templates=/path/to/templates” –python_gapic_opt=”python-gapic-templates=DEFAULT”
Building with Docker¶
When building with Docker, you instead provide the --python-gapic-templates
argument after the docker run
command:
$ docker run \
--mount type=bind,source=google/cloud/vision/v1/,destination=/in/google/cloud/vision/v1/,readonly \
--mount type=bind,source=dest/,destination=/out/ \
--mount type=bind,source=/path/to/templates,destination=/templates/,readonly \
--rm \
--user $UID \
gcr.io/gapic-images/gapic-generator-python \
--python-gapic-templates /templates/ \
--python-gapic-templates DEFAULT
As before, to provide more than one location for templates, specify the argument more than once.
Warning
If you are using custom templates with Docker, be sure to also mount
the directory with the templates into the Docker image; otherwise
the generator will not be able to read that directory. When specifying
the --python-gapic-templates
argument, it is the path inside
the Docker image that matters!