Skip to content

routes

HTTP API framework similar to flask.

Attributes

OK = 200 module-attribute

ACCEPTED = 202 module-attribute

INTERNAL_SERVER_ERROR = 500 module-attribute

NO_CONTENT = 204 module-attribute

Classes

Request(path='/', method='GET', data=None, params=None, query_params=None)

Bases: object

Request wrapper object.

Source code in pyrevitlib/pyrevit/routes/server/base.py 
23
24
25
26
27
28
29
30
31
def __init__(
    self, path="/", method="GET", data=None, params=None, query_params=None
):
    self.path = path
    self.method = method
    self.data = data
    self._headers = {}
    self._params = params or []
    self._query_params = query_params or {}

Attributes

path = path instance-attribute
method = method instance-attribute
data = data instance-attribute
headers property

Request headers dict.

params property

Request parameters.

query_params property

Request query string parameters as a dictionary.

callback_url property

Request callback url, if provided in payload.

Methods:

add_header(key, value)

Add new header key:value.

Source code in pyrevitlib/pyrevit/routes/server/base.py 
55
56
57
def add_header(self, key, value):
    """Add new header key:value."""
    self._headers[key] = value

Response(status=200, data=None, headers=None)

Bases: object

Response wrapper object.

Source code in pyrevitlib/pyrevit/routes/server/base.py 
63
64
65
66
def __init__(self, status=200, data=None, headers=None):
    self.status = status
    self.data = data
    self._headers = headers or {}

Attributes

status = status instance-attribute
data = data instance-attribute
headers property

Response headers dict.

Methods:

add_header(key, value)

Add new header key:value.

Source code in pyrevitlib/pyrevit/routes/server/base.py 
73
74
75
def add_header(self, key, value):
    """Add new header key:value."""
    self._headers[key] = value

API(name)

Bases: object

API root object.

Parameters:

Name Type Description Default
name str

URL-safe unique root name of the API

 required

Examples:

from pyrevit import routes
api = routes.API("pyrevit-core")
@api.route('/sessions/', methods=['POST'])
def reload_pyrevit(uiapp):
    new_session_id = sessionmgr.reload_pyrevit()
    return {"session_id": new_session_id}
Source code in pyrevitlib/pyrevit/routes/__init__.py 
27
28
def __init__(self, name):
    self.name = name

Attributes

name = name instance-attribute

Methods:

route(pattern, methods=['GET'])

Define a new route on this API.

Source code in pyrevitlib/pyrevit/routes/__init__.py 
30
31
32
33
34
35
36
37
38
39
40
def route(self, pattern, methods=["GET"]):
    """Define a new route on this API."""

    def __func_wrapper__(f):
        for method in methods:
            add_route(
                api_name=self.name, pattern=pattern, method=method, handler_func=f
            )
        return f

    return __func_wrapper__

Functions:

init()

Initialize routes. Reset all registered routes and shutdown servers.

Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
42
43
44
45
46
47
def init():
    """Initialize routes. Reset all registered routes and shutdown servers."""
    # clear all routes
    router.reset_routes()
    # stop existing server
    deactivate_server()

activate_server()

Activate routes server for this host instance.

The server module is imported on first activation, so that sessions with the routes server disabled never import the HTTP stack.

Important

That module creates a Revit external event as it is imported, and the host prohibits creating one off its main thread. Activation must run on the main thread.

Activation is idempotent within a session: an already active server serves the routes that are registered now, so handing it back is correct. It is not how a server survives a reload - init() still stops the old one on every session load.

Idempotency is only claimed of a server that is still accepting. A server whose accept loop has exited is torn down and replaced, because handing that one back is the same dead registration that #3473 was reported for, reached from the other end.

Returns:

Type Description
RoutesServer

the active server, or None if it could not be started.
Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def activate_server():
    """Activate routes server for this host instance.

    The server module is imported on first activation, so that sessions with
    the routes server disabled never import the HTTP stack.

    Important:
        That module creates a Revit external event as it is imported, and the
        host prohibits creating one off its main thread. Activation must run
        on the main thread.

        Activation is idempotent within a session: an already active server
        serves the routes that are registered now, so handing it back is
        correct. It is not how a server survives a reload - init() still stops
        the old one on every session load.

        Idempotency is only claimed of a server that is still accepting. A
        server whose accept loop has exited is torn down and replaced, because
        handing that one back is the same dead registration that #3473 was
        reported for, reached from the other end.

    Returns:
        (RoutesServer): the active server, or None if it could not be started.
    """
    routes_server = envvars.get_pyrevit_env_var(envvars.ROUTES_SERVER)
    if routes_server:
        if routes_server.is_running:
            mlogger.debug("Routes server already active | %s", routes_server)
            return routes_server
        mlogger.debug("Routes server registered but not accepting | %s", routes_server)
        deactivate_server()
    try:
        from pyrevit.routes.server import server

        rsinfo = serverinfo.register()
        routes_server = server.RoutesServer(
            host=rsinfo.server_host, port=rsinfo.server_port
        )
        envvars.set_pyrevit_env_var(envvars.ROUTES_SERVER, routes_server)
        mlogger.debug("Routes server activated | %s", routes_server)
        return routes_server
    except Exception as rs_ex:
        mlogger.error("Error starting Routes server | %s", str(rs_ex), exc_info=True)
        try:
            serverinfo.unregister()
        except Exception as unreg_ex:
            mlogger.error(
                "Error unregistering Routes server | %s", str(unreg_ex), exc_info=True
            )
        return None

deactivate_server()

Deactivate the active routes server for this host instance.

Deregisters whether or not the stop succeeded (#3473). A server that is no longer listening but is still in the env var made the next activation hand that dead server back instead of binding the port, so a reload silently lost routes.

Every step is contained, including the one that clears the env var: a failure there must not skip the deregistration, which is the step that keeps the next session from being handed this server.

Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def deactivate_server():
    """Deactivate the active routes server for this host instance.

    Deregisters whether or not the stop succeeded (#3473). A server that is no
    longer listening but is still in the env var made the next activation hand
    that dead server back instead of binding the port, so a reload silently
    lost routes.

    Every step is contained, including the one that clears the env var: a
    failure there must not skip the deregistration, which is the step that keeps
    the next session from being handed this server.
    """
    routes_server = envvars.get_pyrevit_env_var(envvars.ROUTES_SERVER)
    if not routes_server:
        return
    try:
        routes_server.stop()
    except Exception as rs_ex:
        mlogger.error("Error stopping Routes server | %s", str(rs_ex), exc_info=True)
    finally:
        try:
            envvars.set_pyrevit_env_var(envvars.ROUTES_SERVER, None)
        except Exception as env_ex:
            mlogger.error(
                "Error clearing Routes server env var | %s", str(env_ex), exc_info=True
            )
        try:
            serverinfo.unregister()
        except Exception as unreg_ex:
            mlogger.error(
                "Error unregistering Routes server | %s", str(unreg_ex), exc_info=True
            )
    mlogger.debug("Routes server deactivated | %s", routes_server)

get_active_server()

Get active routes server for this host instance.

Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
137
138
139
def get_active_server():
    """Get active routes server for this host instance."""
    return envvars.get_pyrevit_env_var(envvars.ROUTES_SERVER)

make_response(data, status=OK, headers=None)

Create Reponse object with.

Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
142
143
144
145
146
147
def make_response(data, status=OK, headers=None):
    """Create Reponse object with."""
    res = Response(status=status, data=data)
    for key, value in (headers or {}).items():
        res.add_header(key, value)
    return res

get_routes(api_name)

Get all registered routes for given API name.

Parameters:

Name Type Description Default
api_name str

unique name of the api

 required
Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
150
151
152
153
154
155
156
def get_routes(api_name):
    """Get all registered routes for given API name.

    Args:
        api_name (str): unique name of the api
    """
    return router.get_routes(api_name)

add_route(api_name, pattern, method, handler_func)

Add new route for given API name.

Parameters:

Name Type Description Default
api_name str

unique name of the api

 required
pattern str

route pattern

 required
method str

method name

 required
handler_func function

route handler function

 required
Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
159
160
161
162
163
164
165
166
167
168
def add_route(api_name, pattern, method, handler_func):
    """Add new route for given API name.

    Args:
        api_name (str): unique name of the api
        pattern (str): route pattern
        method (str): method name
        handler_func (function): route handler function
    """
    return router.add_route(api_name, pattern, method, handler_func)

remove_route(api_name, pattern, method)

Remove previously registered route for given API name.

Parameters:

Name Type Description Default
api_name str

unique name of the api

 required
pattern str

route pattern

 required
method str

method name

 required
Source code in pyrevitlib/pyrevit/routes/server/__init__.py 
171
172
173
174
175
176
177
178
179
def remove_route(api_name, pattern, method):
    """Remove previously registered route for given API name.

    Args:
        api_name (str): unique name of the api
        pattern (str): route pattern
        method (str): method name
    """
    return router.remove_route(api_name, pattern, method)

active_routes_api()

Activates routes API.

Source code in pyrevitlib/pyrevit/routes/__init__.py 
43
44
45
def active_routes_api():
    """Activates routes API."""
    from pyrevit.routes import api