Skip to content

Commit 86e54c1

Browse files
Stan Janssenstan-janssen
authored andcommitted
Release version 3.0.0 with WSGI implementation
1 parent 8ffd5ef commit 86e54c1

9 files changed

Lines changed: 297 additions & 50 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
Changelog
22
---------
3+
- v3.0.0 (2025-10-18)
4+
- Removed FastAPI dependency and moved to a standard WSGI interface model
35
- v2.4.0 (2026-06-25)
46
- Updated dependencies and removed `.value` of StrEnum which didn't work with newer versions of FastAPI
57
- v2.3.2 (2026-05-26)

‎README.rst‎

Lines changed: 223 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
.. |.running-in-fastapi| replace:: Running in FastAPI
2+
.. _.running-in-fastapi: https://shapeshifter-uftp.readthedocs.io/en/latest/README.html#running-in-fastapi
3+
.. |.running-in-flask| replace:: Running in Flask
4+
.. _.running-in-flask: https://shapeshifter-uftp.readthedocs.io/en/latest/README.html#running-in-flask
5+
6+
17
Shapeshifter library for Python
28
===============================
39

@@ -39,12 +45,225 @@ If you want to develop shapeshifter-uftp, you can fork or clone this repository
3945
$ pytest .
4046
4147
42-
Getting Started
43-
---------------
48+
Running the Shapeshifter Service
49+
================================
50+
51+
The shapeshifter protocol requires you to run a server that can receive HTTP POST requests. You have the following options.
52+
53+
- If you already have a **FastAPI** application and you'd like to run the Shapeshifter service inside that application, see |.running-in-fastapi|_.
54+
55+
- If you already have a **Flask** application and you'd like to run the Shapeshifter service inside that, see |.running-in-flask|_.
56+
57+
- If you don't have an existing application, or you want to run the Shapeshifter interface stand alone (perhaps inside its own Docker container), see Running stand-alone. Since the service is implemented as a standard WSGI service, you can choose several web servers like nginx, apache2 or gunicorn, which all support WSGI interfaces.
58+
59+
60+
.. _running-in-fastapi:
61+
62+
Running in FastAPI
63+
------------------
64+
65+
To run the module in FastAPI, you can use the ``.app`` property on your instance of the Shapeshifter service, like so:
66+
67+
.. code-block:: python3
68+
69+
from a2wsgi import WSGIMiddleware
70+
from fastapi import FastAPI
71+
72+
from shapeshifter_uftp.service import ShapeshifterAgrService
73+
74+
75+
class MyShapeshifterService(ShapeshifterAgrService):
76+
# Your implementation of the service goes here, see next section
77+
...
78+
79+
80+
# Create an instance of the Shapeshifter Service
81+
shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message")
82+
83+
# Your existing FastAPI application
84+
app = FastAPI()
85+
86+
# Mount the Shapeshifte service inside your existing FastAPI application
87+
app.mount("/shapeshifter", shapeshifter_service.app)
88+
89+
...
90+
91+
Note that the full path will be the mount point (``/shapeshifter``) plus the ``path`` defined in the MyShapeshifterService consructor (in this case, ``/api/v3/message``).
92+
93+
94+
.. _running-in-flask:
95+
96+
Running in Flask
97+
----------------
98+
99+
To run the module as part of an existing Flask application, wrap your existing application in a ``DispatcherMiddleware`` like so:
100+
101+
.. code-block:: python3
102+
103+
from flask import Flask, DispatcherMiddleware
104+
105+
from shapeshifter_uftp.service import ShapeshifterAgrService
106+
107+
108+
class MyShapeshifterService(ShapeshifterAgrService):
109+
# Your implementation of the service goes here, see next section
110+
...
111+
112+
my_app = Flask(__name__)
113+
114+
shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message")
115+
116+
app = DispatcherMiddleware(
117+
my_app,
118+
{"/shapeshifter": shapeshifter_service}
119+
)
120+
121+
Note that the full path will be the mount point (``/shapeshifter``) plus the ``path`` defined in the MyShapeshifterService consructor (in this case, ``/api/v3/message``).
122+
123+
124+
Running stand-alone
125+
-------------------
126+
127+
To run the module completely stand-alone, you can use one of these following options.
128+
129+
Standard library wsgiref.simple_server
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131+
132+
This is a build-in function, and you can simply use:
133+
134+
.. code-block:: python3
135+
136+
from shapeshifter_uftp.service import ShapeshifterAgrService
137+
138+
139+
class MyShapeshifterService(ShapeshifterAgrService):
140+
# Your implementation of the service goes here, see next section
141+
...
142+
143+
service = MyShapeshifterService(...)
144+
service.run()
145+
146+
147+
You can customize the host, port and path from their defaults of ``'0.0.0.0'`` and ``8080`` and ``/shapeshifter/api/v3/message``. It is recommended that you leave the ``path`` to the default value, as that is the convention for Shapeshifter servers.
148+
149+
150+
Using apache httpd
151+
~~~~~~~~~~~~~~~~~~
152+
153+
You should use ``mod_wsgi``. For a python module like this, stored in the directory ``/app/main.py`` (as would be conventional in, say , a Docker image):
154+
155+
.. code-block:: python3
156+
157+
from shapeshifter_uftp.service import ShapeshifterAgrService
158+
159+
class MyShapeshifterService(ShapeshifterAgrService):
160+
# Your implementation of the service goes here, see next section
161+
...
162+
163+
service = MyShapeshifterService(..., path="/api/v3/message")
164+
165+
You would point the apache2 webserver to it like so:
166+
167+
.. code-block:: apacheconf
168+
169+
<VirtualHost *:80>
170+
171+
ServerName www.example.com
172+
173+
WSGIPythonHome /app/.venv/bin/python
174+
WSGIScriptAlias /shapeshifter /app/main.py
175+
WSGICallableObject service
176+
177+
<Directory /app>
178+
Require all granted
179+
</Directory>
180+
181+
</VirtualHost>
182+
183+
The directive ``WSGIPythonHome`` sets the location of the python interpreter to use. In this example, a uv-like ``venv`` is assumed.
184+
185+
The directive ``WSGIScriptAlias`` takes two arguments:
186+
187+
- The mount path (``/shapeshifter``)
188+
- The location of the python module containing the wsgi callable (``/app/main.py``)
189+
190+
The directive ``WSGICallableObject`` takes one argument:
191+
192+
- The name of the callable object. In the case of Shapeshifter-UFTP, this is the name you gave to your instance of your service subclass.
193+
194+
You may need to enable ``mod_wsgi`` using ``a2enmod wsgi`` or other methods.
195+
196+
If you are running apache exposed to the internet directly (and not in a Docker image behind some other infrastructure), you should use HTTPS on port 443, using the ``SSLEngine`` directives.
197+
198+
199+
Using gunicorn
200+
~~~~~~~~~~~~~~
201+
202+
A simple Python webserver that uses WSGI:
203+
204+
205+
.. code-block:: python3
206+
207+
# main.py
208+
from shapeshifter_uftp.service import ShapeshifterAgrService
209+
210+
class MyShapeshifterService(ShapeshifterAgrService):
211+
# Your implementation of the service goes here, see next section
212+
...
213+
214+
service = MyShapeshifterService(...)
215+
216+
Then run it like so:
217+
218+
.. code-block:: shell
219+
220+
gunicorn main:service
221+
222+
223+
224+
Implementing your Shapeshifter Service
225+
======================================
44226

45227
Shapehifter always requires the use of a Client and a Service, because all responses are asynchronous.
46228

47-
You choose the server class based on your role in the Shapeshifter conversation. If you are an Aggregator (also known as a CSP), you can use this setup:
229+
You choose the server class based on your role in the Shapeshifter conversation, and subclass the abstract implementation of the appropriate service. You then add implementations for each of the messages that you can receive, in order to post-process them according to you own business logic.
230+
231+
This is an overview of the roles, the base class, and the methods you must implement:
232+
233+
234+
+------+------------------------+----------------------------------------------------------------------------------------------+
235+
| Role | Base class | Methods to implement |
236+
+======+========================+==============================================================================================+
237+
| AGR | ShapeshifterAgrService | * ``process_d_prognosis_response(self, message: DPrognosisResponse)`` |
238+
| | | * ``process_flex_request(self, message: FlexRequest)`` |
239+
| | | * ``process_flex_offer_response(self, message: FlexOfferResponse)`` |
240+
| | | * ``process_flex_offer_revocation_response(self, message: FlexOfferRevocationResponse)`` |
241+
| | | * ``process_flex_order(self, message: FlexOrder)`` |
242+
| | | * ``process_flex_reservation_update(self, message: FlexReservationUpdate)`` |
243+
| | | * ``process_flex_settlement(self, message: FlexSettlement)`` |
244+
| | | * ``process_metering_response(self, message: MeteringResponse)`` |
245+
| | | * ``process_agr_portfolio_query_response(self, message: AgrPortfolioQueryResponse)`` |
246+
| | | * ``process_agr_portfolio_update_response(self, message: AgrPortfolioUpdateResponse)`` |
247+
+------+------------------------+----------------------------------------------------------------------------------------------+
248+
| DSO | ShapeshifterDsoService | * ``process_d_prognosis(self, message: DPrognosis)`` |
249+
| | | * ``process_flex_request_response(self, message: FlexRequestResponse)`` |
250+
| | | * ``process_flex_offer(self, message: FlexOffer)`` |
251+
| | | * ``process_flex_order_response(self, message: FlexOrderResponse)`` |
252+
| | | * ``process_flex_offer_revocation(self, message: FlexOfferRevocation)`` |
253+
| | | * ``process_flex_reservation_update_response(self, message: FlexReservationUpdateResponse)`` |
254+
| | | * ``process_flex_settlement_response(self, message: FlexSettlementResponse)`` |
255+
| | | * ``process_dso_portfolio_query_response(self, message: DsoPortfolioQueryResponse)`` |
256+
| | | * ``process_dso_portfolio_update_response(self, message: DsoPortfolioUpdateResponse)`` |
257+
| | | * ``process_metering(self, message: Metering)`` |
258+
+------+------------------------+----------------------------------------------------------------------------------------------+
259+
| CRO | ShapshifterCroService | * ``process_agr_portfolio_query(self, message: AgrPortfolioQuery)`` |
260+
| | | * ``process_agr_portfolio_update(self, message: AgrPortfolioUpdate)`` |
261+
| | | * ``process_dso_portfolio_query(self, message: DsoPortfolioQuery)`` |
262+
| | | * ``process_dso_portfolio_update(self, message: DsoPortfolioQuery)`` |
263+
+------+------------------------+----------------------------------------------------------------------------------------------+
264+
265+
266+
If you are an Aggregator (also known as a CSP), you can use this setup:
48267

49268
.. code-block:: python3
50269
@@ -231,3 +450,4 @@ To use OAuth in outgoing requests, you can use the provided OAuthClient class. T
231450
232451
233452
Similarly, if you have a Service instance that dynamically needs to retrieve the OAuth information for each different recipient server, you can provide an ``oauth_lookup_function`` that takes a ``(sender_domain, sender_role)`` and returns an instance of OAuthClient.
453+

‎docs/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# You can set these variables from the command line, and also
55
# from the environment for the first two.
66
SPHINXOPTS ?=
7-
SPHINXBUILD ?= sphinx-build
7+
SPHINXBUILD ?= uv run sphinx-build
88
SOURCEDIR = source
99
BUILDDIR = build
1010

‎docs/source/api/types.rst‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,5 @@ Types API Reference
33

44
These objects correspond directly to the UFTP objects that are sent across the wire. You will encounter these in the messages and response when using Shapeshifter UFTP.
55

6-
.. automodule:: shapeshifter_uftp.uftp.common
7-
.. automodule:: shapeshifter_uftp.uftp.agr_cro
8-
.. automodule:: shapeshifter_uftp.uftp.agr_dso
9-
.. automodule:: shapeshifter_uftp.uftp.cro_dso
10-
.. automodule:: shapeshifter_uftp.uftp.metering
6+
.. automodule:: shapeshifter_uftp.uftp.enums
7+
.. automodule:: shapeshifter_uftp.uftp.messages

‎docs/source/conf.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
"sphinx.ext.autosummary",
2929
"sphinx.ext.napoleon",
3030
"sphinx.ext.viewcode",
31+
"sphinx_readme",
3132
]
3233

3334
autosummary_generate = True
@@ -49,3 +50,15 @@
4950

5051
html_theme = "sphinx_rtd_theme"
5152
html_static_path = ["_static"]
53+
54+
html_context = {
55+
'display_github': True,
56+
'github_user': 'shapeshifter',
57+
'github_repo': 'shapeshifter-library-python',
58+
}
59+
60+
html_baseurl = "https://shapeshifter-uftp.readthedocs.io/en/latest"
61+
62+
readme_src_files = "README.rst"
63+
64+
readme_docs_url_type = "code"

‎docs/source/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@
66
Welcome to Shapeshifter UFTP's documentation!
77
=============================================
88

9-
This library allows you to quickly build applications that talk to Distribution System Operators, Aggregators and Common Reference Operators as defined in the UFTP Specification.
9+
This library allows you to quickly build applications that talk to Distribution System Operators (DSO), Aggregators (AGR) and Common Reference Operators (CRO) as defined in the UFTP Specification.
1010

1111
.. toctree::
1212
:maxdepth: 2
1313
:caption: Contents:
1414

15-
readme
15+
README
1616
concepts
1717
examples/index
1818
cli

‎docs/source/readme.rst‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎pyproject.toml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "shapeshifter_uftp"
3-
version = "3.0.0"
3+
version = "3.0.0rc1"
44
description = "Implementation of the Shapeshifter (UFTP) protocol"
55
dependencies = [
66
"a2wsgi<2.0",
@@ -29,7 +29,8 @@ dev = [
2929
"pylint",
3030
"responses",
3131
"sphinx",
32-
"sphinx-rtd-theme"
32+
"sphinx-rtd-theme",
33+
"sphinx-readme>=1.2.1",
3334
]
3435

3536
[build-system]

0 commit comments

Comments
 (0)