Installation¶
This version of the library is compatible with Python versions 3.9, 3.10, 3.11, 3.12, and 3.13.
This package depends only on modules from the Python Standard Library,
except for typing_extensions and the extra install options described below.
Pip install¶
You can use pip to install the library from the Python Package Index.
$ pip install eventsourcing
It is recommended to install the library into a Python virtual environment.
$ python3 -m venv my_venv
$ source my_venv/bin/activate
(my_venv) $ pip install eventsourcing
Assuming you are developing a true application (and not a library), when including this library in your list of project dependencies, in order to avoid installing future incompatible releases, it is recommended to specify the major and minor version numbers, use dependency locking, and walk the dependency forward in a controlled way. Please note, it is recommended to test all updates in your CI.
As an example, the expression eventsourcing>=9.4.6,==9.4.* would install the latest version of
the 9.4 series, allowing future bug fixes released with point version increments, whilst avoiding
any changes introduced by major and minor version increments that might break your code. You can use
this expression in a pip install command.
$ pip install "eventsourcing>=9.4.6,==9.4.*"
You can use the same expression in requirements.txt files, in setup.py files, and
in pyproject.toml files.
For example, if you are specifying the dependencies of your project in a pyproject.toml
file, you can specify the dependency on this library in the following way.
[project]
requires-python = ">=3.9.2"
dependencies = [
"eventsourcing>=9.4.6,==9.4.*",
]
Requiring a specific major and minor version number in this way will avoid any potentially destabilising additional features with minor version increments, and also avoid potentially backward incompatible changes introduced with major version number increments.
Upgrading to new versions is encouraged, but it is recommended to do this carefully so that you can be sure your project isn’t inadvertently broken by changes in the library.
Please note, if you are developing a library that depends on this library, then it is generally recommended not to have upper limit caps on the versions of your dependencies, and to leave the responsibility for ensuring application integrity to application developers.
Install options¶
Running the install command with different options will install the extra dependencies associated with that option. If you installed without any options, you can easily install optional dependencies later by running the install command again with the options you want.
If you want to store events with PostgreSQL, then install with
the postgres option. This installs Psycopg v3
and its connection pool package.
The C optimization is recommended by the Psycopg developers for production usage.
The pre-built binary option psycopg[binary] is a convenient alternative for development and testing, and
for those unable to meet the prerequisites needed for building psycopg[c].
This package now follows the recommendation that libraries should depend only on the pure Python package, giving
users the choice of either compiling the C optimization or using the pre-built binary or using the pure
Python package. If you don’t install either psycopg[c] or psycopg[binary] then you need to make sure
libpq is installed (libpq is the client library used by psql, the PostgreSQL command line client). See
the Psycopg docs for more
information.
See the PostgreSQL persistence module documentation for more information about storing events in PostgreSQL.
$ pip install "eventsourcing[postgres]"
If you want to store cryptographically encrypted events,
then install with the cryptography option. This simply installs
the Python cryptography package.
Please note, you will need to configure your application
environment to enable encryption.
$ pip install "eventsourcing[cryptography]"
Alternatively, if you want to store cryptographically encrypted events,
then you can install with the crypto option. This simply installs
PyCryptodome.
Please note, you will need to configure your application
environment to enable encryption.
$ pip install "eventsourcing[crypto]"
Options can be combined, so that if you want to store encrypted events in PostgreSQL,
then install with both the postgres and the cryptography options.
$ pip install "eventsourcing[postgres,cryptography]"
Project template¶
To start a new project with modern tooling, you can use the template for Python eventsourcing projects.
The project template uses Cookiecutter to generate project files. It uses the build tool Poetry to create Python virtual environments for your project, to manage project dependencies, and to create distributions. It uses popular development dependencies such as pytest, coverage, Black, isort, and mypy to help you develop and maintain your code. It has a GitHub Actions workflow, and has an initial README and LICENCE files that you can adjust.
The project template also includes the “dog school” example. The tests should pass. You can adjust the tests, rename the classes, and change the methods. Or just delete the included example code for a fresh start.
Developers¶
If you want to install the code for the purpose of developing the library, then fork and clone the GitHub repository.
Once you have cloned the project’s GitHub repository, change into the root folder, or open the project in an IDE. You should see a Makefile.
If you don’t already have the required version of Poetry installed, running
make install-poetry will install it with pipx, using a suffix to indicate
the version e.g. poetry@2.1.2.
$ make install-poetry
Run make install to create a new virtual environment and install packages that
are needed for development, such as sphinx, coverage, black, ruff, isort, mypy,
and pyright.
$ make install
Once installed, check the project’s test suite passes by running make test.
$ make test
Before the tests will pass, you will need to set up PostgreSQL, with a database called ‘eventsourcing’ that can be accessed by a user called ‘eventsourcing’ that has password ‘eventsourcing’.
The following commands will install PostgreSQL on MacOS and set up the database and database user. If you already have PostgreSQL installed, just create the database and user. You may prefer to run PostgreSQL in a Docker container.
$ brew install postgresql
$ brew services start postgresql
$ psql postgres
postgres=# CREATE DATABASE eventsourcing;
postgres=# CREATE USER eventsourcing WITH PASSWORD 'eventsourcing';
postgres=# ALTER DATABASE eventsourcing OWNER TO eventsourcing;
$ psql eventsourcing
postgres=# CREATE SCHEMA myschema AUTHORIZATION eventsourcing;
The code can be automatically reformatted using the following command (which uses isort and Black). Ruff and mypy errors will often need to be fixed by hand.
$ make fmt
Check the syntax and static types are correct by running make lint.
$ make lint
You can build the docs (and check they build) with make docs.
$ make docs
You can update the locked package dependencies and install them with make update.
$ make update
You can make sure everything is okay by running make install docs fmt lint test benchmark.
$ make install docs lint test benchmark
Or more simply, run make all:
$ make all
Or more simply make:
$ make