ITQC/pydase_service_base
24
0
Fork 0
mirror of https://github.com/tiqi-group/pydase_service_base.git synced 2025-04-23 01:30:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Updating Readme.md

Browse Source
This commit is contained in:
Mose Mueller 2023-08-02 10:15:51 +02:00
parent 848e3b2db9
commit 2310186065
1 changed files with 78 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
README.md
View File

@ -1,60 +1,103 @@
# ICON Service Base
ICON Service Base is a git repository that contains code shared among all Icon services in a service-oriented architecture. The repository consists of a backend written in Python and a frontend written in TypeScript.
## Modules
### Database Module
The Database module provides a robust and scalable solution for interacting with our PostgreSQL and InfluxDB databases. Both connections are managed using credentials provided through environment variables.
#### PostgreSQL
The PostgreSQL submodule includes a class for managing PostgreSQL database sessions (`PostgresDatabaseSession`). It provides a Pythonic interface to the SQL language using the `sqlmodel` library, and includes features for managing transactions and handling errors.
#### InfluxDB
The InfluxDB submodule provides a class (`InfluxDBConnection`) to manage connections to an InfluxDB server. This class serves as a context manager to handle these connections, automatically opening and closing the connection when needed. It provides functionalities for writing data points to a bucket and creating new buckets.
ICON Service Base is a shared code repository for Icon services in a service-based architecture. It is written in Python and provides functionality for interacting with PostgreSQL and InfluxDB v2 databases.
## Installation
### Python
Make sure you have Python 3.10 or later installed on your system. The dependencies of this package are handled with [`poetry`](https://python-poetry.org/docs/#installation). You can install the `icon_service_base` like so:
```bash
poetry add git+ssh://git@gitlab.phys.ethz.ch:tiqi-projects/qchub/icon-services/icon_service_base.git
```
### TypeScript frontend
## Configuration
Make sure you have Node.js and npm or yarn installed on your system. You can install `@icon-services/icon_service_base` like so:
The database connections are managed using configurations provided through environment variables or a configuration file.
```bash
npm install git+ssh://git@gitlab.phys.ethz.ch:tiqi-projects/qchub/icon-services/icon_service_base.git
The package expects a `database_config` folder in the root directory of any module installing this package, which should contain the configuration files for the databases. The location of the `database_config` folder can be overridden by passing a different path to the constructor of the database classes.
The `database_config` folder should have the following structure:
```
database_config
├── influxdb_config.yaml
├── postgres_development.yaml
└── postgres_production.yaml
```
Here is an example of the contents of the configuration files:
`influxdb_config.yaml`:
```yaml
url: https://database-url.ch
org: your-org
token: <influxdb-token>
```
`postgres_development.yaml` / `postgres_production.yaml`:
```yaml
database: ...
host: https://database-url.ch
port: 5432
password: ...
user: ...
```
## Usage
### Python
### InfluxDBSession
The Python code can be used as a library in other ICON services. Import the relevant modules and classes from the `icon_service_base` package in your Python code, as needed.
You can use the `InfluxDBSession` class to interact with an InfluxDB server. **Please note that this class only supports InfluxDB v2**.
### TypeScript Frontend
```python
from icon_service_base.database import InfluxDBSession
The frontend code contains the core of the typescript openAPI clients generated by [`openapi-typescript-codegen`](https://github.com/ferdikoomen/openapi-typescript-codegen/tree/master). This needs to be imported in the ICON services like so:
with InfluxDBSession() as influx_client:
# Creating a bucket
influx_client.create_bucket(
bucket_name='my_new_bucket', description='This is a new bucket'
)
```ts
import { OpenAPI } from '@icon-services/icon_service_base'
import { request as __request } from '@icon-services/icon_service_base'
export { ApiError } from '@icon-services/icon_service_base'
export {
CancelablePromise,
CancelError,
} from '@icon-services/icon_service_base'
export type { OpenAPIConfig } from '@icon-services/icon_service_base'
# Writing data to a bucket
record = {
"measurement": "your_measurement", # Replace with your measurement
"tags": {
"example_tag": "tag_value", # Replace with your tag and its value
},
"fields": {
"example_field": 123, # Replace with your field and its value
},
"time": "2023-06-05T00:00:00Z", # Replace with your timestamp
}
influx_client.write_api.write(
bucket='my_new_bucket', record=record
)
```
### PostgresDatabaseSession
The `PostgresDatabaseSession` class can be used to interact with a PostgreSQL database. Here's an example of how to use it:
```python
from icon_service_base.database import PostgresDatabaseSession
from your_module.models import YourModel # replace with your model
from sqlmodel import select
with PostgresDatabaseSession() as session:
row = session.exec(select(YourModel).limit(1)).all()
```
You can also use it to add new data to the table:
```python
with PostgresDatabaseSession() as session:
new_row = YourModel(...) # replace ... with your data
session.add(new_row)
session.commit()
```
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.