# emon_tools

[](https://pypi.org/project/emon_tools/)
[](https://codecov.io/gh/vemonitor/emon_tools)
[](https://pepy.tech/project/emon_tools)
`emon-tools` is a Python library that provides a streamlined API interface for seamless interactions with [EmonCMS](https://emoncms.org/), along with tools designed to analyze and visualize PhpFina files.
Explore the project Wiki for detailed documentation and guides: [emon_tools Wiki](https://github.com/vemonitor/emon_tools/wiki).
## Table of Contents
1. [Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)
- [Best Practices for Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)
- [Global Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#global-installation)
- [Module-Specific Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)
2. [Modules](https://github.com/vemonitor/emon_tools/blob/main/README.md#modules)
- [emon_fina](https://github.com/vemonitor/emon_tools/blob/main/README.md#emon_fina)
- [emon_api](https://github.com/vemonitor/emon_tools/blob/main/README.md#emon_api)
3. [Running Tests](https://github.com/vemonitor/emon_tools/blob/main/README.md#running-tests)
4. [Contributing](https://github.com/vemonitor/emon_tools/blob/main/README.md#contributing)
5. [License](https://github.com/vemonitor/emon_tools/blob/main/README.md#license)
## Installation
The `emon-tools` package offers flexible installation options tailored to various use cases. Depending on your requirements, you can choose to install the complete package or specific subsets of dependencies.
### Best Practices for Installation
1. **Environment Management**: Always use a virtual environment (e.g., `venv` or `conda`) to isolate your dependencies and prevent conflicts with other projects.
2. **Upgrading Dependencies**: Keep your dependencies up to date by running `pip install --upgrade emon-tools` periodically.
3. **Check Requirements**: Review the module's requirements in the `setup.cfg` file or on the PyPI page to ensure compatibility with your system.
### Global Installation
To install the entire emon-tools package along with all dependencies, run the following command:
```
pip install emon-tools["all"]
```
Included Dependencies:
- aiohttp
- numpy
- pandas
- matplotlib
**Tip**: This is the best option if you plan to use all features, including data manipulation and visualization.
### Module-Specific Installation
You can install specific modules and their dependencies as needed. For example:
- To enable `emon_fina` module:
```
pip install emon-tools["fina"]
```
- To enable pandas time-series output functionality:
```
pip install emon-tools["fina, time_series"]
```
- To include graph plotting capabilities:
```
pip install emon-tools["fina, plot"]
```
- To enable `emon_api` module:
```
pip install emon-tools["api"]
```
- To enable `emon_fina` and `emon_api` modules:
```
pip install emon-tools["api, fina"]
```
## Modules
`emon_tools` is modular, allowing you to install and use individual components as needed.
### 1. emon_fina
The `emon_fina` module facilitates the analysis and processing of time-series data, particularly from PhpFina file formats.
#### Features
- Data Reading: Efficiently read data from PhpFina file formats.
- Time-Series Analysis: Compute daily statistics such as min, max, mean, and more.
- Filtering: Validate and filter data based on custom thresholds.
- Utilities: Timestamp manipulation and interval computation tools.
#### Usage Example
```python
from emon_tools.fina_time_series import FinaDataFrame
from emon_tools.fina_plot import PlotData
fdf = FinaDataFrame(
feed_id=1,
data_dir="/path/to/phpfina/files"
)
# Access metadata of the .meta file:
print("Meta: ", fdf.meta)
# get height days of data points from meta start_time
ts = fdf.get_fina_df_time_series(
start=fdf.meta.start_time,
step=10,
window=8 * 24 * 3600
)
PlotData.plot(data=ts)
```
<img src="https://github.com/vemonitor/emon_tools/blob/main/img/1_data_8_days.png" with="100%">
- **Wiki**: See `emon_fina` module [wiki](https://github.com/vemonitor/emon_tools/wiki/emon_fina) section.
- **Jupiter NoteBook**: See `emon_fina` [NoteBook](https://github.com/vemonitor/emon_tools/blob/main/notebook/emon_fina.ipynb)
### 2. emon_api
The `emon_api` module is Emoncms python api interface, used to easy interract with an EmonCMS instance via its JSON API.
#### Features
- **Streamlined Interface**: A user-friendly Python API for EmonCMS.
- **RESTful Communication**: Perform seamless data exchanges with EmonCMS through JSON APIs.
- **Data Management**: Retrieve and manage feeds, inputs, and other EmonCMS structures with ease.
#### Usage Example
```python
from emon_tools.emon_api import EmonFeedsApi
cli = EmonApi(
url="http://127.0.0.1:8080",
api_key="MyAPIKey123"
)
# Get current inputs and feeds on Emoncms server
inputs = cli.list_inputs()
print("Inputs: ", inputs)
feeds = cli.list_feeds()
print("Feeds: ", feeds)
```
- **Wiki**: See `emon_api` module [wiki](https://github.com/vemonitor/emon_tools/wiki/emon_api) section.
- **Examples**: Explore [api_bulk_structure](https://github.com/vemonitor/emon_tools/blob/main/examples/emon_api.py) for input and feed supervision, as well as posting bulk dummy data.
## Running Tests
To ensure everything is functioning correctly, run the test suite:
```
pytest -v
```
## Contributing
Contributions are welcome! To contribute:
1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with a clear description.
## License
This project is licensed under the MIT License. See [LICENSE](https://github.com/vemonitor/emon_tools/blob/main/LICENSE) for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/vemonitor/emon-tools",
"name": "emon-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "EmonCms, Python, PhpFina, JsonApi",
"author": "Eli Serra",
"author_email": "mano8@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7d/ba/d7e9ef3fcac1b3af69992f8e3e882efe3ae4c5f0237c0680ea31d3a9cdfb/emon_tools-0.2.4.tar.gz",
"platform": null,
"description": "# emon_tools\n\n\n[](https://pypi.org/project/emon_tools/)\n[](https://codecov.io/gh/vemonitor/emon_tools)\n[](https://pepy.tech/project/emon_tools)\n\n`emon-tools` is a Python library that provides a streamlined API interface for seamless interactions with [EmonCMS](https://emoncms.org/), along with tools designed to analyze and visualize PhpFina files.\n\nExplore the project Wiki for detailed documentation and guides: [emon_tools Wiki](https://github.com/vemonitor/emon_tools/wiki).\n\n## Table of Contents\n\n1. [Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)\n\n - [Best Practices for Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)\n\n - [Global Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#global-installation)\n\n - [Module-Specific Installation](https://github.com/vemonitor/emon_tools/blob/main/README.md#installation)\n\n2. [Modules](https://github.com/vemonitor/emon_tools/blob/main/README.md#modules)\n\n - [emon_fina](https://github.com/vemonitor/emon_tools/blob/main/README.md#emon_fina)\n\n - [emon_api](https://github.com/vemonitor/emon_tools/blob/main/README.md#emon_api)\n\n3. [Running Tests](https://github.com/vemonitor/emon_tools/blob/main/README.md#running-tests)\n\n4. [Contributing](https://github.com/vemonitor/emon_tools/blob/main/README.md#contributing)\n\n5. [License](https://github.com/vemonitor/emon_tools/blob/main/README.md#license)\n\n## Installation\n\nThe `emon-tools` package offers flexible installation options tailored to various use cases. Depending on your requirements, you can choose to install the complete package or specific subsets of dependencies.\n\n### Best Practices for Installation\n\n1. **Environment Management**: Always use a virtual environment (e.g., `venv` or `conda`) to isolate your dependencies and prevent conflicts with other projects.\n\n2. **Upgrading Dependencies**: Keep your dependencies up to date by running `pip install --upgrade emon-tools` periodically.\n\n3. **Check Requirements**: Review the module's requirements in the `setup.cfg` file or on the PyPI page to ensure compatibility with your system.\n\n### Global Installation\nTo install the entire emon-tools package along with all dependencies, run the following command:\n\n```\npip install emon-tools[\"all\"]\n```\n\nIncluded Dependencies:\n- aiohttp\n- numpy\n- pandas\n- matplotlib\n\n**Tip**: This is the best option if you plan to use all features, including data manipulation and visualization.\n\n### Module-Specific Installation\n\nYou can install specific modules and their dependencies as needed. For example: \n- To enable `emon_fina` module:\n\n```\npip install emon-tools[\"fina\"]\n```\n\n- To enable pandas time-series output functionality:\n\n```\npip install emon-tools[\"fina, time_series\"]\n```\n\n- To include graph plotting capabilities:\n\n```\npip install emon-tools[\"fina, plot\"]\n```\n\n- To enable `emon_api` module:\n\n```\npip install emon-tools[\"api\"]\n```\n\n- To enable `emon_fina` and `emon_api` modules:\n\n```\npip install emon-tools[\"api, fina\"]\n```\n\n## Modules\n`emon_tools` is modular, allowing you to install and use individual components as needed.\n\n### 1. emon_fina\n\nThe `emon_fina` module facilitates the analysis and processing of time-series data, particularly from PhpFina file formats.\n\n#### Features\n\n- Data Reading: Efficiently read data from PhpFina file formats.\n- Time-Series Analysis: Compute daily statistics such as min, max, mean, and more.\n- Filtering: Validate and filter data based on custom thresholds.\n- Utilities: Timestamp manipulation and interval computation tools.\n\n#### Usage Example\n\n```python\nfrom emon_tools.fina_time_series import FinaDataFrame\nfrom emon_tools.fina_plot import PlotData\n\nfdf = FinaDataFrame(\n feed_id=1,\n data_dir=\"/path/to/phpfina/files\"\n)\n# Access metadata of the .meta file:\nprint(\"Meta: \", fdf.meta)\n\n# get height days of data points from meta start_time\nts = fdf.get_fina_df_time_series(\n start=fdf.meta.start_time,\n step=10,\n window=8 * 24 * 3600\n)\n\nPlotData.plot(data=ts)\n\n```\n\n<img src=\"https://github.com/vemonitor/emon_tools/blob/main/img/1_data_8_days.png\" with=\"100%\">\n\n- **Wiki**: See `emon_fina` module [wiki](https://github.com/vemonitor/emon_tools/wiki/emon_fina) section.\n\n- **Jupiter NoteBook**: See `emon_fina` [NoteBook](https://github.com/vemonitor/emon_tools/blob/main/notebook/emon_fina.ipynb)\n\n### 2. emon_api\n\nThe `emon_api` module is Emoncms python api interface, used to easy interract with an EmonCMS instance via its JSON API.\n\n#### Features\n\n- **Streamlined Interface**: A user-friendly Python API for EmonCMS.\n- **RESTful Communication**: Perform seamless data exchanges with EmonCMS through JSON APIs.\n- **Data Management**: Retrieve and manage feeds, inputs, and other EmonCMS structures with ease.\n\n#### Usage Example\n\n```python\nfrom emon_tools.emon_api import EmonFeedsApi\ncli = EmonApi(\n url=\"http://127.0.0.1:8080\",\n api_key=\"MyAPIKey123\"\n)\n# Get current inputs and feeds on Emoncms server\ninputs = cli.list_inputs()\nprint(\"Inputs: \", inputs)\nfeeds = cli.list_feeds()\nprint(\"Feeds: \", feeds)\n```\n\n- **Wiki**: See `emon_api` module [wiki](https://github.com/vemonitor/emon_tools/wiki/emon_api) section.\n- **Examples**: Explore [api_bulk_structure](https://github.com/vemonitor/emon_tools/blob/main/examples/emon_api.py) for input and feed supervision, as well as posting bulk dummy data.\n\n## Running Tests\n\nTo ensure everything is functioning correctly, run the test suite:\n\n```\npytest -v\n```\n\n## Contributing\n\nContributions are welcome! To contribute:\n1. Fork the repository.\n2. Create a feature branch.\n3. Submit a pull request with a clear description.\n\n## License\nThis project is licensed under the MIT License. See [LICENSE](https://github.com/vemonitor/emon_tools/blob/main/LICENSE) for more details.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python PHPFINA feeds and Api Tools to interact with EmonCms.",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/vemonitor/emon-tools"
},
"split_keywords": [
"emoncms",
" python",
" phpfina",
" jsonapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f21c97cf5bdce0c2457cefcf1fb981bb56e5318b708ca1dae0cb4008464e9f3a",
"md5": "c40bde29ad30d81a428ed4c502bf834b",
"sha256": "7f03e31374ebfcbdaae2600ddc34622798d82b0cc40a9a00edba8ce07f36be34"
},
"downloads": -1,
"filename": "emon_tools-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c40bde29ad30d81a428ed4c502bf834b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 52595,
"upload_time": "2025-01-20T03:58:58",
"upload_time_iso_8601": "2025-01-20T03:58:58.787027Z",
"url": "https://files.pythonhosted.org/packages/f2/1c/97cf5bdce0c2457cefcf1fb981bb56e5318b708ca1dae0cb4008464e9f3a/emon_tools-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7dbad7e9ef3fcac1b3af69992f8e3e882efe3ae4c5f0237c0680ea31d3a9cdfb",
"md5": "29e0275a2bb18651c0b2f0912a9c06d0",
"sha256": "be81e2f9416640c6792a7adb2156182ffa4d993c25fe835dda8764cf5140a107"
},
"downloads": -1,
"filename": "emon_tools-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "29e0275a2bb18651c0b2f0912a9c06d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64736,
"upload_time": "2025-01-20T03:59:00",
"upload_time_iso_8601": "2025-01-20T03:59:00.338097Z",
"url": "https://files.pythonhosted.org/packages/7d/ba/d7e9ef3fcac1b3af69992f8e3e882efe3ae4c5f0237c0680ea31d3a9cdfb/emon_tools-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 03:59:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vemonitor",
"github_project": "emon-tools",
"github_not_found": true,
"lcname": "emon-tools"
}