smartspread 1.0.0__tar.gz

smartspread-1.0.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.1
+Name: smartspread
+Version: 1.0.0
+Summary: A Python library that extends gspread for enhanced spreadsheet manipulation.
+Author-email: Arved Klöhn <arved.kloehn@gmail.com>
+Project-URL: Homepage, https://github.com/Redundando/smart_spread
+Project-URL: Repository, https://github.com/Redundando/smart_spread
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: gspread>=5.0.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: cacherator>=0.1.0
+Requires-Dist: logorator>=0.1.0
+
+# SmartSpread
+
+SmartSpread is a Python library that extends the functionality of `gspread` for enhanced spreadsheet manipulation, enabling easier integration with Google Sheets.
+
+## Features
+- Simplified spreadsheet creation and access.
+- Easy tab (worksheet) management.
+- Supports data handling with Pandas DataFrames, lists, and dictionaries.
+- Batch updates and row-level modifications.
+- Cached properties for optimized performance.
+
+## Installation
+```bash
+pip install smartspread
+```
+
+## Requirements
+- Python 3.7+
+- `gspread`
+- `pandas`
+- `cacherator`
+- `logorator`
+
+## Usage
+```python
+from smartspread import SmartSpread
+
+# Initialize
+spread = SmartSpread(sheet_identifier="MySheet", key_file="path/to/google_service_account_keyfile.json")
+
+# Write data
+data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]
+spread.write_to_tab(data, tab_name="Sheet1", overwrite_tab=True)
+
+# Read data
+df = spread.tab_to_df("Sheet1")
+print(df)
+```
+
+## License
+This project is licensed under the MIT License.
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## Author
+Arved Klöhn - [Redundando](https://github.com/Redundando/)

smartspread-1.0.0/README.md

@@ -0,0 +1,47 @@
+# SmartSpread
+
+SmartSpread is a Python library that extends the functionality of `gspread` for enhanced spreadsheet manipulation, enabling easier integration with Google Sheets.
+
+## Features
+- Simplified spreadsheet creation and access.
+- Easy tab (worksheet) management.
+- Supports data handling with Pandas DataFrames, lists, and dictionaries.
+- Batch updates and row-level modifications.
+- Cached properties for optimized performance.
+
+## Installation
+```bash
+pip install smartspread
+```
+
+## Requirements
+- Python 3.7+
+- `gspread`
+- `pandas`
+- `cacherator`
+- `logorator`
+
+## Usage
+```python
+from smartspread import SmartSpread
+
+# Initialize
+spread = SmartSpread(sheet_identifier="MySheet", key_file="path/to/google_service_account_keyfile.json")
+
+# Write data
+data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]
+spread.write_to_tab(data, tab_name="Sheet1", overwrite_tab=True)
+
+# Read data
+df = spread.tab_to_df("Sheet1")
+print(df)
+```
+
+## License
+This project is licensed under the MIT License.
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## Author
+Arved Klöhn - [Redundando](https://github.com/Redundando/)

smartspread-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = [
+    "setuptools>=61.0",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartspread"
+version = "1.0.0"
+readme = "README.md"
+description = "A Python library that extends gspread for enhanced spreadsheet manipulation."
+authors = [
+    { name = "Arved Klöhn", email = "arved.kloehn@gmail.com" }
+]
+
+requires-python = ">=3.7"
+dependencies = [
+    "gspread>=5.0.0",
+    "pandas>=1.3.0",
+    "cacherator>=0.1.0",
+    "logorator>=0.1.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/Redundando/smart_spread"
+"Repository" = "https://github.com/Redundando/smart_spread"
+
+[tool.setuptools]
+packages = ["smart_spread"]

smartspread-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smartspread-1.0.0/smart_spread/__init__.py

@@ -0,0 +1 @@
+from .smart_spread import SmartSpread

smartspread-1.0.0/smart_spread/smart_spread.py

@@ -0,0 +1,229 @@
+import gspread
+from cacherator import JSONCache, Cached
+from logorator import Logger
+import pandas as pd
+
+class SmartSpread(JSONCache):
+
+    def __init__(self,
+                 sheet_identifier="",
+                 directory = "data/smart_spread",
+                 user_email = None,
+                 key_file = "",
+                 clear_cache = False):
+        super().__init__(directory=directory, data_id=f"{sheet_identifier}", clear_cache=clear_cache)
+        self.user_email = user_email
+        self.key_file = key_file
+        self.sheet_identifier = sheet_identifier
+        self.gc = gspread.service_account(filename=key_file)
+
+
+
+    @property
+    @Cached()
+    def sheet(self):
+        try:
+            try:
+                # Attempt to open by ID
+                sheet = self.gc.open_by_key(self.sheet_identifier)
+                Logger.note(f"Spreadsheet '{sheet.title}' successfully opened by ID.")
+            except gspread.exceptions.SpreadsheetNotFound:
+                # If not found by ID, try to open by name
+                sheet = self.gc.open(self.sheet_identifier)
+                Logger.note(f"Spreadsheet '{sheet.title}' successfully opened by name.")
+            return sheet
+        except gspread.exceptions.SpreadsheetNotFound:
+            Logger.note(f"Spreadsheet '{self.sheet_identifier}' not found.")
+            return self.create_sheet()
+
+    @Logger(mode="short")
+    def create_sheet(self):
+        Logger.note(f"Creating a new spreadsheet ('{self.sheet_identifier}').", mode="short")
+        try:
+            # Create a new spreadsheet if it does not exist
+            new_sheet = self.gc.create(self.sheet_identifier)
+            if self.user_email:
+                new_sheet.share(email_address=self.user_email,perm_type="user", role="writer")
+                Logger.note(f"Access granted to {self.user_email}.", mode="short")
+            return new_sheet
+        except Exception as e:
+            Logger.note(f"Error creating spreadsheet: {e}", mode="short")
+            raise
+
+
+
+    @Logger(mode="short")
+    def grant_access(self, email:str=None, role:str="owner"):
+        if not self.sheet:
+            raise ValueError("No spreadsheet is currently opened. Please open or create a sheet first.")
+        try:
+            self.sheet.share(email, perm_type="user", role=role)
+            Logger.note(f"Access granted to '{email}' with role '{role}' for sheet '{self.sheet.title}'.", mode="short")
+        except Exception as e:
+            Logger.note(f"Error granting access to '{email}': {e}", mode="short")
+            raise
+
+    @property
+    @Cached()
+    def url(self):
+        return self.sheet.url
+
+    @property
+    @Cached()
+    def tab_names(self):
+        if not self.sheet:
+            raise ValueError("No spreadsheet is currently opened. Please open a sheet first.")
+
+        try:
+            tab_names = [worksheet.title for worksheet in self.sheet.worksheets()]
+            return tab_names
+        except Exception as e:
+            Logger.note(f"Error fetching tab names: {e}", mode="short")
+            raise
+
+    @Cached()
+    @Logger(mode="short")
+    def get_tab_values(self, tab_name:str=None):
+        if not self.sheet:
+            Logger.note("No spreadsheet is currently opened. Please open or create a sheet first.", mode="short")
+            raise ValueError("No spreadsheet is currently opened. Please open or create a sheet first.")
+
+        try:
+            if tab_name is None:
+                tab_name = self.tab_names[0]
+            worksheet = self.sheet.worksheet(tab_name)
+            data = worksheet.get_all_values()
+            return data
+        except gspread.exceptions.WorksheetNotFound:
+            raise ValueError(f"Worksheet '{tab_name}' not found in spreadsheet '{self.sheet.title}'.")
+        except Exception as e:
+            Logger.note(f"Error retrieving data from worksheet '{tab_name}': {e}", mode="short")
+            raise
+
+    def tab_to_list(self, tab_name: str = None):
+        return self.get_tab_values(tab_name=tab_name)
+
+    @Cached()
+    def tab_to_flat_list(self, tab_name: str = None):
+        try:
+            data = self.get_tab_values(tab_name)
+            return [item for row in data for item in row]
+        except Exception as e:
+            Logger.note(f"Error converting tab values to list: {e}", mode="short")
+            raise
+
+    @Cached()
+    @Logger(mode="short")
+    def tab_to_dict(self, tab_name: str = None):
+        try:
+            data = self.get_tab_values(tab_name)
+            if len(data) < 2:
+                raise ValueError("Insufficient data to create a dictionary. Need at least headers and one row.")
+            headers = data[0]
+            rows = data[1:]
+            return [dict(zip(headers, row)) for row in rows]
+        except Exception as e:
+            Logger.note(f"Error converting tab values to dict: {e}", mode="short")
+            raise
+
+    @Cached()
+    @Logger(mode="short")
+    def tab_to_df(self, tab_name: str = None):
+        try:
+            data = self.get_tab_values(tab_name)
+            if len(data) < 2:
+                raise ValueError("Insufficient data to create a DataFrame. Need at least headers and one row.")
+            df = pd.DataFrame(data[1:], columns=data[0])
+            return df
+        except Exception as e:
+            Logger.note(f"Error converting tab values to DataFrame: {e}", mode="short")
+            raise
+
+    @Logger(mode="short")
+    def filter_rows_by_column(self, tab_name: str, column_name: str, pattern: str):
+        try:
+            df = self.tab_to_df(tab_name)
+            if column_name not in df.columns:
+                raise ValueError(f"Column '{column_name}' not found in the data.")
+            matching_rows = df[df[column_name].str.contains(pattern, na=False)]
+            return matching_rows
+        except Exception as e:
+            Logger.note(f"Error filtering rows by column '{column_name}': {e}", mode="short")
+            raise
+
+    @Logger(mode="short")
+    def update_row_by_column_pattern(self, tab_name: str, column_name: str, pattern: str, updates: dict):
+        try:
+            worksheet = self.sheet.worksheet(tab_name)
+            df = self.tab_to_df(tab_name)
+            if column_name not in df.columns:
+                raise ValueError(f"Column '{column_name}' not found in the data.")
+
+            # Find the first matching row index
+            matching_row_index = df[df[column_name].str.contains(pattern, na=False)].index[0]
+
+            # Add missing columns and apply updates
+            headers = df.columns.tolist()
+            row = worksheet.row_values(matching_row_index + 2)  # Adjust for 1-based index and header row
+            while len(row) < len(headers):
+                row.append("")
+
+            # Update only the modified columns
+            for col, value in updates.items():
+                if col not in headers:
+                    headers.append(col)
+                    worksheet.update_cell(1, len(headers), col)
+                col_idx = headers.index(col) + 1
+                worksheet.update_cell(matching_row_index + 2, col_idx, value)
+
+            Logger.note(f"Row updated successfully in tab '{tab_name}'.", mode="short")
+
+        except Exception as e:
+            Logger.note(f"Error updating row by column pattern: {e}", mode="short")
+            raise
+
+
+    def tab_exists(self, tab_name: str) -> bool:
+        try:
+            # Attempt to get the worksheet by name
+            self.sheet.worksheet(tab_name)
+            return True
+        except gspread.exceptions.WorksheetNotFound:
+            return False
+
+
+    @Logger(mode="short")
+    def write_to_tab(self, data, tab_name: str, overwrite_tab: bool = False):
+        try:
+            if self.tab_exists(tab_name):
+                worksheet = self.sheet.worksheet(tab_name)
+            else:
+                Logger.note(f"Tab '{tab_name}' not found. Creating new tab.")
+                worksheet = self.sheet.add_worksheet(title=tab_name, rows=1000, cols=26)
+
+            # Prepare data
+            if isinstance(data, pd.DataFrame):
+                values = [data.columns.tolist()] + data.values.tolist()
+            elif isinstance(data, list) and all(isinstance(row, dict) for row in data):
+                keys = list(data[0].keys())
+                values = [keys] + [[row.get(k, "") for k in keys] for row in data]
+            elif isinstance(data, list) and all(isinstance(row, list) for row in data):
+                values = data
+            else:
+                raise ValueError("Unsupported data format. Provide a DataFrame, List of Lists, or List of Dicts.")
+
+            # Overwrite behavior
+            if overwrite_tab:
+                worksheet.clear()
+                worksheet.update(values)
+            else:
+                # Prepare range for the batch update
+                start_cell = 'A1'
+                end_cell = f'{chr(65 + len(values[0]) - 1)}{len(values)}'  # Calculates range based on data size
+                worksheet.update(f'{start_cell}:{end_cell}', values)
+
+            Logger.note(f"Data written successfully to '{tab_name}'.",)
+
+        except Exception as e:
+            Logger.note(f"Error writing data to tab '{tab_name}': {e}")
+            raise

smartspread-1.0.0/smartspread.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.1
+Name: smartspread
+Version: 1.0.0
+Summary: A Python library that extends gspread for enhanced spreadsheet manipulation.
+Author-email: Arved Klöhn <arved.kloehn@gmail.com>
+Project-URL: Homepage, https://github.com/Redundando/smart_spread
+Project-URL: Repository, https://github.com/Redundando/smart_spread
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: gspread>=5.0.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: cacherator>=0.1.0
+Requires-Dist: logorator>=0.1.0
+
+# SmartSpread
+
+SmartSpread is a Python library that extends the functionality of `gspread` for enhanced spreadsheet manipulation, enabling easier integration with Google Sheets.
+
+## Features
+- Simplified spreadsheet creation and access.
+- Easy tab (worksheet) management.
+- Supports data handling with Pandas DataFrames, lists, and dictionaries.
+- Batch updates and row-level modifications.
+- Cached properties for optimized performance.
+
+## Installation
+```bash
+pip install smartspread
+```
+
+## Requirements
+- Python 3.7+
+- `gspread`
+- `pandas`
+- `cacherator`
+- `logorator`
+
+## Usage
+```python
+from smartspread import SmartSpread
+
+# Initialize
+spread = SmartSpread(sheet_identifier="MySheet", key_file="path/to/google_service_account_keyfile.json")
+
+# Write data
+data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]
+spread.write_to_tab(data, tab_name="Sheet1", overwrite_tab=True)
+
+# Read data
+df = spread.tab_to_df("Sheet1")
+print(df)
+```
+
+## License
+This project is licensed under the MIT License.
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## Author
+Arved Klöhn - [Redundando](https://github.com/Redundando/)

smartspread-1.0.0/smartspread.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+smart_spread/__init__.py
+smart_spread/smart_spread.py
+smartspread.egg-info/PKG-INFO
+smartspread.egg-info/SOURCES.txt
+smartspread.egg-info/dependency_links.txt
+smartspread.egg-info/requires.txt
+smartspread.egg-info/top_level.txt

smartspread-1.0.0/smartspread.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smartspread-1.0.0/smartspread.egg-info/requires.txt

@@ -0,0 +1,4 @@
+gspread>=5.0.0
+pandas>=1.3.0
+cacherator>=0.1.0
+logorator>=0.1.0

smartspread-1.0.0/smartspread.egg-info/top_level.txt

@@ -0,0 +1 @@
+smart_spread