{"id":31730297,"url":"https://github.com/vemonitor/emon_tools","last_synced_at":"2026-03-11T15:33:14.221Z","repository":{"id":269292587,"uuid":"896963197","full_name":"vemonitor/emon_tools","owner":"vemonitor","description":"Python Emoncms Tools and Api IIterface","archived":false,"fork":false,"pushed_at":"2025-05-30T18:09:11.000Z","size":8322,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-20T06:49:06.764Z","etag":null,"topics":["emoncms","phpfina","python"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vemonitor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"eliserra","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2024-12-01T18:22:17.000Z","updated_at":"2025-04-25T23:25:58.000Z","dependencies_parsed_at":"2025-01-13T20:35:14.463Z","dependency_job_id":"0e352658-46b4-4a67-8826-513da62f1ae0","html_url":"https://github.com/vemonitor/emon_tools","commit_stats":null,"previous_names":["vemonitor/emon_tools"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/vemonitor/emon_tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vemonitor%2Femon_tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vemonitor%2Femon_tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vemonitor%2Femon_tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vemonitor%2Femon_tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vemonitor","download_url":"https://codeload.github.com/vemonitor/emon_tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vemonitor%2Femon_tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000982,"owners_count":26082973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emoncms","phpfina","python"],"created_at":"2025-10-09T07:26:40.257Z","updated_at":"2025-10-09T07:26:43.010Z","avatar_url":"https://github.com/vemonitor.png","language":"Jupyter Notebook","funding_links":["https://ko-fi.com/eliserra"],"categories":[],"sub_categories":[],"readme":"# emon_tools\n\n![CI](https://github.com/vemonitor/emon_tools/actions/workflows/python-package.yml/badge.svg?branch=main)\n[![PyPI package](https://img.shields.io/pypi/v/emon_tools.svg)](https://pypi.org/project/emon_tools/)\n[![codecov](https://codecov.io/gh/vemonitor/emon_tools/graph/badge.svg?token=M7VgGzkApi)](https://codecov.io/gh/vemonitor/emon_tools)\n[![Downloads](https://static.pepy.tech/badge/emon_tools)](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. [Optional Full-Stack Visualization App](#optional-full-stack-visualization-app)\n    - [Overview](#overview)\n    - [Local Development Setup](#local-development-setup)\n    - [Docker Compose Deployment](#docker-compose-deployment)\n4. [Running Tests](#running-tests)\n5. [Contributing](#contributing)\n6. [License](#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—and to ensure you get the latest version—run:\n\n```\npip install emon-tools[\"all\"] --upgrade\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\"] --upgrade\n```\n\n- To enable pandas time-series output functionality:\n\n```\npip install emon-tools[\"fina, time_series\"] --upgrade\n```\n\n- To include graph plotting capabilities:\n\n```\npip install emon-tools[\"fina, plot\"] --upgrade\n```\n\n- To enable `emon_api` module:\n\n```\npip install emon-tools[\"api\"] --upgrade\n```\n\n- To enable `emon_fina` and `emon_api` modules:\n\n```\npip install emon-tools[\"api, fina\"] --upgrade\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.emon_fina.fina_plot import PlotData\nfrom emon_tools.emon_fina.fina_models import FinaByTimeParamsModel\n\nfdf = FinaDataFrame(\n    file_name=\"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_df_data(\n    props=FinaByTimeParamsModel(\n        start_time=fr.meta.start_time,\n        time_window=8 * 24 * 3600,\n        time_interval=10\n    )\n)\n\nPlotData.plot(data=ts)\n\n```\n\n\u003cimg src=\"https://github.com/vemonitor/emon_tools/blob/main/img/1_data_8_days.png\" with=\"100%\"\u003e\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.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## 🚀 Full-Stack Visualization App Deployment\n\nThis optional full-stack application offers a graphical interface to visualize data from any EmonCMS instance and explore archived PhpFina file backups. It comprises:\n\n- FastAPI Backend: Exposes the `emon-tools` functionalities via a RESTful API.\n- Vite React Frontend: A modern dashboard built using React, TypeScript, and Tailwind CSS.\n\n### Overview\n\nThe full-stack app enables users to:\n\n- Interactively browse and monitor live data from EmonCMS instances.\n- Visualize historical time-series data from archived PhpFina files.\n- Manage EmonCMS feeds and inputs via an intuitive web interface.\n\n### 🧰 Prerequisites\n\nEnsure the following are installed on your system:\n- Docker\n- Docker Compose\n\n### 📦 Deployment Steps\nThis repository now includes a Docker Compose example that leverages the provided Dockerfiles for both backend and frontend. This approach is ideal for quickly deploying the full-stack app in a containerized environment.\n\n1. Clone the Repository\n\n```bash\ngit clone https://github.com/vemonitor/emon_tools.git\ncd emon_tools\n```\n\n2. Set Up Environment Variables\n\nNavigate to the Docker Compose development directory and create a `.env` file by copying the provided example:\n\n```bash\ncd docker-compose\\dev\ncopy .example_env .env\n```\n\nEdit the .env file to replace placeholder values (changethis) with your actual configuration:\n\n```env\nMYSQL_HOST=your_mysql_host\nMYSQL_PORT=3306\nMYSQL_DB=your_database_name\nMYSQL_USER=your_username\nMYSQL_PASSWORD=your_password\nMYSQL_ROOT_PASSWORD=your_root_password\n```\n\n\u003e Note: The `.env` file is utilized by Docker Compose for variable substitution in the `docker-compose.yml` file. Ensure all required variables are defined to prevent runtime errors. \n\n3. Build containers and start the containers:\n\nFrom the `docker-compose/dev` directory, execute:\n\n```bash\ndocker-compose up --build\n```\n\nThis command builds the Docker images and starts the containers as defined in the `docker-compose.yml` file.\n\n4. Access the Application\n\nOnce the containers are running:\n\n- Frontend: Access the React dashboard at http://localhost:3000\n- Backend: Access the FastAPI backend at http://localhost:8000\n    - Swagger UI: http://localhost:8000/docs\n    - ReDoc: http://localhost:8000/redoc\n\n### 🪟 Accessing from Windows Host (WSL2 Users)\n\nIf you're running Docker within WSL2 and need to access the application from your Windows host:\n\n 1. Determine the IP address of your WSL2 instance:\n\n    ```bash\n    ip addr show eth0 | grep inet\n    ```\n\n    Look for an output similar to:\n\n    ```ccp\n    inet 172.20.39.89/20 brd 172.20.47.255 scope global eth0\n    ```\n\n 2. Use the extracted IP address to access the application from your Windows browser:\n\n - Frontend: http://172.20.39.89:3000​\n\n - Backend: http://172.20.39.89:8000\n\n \u003e Note: WSL2 has a separate network interface, so `localhost` on Windows does not directly map to `localhost` within WSL2. Using the WSL2 IP address bridges this gap. ​\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvemonitor%2Femon_tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvemonitor%2Femon_tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvemonitor%2Femon_tools/lists"}