Skip to main content
Incomplete provenance

2 of 7 release files were uploaded without provenance metadata. View details.

Saengra

Python wrapper for Saengra graph database.

Quickstart: primitives and edges

Saengra is a graph database. It supports hashable Python objects (primitives) as graph vertices. Built-in types like int or str can be used directly; also Saengra provides @primitive decorator to declare dataclass-like types to be used as graph vertices.

Directed edges between primitives are always labelled with a string (edge label). It can be an arbitrary string, but the engine is optimized to support limited number of different labels per graph. There can't be two edges between the same two primitives with the same label.

We can construct a graph directly from primitives and edges by using elementary graph operations:

from datetime import datetime
from saengra import primitive, Environment
from saengra.graph import AddVertex, AddEdge

@primitive
class user:
    id: int

u1 = user(id=1)
u2 = user(id=2)
u1_registered_at = datetime(2022, 1, 1, 12, 0, 0)
u2_registered_at = datetime(2023, 2, 3, 15, 0, 0)

env = Environment()
env.update(
    AddVertex(u1),
    AddVertex(u2),
    AddVertex(u1_registered_at),
    AddVertex(u2_registered_at),
    AddEdge(u1, "follows", u2),
    AddEdge(u1, "registered_at", u1_registered_at),
    AddEdge(u2, "registered_at", u2_registered_at),
)
env.commit()

Quickstart: entities and environment

Operating with vertices and edges is tedious and slow. A higher-level abstraction, entities, is provided to make working with graph more like your normal object-oriented programming.

Let's declare some entity classes and rewrite the code above:

from datetime import datetime
from saengra import primitive, Entity, Environment

@primitive
class user:
    id: int

class User(Entity, user):
    registered_at: datetime
    follows: set["User"]

env = Environment(entity_types=[User])

u1 = User.create(env, id=1, registered_at=datetime(2022, 1, 1, 12, 0, 0))
u2 = User.create(env, id=2, registered_at=datetime(2023, 2, 3, 15, 0, 0))
u1.follows.add(u2)

env.commit()

Quickstart: expressions and observers

Saengra introduces a domain-specific language to describe subgraphs of the graph, i.e. subset of vertices and edges. These expressions are quite similar to queries in SQL.

# Find all subscriptions, i.e. pairs (u1, u2) where u1 follows u2:
env.match("user as u1 -follows> user as u2")
# -> [{"u1": User(id=1), "u2": User(id=2)}]

# Find all mutual subscriptions:
env.match("user as u1 <follows> user as u2")
# -> []

But the most powerful aspect of Saengra is its observation capability. Saengra can match expressions incrementally after processing graph updates, and notify the program about created, changed and deleted subgraphs after each commit.

from saengra import observer

mutual_follow = observer("user as u1 <follows> user as u2")


@mutual_follow.on_create
def notify_mutuals(u1: User, u2: User):
    print(f"{u1} is now mutuals with {u2}!")


env.register_observers([mutual_follow])

u2.follows.add(u1)
env.commit()
# -> User(id=1) is now mutuals with User(id=2)!
# -> User(id=2) is now mutuals with User(id=1)!

Generating Protobuf Code

The messages_pb2.py file is generated from the protobuf definitions in saengra-server/proto/messages.proto.

To regenerate:

protoc --python_out=saengra --proto_path=saengra-server/proto saengra-server/proto/messages.proto

Requirements:

  • protoc (Protocol Buffers compiler) must be installed
  • Python protobuf library: pip install protobuf>=4.21.0

Usage

Option 1: Automatically start server

from saengra.client import SaengraClient

# Client automatically starts saengra-server in background
with SaengraClient() as client:
    # Connect to a graph
    created = client.connect("my_graph")

    # Add vertices and edges
    client.apply_updates([
        # Your updates here
    ])

    # Commit changes
    response = client.commit()

The client expects saengra-server binary to be available in PATH.

Option 2: Connect to existing server

from saengra.client import SaengraClient

# Connect to an existing server socket
with SaengraClient(socket_path="/path/to/server.sock") as client:
    # Connect to a graph
    created = client.connect("my_graph")

    # Work with the graph...

When using an existing socket, the client will not start or stop the server process, and will not clean up the socket file.

Metadata

Release files for saengra 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Incomplete provenance

2 of 7 files were uploaded without provenance metadata.

We recommend further investigation before installing these files. View details.

Source distribution (sdist)

Source distribution for saengra 0.2.1
File Size Uploaded Provenance Actions
saengra-0.2.1.tar.gz 111.5 kB With provenance Details for saengra-0.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for saengra 0.2.1
File Actions
saengra-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for saengra-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
saengra-0.2.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl CPython 3.12 CPython 3.12 Linux glibc 2.27+ ARM64, Linux glibc 2.28+ ARM64 Details for saengra-0.2.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
saengra-0.2.1-cp312-cp312-macosx_15_0_arm64.whl CPython 3.12 CPython 3.12 macOS 15.0+ ARM64 Details for saengra-0.2.1-cp312-cp312-macosx_15_0_arm64.whl
saengra-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for saengra-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
saengra-0.2.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ ARM64, Linux glibc 2.28+ ARM64 Details for saengra-0.2.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
saengra-0.2.1-cp311-cp311-macosx_15_0_arm64.whl CPython 3.11 CPython 3.11 macOS 15.0+ ARM64 Details for saengra-0.2.1-cp311-cp311-macosx_15_0_arm64.whl

Total release size: 24.2 MB

Release files / saengra-0.2.1.tar.gz

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1.tar.gz
Size 111.5 kB
Tags Source
SHA-256 checksum
How to use checksums
269f28efb6d22deb322d44c22eb13d6107e820c196bf6dbb2d963d81637cea70
BLAKE2b-256 checksum
How to use checksums
d84dbb0f154413ee6c59b3af53003a25c70a0eacf143138fa5f58333da7263c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / saengra-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 5.0 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
b80da937b11fd9e2f256dee97f113779cd5a8b9712ea8be385526e4efe557c66
BLAKE2b-256 checksum
How to use checksums
06db7b86f9512aaeb8b8f286b5bfedaf52bc54fdfee63aeb5511d97a9c32cc70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / saengra-0.2.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Size 4.7 MB
Tags CPython 3.12 Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
16bc0acacc6626bdc98617bb5c683e8c61a9378b3a979b5f2f3d818d8a2cac2f
BLAKE2b-256 checksum
How to use checksums
ccfe519359168a00aea8b8bf2797987cc820d8a01e88060ab382c5557b7b48ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / saengra-0.2.1-cp312-cp312-macosx_15_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp312-cp312-macosx_15_0_arm64.whl
Size 2.3 MB
Tags CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
f88319b3ea196d1ac9bafa145fdbd307849e99d2f4a3792b195d8da61bd518b8
BLAKE2b-256 checksum
How to use checksums
ea5cc00a9342ff7183269422a0aeb9ff564e87f28a16326756eec98749bf8b43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Release files / saengra-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 5.0 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
54dc697f33201e0a9801c48890f27528930faa6dbabf68023d70d0c6788fa8ab
BLAKE2b-256 checksum
How to use checksums
0f59a199661a1f8e4b9d73701574c3bfcc1df5de5524f1aa58c721630b5dcc0b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / saengra-0.2.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Size 4.7 MB
Tags CPython 3.11 Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
04a7835137c8e32bd7889cde1374eee2a09c539f7140440d02be05d295bfa316
BLAKE2b-256 checksum
How to use checksums
b6c9636dc993574bb25d19236575fd77d572ab9291e7273003001a6cdc011ed1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / saengra-0.2.1-cp311-cp311-macosx_15_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL saengra-0.2.1-cp311-cp311-macosx_15_0_arm64.whl
Size 2.3 MB
Tags CPython 3.11 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
39694956c698a3095b6583a6ea8bcc194b66e88a95c47c39da120c5c7862dcad
BLAKE2b-256 checksum
How to use checksums
6e881de16e2ebb0c11b9ed6b238ffc21d80775017895a6ca5121d6b1cd9cd1ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Security for saengra 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Incomplete provenance

2 of 7 release files were uploaded without provenance metadata.

Files with provenance 5 / 7
Files without provenance 2 / 7
Select from 7 files

Attestation for saengra-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page