Skip to main content
Loss of provenance

A previous release had provenance metadata, but this release does not. 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.3

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

Loss of provenance

These files do not have provenance metadata, despite files in a prior release including this data.

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

Built distributions (wheels)

Table of built distributions (wheels) for saengra 0.2.3
File Actions
saengra-0.2.3-cp314-cp314-macosx_15_0_arm64.whl CPython 3.14 CPython 3.14 macOS 15.0+ ARM64 Details for saengra-0.2.3-cp314-cp314-macosx_15_0_arm64.whl
saengra-0.2.3-cp313-cp313-macosx_15_0_arm64.whl CPython 3.13 CPython 3.13 macOS 15.0+ ARM64 Details for saengra-0.2.3-cp313-cp313-macosx_15_0_arm64.whl
saengra-0.2.3-cp312-cp312-macosx_15_0_arm64.whl CPython 3.12 CPython 3.12 macOS 15.0+ ARM64 Details for saengra-0.2.3-cp312-cp312-macosx_15_0_arm64.whl
saengra-0.2.3-cp311-cp311-macosx_15_0_arm64.whl CPython 3.11 CPython 3.11 macOS 15.0+ ARM64 Details for saengra-0.2.3-cp311-cp311-macosx_15_0_arm64.whl

Total release size: 9.7 MB

Release files / saengra-0.2.3-cp314-cp314-macosx_15_0_arm64.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

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

Download URL saengra-0.2.3-cp314-cp314-macosx_15_0_arm64.whl
Size 2.4 MB
Tags CPython 3.14 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
f6097b32b548d63bac8ac43f54b3028771218fa87faf328bd4ce77f77298e5a5
BLAKE2b-256 checksum
How to use checksums
85ac399d91c2d656cc1973192a5d2c259df2f100ae7ca248b6ce7dd5c4f7074d
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.3-cp313-cp313-macosx_15_0_arm64.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

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

Download URL saengra-0.2.3-cp313-cp313-macosx_15_0_arm64.whl
Size 2.4 MB
Tags CPython 3.13 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
4766a3d3f5780d3cec7faa7423fe80cb2465b38126f3627fa5d59e79607e4aad
BLAKE2b-256 checksum
How to use checksums
a758ce5ff7d7a626202d27aa95d7e886a6519287cbe847b32641c304c115e66c
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.3-cp312-cp312-macosx_15_0_arm64.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

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

Download URL saengra-0.2.3-cp312-cp312-macosx_15_0_arm64.whl
Size 2.4 MB
Tags CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
86d374bc3ca035a3363929c2e1f10165a279c6288111c540f0fc3481f48cadf1
BLAKE2b-256 checksum
How to use checksums
6a31620f5fa5aed387ce93fd62fded14455eef528271a4a237324794c68eda57
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.3-cp311-cp311-macosx_15_0_arm64.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

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

Download URL saengra-0.2.3-cp311-cp311-macosx_15_0_arm64.whl
Size 2.4 MB
Tags CPython 3.11 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
8dbe259fecc6149d7294e494c5481b25009cfcbcdc1a2843539d2d1d84827758
BLAKE2b-256 checksum
How to use checksums
582fbbc6d653ca572178055b2bd56f7e0b0e1ab90a9d9fd26c81cd4fedab3ab0
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.3

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.

Loss of provenance

A previous release of these files had provenance metadata, but this release does not.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Release comparison

  • Removed 0.2.2 13 files Partial provenance
  • Added 0.2.3 4 files Without provenance

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