Package: eventsourcing-eventstoredb
Event Sourcing in Python with EventStoreDBThis is an extension package for the Pythoneventsourcinglibrary
that provides a persistence module forEventStoreDB.
It uses theesdbclientpackage to communicate with EventStoreDB via its gRPC interface.InstallationUse pip to install thestable distributionfrom the Python Package Index.$ pip install eventsourcing-eventstoredbPlease note, it is recommended to install Python packages into a Python virtual environment.Getting startedDefine aggregates and applications in the usual way. Please note, "streams"
in EventStoreDB are constrained to start from position0, and this package
expects theoriginator_versionof the first event in an aggregate sequence
to be0, so you must setINITIAL_VERSIONon your aggregate classes to0.fromeventsourcing.applicationimportApplicationfromeventsourcing.domainimportAggregate,eventclassTrainingSchool(Application):defregister(self,name):dog=Dog(name)self.save(dog)returndog.iddefadd_trick(self,dog_id,trick):dog=self.repository.get(dog_id)dog.add_trick(trick)self.save(dog)defget_dog(self,dog_id):dog=self.repository.get(dog_id)return{'name':dog.name,'tricks':list(dog.tricks)}classDog(Aggregate):INITIAL_VERSION=0# for EventStoreDB@event('Registered')def__init__(self,name):self.name=nameself.tricks=[]@event('TrickAdded')defadd_trick(self,trick):self.tricks.append(trick)Configure the application to use EventStoreDB by setting the application environment
variablePERSISTENCE_MODULEto'eventsourcing_eventstoredb'. You can do this
in actual environment variables, by passing in anenvargument when constructing
the application object, or by settingenvon the application class.importosos.environ['PERSISTENCE_MODULE']='eventsourcing_eventstoredb'Also set environment variableEVENTSTOREDB_URIand to an EventStoreDB
connection string URI. This value will be used as theuriargument when theESDBClientclass is constructed by this package.os.environ['EVENTSTOREDB_URI']='esdb://localhost:2113?Tls=false'If you are connecting to a "secure" EventStoreDB server, also set
environment variableEVENTSTOREDB_ROOT_CERTIFICATESto an SSL/TLS certificate
suitable for making a secure gRPC connection to the EventStoreDB server(s).
This value will be used as theroot_certificatesargument when theESDBClientclass is constructed by this package.os.environ['EVENTSTOREDB_ROOT_CERTIFICATES']='<PEM encoded SSL/TLS root certificates>'Please refer to theesdbclientdocumentation for details about starting a "secure" or "insecure" EventStoreDB
server, the "esdb" and "esdb+discover" EventStoreDB connection string
URI schemes, and how to obtain a suitable SSL/TLS certificate for use
in the client when connecting to a "secure" EventStoreDB server.Construct the application.school=TrainingSchool()Call application methods from tests and user interfaces.dog_id=school.register('Fido')school.add_trick(dog_id,'roll over')school.add_trick(dog_id,'play dead')dog_details=school.get_dog(dog_id)assertdog_details['name']=='Fido'assertdog_details['tricks']==['roll over','play dead']To see the events have been saved, we can reconstruct the application
and get Fido's details again.school=TrainingSchool()dog_details=school.get_dog(dog_id)assertdog_details['name']=='Fido'assertdog_details['tricks']==['roll over','play dead']For more information, please refer to the Pythoneventsourcinglibrary, the
Pythonesdbclientpackage,
and theEventStoreDBproject.ContributorsInstall PoetryThe first thing is to check you have Poetry installed.$ poetry --versionIf you don't, then pleaseinstall Poetry.It will help to make sure Poetry's bin directory is in yourPATHenvironment variable.But in any case, make sure you know the path to thepoetryexecutable. The Poetry
installer tells you where it has been installed, and how to configure your shell.Please refer to thePoetry docsfor guidance on
using Poetry.Setup for PyCharm usersYou can easily obtain the project files using PyCharm (menu "Git > Clone...").
PyCharm will then usually prompt you to open the project.Open the project in a new window. PyCharm will then usually prompt you to create
a new virtual environment.Create a new Poetry virtual environment for the project. If PyCharm doesn't already
know where yourpoetryexecutable is, then set the path to yourpoetryexecutable
in the "New Poetry Environment" form input field labelled "Poetry executable". In the
"New Poetry Environment" form, you will also have the opportunity to select which
Python executable will be used by the virtual environment.PyCharm will then create a new Poetry virtual environment for your project, using
a particular version of Python, and also install into this virtual environment the
project's package dependencies according to thepyproject.tomlfile, or thepoetry.lockfile if that exists in the project files.You can add different Poetry environments for different Python versions, and switch
between them using the "Python Interpreter" settings of PyCharm. If you want to use
a version of Python that isn't installed, either use your favourite package manager,
or install Python by downloading an installer for recent versions of Python directly
from thePython website.Once project dependencies have been installed, you should be able to run tests
from within PyCharm (right-click on thetestsfolder and select the 'Run' option).Because of a conflict between pytest and PyCharm's debugger and the coverage tool,
you may need to add--no-covas an option to the test runner template. Alternatively,
just use the Python Standard Library'sunittestmodule.You should also be able to open a terminal window in PyCharm, and run the project's
Makefile commands from the command line (see below).Setup from command lineObtain the project files, using Git or suitable alternative.In a terminal application, change your current working directory
to the root folder of the project files. There should be a Makefile
in this folder.Use the Makefile to create a new Poetry virtual environment for the
project and install the project's package dependencies into it,
using the following command.$ make install-packagesIt's also possible to also install the project in 'editable mode'.$ make installPlease note, if you create the virtual environment in this way, and then try to
open the project in PyCharm and configure the project to use this virtual
environment as an "Existing Poetry Environment", PyCharm sometimes has some
issues (don't know why) which might be problematic. If you encounter such
issues, you can resolve these issues by deleting the virtual environment
and creating the Poetry virtual environment using PyCharm (see above).Project Makefile commandsYou can start EventStoreDB using the following command.$ make start-eventstoredbYou can run tests using the following command (needs EventStoreDB to be running).$ make testYou can stop EventStoreDB using the following command.$ make stop-eventstoredbYou can check the formatting of the code using the following command.$ make lintYou can reformat the code using the following command.$ make fmtTests belong in./tests. Code-under-test belongs in./eventsourcing_eventstoredb.Edit package dependencies inpyproject.toml. Update installed packages (and thepoetry.lockfile) using the following command.$ make update-packages