<h1 align="center">pepdbagent</h1>
[](https://pep.databio.org/)
[](https://pypi.org/project/pepdbagent)
[](https://pypi.org/project/pepdbagent)
[](https://coverage-badge.samuelcolvin.workers.dev/redirect/pepkit/pepdbagent)
[](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 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'])
```
#### Namespace
The `.namespace` module contains search namespace functionality that helps to find namespaces in database
and retrieve information: `number of samples`, `number of projects`.
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')
# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/pepkit/pepdbagent/",
"name": "pepdbagent",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "project, metadata, bioinformatics, database",
"author": "Oleksandr Khoroshevskyi <khorosh@virginia.edu>",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/35/a1/0ebead19573d31dd9b7b953e25796b7ed24fefd585351f78d3efba75f60a/pepdbagent-0.11.1.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">pepdbagent</h1>\n\n[](https://pep.databio.org/)\n\n[](https://pypi.org/project/pepdbagent)\n[](https://pypi.org/project/pepdbagent)\n[](https://coverage-badge.samuelcolvin.workers.dev/redirect/pepkit/pepdbagent)\n[](https://github.com/pepkit/pepdbagent)\n\n\n---\n\n**Documentation**: <a href=\"https://pep.databio.org\" target=\"_blank\">https://pep.databio.org</a>\n\n**Source Code**: <a href=\"https://github.com/pepkit/pepdbagent\" target=\"_blank\">https://github.com/pepkit/pepdbagent</a>\n\n---\n\n`pepdbagent` is a Python library and toolkit that gives a user-friendly \ninterface to connect, upload, update and retrieve information from the pep database. This library is designed to work \nwith PEPhub, but it can be used for any other purpose.\n\n`pepdbagent` creates a connection to the database and creates table schemas for the PEPhub database if necessary.\nCore database is `postgres` database, but it can be easily extended to other relational databases.\nTo use `pepdbagent`, you need to have a database instance running with its credentials.\nIf the version of the database schema is not compatible with the version of `pepdbagent`, it will throw an exception.\n\n## Installation\nTo install `pepdbagent` use this command: \n```\npip install pepdbagent\n```\nor install the latest version from the GitHub repository:\n```\npip install git+https://github.com/pepkit/pepdbagent.git\n```\n\n---\n## Overview:\n\nThe pepdbagent provides a core class called **PEPDatabaseAgent**. This class has 4 modules, divided \nto increase readability, maintainability, and user experience of pepdbagent, which are:\n\n**The `pepdbagent` consists of 6 main modules:**\n- <u>Namespace</u>: Includes methods for searching namespaces, retrieving statistics, and fetching information.\n- <u>Project</u>: Provides functionality for retrieving, uploading, updating, and managing projects.\n- <u>Annotation</u>: Offers features for searching projects in the database and namespaces, retrieving annotations, and other related information.\n- <u>Sample</u>: Handles the creation, modification, and deletion of samples, without modification of the entire project.\n- <u>View</u>: Manages the creation, modification, and deletion of views for specific projects.\n- <u>User</u>: Contains user-related information such as favorites and other user-related data.\n\n## Example:\n\n#### Instiantiate a PEPDatabaseAgent object and connect to database:\n\n```python\nimport pepdbagent\n# 1) By providing credentials and connection information:\nagent = pepdbagent.PEPDatabaseAgent(user=\"postgres\", password=\"docker\", )\n# 2) or By providing connection string:\nagent = pepdbagent.PEPDatabaseAgent(dsn=\"postgresql://postgres:docker@localhost:5432/pep-db\")\n```\n\n#### Example of usage of the pepdbagent modules:\n\n```python\nimport peppy\n\nprj_obj = peppy.Project(\"sample_pep/basic/project_config.yaml\")\n\n# create a project\nnamespace = \"demo\"\nname = \"basic_project\"\ntag = None\nagent.project.create(prj_obj, namespace, name, tag)\n\nupdate_dict = {\"is_private\" = True}\n# after creation of the dict, update record by providing update_dict and namespace, name and tag:\nagent.project.update(update_dict, namespace, name, tag)\n```\n\n\n#### Annotation example:\n\n\nThe `.annotation` module provides an interface to PEP annotations. \nPEP annotations refers to the information *about* the PEPs (or, the PEP metadata). \nRetrieved information contains: [number of samples, submission date, last update date,\nis private, PEP description, digest, namespace, name, tag]\n\n```python\n\n```python\n# Get annotation of one project:\nagent.annotation.get(namespace, name, tag)\n\n# Get annotations of all projects from db:\nagent.annotation.get()\n\n# Get annotations of all projects within a given namespace:\nagent.annotation.get(namespace='namespace')\n\n# Search for a project with partial string matching, either within namespace or entire database\n# This returns a list of projects\nagent.annotation.get(query='query')\nagent.annotation.get(query='query', namespace='namespace')\n\n# Get annotation of multiple projects given a list of registry paths\nagent.annotation.get_by_rp([\"namespace1/project1:tag1\", \"namespace2/project2:tag2\"])\n\n# By default get function will retrun annotations for public projects,\n# To get annotation including private projects admin list should be provided.\n# admin list means list of namespaces where user has admin rights\n# For example:\nagent.annotation.get(query='search_pattern', admin=['databio', 'ncbi'])\n```\n\n\n#### Namespace\nThe `.namespace` module contains search namespace functionality that helps to find namespaces in database \nand retrieve information: `number of samples`, `number of projects`.\n\nExample:\n```python\n# Get info about namespace by providing query argument. Then pepdbagent will\n# search for a specified pattern of namespace in database.\nagent.namespace.get(query='Namespace')\n\n# By default all get functions will return namespace information for public projects,\n# To get information with private projects, admin list should be provided.\n# admin list means list of namespaces where user has admin rights\n# For example:\nagent.namespace.get(query='search_pattern', admin=['databio', 'geo', 'ncbi'])\n```\nFor more information, developers should use `pepdbagent pytest` as documentation due to its natural language syntax and the \nability to write tests that serve as executable examples. \nThis approach not only provides detailed explanations but also ensures that code examples are kept \nup-to-date with the latest changes in the codebase.\n",
"bugtrack_url": null,
"license": "BSD2",
"summary": "A python-based database manager for portable encapsulated projects",
"version": "0.11.1",
"project_urls": {
"Homepage": "https://github.com/pepkit/pepdbagent/"
},
"split_keywords": [
"project",
" metadata",
" bioinformatics",
" database"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8a1dff1985bc1c4f9d760421428531b690e76ffa2d4b1c3c74c4436b69db09f0",
"md5": "2ece45a8eb26fda47abcbb43faade3f1",
"sha256": "c65fe25eb23ffb7f19bcc98f1b10a4b574c8feb03c9bac293098092fb7e8d859"
},
"downloads": -1,
"filename": "pepdbagent-0.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ece45a8eb26fda47abcbb43faade3f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 56549,
"upload_time": "2024-09-18T16:38:42",
"upload_time_iso_8601": "2024-09-18T16:38:42.823967Z",
"url": "https://files.pythonhosted.org/packages/8a/1d/ff1985bc1c4f9d760421428531b690e76ffa2d4b1c3c74c4436b69db09f0/pepdbagent-0.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35a10ebead19573d31dd9b7b953e25796b7ed24fefd585351f78d3efba75f60a",
"md5": "f5f50ae475e44cdd40a3763a9c0fee9c",
"sha256": "01833216857c44412164baa47f9f3b326b9a756861eeda901641c62ca5cc67bd"
},
"downloads": -1,
"filename": "pepdbagent-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "f5f50ae475e44cdd40a3763a9c0fee9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 47693,
"upload_time": "2024-09-18T16:38:44",
"upload_time_iso_8601": "2024-09-18T16:38:44.064112Z",
"url": "https://files.pythonhosted.org/packages/35/a1/0ebead19573d31dd9b7b953e25796b7ed24fefd585351f78d3efba75f60a/pepdbagent-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 16:38:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pepkit",
"github_project": "pepdbagent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pepdbagent"
}
JSON
