diff --git a/.gitignore b/.gitignore index 5a6c4a1..9189faa 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ *.env !.sample.env -*.pyc \ No newline at end of file +*.pyc +/dist/ +/dist/** +/innoldb/innoldb.egg-info/* \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..16a1958 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +include version.txt \ No newline at end of file diff --git a/README.md b/README.md index d92ef76..2f2c26e 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ my_document.property_two = 'property 2' my_document.save() ``` -If you do not have the **LEDGER** environment variable set, you must pass in the ledger name along with the table name through named arguments, +Then a document will be inserted into the **QLDB** ledger table. If you do not have the **LEDGER** environment variable set, you must pass in the ledger name along with the table name through named arguments, ```python from innoldb.qldb import Document diff --git a/env/.sample.env b/env/.sample.env index 79ccb46..7009ccc 100644 --- a/env/.sample.env +++ b/env/.sample.env @@ -1,3 +1,7 @@ # APPLICATION CONFIGURATION LEDGER=innolab-laboratory -DEFAULT_INDEX=id \ No newline at end of file +DEFAULT_INDEX=id + +# DISTRIBUTION CONFIGURATION +PYPI_USERNAME=__token__ +PYPI_PASSWORD=xxxx \ No newline at end of file diff --git a/innoldb/innolqb.egg-info/PKG-INFO b/innoldb/innolqb.egg-info/PKG-INFO new file mode 100644 index 0000000..f9c9f39 --- /dev/null +++ b/innoldb/innolqb.egg-info/PKG-INFO @@ -0,0 +1,127 @@ +Metadata-Version: 2.1 +Name: innolqb +Version: 1.0.0 +Summary: a ORM model for AWS QLDB +Author: Makpar Innovation Lab +Author-email: gmoore@makpar.com +License: GNU GPL v3 +Project-URL: Documentation, https://github.com/Makpar-Innovation-Laboratory/innolqb +Project-URL: Source, https://github.com/Makpar-Innovation-Laboratory/innolqb +Keywords: aws,qldb,quantum-ledger-database,orm +Platform: any +Requires-Python: >=3.8 +Description-Content-Type: text/markdown +License-File: LICENSE + +# Makpar Innovation Lab +## innolqb + +A simple [Object-Relation-Mapping](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping) for a serverless [AWS Quantum Ledger Database](https://docs.aws.amazon.com/qldb/latest/developerguide/what-is.html) backend. The user or process using this library must have an [IAM policy that allows access to QLDB](https://docs.aws.amazon.com/qldb/latest/developerguide/security-iam.html). + + +```python +from innoldb.qldb import Document + +document = Document('my-table') +document.field = 'my field' +document.save() +``` + +## Setup +### Overview +1. (Optional) Configure environment +2. Create **QLDB** Ledger +3. Configure IAM user/role permissions for ledger +4. Install library + +### Steps + +1. (Optional) Configure Environment + +```shell +export LEDGER='ledger-name' +``` + +The environment variable **LEDGER** should point to the **QLDB** ledger. If you do not configure the **LEDGER** environment variable, you will need to pass in the ledger name to the `Document` object. See [below](#documents) for more information. + +2. Create **QLDB** Ledger + +A **QLDB** CloudFormation template is available in the *cf* directory of this project's [Github](https://github.com/Makpar-Innovation-Laboratory/innolqb). A script has been provided to post this template to **CloudFormation**, assuming your [AWS CLI has been authenticated and configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). Clone the repository and then rrom the project root, execute the following script and specify the `` to create a ledger on the QLDB service, + +```shell +./scripts/cf-stack --ledger +``` + +**NOTE**: The `` must match the value of the **LEDGER** environment variable. The name of the ledger that is stood up on AWS is passed to the library through this environment variable. + +**NOTE**: This script has other optional arguments detailed in the comments of the script itself. + +3. Configure User Permissions + +In production, you will want to limit the permissions of the application client to the ledger and table to which it is authorized to read and write. For the purposes of using this library locally, you can add a blanket policy to your user account by [following the instructions here](https://docs.aws.amazon.com/qldb/latest/developerguide/getting-started.prereqs.html#getting-started.prereqs.permissions). + +If you are configuring an application role to use this library for a particular ledger and table, you will need to scope the permissions using [this reference](https://docs.aws.amazon.com/qldb/latest/developerguide/getting-started-standard-mode.html). + +4. Install `innolqb` + +```shell +pip install innolqb +``` + +## Documents + +This library abstracts much of the QLDB implementation away from its user. All the user has to do is create a `Document`, add fields to it and then call `save()`. Under the hood, the library will translate the `Document` fields into [PartiQL queries](https://partiql.org/docs.html) and use the [pyqldb Driver](https://amazon-qldb-driver-python.readthedocs.io/en/stable/index.html) to post the queries to the **QLDB** instance on AWS. + +### Saving + +If you have the **LEDGER** environment variable set, all that is required is to create a `Document` object and pass it the table name of the **QLDB** ledger. If the following lines are feed into an interactive **Python** shell or copied into a script, + +```python +from innoldb.qldb import Document + +my_document = Document('table-name') +my_document.property_one = 'property 1' +my_document.property_two = 'property 2' +my_document.save() +``` + +If you do not have the **LEDGER** environment variable set, you must pass in the ledger name along with the table name through named arguments, + +```python +from innoldb.qldb import Document + +my_document = Document(name='table-name', ledger='ledger-name') +my_document.property_one = 'property 1' +my_document.property_two = 'property 2' +my_document.save() +``` + +Congratulations! You have saved a document to QLDB! + +### Updating + +Updating and saving are different operations, in terms of the **PartiQL** queries that implement these operations, but from the `Document`'s perspective, they are the same operation; the same method is called in either case. The following script will save a value of `test 1` to `field` and then overwrite it with a value of `test 2`, + +```python +from innoldb.qldb import Document + +my_document = Document('table-name') +my_document.field = 'test 1' +my_document.save() +my_document.field = 'test 2' +my_document.save() +``` + +Behind the scenes, whenever the `save()` method is called, a query is run to check for the existence of the given `Document`. If the `Document` doesn't exist, the library will create a new one. If the `Document` does exist, the library will overwrite the existing `Document`. + +## References +- [AWS QLDB Documentation](https://docs.aws.amazon.com/qldb/latest/developerguide/what-is.html) +- [QLDB Python Driver Documentation](https://amazon-qldb-driver-python.readthedocs.io/en/stable/index.html) +- [PartiQL Documentation](https://partiql.org/docs.html) + +## TODOS + +1. Provision QLDB through Boto3 client instead of using CloudFormation template; i.e., make the provisioning of the Ledger part of the library. + +2. Query class to return iterable of Documents. + diff --git a/innoldb/innolqb.egg-info/SOURCES.txt b/innoldb/innolqb.egg-info/SOURCES.txt new file mode 100644 index 0000000..36d0b07 --- /dev/null +++ b/innoldb/innolqb.egg-info/SOURCES.txt @@ -0,0 +1,11 @@ +LICENSE +MANIFEST.in +README.md +pyproject.toml +setup.cfg +version.txt +innoldb/innolqb.egg-info/PKG-INFO +innoldb/innolqb.egg-info/SOURCES.txt +innoldb/innolqb.egg-info/dependency_links.txt +innoldb/innolqb.egg-info/requires.txt +innoldb/innolqb.egg-info/top_level.txt \ No newline at end of file diff --git a/innoldb/innolqb.egg-info/dependency_links.txt b/innoldb/innolqb.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/innoldb/innolqb.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/innoldb/innolqb.egg-info/requires.txt b/innoldb/innolqb.egg-info/requires.txt new file mode 100644 index 0000000..67364b9 --- /dev/null +++ b/innoldb/innolqb.egg-info/requires.txt @@ -0,0 +1,3 @@ +amazon.ion>=0.9.1 +pyqldb>=3.2.2 +python-dotenv>=0.19.2 diff --git a/innoldb/innolqb.egg-info/top_level.txt b/innoldb/innolqb.egg-info/top_level.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/innoldb/innolqb.egg-info/top_level.txt @@ -0,0 +1 @@ + diff --git a/requirements.txt b/requirements.txt index bd1569d..c9c1ea8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,7 @@ amazon.ion==0.9.1 pyqldb==3.2.2 python-dotenv==0.19.2 -pytest==7.0.0 \ No newline at end of file +pytest==7.0.0 + +build==0.7.0 +twine==3.8.0 \ No newline at end of file diff --git a/scripts/cf-stack b/scripts/cf-stack index b0fc1be..0d821e0 100644 --- a/scripts/cf-stack +++ b/scripts/cf-stack @@ -7,7 +7,7 @@ PROJECT_DIR=$SCRIPT_DIR/.. source $PROJECT_DIR/env/.env # Example Usage: -# >$ qldb-stack> --ledger +# >$ qldb-stack --ledger function log(){ echo -e "\e[92m$(date +"%r")\e[0m: \e[4;32m$SCRIPT_NAME\e[0m : >> $1" diff --git a/scripts/distribute b/scripts/distribute new file mode 100644 index 0000000..6bb67d9 --- /dev/null +++ b/scripts/distribute @@ -0,0 +1,15 @@ + +#!/bin/bash + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" +SCRIPT_NAME="install" +SCRIPT_DES=$'Build and install the \e[3minnoldb\e[om from source.' +PROJECT_DIR=$SCRIPT_DIR/.. +source $PROJECT_DIR/env/.env + +if [ ! -d $PROJECT_DIR/dist ] +then + $SCRIPT_DIR/install +fi + +twine upload -u $PYPI_USERNAME -p $PYPI_PASSWORD $PROJECT_DIR/dist/* \ No newline at end of file diff --git a/scripts/install b/scripts/install new file mode 100644 index 0000000..fef5ff0 --- /dev/null +++ b/scripts/install @@ -0,0 +1,18 @@ +#!/bin/bash + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" +SCRIPT_NAME="install" +SCRIPT_DES=$'Build and install the \e[3minnoldb\e[om from source.' +PROJECT_DIR=$SCRIPT_DIR/.. +source $PROJECT_DIR/env/.env + +if [ -d $PROJECT_DIR/dist ] +then + rm -r $PROJECT_DIR/dist +fi + +python -m build + +VERSION=$(cat $PROJECT_DIR/version.txt) + +pip install $PROJECT_DIR/dist/innolqb-${VERSION}-py3-none-any.whl \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index d98c5cd..bbf02d6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [metadata] -name = scrilla +name = innolqb version = file: version.txt author = Makpar Innovation Lab author_email = gmoore@makpar.com @@ -27,6 +27,7 @@ install_requires = amazon.ion >=0.9.1 pyqldb >=3.2.2 python-dotenv >=0.19.2 +include_package_data = True [options.packages.find] where=innoldb \ No newline at end of file