clope 0.1.2__tar.gz

clope-0.1.2/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

clope-0.1.2/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include README.md
+include LICENSE

clope-0.1.2/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.1
+Name: clope
+Version: 0.1.2
+Summary: Python package for interacting with the Cantaloupe/Seed vending system. Primarily the Spotlight API.
+Home-page: https://github.com/pepsimidamerica/clope
+Author: Jordan Maynor
+Author-email: jmaynor@pepsimidamerica.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pandas==2.2.2
+Requires-Dist: pyarrow==17.0.0
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: snowflake-connector-python[pandas]==3.11.0
+
+# Overview
+
+clope (see-lope) is a Python package for interacting with the Cantaloupe/Seed vending system. Primarily being a wrapper for their Spotlight API. It uses the pandas library to return information from a given spotlight report as a dataframe object. clope also has functionality for connecting to the snowflake data warehouse Cantaloupe product as well.
+
+## Installation
+
+Haven't yet bothered to publish as a python package, intent is to simply add clope as a git submodule in any projects where it's needed.
+
+## Usage
+
+Several environment variables are required for clope to function. Functionality is divided into two modules, so vars are only required if you are using functions from that particular module.
+
+| Module | Required? | Env Variable | Description |
+| --------- | --------- | ------------ | ----------- |
+| Spotlight | Yes       | CLO_USERNAME | Username of the Spotlight API user. Should be provided by Cantaloupe. |
+| Spotlight | Yes       | CLO_PASSWORD | Password of the Spotlight API user. Should be provided by Cantaloupe. |
+| Spotlight | No        | CLO_BASE_URL | Not actually sure if this varies between clients. I have this as an optional variable in case it does. Default value if no env variable is <https://api.mycantaloupe.com>, otherwise can be overridden. |
+| Spotlight | No        | CLO_ARCHIVE_FILES | Optional variable. Will archive the interim excel files that run_report() generates so can be later looked at in the Archive folder. Default behavior is to not archive and simply delete the excel files after data is pulled from them. |
+| Snowflake | Yes | SNOWFLAKE_USER | Username of the Snowflake user |
+| Snowflake | Yes | SNOWFLAKE_PASSWORD | Password of the snowflake user |
+| Snowflake | Yes | SNOWFLAKE_ACCOUNT | Snowflake account you're connecting to. Should be something along the lines of "{Cantaloupe account}-{Your Company Name}" |
+| Snowflake | Yes | SNOWFLAKE_DATABASE | Snowflake database to connect to. Likely begins with "PRD_SEED...". |
+
+## Spotlight
+
+The spotlight module invloves interaction with the Cantaloupe Spotlight API. The API essentially allows remotely run a spotlight report and getting the raw excel data via HTTP requests. Reports must be set up in the browser prior to using the API. Fairly quick and suited for getting data that needs to be up-to-date at that moment.
+
+### Run Spotlight Report (run_report())
+
+The primary function. Used to run a spotlight report, retrieve the excel results, and transform the excel file into a workable pandas dataframe. Cantaloupe's spotlight reports return an excel file with two tabs: Report and Stats. This pulls the info from the Report tab, Stats is ignored.
+
+> Note: Make sure your spotlight report has been shared with the "Seed Spotlight API Users" security group in Seed Office. Won't be accessible otherwise.
+
+Takes in two parameters:
+
+*report_id*
+
+A string ID for the report in Cantaloupe. When logged into Seed Office, the report ID can be found in the URL. E.G. <https://mycantaloupe.com/cs3/ReportsEdit/Run?ReportId=XXXXX>, XXXXX being the report ID needed.
+
+*params*
+
+Optional parameter, list of tuples of strings. Some Spotlight reports have required filters which must be supplied to get data back. Date ranges being a common one. Cantaloupe's error messages are fairly clear, in my experience, with telling you what parameteres are needed to run the report and in what format they should be. First element of tuple is filter name and second is filter value. Filter names are in format of "filter0", "filter1", "filter2", etc.
+
+Example call
+
+```python
+# Import package
+from clope import run_report
+
+# Run report with a report_id and additional parameters
+df_report = run_report('123', [('filter0', '2024-01-01'), ('filter0', '2024-01-31')])
+```
+
+## Snowflake
+
+Cantaloupe also offers a data warehouse product in Snowflake. Good for aggregating lots of information, as well as pulling historical information. However, notably, data is only pushed from Seed into the Snowflake data warehouse once a day, so it is not necessarily going to be accurate as of that moment.
+
+Also something to keep in mind is that the system makes use of SCD (slowly changing dimension) in order to keep track of historical info vs current info. So some care should be taken when interpreting the data.
+
+For each dataset that uses SCD, a parameter has been included to restrict to current data only or include all data.
+
+### Dates
+
+In Snowflake, most date columns are represented by an integer key, rather than the date itself. A couple functions are included with regards to dates. If working directly with Snowflake, you would join the date table onto the fact table you're working with. However, from what I can see the dates are largely deterministic. 1 is 1900-01-01, 2 is 1900-01-02. So I just directly translate from key to date and vice versa with some date math. Much quicker and should give same results as querying the date table itself.
+
+### Dimensions
+
+Dimensions describe facts. The location something happened in. The route it happened on. Dimensions generally change over time and make the most use of the SCD schema.
+
+- Barcodes (for each pack)
+- Branches
+- Coils (planogram slots)
+- Customers
+- Devices (telemetry)
+- Item Packs (UOMs)
+- Items
+- Lines of Business
+- Locations
+- Machines
+- Micromarkets
+- Operators
+- Routes
+- Supplier Branch
+- Supplier Items (Not yet used seemingly)
+- Suppliers
+- Warehouses
+- Machine Alerts
+
+### Facts
+
+A fact is the central information being stored. Generally, things that are not changing. A sale, an inventory, a product movement.
+
+- Cashless Vending Tranaction
+- Collection Micromarket Sales
+- Order to Fulfillment (Delivery)
+- Order to Fulfillment (Vending and Micromarket)
+- Delivery Order Receive
+- Sales Revenue By Day
+- Sales Revenue By Visit
+- Sales By Coil
+- Scheduling Machine
+- Scheduling Route Summary
+- Telemetry Sales
+- Vending Micromarket Visit
+- Warehouse Inventory
+- Warehouse Observed Inventory
+- Warehouse Product Movement
+- Warehouse Purchase
+- Warehouse Receive
+
+### Functions
+
+Also included in Cantaloupe's Snowflake are a couple functions. General intention seems to be gathering a subset of data from a couple core fact tables. Haven't yet implemented wrappers for these.

clope-0.1.2/README.md

@@ -0,0 +1,113 @@
+# Overview
+
+clope (see-lope) is a Python package for interacting with the Cantaloupe/Seed vending system. Primarily being a wrapper for their Spotlight API. It uses the pandas library to return information from a given spotlight report as a dataframe object. clope also has functionality for connecting to the snowflake data warehouse Cantaloupe product as well.
+
+## Installation
+
+Haven't yet bothered to publish as a python package, intent is to simply add clope as a git submodule in any projects where it's needed.
+
+## Usage
+
+Several environment variables are required for clope to function. Functionality is divided into two modules, so vars are only required if you are using functions from that particular module.
+
+| Module | Required? | Env Variable | Description |
+| --------- | --------- | ------------ | ----------- |
+| Spotlight | Yes       | CLO_USERNAME | Username of the Spotlight API user. Should be provided by Cantaloupe. |
+| Spotlight | Yes       | CLO_PASSWORD | Password of the Spotlight API user. Should be provided by Cantaloupe. |
+| Spotlight | No        | CLO_BASE_URL | Not actually sure if this varies between clients. I have this as an optional variable in case it does. Default value if no env variable is <https://api.mycantaloupe.com>, otherwise can be overridden. |
+| Spotlight | No        | CLO_ARCHIVE_FILES | Optional variable. Will archive the interim excel files that run_report() generates so can be later looked at in the Archive folder. Default behavior is to not archive and simply delete the excel files after data is pulled from them. |
+| Snowflake | Yes | SNOWFLAKE_USER | Username of the Snowflake user |
+| Snowflake | Yes | SNOWFLAKE_PASSWORD | Password of the snowflake user |
+| Snowflake | Yes | SNOWFLAKE_ACCOUNT | Snowflake account you're connecting to. Should be something along the lines of "{Cantaloupe account}-{Your Company Name}" |
+| Snowflake | Yes | SNOWFLAKE_DATABASE | Snowflake database to connect to. Likely begins with "PRD_SEED...". |
+
+## Spotlight
+
+The spotlight module invloves interaction with the Cantaloupe Spotlight API. The API essentially allows remotely run a spotlight report and getting the raw excel data via HTTP requests. Reports must be set up in the browser prior to using the API. Fairly quick and suited for getting data that needs to be up-to-date at that moment.
+
+### Run Spotlight Report (run_report())
+
+The primary function. Used to run a spotlight report, retrieve the excel results, and transform the excel file into a workable pandas dataframe. Cantaloupe's spotlight reports return an excel file with two tabs: Report and Stats. This pulls the info from the Report tab, Stats is ignored.
+
+> Note: Make sure your spotlight report has been shared with the "Seed Spotlight API Users" security group in Seed Office. Won't be accessible otherwise.
+
+Takes in two parameters:
+
+*report_id*
+
+A string ID for the report in Cantaloupe. When logged into Seed Office, the report ID can be found in the URL. E.G. <https://mycantaloupe.com/cs3/ReportsEdit/Run?ReportId=XXXXX>, XXXXX being the report ID needed.
+
+*params*
+
+Optional parameter, list of tuples of strings. Some Spotlight reports have required filters which must be supplied to get data back. Date ranges being a common one. Cantaloupe's error messages are fairly clear, in my experience, with telling you what parameteres are needed to run the report and in what format they should be. First element of tuple is filter name and second is filter value. Filter names are in format of "filter0", "filter1", "filter2", etc.
+
+Example call
+
+```python
+# Import package
+from clope import run_report
+
+# Run report with a report_id and additional parameters
+df_report = run_report('123', [('filter0', '2024-01-01'), ('filter0', '2024-01-31')])
+```
+
+## Snowflake
+
+Cantaloupe also offers a data warehouse product in Snowflake. Good for aggregating lots of information, as well as pulling historical information. However, notably, data is only pushed from Seed into the Snowflake data warehouse once a day, so it is not necessarily going to be accurate as of that moment.
+
+Also something to keep in mind is that the system makes use of SCD (slowly changing dimension) in order to keep track of historical info vs current info. So some care should be taken when interpreting the data.
+
+For each dataset that uses SCD, a parameter has been included to restrict to current data only or include all data.
+
+### Dates
+
+In Snowflake, most date columns are represented by an integer key, rather than the date itself. A couple functions are included with regards to dates. If working directly with Snowflake, you would join the date table onto the fact table you're working with. However, from what I can see the dates are largely deterministic. 1 is 1900-01-01, 2 is 1900-01-02. So I just directly translate from key to date and vice versa with some date math. Much quicker and should give same results as querying the date table itself.
+
+### Dimensions
+
+Dimensions describe facts. The location something happened in. The route it happened on. Dimensions generally change over time and make the most use of the SCD schema.
+
+- Barcodes (for each pack)
+- Branches
+- Coils (planogram slots)
+- Customers
+- Devices (telemetry)
+- Item Packs (UOMs)
+- Items
+- Lines of Business
+- Locations
+- Machines
+- Micromarkets
+- Operators
+- Routes
+- Supplier Branch
+- Supplier Items (Not yet used seemingly)
+- Suppliers
+- Warehouses
+- Machine Alerts
+
+### Facts
+
+A fact is the central information being stored. Generally, things that are not changing. A sale, an inventory, a product movement.
+
+- Cashless Vending Tranaction
+- Collection Micromarket Sales
+- Order to Fulfillment (Delivery)
+- Order to Fulfillment (Vending and Micromarket)
+- Delivery Order Receive
+- Sales Revenue By Day
+- Sales Revenue By Visit
+- Sales By Coil
+- Scheduling Machine
+- Scheduling Route Summary
+- Telemetry Sales
+- Vending Micromarket Visit
+- Warehouse Inventory
+- Warehouse Observed Inventory
+- Warehouse Product Movement
+- Warehouse Purchase
+- Warehouse Receive
+
+### Functions
+
+Also included in Cantaloupe's Snowflake are a couple functions. General intention seems to be gathering a subset of data from a couple core fact tables. Haven't yet implemented wrappers for these.

clope-0.1.2/clope/__init__.py

@@ -0,0 +1 @@
+from .clope import *

clope-0.1.2/clope/clope.py

@@ -0,0 +1,15 @@
+"""
+clope is a package for pulling data from the Cantaloupe/Seed Office system.
+Primarily via the Spotlight API.
+"""
+
+from .snow.dates import *
+from .snow.dimensions import *
+from .snow.facts import *
+from .spotlight.spotlight import run_report
+
+if __name__ == "__main__":
+    """
+    Example usage
+    """
+    pass

clope-0.1.2/clope/snow/__init__.py

@@ -0,0 +1 @@
+# Empty

clope-0.1.2/clope/snow/connection_handling.py

@@ -0,0 +1,31 @@
+import os
+
+import snowflake.connector
+
+
+def _get_snowflake_connection(
+    schema: str = "PUBLIC",
+) -> snowflake.connector.SnowflakeConnection:
+    """
+    Connect to Snowflake data warehouse using environment variables. By default,
+    connects to the main PUBLIC schema. Can be overridden to connect to others.
+    """
+    for env in [
+        "SNOWFLAKE_USER",
+        "SNOWFLAKE_PASSWORD",
+        "SNOWFLAKE_ACCOUNT",
+        "SNOWFLAKE_WAREHOUSE",
+        "SNOWFLAKE_DATABASE",
+    ]:
+        if env not in os.environ:
+            raise Exception(f"Missing required environment variable: {env}")
+
+    conn = snowflake.connector.connect(
+        user=os.environ["SNOWFLAKE_USER"],
+        password=os.environ["SNOWFLAKE_PASSWORD"],
+        account=os.environ["SNOWFLAKE_ACCOUNT"],
+        warehouse=os.environ["SNOWFLAKE_WAREHOUSE"],
+        database=os.environ["SNOWFLAKE_DATABASE"],
+        schema=schema,
+    )
+    return conn

clope-0.1.2/clope/snow/dates.py

@@ -0,0 +1,120 @@
+"""
+This module contains functionality to translate between datekeys and dates.
+
+Technically there are tables containing this data, but I don't think
+it's necessary to actually query them. We can just calculate them directly.
+Should be much quicker.
+"""
+
+from datetime import datetime, timedelta
+
+import pandas
+
+# from connection_handling import _get_snowflake_connection
+
+
+def datekey_to_date(datekey: int) -> datetime:
+    """
+    Convert a datekey to a datetime object.
+    """
+    base_date = datetime(1900, 1, 1)
+    return base_date + timedelta(days=datekey - 1)
+
+
+def date_to_datekey(date: datetime) -> int:
+    """
+    Convert a datetime object to a datekey.
+    """
+    base_date = datetime(1900, 1, 1)
+    return (date - base_date).days + 1
+
+
+def get_datekey_range(start_date: datetime, end_date: datetime) -> list[int]:
+    """
+    Get a list of datekeys between two dates.
+    """
+    return [date_to_datekey(x) for x in pandas.date_range(start_date, end_date)]
+
+
+def get_date_range(start_datekey: int, end_datekey: int) -> list[datetime]:
+    """
+    Get a list of dates between two datekeys.
+    """
+    return [datekey_to_date(x) for x in range(start_datekey, end_datekey + 1)]
+
+
+def monthkey_to_date(monthkey: int) -> datetime:
+    """
+    Convert a monthkey to a datetime object representing the first day of the month.
+    """
+    year = 1900 + (monthkey - 1) // 12
+    month = (monthkey - 1) % 12 + 1
+    return datetime(year, month, 1)
+
+
+def date_to_monthkey(date: datetime) -> int:
+    """
+    Convert a datetime object to a monthkey.
+    """
+    return (date.year - 1900) * 12 + date.month
+
+
+def quarterkey_to_date(quarterkey: int) -> datetime:
+    """
+    Convert a quarterkey to a datetime object representing the first day of the quarter.
+    """
+    year = 1900 + (quarterkey - 1) // 4
+    quarter = (quarterkey - 1) % 4 + 1
+    month = (quarter - 1) * 3 + 1
+    return datetime(year, month, 1)
+
+
+def date_to_quarterkey(date: datetime) -> int:
+    """
+    Convert a datetime object to a quarterkey.
+    """
+    quarter = (date.month - 1) // 3 + 1
+    return (date.year - 1900) * 4 + quarter
+
+
+def yearkey_to_date(yearkey: int) -> datetime:
+    """
+    Convert a yearkey to a datetime object representing the first day of the year.
+    """
+    year = 1900 + yearkey - 1
+    return datetime(year, 1, 1)
+
+
+def date_to_yearkey(date: datetime) -> int:
+    """
+    Convert a datetime object to a yearkey.
+    """
+    return date.year - 1900 + 1
+
+
+# Commented out in-progress code
+# def date_dim(
+#     datekey: int | None = None, date: datetime | None = None
+# ) -> pandas.DataFrame:
+#     """
+#     Retrieve corresponding datekey from a given date or vice versa.
+#     """
+#     if date and datekey:
+#         raise Exception("Only one of datekey or date must be provided")
+#     if not datekey and not date:
+#         raise Exception("Either datekey or date must be provided")
+
+#     conn = _get_snowflake_connection(schema="TIME_DIMENSION")
+#     try:
+#         if datekey:
+#             query = f"SELECT * FROM DATE_DIM WHERE DATEKEY = {datekey}"
+#         else:
+#             query = f"SELECT * FROM DATE_DIM WHERE DATE = '{date}'"
+#         cur = conn.cursor()
+#         cur.execute(query)
+#         df = cur.fetch_pandas_all()
+#     except Exception as e:
+#         raise Exception("Error reading Snowflake table", e)
+#     finally:
+#         conn.close()
+#     return df