Metadata-Version: 2.4
Name: gspace
Version: 0.1.0
Summary: A Python SDK for Google Workspace APIs (Calendar, Gmail, Drive, Docs, and more)
Home-page: https://github.com/Sentivs-co/gspace
Author: Prasant Poudel
Author-email: Prasant Poudel <dev@sentivs.com>
License: MIT License
        
        Copyright (c) 2025 Sentivs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        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 OR COPYRIGHT HOLDERS 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.
        
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.32.5
Requires-Dist: google-api-python-client<3.0.0,>=2.179.0
Requires-Dist: google-auth-httplib2<0.3.0,>=0.2.0
Requires-Dist: google-auth-oauthlib<2.0.0,>=1.2.2
Provides-Extra: dev
Requires-Dist: black>=25.9.0; extra == "dev"
Requires-Dist: ruff>=0.14.3; extra == "dev"
Requires-Dist: isort>=7.0.0; extra == "dev"
Requires-Dist: pre-commit>=4.3.0; extra == "dev"
Requires-Dist: pytest>=8.4.2; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# gspace 🚀

*A comprehensive Python SDK for Google Workspace APIs (Calendar, Gmail, Drive, Docs, Sheets, and more).*

[![PyPI version](https://img.shields.io/pypi/v/gspace.svg)](https://pypi.org/project/gspace/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

---

## 🌟 Overview

`gspace` is a unified Python client library for **Google Workspace APIs**, making it simple to interact with Google Calendar, Gmail, Drive, Docs, Sheets, and other services from a single, well-designed interface.

Instead of juggling multiple SDKs, authentication flows, and scattered scopes, `gspace` provides:

- ✅ **Single Authentication** - OAuth2 or Service Account credentials
- ✅ **Consistent API Wrappers** - Unified interface across all Google services
- ✅ **Comprehensive Logging** - Built-in logging with configurable levels
- ✅ **Helper Methods** - Common tasks simplified (send email, create event, upload file, etc.)
- ✅ **Type Hints** - Full Python type annotations for better development experience
- ✅ **Error Handling** - Robust error handling with detailed logging
- ✅ **Extensible Design** - Easy to add new Google Workspace APIs

---

## 📦 Installation

### From PyPI (Recommended)

```bash
Comming soon
```

### From Source

```bash
git https://github.com/Sentivs-co/gspace
poetry install
```

---

## 🚀 Quick Start

### 1. Set Up Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable the APIs you need:
   - Google Calendar API
   - Gmail API
   - Google Drive API
   - Google Sheets API
   - Google Docs API
4. Create credentials (OAuth2 or Service Account)

### 2. Basic Usage

```python
from gspace import gspace
from datetime import datetime, timedelta

# Initialize with OAuth2 credentials
gspace = gspace.from_oauth(
    credentials_file="path/to/credentials.json",
    scopes=["calendar", "gmail", "drive"]
)

# Use Calendar service
calendar = gspace.calendar()
event = calendar.create_event(
    summary="Team Meeting",
    start_time=datetime.now() + timedelta(hours=1),
    end_time=datetime.now() + timedelta(hours=2),
    description="Weekly team sync"
)

# Use Gmail service
gmail = gspace.gmail()
gmail.send_simple_email(
    to="team@company.com",
    subject="Meeting Reminder",
    body="Don't forget our team meeting in 1 hour!"
)

# Use Drive service
drive = gspace.drive()
files = drive.list_files(page_size=10)
```

---

## 🔧 Features

### 📅 Calendar Service
- Create, read, update, delete events
- Manage multiple calendars
- Handle attendees and reminders
- Free/busy time queries
- Recurring events support

### 📧 Gmail Service
- Send emails (simple and with attachments)
- Read and search messages
- Manage labels and filters
- Handle drafts and threads
- Profile information

### 💾 Drive Service
- Upload and download files
- Create folders and organize content
- Share files and manage permissions
- Search and filter files
- Handle different file types

### 📊 Sheets Service
- Create and manage spreadsheets
- Read and write cell data
- Format cells and ranges
- Manage sheets and tabs
- Batch operations

### 📝 Docs Service
- Create and edit documents
- Insert text, tables, and images
- Apply formatting and styles
- Handle comments and revisions
- Batch updates

---

## 📚 API Reference

### Core Client

#### `gspace(credentials, scopes =None, auth_type = service_account or OAuth2 )`
Main client class for accessing Google Workspace services.

**Parameters:**
- `credentials` (str|Path): Path to credentials JSON file
- `scopes` (List[str], optional): List of Google API scopes

**Methods:**
- `calendar()` → Calendar service
- `gmail()` → Gmail service
- `drive()` → Drive service
- `sheets()` → Sheets service
- `docs()` → Docs service
- `close()` → None

#### Factory Methods

```python
# OAuth2 authentication
gspace = gspace.from_oauth(credentials_file, scopes)

# Service Account authentication
gspace = gspace.from_service_account(service_account_file, scopes)
```

### Authentication

The library supports two authentication methods:

1. **OAuth2** - For user applications
2. **Service Account** - For server-to-server applications

### Scopes

Use the `GoogleScopes` utility class to manage API scopes:

```python
from gspace.utils.scopes import GoogleScopes

# Get scopes for a specific service
calendar_scopes = GoogleScopes.get_service_scopes("calendar", "full")
gmail_scopes = GoogleScopes.get_service_scopes("gmail", "readonly")

# Get all available scopes
all_scopes = GoogleScopes.get_all_scopes()
```

---

## 📖 Examples

### Calendar Management

```python
# Create an event
event = calendar.create_event(
    summary="Project Review",
    start_time=datetime.now() + timedelta(days=1, hours=10),
    end_time=datetime.now() + timedelta(days=1, hours=11),
    description="Monthly project status review",
    location="Conference Room A",
    attendees=["team@company.com", "manager@company.com"]
)

# List upcoming events
events = calendar.list_events(
    time_min=datetime.now(),
    time_max=datetime.now() + timedelta(days=7),
    max_results=20
)

# Get free/busy information
free_busy = calendar.get_free_busy(
    time_min=datetime.now(),
    time_max=datetime.now() + timedelta(days=1),
    items=[{"id": "primary"}]
)
```

### Email Operations

```python
# Send simple email
gmail.send_simple_email(
    to="recipient@example.com",
    subject="Important Update",
    body="Please review the attached document."
)

# Send email with attachments
gmail.send_email(
    to=["user1@example.com", "user2@example.com"],
    subject="Project Documents",
    body="Please find the project documents attached.",
    attachments=["/path/to/doc1.pdf", "/path/to/doc2.docx"],
    cc="manager@example.com"
)

# Search for emails
messages = gmail.search_messages(
    query="from:important@company.com subject:urgent",
    max_results=50
)
```

### File Management

```python
# Upload a file
file = drive.upload_file(
    file_path="/path/to/document.pdf",
    name="Important Document",
    description="Project proposal document"
)

# Create a folder
folder = drive.create_folder(
    name="Project Files",
    description="All project-related documents"
)

# Share a file
drive.share_file(
    file_id=file.get('id'),
    email="collaborator@company.com",
    role="writer"
)

# Search for files
files = drive.search_files(
    query="name contains 'report' and modifiedTime > '2024-01-01'"
)
```

### Spreadsheet Operations

```python
# Create a new spreadsheet
spreadsheet = sheets.create_spreadsheet(
    title="Monthly Report",
    sheets=[{
        'properties': {
            'title': 'Data',
            'gridProperties': {
                'rowCount': 1000,
                'columnCount': 26
            }
        }
    }]
)

# Add data to cells
sheets.update_values(
    spreadsheet_id=spreadsheet.get('spreadsheetId'),
    range_name="Data!A1:D5",
    values=[
        ["Name", "Department", "Salary", "Start Date"],
        ["John Doe", "Engineering", 75000, "2023-01-15"],
        ["Jane Smith", "Marketing", 65000, "2023-03-20"],
        ["Bob Johnson", "Sales", 70000, "2023-02-10"]
    ]
)

# Format cells
sheets.format_cells(
    spreadsheet_id=spreadsheet.get('spreadsheetId'),
    range_name="Data!A1:D1",
    format_properties={
        'backgroundColor': {'red': 0.8, 'green': 0.8, 'blue': 0.8},
        'textFormat': {'bold': True}
    }
)
```

### Document Creation

```python
# Create a new document
document = docs.create_document(title="Project Proposal")

# Add content
docs.insert_text(
    document_id=document.get('documentId'),
    location=1,
    text="Executive Summary\n\nThis document outlines our proposed solution..."
)

# Insert a table
docs.insert_table(
    document_id=document.get('documentId'),
    location=100,
    rows=3,
    columns=4
)

# Apply formatting
docs.update_text_style(
    document_id=document.get('documentId'),
    start_index=1,
    end_index=20,
    bold=True,
    font_size=16
)
```
---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: `pytest tests/`
6. Commit your changes: `git commit -m 'Add amazing feature'`
7. Push to the branch: `git push origin feature/amazing-feature`
8. Open a Pull Request

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Google for providing excellent APIs
- The Python community for amazing tools and libraries
- Contributors and users of this library

---

## 📞 Support

- 📧 **Email**: [dev@sentivs.com](mailto:dev@sentivs.com)
- 🐛 **Issues**: [GitHub Issues](https://github.com/Sentivs-co/gspace/issues)
- 📖 **Documentation**: **Comming SOON**
- 💬 **Discussions**: **Comming SOON**
---

## 🔄 Changelog

### v0.1.0 (Current)
- ✨ Initial release
- 🔐 OAuth2 and Service Account authentication
- 📅 Calendar API support
- 📧 Gmail API support
- 💾 Drive API support
- 📊 Sheets API support
- 📝 Docs API support
- 📝 Comprehensive logging
- 🎯 Type hints throughout
- 📚 Extensive documentation and examples

