Commit f231400d authored by Grant, Josh's avatar Grant, Josh
Browse files

Merge branch 'feature/up-to-date-docs' into 'develop' 

update the documentation; include documentation dependency in Pipfile

See merge request !47
parents faea14fa 23218caa

Pipfile

+1 −0
Original line number Diff line number Diff line
@@ -16,6 +16,7 @@ pylint = "*" 
tox = "*"

twine = "*"

moto = {extras = ["all"], version = "*"}

pydoc-markdown = "*"



[scripts]

lint = "tox -e lint"

Pipfile.lock

+1048 −877

File changed.

Preview size limit exceeded, changes collapsed.

README.md

+27 −12
Original line number Diff line number Diff line 
# Common Package

# pyGARDEN Package



Code for the Common Python Package to include logging, environment checking, 

and database connections and query. 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.

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`: 



* 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]`



You may then need to source your `uv` environment to use the `pygarden` command line interface, e.g. `source .venv/bin/activate`.



Replace the above extras with the extras of your choice.



### Installation via pip
@@ -34,7 +49,7 @@ Below is a list of environmental variables and what they do: 
- DATABASE_PORT, PG_PORT: an integer representing the port to connect to the database on

- DATABASE_SCHEMA, PG_SCHEMA: a string representing the schema to default to when creating a database connection



These evironmental 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`

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
@@ -44,8 +59,8 @@ additional functionality not provided by the `Database` class. Below is an 
example of how to create a Database class that uses the PostgresMixin:



```python

from common.mixins.postgres import PostgresMixin

from common.database import Database

from pygarden.mixins.postgres import PostgresMixin

from pygarden.database import Database





class PostgresDatabase(Database, PostgresMixin):
@@ -58,13 +73,13 @@ with PostgresDatabase() as db: 


### Creating a CRUD table with crud_table.py

```python

from common.mixins.postgres import PostgresMixin

from common.database import Database

from common.crud_table import CRUDTable

from pygarden.mixins.postgres import PostgresMixin

from pygarden.database import Database

from pygarden.crud_table import CRUDTable



# PLEASE NOTE: the name of class MUST be consistent with the name of the

# table in the database itself.

class users(CRUDTable):

class Users(CRUDTable):

    """Provides CRUD access to the users table"""

    def __init__(self, db):

    """__init__:

dev.Dockerfile

+3 −2
Original line number Diff line number Diff line 
FROM --platform=linux/amd64 python:3.11-slim

ARG GITLAB_TOKEN=3t2LFTptHcudHsKRsgr8

ARG COMMON_VERSION=0.3.1

ARG COMMON_VERSION=0.3.7

ARG COMMON_EXTRAS="postgres"



RUN apt-get -yqq update && apt-get install -yqq postgresql-client



RUN pip install common-package[all]==$COMMON_VERSION --index-url https://__token__:$GITLAB_TOKEN@code.ornl.gov/api/v4/projects/10568/packages/pypi/simple

RUN pip install common-package[$COMMON_EXTRAS]==$COMMON_VERSION --index-url https://__token__:$GITLAB_TOKEN@code.ornl.gov/api/v4/projects/10568/packages/pypi/simple



CMD ["tail", "-f", "/dev/null"]
 
 No newline at end of file

doc.sh

+19 −3
Original line number Diff line number Diff line
@@ -6,15 +6,31 @@ for entry in src/common/* 
do

	if [[ $entry == *$EXT* ]]; then

		base=$(basename $entry $EXT)

		pydoc-markdown -I src -m common.$(basename $entry $EXT) > docs/$(basename $entry $EXT).md

		pydoc-markdown -I src -m pygarden.$(basename $entry $EXT) > docs/$(basename $entry $EXT).md

	fi

done



for entry in src/common/mixins/*

for entry in src/pygarden/mixins/*

do



	if [[ $entry == *$EXT* ]]; then

		base=$(basename $entry $EXT)

		pydoc-markdown -I src -m common.mixins.$(basename $entry $EXT) > docs/mixins.$(basename $entry $EXT).md

		pydoc-markdown -I src -m pygarden.mixins.$(basename $entry $EXT) > docs/mixins.$(basename $entry $EXT).md

	fi

done

for entry in src/pygarden/cli/*

do



	if [[ $entry == *$EXT* ]]; then

		base=$(basename $entry $EXT)

		pydoc-markdown -I src -m pygarden.cli.$(basename $entry $EXT) > docs/cli.$(basename $entry $EXT).md

	fi

done

for entry in src/pygarden/scrapers/*

do



	if [[ $entry == *$EXT* ]]; then

		base=$(basename $entry $EXT)

		pydoc-markdown -I src -m pygarden.scrapers.$(basename $entry $EXT) > docs/scrapers.$(basename $entry $EXT).md

	fi

done