Skip to main content

Python-based package implementing an OGM framework for arango; built on top of python-arango.

Project description

Python Arango OGM

Python-based package implementing an OGM (Object Graph Model) framework for arango; built on top of python-arango. This is somewhat a work-in-progress as I integrate it back into the project from which it was extracted. N.B. This is extracted from a project that uses Arango heavily. Obviously, with a graph database, you don't want to be tied too closely to an ORM due to the impedance mismatch between models and graph nodes and edges. Still to do is to marshall query results into models when necessary for that good old model experience. That will be done in the coming week(s).

GitHub

https://github.com/tangledpath/python-arango-ogm

Documentation

https://tangledpath.github.io/python-arango-ogm/python_arango_ogm.html

Installation

pip install python-arango-ogm

Getting started

Create a .env file at the root of your repository with the following keys; values to be adjusted for your application:

Environment file (or production configuration/secrets):

These environment variables should be defined

PAO_APP_DB_NAME=your_app                    # The Arango database name for your app
PAO_APP_DB_USER=your_app                    # The Arango database username for your app
PAO_APP_DB_PASS=<ARANGO_YOUR_APP_PASSWORD>  # The Arango database password for your app
PAO_APP_PACKAGE=your_app.gdb                # The package within your app where models and migrations are built
PAO_DB_HOST=localhost                       # The DB host
PAO_DB_PORT=8529                            # The DB port
PAO_DB_ROOT_USER=root                       # The root DB username
PAO_DB_ROOT_PASS=<ARANGO_ROOT_PASSWORD>     # The root DB password
PAO_GRAPH_NAME=your_app_graph               # Name of the graph to generate from your vertices and edges
  • Models should be in the module PAO_APP_PACKAGE.models, e.g., your_app/gdb/models.py
  • Migrations will be generated in the package PAO_APP_PACKAGE.migrations, e.g., your_app/gdb/migrations/

Initializing the database:

Create an __init__.py file in your application's source tree to initialize the database; causing it to inject itself into the models. PAODatabase is a based on a singleton metaclass: Modify as necessary:

# Filename = your-app/your_app/gdb
import os
from dotenv import load_dotenv
from python_arango_ogm.db.pao_database import PAODatabase

# This assumes a development environment, you can add other environments; e.g., test.
# Production environments will most likely not use dotenv files:
if os.getenv('YOUR_APP_ENV', 'development') == 'development':
    load_dotenv('.env') # Or '.env.dev', '.env.test', etc....

PAODatabase()

In this setup, there should be a models.py in the your_app.gdb package. For example:

from python_arango_ogm.db import pao_fields
from python_arango_ogm.db.pao_edges import PAOEdgeDef
from python_arango_ogm.db.pao_model import PAOModel


class FooModel(PAOModel):
    field_int = pao_fields.IntField(index_name='field_int_idx')
    field_str = pao_fields.StrField(unique=True, index_name='field_str_idx')
    bar_edge = PAOEdgeDef("FooModel", "BarModel")


class BarModel(PAOModel):
    field_int = pao_fields.IntField(index_name='field_int_idx', required=True)
    field_str = pao_fields.StrField(unique=True, index_name='field_str_idx')


class BazModel(PAOModel):
    field_int = pao_fields.IntField(index_name='field_int_idx', unique=True, required=True)
    field_str = pao_fields.StrField(index_name='field_str_idx')
    foo_edge = PAOEdgeDef("BazModel", FooModel)

Usage:

pao-migrate CLI

  • Make uncreated migrations for models: pao-migrate make-migrations
  • Migrate the database: pao-migrate migrate
  • Remove and Migrate the database: pao-migrate migrate --clean
  • List migrations: pao-migrate list-migrations
  • Rollback last migration: pao-migrate migrate-rollback
  • Create a blank migration: pao-migrate new-migration <MIGRATION_NAME>
  • To see help pao-migrate --help
  • To see help for a specific command, for example: pao-migrate migrate --help
  • All of the above commands accept an optional "--env-file" argument; useful in development and testing. For production, you will likely not use a dotenv file, and should rely instead on environment variable set in your production environment.

In code

You may use your models to perform various queries and commands TODO: document this more

Development

Linting

   ruff check . # Find linting errors
   ruff check . --fix # Auto-fix linting errors (where possible)

Documentation

# Shows in browser
poetry run pdoc python_arango_ogm
# Generates to ./docs
poetry run pdoc python_arango_ogm -o ./docs

Testing

  clear; pytest

Building and Publishing

Building

poetry build

Publishing

Note: --build flag build before publishing poetry publish --build -u __token__ -p $PYPI_TOKEN

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_arango_ogm-0.2.4.tar.gz (27.6 kB view details)

Uploaded Source

Built Distribution

python_arango_ogm-0.2.4-py3-none-any.whl (36.2 kB view details)

Uploaded Python 3

File details

Details for the file python_arango_ogm-0.2.4.tar.gz.

File metadata

  • Download URL: python_arango_ogm-0.2.4.tar.gz
  • Upload date:
  • Size: 27.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.1 CPython/3.12.2 Darwin/22.6.0

File hashes

Hashes for python_arango_ogm-0.2.4.tar.gz
Algorithm Hash digest
SHA256 4e129520a85314775b241732ae1804de082701ed85a26e15ac1f0b222db14139
MD5 56cbe2c0cac7168712cba226e73ce3ca
BLAKE2b-256 b2492deadfa24161d4ffd3d1d48d22d9ea753f3b0eb825ae59e96dfdda793edf

See more details on using hashes here.

File details

Details for the file python_arango_ogm-0.2.4-py3-none-any.whl.

File metadata

File hashes

Hashes for python_arango_ogm-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 759fca848cebc7cea191352a5455f8db0b78679b4458687c3e5c15ec9854f5e8
MD5 ef5ed73c66b292788997579ca5b8e19f
BLAKE2b-256 9fbf6aa5834315855e1ebd8fd1c21799a315d74dad6364c743e35a5fea05f304

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page