GitLocker: The Coding Marketplace

Description:

FreshPointSync 0.2.1

Welcome to FreshPointSync, your go-to asynchronous tool for extracting and
tracking data from my.freshpoint.cz product webpages.
FreshPoint is a Czech service providing vending
machines with healthy snacks, lunches, and desserts for companies.
Unfortunately, the company does not offer any public API for accessing product
data, such as availability and prices. FreshPointSync is here to help.

Key Features
⚡ Asynchronous I/O. FreshPointSync uses asyncio and aiohttp for
efficient web requests, optimal performance, and responsiveness.
🥄 Robust HTML Scraping. FreshPointSync utilizes beautifulsoup4 for
comprehensive product information extraction from the webpage HTML content.
📊 Advanced Data Modeling and Analysis. FreshPointSync employs pydantic
for modeling, analyzing, and serializing extracted data.
🔔 Event-Driven Handlers. FreshPointSync implements the observer pattern
to register handlers for specific events, such as product availability changes.
🔍 Detailed Logging and Error Handling. FreshPointSync ensures reliability
and ease of debugging with logging and safe runners to handle unexpected
exceptions.
🛠️ Clean and Readable Code. FreshPointSync adheres to PEP 8 standards and
utilizes type hints, ensuring the code is clear, concise, and easy to work
with.
📜 Comprehensive Documentation. FreshPointSync offers extensive in-code
documentation as well as an official user guide and tutorials hosted on the
Read the Docs platform.

Installation
FreshPointSync supports Python 3.8 and higher. Official library releases can be
found on 📦 PyPI. To install
the latest stable version of FreshPointSync, use the following CLI command:
$ pip install freshpointsync
To install the latest development version directly from the project’s
📁 GitHub repository, use
the following CLI command:
$ pip install git+https://github.com/mykhakos/FreshPointSync
You can also install optional development dependencies using the following CLI
commands:

For building documentation:

$ pip install freshpointsync[docs]

For running tests:

$ pip install freshpointsync[tests]

For linting the code:

$ pip install freshpointsync[lint]

For building the package:

$ pip install freshpointsync[build]

For all development dependencies (combines all the above options):

$ pip install freshpointsync[dev]

Minimal Example
The following example demonstrates how to fetch data from a FreshPoint webpage
based on its specific location ID and print the location name, overall product
count, and the number of available products. The extracted data is then dumped
to a JSON file.
import asyncio
from freshpointsync import ProductPage

LOCATION_ID = 296 # from https://my.freshpoint.cz/device/product-list/296
CACHE_FILENAME = f'pageData_{LOCATION_ID}.json'

async def main() -> None:
async with ProductPage(location_id=LOCATION_ID) as page:
await page.update()

products_available = [
p for p in page.data.products.values() if p.is_available
]
print(
f'Location name: {page.data.location}\n'
f'Product count: {len(page.data.products)} '
f'({len(products_available)} in stock)'
)

page_data = page.data.model_dump_json(indent=4, by_alias=True)
with open(CACHE_FILENAME, 'w', encoding='utf-8') as file:
file.write(page_data)

if __name__ == '__main__':
asyncio.run(main())

Reporting Issues and Contributing
FreshPointSync is an open-source project in its early development stages. If you
encounter any issues or have suggestions for improvements, please report them on
the GitHub Issue tracker.
Contributions to FreshPointSync are also welcome! If you would like
to contribute, please fork the repository, implement your changes, and open
a Pull Request with a detailed description of your work on the
GitHub Pull Request page.

License
FreshPointSync is distributed under the MIT License.