Merge pull request #126 from pepkit/dev

Release 0.7.3

.github/workflows/cli-coverage.yml

@@ -0,0 +1,52 @@
+name: test coverage
+
+on:
+  push:
+    branches: [master, dev]
+
+jobs:
+  cli-coverage-report:
+    strategy:
+      matrix:
+        python-version: [ "3.11" ]
+        os: [ ubuntu-latest ] # can't use macOS when using service containers or container jobs
+        r: [ release ]
+    runs-on: ${{ matrix.os }}
+    services:
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: docker
+          POSTGRES_DB: pep-db
+          POSTGRES_HOST: localhost
+        ports:
+          - 5432:5432
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v1
+        with:
+          python-version: '3.10'
+
+      - name: Install dev dependancies
+        run: if [ -f requirements/requirements-dev.txt ]; then pip install -r requirements/requirements-dev.txt; fi
+
+      - run: pip install .
+
+      - name: Run tests
+        run: coverage run -m pytest
+
+      - name: build coverage
+        run: coverage html -i
+
+      - run: smokeshow upload htmlcov
+        env:
+          SMOKESHOW_GITHUB_STATUS_DESCRIPTION: CLI Coverage {coverage-percentage}
+          SMOKESHOW_GITHUB_COVERAGE_THRESHOLD: 50
+          SMOKESHOW_GITHUB_CONTEXT: coverage
+          SMOKESHOW_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SMOKESHOW_GITHUB_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          SMOKESHOW_AUTH_KEY: ${{ secrets.SMOKESHOW_AUTH_KEY }}

.github/workflows/pytest.yml

@@ -10,7 +10,7 @@ jobs:
   pytest:
     strategy:
       matrix:
-        python-version: ["3.8", "3.11"]
+        python-version: ["3.8", "3.12"]
         os: [ubuntu-latest] # can't use macOS when using service containers or container jobs
         r: [release]
     runs-on: ${{ matrix.os }}
@@ -33,12 +33,9 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install dev dependancies
+    - name: Install dev dependencies
       run: if [ -f requirements/requirements-dev.txt ]; then pip install -r requirements/requirements-dev.txt; fi
 
-    - name: Install test dependancies
-      run: if [ -f requirements/requirements-test.txt ]; then pip install -r requirements/requirements-test.txt; fi
-
     - name: Install package
       run: python -m pip install .
 

README.md

@@ -1,15 +1,138 @@
-# pepdbagent
+<h1 align="center">pepdbagent</h1>
+
+[![PEP compatible](https://pepkit.github.io/img/PEP-compatible-green.svg)](https://pep.databio.org/)
+![Run pytests](https://github.com/pepkit/pepdbagent/workflows/Run%20pytests/badge.svg)
+[![pypi-badge](https://img.shields.io/pypi/v/pepdbagent?color=%2334D058)](https://pypi.org/project/pepdbagent)
+[![pypi-version](https://img.shields.io/pypi/pyversions/pepdbagent.svg?color=%2334D058)](https://pypi.org/project/pepdbagent)
+[![Downloads](https://static.pepy.tech/badge/pepdbagent)](https://pepy.tech/project/pepdbagent)
+[![Github badge](https://img.shields.io/badge/source-github-354a75?logo=github)](https://github.com/pepkit/pepdbagent)
+
+
+---
+
+**Documentation**: <a href="https://pep.databio.org" target="_blank">https://pep.databio.org</a>
+
+**Source Code**: <a href="https://github.com/pepkit/pepdbagent" target="_blank">https://github.com/pepkit/pepdbagent</a>
+
+---
 
 `pepdbagent` is a Python library and toolkit that gives a user-friendly 
-interface to connect, upload, update and retrieve information from pep-db.
+interface to connect, upload, update and retrieve information from the pep database. This library is designed to work 
+with PEPhub, but it can be used for any other purpose.
+
+`pepdbagent` creates a connection to the database and creates table schemas for the PEPhub database if necessary.
+Core database is `postgres` database, but it can be easily extended to other relational databases.
+To use `pepdbagent`, you need to have a database instance running with its credentials.
+If the version of the database schema is not compatible with the version of `pepdbagent`, it will throw an exception.
+
+## Installation
+To install `pepdbagent` use this command: 
+```
+pip install pepdbagent
+```
+or install the latest version from the GitHub repository:
+```
+pip install git+https://github.com/pepkit/pepdbagent.git
+```
+
+---
+## Overview:
+
+The pepdbagent provides a core class called **PEPDatabaseAgent**. This class has 4 modules, divided 
+to increase readability, maintainability, and user experience of pepdbagent, which are:
+
+**The `pepdbagent` consists of 6 main modules:**
+- <u>Namespace</u>: Includes methods for searching namespaces, retrieving statistics, and fetching information.
+- <u>Project</u>: Provides functionality for retrieving, uploading, updating, and managing projects.
+- <u>Annotation</u>: Offers features for searching projects in the database and namespaces, retrieving annotations, and other related information.
+- <u>Sample</u>: Handles the creation, modification, and deletion of samples, without modification of the entire project.
+- <u>View</u>: Manages the creation, modification, and deletion of views for specific projects.
+- <u>User</u>: Contains user-related information such as favorites and other user-related data.
+
+## Example:
+
+#### Instiantiate a PEPDatabaseAgent object and connect to database:
+
+```python
+import pepdbagent
+# 1) By providing credentials and connection information:
+agent = pepdbagent.PEPDatabaseAgent(user="postgres", password="docker", )
+# 2) or By providing connection string:
+agent = pepdbagent.PEPDatabaseAgent(dsn="postgresql://postgres:docker@localhost:5432/pep-db")
+```
+
+#### Example of usage of the pepdbagent modules:
+
+```python
+import peppy
+
+prj_obj = peppy.Project("sample_pep/basic/project_config.yaml")
+
+# create a project
+namespace = "demo"
+name = "basic_project"
+tag = None
+agent.project.create(prj_obj, namespace, name, tag)
+
+update_dict = {"is_private" = True}
+# after creation of the dict, update record by providing update_dict and namespace, name and tag:
+agent.project.update(update_dict, namespace, name, tag)
+```
+
+
+#### Annotation example:
+
+
+The `.annotation` module provides an interface to PEP annotations. 
+PEP annotations refers to the information *about* the PEPs (or, the PEP metadata). 
+Retrieved information contains: [number of samples, submission date, last update date,
+is private, PEP description, digest, namespace, name, tag]
+
+```python
+
+```python
+# Get annotation of one project:
+agent.annotation.get(namespace, name, tag)
+
+# Get annotations of all projects from db:
+agent.annotation.get()
+
+# Get annotations of all projects within a given namespace:
+agent.annotation.get(namespace='namespace')
+
+# Search for a project with partial string matching, either within namespace or entire database
+# This returns a list of projects
+agent.annotation.get(query='query')
+agent.annotation.get(query='query', namespace='namespace')
+
+# Get annotation of multiple projects given a list of registry paths
+agent.annotation.get_by_rp(["namespace1/project1:tag1", "namespace2/project2:tag2"])
+
+# By default get function will retrun annotations for public projects,
+# To get annotation including private projects admin list should be provided.
+# admin list means list of namespaces where user has admin rights
+# For example:
+agent.annotation.get(query='search_pattern', admin=['databio', 'ncbi'])
+```
 
-**pep-db** is a postgres database created for storing [PEPs](http://pep.databio.org/en/latest/). 
-It is a backend database for PEPhub. 
 
-Before using pepdbagent, you should install or have access to a pep-db instance.
+#### Namespace
+The `.namespace` module contains search namespace functionality that helps to find namespaces in database 
+and retrieve information: `number of samples`, `number of projects`.
 
-To run a pep-db instance, you can use this tutorial:
-- [pep-db installation](./docs/db_tutorial.md)
+Example:
+```python
+# Get info about namespace by providing query argument. Then pepdbagent will
+# search for a specified pattern of namespace in database.
+agent.namespace.get(query='Namespace')
 
-Then, follow the `pepdbagent` tutorial here:
-- [pedbagent](./docs/README.md)
+# By default all get functions will return namespace information for public projects,
+# To get information with private projects, admin list should be provided.
+# admin list means list of namespaces where user has admin rights
+# For example:
+agent.namespace.get(query='search_pattern', admin=['databio', 'geo', 'ncbi'])
+```
+For more information, developers should use `pepdbagent pytest` as documentation due to its natural language syntax and the 
+ability to write tests that serve as executable examples. 
+This approach not only provides detailed explanations but also ensures that code examples are kept 
+up-to-date with the latest changes in the codebase.

docs/changelog.md

@@ -2,6 +2,14 @@
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [0.7.3] -- 2023-02-05
+- Fixed POP update
+- Improved error handling in views API
+- Added stats method to Namespace module
+- Updated docs
+- Added coverage
+
+
 ## [0.7.2] -- 2023-02-02
 - Fixed Unique Constraint in the Views
 - Fixed update project pop method

docs/db_tutorial.md

@@ -1,6 +1,6 @@
-# pep_db
+# Database setup
 
-### pep_db installation: 
+### container installation: 
 
 
 0) Go to [pep_db](../pep_db)  directory and then run the following lines