From 8d35715a210920a2f03cce8b9d5dfd28ca3a4da7 Mon Sep 17 00:00:00 2001 From: Bhaskar Bishnoi Date: Wed, 21 May 2025 15:52:58 -0400 Subject: [PATCH] first revision to readme --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c4baa96..debe698 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,18 @@ # pyGARDEN Package -Code for the pyGARDEN (**G**eneral **A**pplication **R**esource **D**evelopment **E**nvironment **N**etwork) Python Package to include easy injectable and rich logging, environment checking, and database -connections and query. By default, only SQLite is available as a mixin, but other mixin types to the `Database` class +Code for the pyGARDEN (**G**eneral **A**pplication **R**esource **D**evelopment **E**nvironment **N**etwork) Python Package to include easy injectable and rich logging, environment checking, and database +connections and query. By default, only SQLite is available as a mixin, but other mixin types to the `Database` class are Postgres (`[postgres]` extra) or Microsoft SQL Server (`[mssql]` extra). See the [extras](#Extras) section for more information on how to install these extras, when to choose them, and how to use them. -Some highlights from `pyGARDEN`: +Some highlights from `pyGARDEN`: -* This package contains an extensible `Database` metaclass with a generic query function that is usable out of the box. -* Everything is configurable with environmental variables -- including email sending, logging, and database connections. +- This package contains an extensible `Database` metaclass with a generic query function that is usable out of the box. +- Everything is configurable with environmental variables -- including email sending, logging, and database connections. ## Installation ### Installation via `uv` + If you have a `uv env`, you can run the following command in the `src/` directory: `uv pip install -e ".[dev,cli,postgres]` @@ -22,16 +23,17 @@ Replace the above extras with the extras of your choice. ### Installation via pip -Run this command to install version 0.3.8 (latest) via pip: +Run this command to install version 0.3.18 (latest) via pip: + +`pip install pygarden==0.3.18` -`python3 -m pip --no-cache-dir install common==0.3.8 --index-url https://code.ornl.gov/api/v4/projects/10568/packages/pypi/simple --trusted-host code.ornl.gov` This will install latest (not recommended): -`python3 -m pip --no-cache-dir install common --index-url https://code.ornl.gov/api/v4/projects/10568/packages/pypi/simple --trusted-host code.ornl.gov` +`python3 -m pip --no-cache-dir install pygarden` ## Usage -A docker image and python package are provided for use as a base image in `docker-compose.yaml`. +A docker image and python package are provided for use as a base image in `docker-compose.yaml`. `common_package/sql/` contains the .sql files `create_tables.sql` and `fill_tables.sql` which serve as examples for how to initialize a postgres Database in your project (See below in the Creating an extensible Database Python Class section for details in how to create the Python Class.) The `volumes` statement in the docker-compose files runs these sql files once the container is created. @@ -40,7 +42,9 @@ A docker image and python package are provided for use as a base image in `docke To initiate a release, increment the value in `COMMON_VERSION` run `./release.sh release`. This will force checkout develop and run the release process to push to the package registry and container registry. ### Configuration via Environment Variables + Below is a list of environmental variables and what they do: + - DATABASE_TIMEOUT, PG_TIMEOUT: an integer representing the seconds to wait before deciding a timeout occurred. - DATABASE_DB, PG_DATABASE: a string representing the database to connect to - DATABASE_USER, PG_USER: a string representing the user to connect to the database as @@ -52,10 +56,11 @@ Below is a list of environmental variables and what they do: These environmental variables have been assigned default values for the Docker container in the file `envfile`, which is called in `docker-compose.yaml` and `docker-compose.test.yaml` ### Creating an extensible Database Python Class + Some `Database` methods such as `query` and `open` rely on [python mixins](https://www.python.org/dev/peps/pep-0487/), which allow abstract classes to interact with different types of databases and provide -additional functionality not provided by the `Database` class. Below is an +additional functionality not provided by the `Database` class. Below is an example of how to create a Database class that uses the PostgresMixin: ```python @@ -72,6 +77,7 @@ with PostgresDatabase() as db: ``` ### Creating a CRUD table with crud_table.py + ```python from pygarden.mixins.postgres import PostgresMixin from pygarden.database import Database @@ -152,4 +158,3 @@ Testing for the `common_package` is contained within `/common_package/test/test. `docker-compose -f docker-compose.test.yaml up -d` and subsequently checking the results in the logs: `docker-compose -f docker-compose.test.yaml logs package` - -- GitLab