Skip to content

Commit 3b15bec

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

8 files changed

Lines changed: 267 additions & 49 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: 222 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,231 @@ If you want to develop shapeshifter-uftp, you can fork or clone this repository
3939
$ pytest .
4040
4141
42-
Getting Started
43-
---------------
42+
Running the Shapeshifter Service
43+
================================
44+
45+
The shapeshifter protocol requires you to run a server that can receive HTTP POST requests. You have the following options.
46+
47+
- If you already have a **FastAPI** application and you'd like to run the Shapeshifter service inside that application, see `Running in FastAPI <#running-in-fastapi>`_.
48+
49+
- If you already have a **Flask** application and you'd like to run the Shapeshifter service inside that, see `Running in Flask <#running-in-flask>`_.
50+
51+
- 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 <#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.
52+
53+
54+
.. _running-in-fastapi:
55+
56+
Running in FastAPI
57+
------------------
58+
59+
To run the module in FastAPI, you can use the ``.app`` property on your instance of the Shapeshifter service, like so:
60+
61+
.. code-block:: python3
62+
63+
from fastapi import FastAPI
64+
from shapeshifter_uftp.service import ShapeshifterAgrService
65+
66+
67+
class MyShapeshifterService(ShapeshifterAgrService):
68+
# Your implementation of the service goes here, see next section
69+
...
70+
71+
72+
# Create an instance of the Shapeshifter Service
73+
shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message")
74+
75+
# Your existing FastAPI application
76+
app = FastAPI()
77+
78+
# Mount the Shapeshifte service inside your existing FastAPI application
79+
app.mount("/shapeshifter", shapeshifter_service.app)
80+
81+
...
82+
83+
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``).
84+
85+
86+
.. _running-in-flask:
87+
88+
Running in Flask
89+
----------------
90+
91+
To run the module as part of an existing Flask application, wrap your existing application in a ``DispatcherMiddleware`` like so:
92+
93+
.. code-block:: python3
94+
95+
from flask import Flask, DispatcherMiddleware
96+
97+
from shapeshifter_uftp.service import ShapeshifterAgrService
98+
99+
100+
class MyShapeshifterService(ShapeshifterAgrService):
101+
# Your implementation of the service goes here, see next section
102+
...
103+
104+
my_app = Flask(__name__)
105+
106+
shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message")
107+
108+
app = DispatcherMiddleware(
109+
my_app,
110+
{"/shapeshifter": shapeshifter_service}
111+
)
112+
113+
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``).
114+
115+
116+
.. _running-stand-alone:
117+
118+
Running stand-alone
119+
-------------------
120+
121+
To run the module completely stand-alone, you can use one of these following options.
122+
123+
Standard library wsgiref.simple_server
124+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125+
126+
This is a build-in function, and you can simply use:
127+
128+
.. code-block:: python3
129+
130+
from shapeshifter_uftp.service import ShapeshifterAgrService
131+
132+
133+
class MyShapeshifterService(ShapeshifterAgrService):
134+
# Your implementation of the service goes here, see next section
135+
...
136+
137+
service = MyShapeshifterService(...)
138+
service.run()
139+
140+
141+
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.
142+
143+
144+
Using apache httpd
145+
~~~~~~~~~~~~~~~~~~
146+
147+
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):
148+
149+
.. code-block:: python3
150+
151+
# /app/main.py
152+
153+
from shapeshifter_uftp.service import ShapeshifterAgrService
154+
155+
class MyShapeshifterService(ShapeshifterAgrService):
156+
# Your implementation of the service goes here, see next section
157+
...
158+
159+
# Create an instance of your Shapeshifter service.
160+
# This instance itself is also a WSGI-compatible callable.
161+
service = MyShapeshifterService(..., path="/api/v3/message")
162+
163+
You would point the apache2 webserver to it like so:
164+
165+
.. code-block:: apacheconf
166+
167+
<VirtualHost *:80>
168+
169+
ServerName www.example.com
170+
171+
WSGIPythonHome /app/.venv/bin/python
172+
WSGIScriptAlias /shapeshifter /app/main.py
173+
WSGICallableObject service
174+
175+
<Directory /app>
176+
Require all granted
177+
</Directory>
178+
179+
</VirtualHost>
180+
181+
The directive ``WSGIPythonHome`` sets the location of the python interpreter to use. In this example, a uv-like ``venv`` is assumed.
182+
183+
The directive ``WSGIScriptAlias`` takes two arguments:
184+
185+
- The mount path (``/shapeshifter``)
186+
- The location of the python module containing the wsgi callable (``/app/main.py``)
187+
188+
The directive ``WSGICallableObject`` takes one argument:
189+
190+
- 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.
191+
192+
You may need to enable ``mod_wsgi`` using ``a2enmod wsgi`` or other methods.
193+
194+
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.
195+
196+
197+
Using gunicorn
198+
~~~~~~~~~~~~~~
199+
200+
A simple Python webserver that uses WSGI:
201+
202+
203+
.. code-block:: python3
204+
205+
# main.py
206+
from shapeshifter_uftp.service import ShapeshifterAgrService
207+
208+
class MyShapeshifterService(ShapeshifterAgrService):
209+
# Your implementation of the service goes here, see next section
210+
...
211+
212+
# Create an instance of your Shapeshifter service.
213+
# This instance itself is also a WSGI-compatible callable.
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

‎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/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
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

‎docs/source/readme.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
.. include:: ../../README.rst
1+
.. include:: ../../README.rst

‎pyproject.toml‎

Lines changed: 2 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,7 @@ dev = [
2929
"pylint",
3030
"responses",
3131
"sphinx",
32-
"sphinx-rtd-theme"
32+
"sphinx-rtd-theme",
3333
]
3434

3535
[build-system]

‎uv.lock‎

Lines changed: 36 additions & 36 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)