Pyjo.URL.Template - URI Templates

from Pyjo.URL.Template import Template

template = Template('https://api.github.com/repos/{owner}/{repo}/issues{?state,labels}')
print(template.expand(owner='pyjoyment', repo='Pyjoyment', state='open'))
print(template.match('https://api.github.com/repos/pyjoyment/Pyjoyment/issues?state=open'))

# Or import the module, as in Google Python Style Guide

import Pyjo.URL.Template

template = Pyjo.URL.Template.new('file:///project/{+path}')
print(template.expand({'path': 'src/main.py'}))
print(template.match('file:///project/src/main.py')['path'])

Pyjo.URL.Template is an implementation of the URI Templates of RFC 6570, of all its levels: a template is a URI with expressions in braces, which expand() replaces with the values of their variables, encoded as the operator of each expression says.

# "/search?q=Hello%20World%21&lang=en"
Pyjo.URL.Template.new('/search{?q,lang}').expand(q='Hello World!', lang='en')

match() is the opposite, which the RFC leaves to its implementations: the values of the variables of a URI that the template expands to, as a server that routes a URI by its template needs them. The URI is matched from both of its ends, in a time linear in its length, so a URI of a client cannot make it slow. One expression takes what the others leave: the one of the reserved expansion {+var}, of a fragment {#var} or with the explode modifier {var*}, of which a template has at most one, or else the last expression of the template. Every other expression ends at the first character of what follows it in the template, as {name} ends at the / of {name}/raw.

# {'owner': 'pyjoyment', 'path': 'src/main.py'}
Pyjo.URL.Template.new('repo://{owner}/blob/{+path}').match('repo://pyjoyment/blob/src/main.py')

A template is for the URIs that a protocol gives as templates, as the resource templates of the Model Context Protocol. A request of an application is dispatched by its routes, whose patterns of Pyjoyment.Routes.Pattern have placeholders with types, defaults and formats, which a template does not have.

See also

Pyjo.URL, Pyjoyment.Routes.Pattern, https://mojolicious.org.

It has no counterpart in Mojolicious, and is written from RFC 6570.

Classes

class Pyjo.URL.Template.Pyjo_URL_Template(template: str = '')[source]

Pyjo.URL.Template inherits all methods from Pyjo.Base and implements the following new ones.

__init__(template: str = '') → None[source]
template = Pyjo.URL.Template.new('/search{?q,lang}')

Construct a new Pyjo.URL.Template object from a template, or raise a Pyjo.Exception for one that is not valid.

__str__() → str[source]
string = str(tpl)

The template.

expand(variables: Mapping[str, Any] | None = None, /, **kwargs: Any) → Pyjo_String_Unicode[source]
url = tpl.expand(q='Hello World!')
url = tpl.expand({'q': 'Hello World!', 'lang': 'en'})

Expand the template with the values of its variables, as a dict or as keyword arguments, and return the URI as a Pyjo.String.Unicode object, with the encoding that the RFC gives it, which Pyjo.URL would normalize. A value is a string, a number, a list or a tuple of them, or a dict of them, and None, an empty list and an empty dict are undefined, which their expressions leave out. A prefix modifier of a list or a dict raises a Pyjo.Exception.

# "/repos/pyjoyment/Pyjoyment/issues?labels=bug,docs"
template = Pyjo.URL.Template.new('/repos/{owner}/{repo}/issues{?labels}')
template.expand(owner='pyjoyment', repo='Pyjoyment', labels=['bug', 'docs'])
match(uri: Anything) → dict[str, Any] | None[source]
variables = tpl.match('/search?q=Hello%20World%21')

Match a URI, a string or a Pyjo.URL object, with the template, and return the values of the variables that it has, decoded, or None for a URI that does not match. The value of a variable with the explode modifier is a list, or a dict for the pairs of a named one, and a list without it is a string with the commas, as the template cannot tell it from a string. A template whose expressions cannot be told apart, two of them that take what the others leave, or two that follow each other without a literal or the first character of an operator between them, raises a Pyjo.Exception.

# {'q': 'Hello World!'}
Pyjo.URL.Template.new('/search{?q,lang}').match('/search?q=Hello%20World%21')

# {'path': ['src', 'main.py']}
Pyjo.URL.Template.new('file:///project{/path*}').match('file:///project/src/main.py')
template
template = tpl.template

The template, as a string.

property variables: list[str][source]
names = tpl.variables

The names of the variables of the template, in the order of the template, each once.

# ['owner', 'repo', 'state']
Pyjo.URL.Template.new('/repos/{owner}/{repo}/issues{?state}').variables