# SharePoint API Client
A modern Python library for interacting with Microsoft SharePoint sites using the Microsoft Graph API. Built with httpx for high-performance async/sync operations, automatic connection management, and streaming support for large files.
## Features
✨ **Modern httpx-based implementation** with HTTP/2 support ready
🔄 **Both sync and async clients** with identical APIs
🚀 **Automatic URL parsing** - just paste SharePoint URLs
💾 **Streaming support** for large file uploads/downloads
🔧 **Automatic connection management** with configurable cleanup
📁 **Rich data models** with comprehensive SharePoint object support
🛡️ **OAuth2 authentication** via Microsoft Graph API
## Installation
```bash
pip install sharepoint-api-py
# or
poetry add sharepoint-api-py
```
## Quick Start
### 1. Setup Credentials
Create a `.env` file or set environment variables:
```bash
SHAREPOINT_TENANT_ID="your_tenant_id"
SHAREPOINT_APP_ID="your_app_id"
SHAREPOINT_APP_SECRET="your_app_secret"
```
### 2. Basic Usage
```python
from sharepoint_api import SharePointClient
# Initialize client from environment
client = SharePointClient.from_env()
# Upload a file - just provide local path and SharePoint folder URL
client.upload(
"./report.pdf",
"https://contoso.sharepoint.com/sites/MyTeam/Shared%20Documents/Reports/"
)
# Download a file - just provide SharePoint file URL and local folder
client.download(
"https://contoso.sharepoint.com/sites/MyTeam/Shared%20Documents/data.xlsx",
target_path="./downloads/"
)
```
### 3. Async Usage
```python
from sharepoint_api import AsyncSharePointClient
async def main():
client = AsyncSharePointClient.from_env()
# Same simple API, but async
await client.upload(
"./large_dataset.csv",
"https://contoso.sharepoint.com/sites/MyTeam/Documents/"
)
await client.download(
"https://contoso.sharepoint.com/sites/MyTeam/Documents/results.xlsx",
target_path="./downloads/"
)
```
## Core Concepts
### Automatic URL Parsing
No need to manually extract site IDs, drive names, or folder paths. Just copy SharePoint URLs from your browser:
```python
# Copy any SharePoint URL from your browser and use it directly
client.upload("./file.pdf", "https://contoso.sharepoint.com/sites/TeamSite/Documents/Reports/")
client.download("https://contoso.sharepoint.com/sites/TeamSite/Documents/file.xlsx", "./downloads/")
```
### Context Management
The client automatically handles all the complexity behind the scenes. You just provide URLs:
```python
# No setup needed - each operation is self-contained
client.upload("./file1.txt", "https://sharepoint.com/sites/TeamA/Documents/")
client.upload("./file2.txt", "https://sharepoint.com/sites/TeamB/Reports/") # Different site? No problem!
```
### Streaming for Large Files
Large files are automatically streamed to avoid memory issues:
```python
# Files larger than threshold (default: 100MB) are automatically streamed
large_file = client.download("https://sharepoint.com/huge_dataset.csv")
# Force streaming for any file
client.download_file(file_obj, use_streaming=True)
# Configure thresholds
client = SharePointClient.from_env(
large_file_threshold=50*1024*1024, # 50MB threshold
auto_close_timeout=60 # Close idle connections after 60s
)
```
## API Reference
### Client Initialization
```python
from sharepoint_api import SharePointClient, AsyncSharePointClient
from sharepoint_api.config import SharepointConfig
# From environment variables
client = SharePointClient.from_env()
# From config object
config = SharepointConfig(
tenant_id="...",
client_id="...",
client_secret="...",
resource_url="https://graph.microsoft.com/",
resource_url_version="v1.0"
)
client = SharePointClient.from_config(config)
# With custom settings
client = SharePointClient.from_env(
auto_close_timeout=120, # Close idle connections after 2 minutes
large_file_threshold=200*1024*1024 # 200MB streaming threshold
)
```
### File and Folder Operations
```python
# Upload files - just provide local path and SharePoint folder URL
client.upload("./document.pdf", "https://sharepoint.com/sites/Team/Documents/Reports/")
# Download files - provide SharePoint file URL and local destination
client.download("https://sharepoint.com/sites/Team/Documents/report.xlsx", "./downloads/")
# Browse folder contents (if needed)
folder = client.path("https://sharepoint.com/sites/Team/Documents/Reports/")
for item in folder.children:
print(f"📄 {item.name}")
```
### Data Models
Rich data models provide comprehensive SharePoint object information:
```python
from sharepoint_api import GraphSiteData, DriveFolder, DriveFile, FileSize
# Site information
site = client.get_site(site_name="TeamSite")
print(f"Site: {site.name} ({site.web_url})")
# File information with rich metadata
file = client.path("https://sharepoint.com/file.xlsx")
print(f"File: {file.name}")
print(f"Size: {file.size}") # Automatically formatted (e.g., "1.5 MB")
print(f"Modified: {file.last_modified_date_time}")
print(f"Download URL: {file.download_url}")
# Folder with children
folder = client.path("https://sharepoint.com/folder/")
for item in folder.children:
item_type = "📁" if isinstance(item, DriveFolder) else "📄"
print(f"{item_type} {item.name}")
```
## Advanced Usage
### Custom Authentication
```python
# Use your own OAuth2 tokens
client = SharePointClient(
client_id="your_app_id",
client_secret="your_secret",
tenant_id="your_tenant",
resource_url="https://graph.microsoft.com/",
resource_url_version="v1.0"
)
```
### Error Handling
```python
from sharepoint_api.core.errors import SharepointAPIError
try:
file = client.download("https://sharepoint.com/nonexistent.xlsx")
except SharepointAPIError as e:
print(f"SharePoint API error: {e}")
except Exception as e:
print(f"General error: {e}")
```
### Performance Tuning
```python
# Configure connection pooling and timeouts
client = SharePointClient.from_env(
auto_close_timeout=300, # 5 minute idle timeout
large_file_threshold=500*1024*1024, # 500MB streaming threshold
)
# HTTP/2 support (requires h2 package)
# pip install h2
# client.http2 = True # Coming soon
```
## Examples
See the `examples/` directory for complete examples:
- **Basic operations**: Site access, file upload/download
- **Async operations**: Using AsyncSharePointClient
- **Bulk operations**: Processing multiple files
- **Advanced scenarios**: Custom authentication, error handling
## Contributing
Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.
---
**Built with ❤️ using:**
- [httpx](https://www.python-httpx.org/) - Modern HTTP client
- [authlib](https://authlib.org/) - OAuth2 authentication
- [pydantic](https://pydantic.dev/) - Data validation and models
Raw data
{
"_id": null,
"home_page": "https://github.com/earldennison/sharepoint-api-py",
"name": "sharepoint-api-py",
"maintainer": "Earl Dennison",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "earl@example.com",
"keywords": "sharepoint, microsoft, graph-api, httpx, async, office365",
"author": "Earl Dennison",
"author_email": "earl@example.com",
"download_url": "https://files.pythonhosted.org/packages/1e/76/5c6e038a24e5f73a22f62c26eeb8c2c0466ca2c98870c1dc9ba9fef8646a/sharepoint_api_py-0.1.0.tar.gz",
"platform": null,
"description": "# SharePoint API Client\n\nA modern Python library for interacting with Microsoft SharePoint sites using the Microsoft Graph API. Built with httpx for high-performance async/sync operations, automatic connection management, and streaming support for large files.\n\n## Features\n\n\u2728 **Modern httpx-based implementation** with HTTP/2 support ready \n\ud83d\udd04 **Both sync and async clients** with identical APIs \n\ud83d\ude80 **Automatic URL parsing** - just paste SharePoint URLs \n\ud83d\udcbe **Streaming support** for large file uploads/downloads \n\ud83d\udd27 **Automatic connection management** with configurable cleanup \n\ud83d\udcc1 **Rich data models** with comprehensive SharePoint object support \n\ud83d\udee1\ufe0f **OAuth2 authentication** via Microsoft Graph API \n\n## Installation\n\n```bash\npip install sharepoint-api-py\n# or\npoetry add sharepoint-api-py\n```\n\n## Quick Start\n\n### 1. Setup Credentials\n\nCreate a `.env` file or set environment variables:\n\n```bash\nSHAREPOINT_TENANT_ID=\"your_tenant_id\"\nSHAREPOINT_APP_ID=\"your_app_id\" \nSHAREPOINT_APP_SECRET=\"your_app_secret\"\n```\n\n### 2. Basic Usage\n\n```python\nfrom sharepoint_api import SharePointClient\n\n# Initialize client from environment\nclient = SharePointClient.from_env()\n\n# Upload a file - just provide local path and SharePoint folder URL\nclient.upload(\n \"./report.pdf\",\n \"https://contoso.sharepoint.com/sites/MyTeam/Shared%20Documents/Reports/\"\n)\n\n# Download a file - just provide SharePoint file URL and local folder\nclient.download(\n \"https://contoso.sharepoint.com/sites/MyTeam/Shared%20Documents/data.xlsx\",\n target_path=\"./downloads/\"\n)\n```\n\n### 3. Async Usage\n\n```python\nfrom sharepoint_api import AsyncSharePointClient\n\nasync def main():\n client = AsyncSharePointClient.from_env()\n \n # Same simple API, but async\n await client.upload(\n \"./large_dataset.csv\",\n \"https://contoso.sharepoint.com/sites/MyTeam/Documents/\"\n )\n \n await client.download(\n \"https://contoso.sharepoint.com/sites/MyTeam/Documents/results.xlsx\",\n target_path=\"./downloads/\"\n )\n```\n\n## Core Concepts\n\n### Automatic URL Parsing\n\nNo need to manually extract site IDs, drive names, or folder paths. Just copy SharePoint URLs from your browser:\n\n```python\n# Copy any SharePoint URL from your browser and use it directly\nclient.upload(\"./file.pdf\", \"https://contoso.sharepoint.com/sites/TeamSite/Documents/Reports/\")\nclient.download(\"https://contoso.sharepoint.com/sites/TeamSite/Documents/file.xlsx\", \"./downloads/\")\n```\n\n### Context Management\n\nThe client automatically handles all the complexity behind the scenes. You just provide URLs:\n\n```python\n# No setup needed - each operation is self-contained\nclient.upload(\"./file1.txt\", \"https://sharepoint.com/sites/TeamA/Documents/\")\nclient.upload(\"./file2.txt\", \"https://sharepoint.com/sites/TeamB/Reports/\") # Different site? No problem!\n```\n\n### Streaming for Large Files\n\nLarge files are automatically streamed to avoid memory issues:\n\n```python\n# Files larger than threshold (default: 100MB) are automatically streamed\nlarge_file = client.download(\"https://sharepoint.com/huge_dataset.csv\")\n\n# Force streaming for any file\nclient.download_file(file_obj, use_streaming=True)\n\n# Configure thresholds\nclient = SharePointClient.from_env(\n large_file_threshold=50*1024*1024, # 50MB threshold\n auto_close_timeout=60 # Close idle connections after 60s\n)\n```\n\n## API Reference\n\n### Client Initialization\n\n```python\nfrom sharepoint_api import SharePointClient, AsyncSharePointClient\nfrom sharepoint_api.config import SharepointConfig\n\n# From environment variables\nclient = SharePointClient.from_env()\n\n# From config object\nconfig = SharepointConfig(\n tenant_id=\"...\",\n client_id=\"...\", \n client_secret=\"...\",\n resource_url=\"https://graph.microsoft.com/\",\n resource_url_version=\"v1.0\"\n)\nclient = SharePointClient.from_config(config)\n\n# With custom settings\nclient = SharePointClient.from_env(\n auto_close_timeout=120, # Close idle connections after 2 minutes\n large_file_threshold=200*1024*1024 # 200MB streaming threshold\n)\n```\n\n### File and Folder Operations\n\n```python\n# Upload files - just provide local path and SharePoint folder URL\nclient.upload(\"./document.pdf\", \"https://sharepoint.com/sites/Team/Documents/Reports/\")\n\n# Download files - provide SharePoint file URL and local destination\nclient.download(\"https://sharepoint.com/sites/Team/Documents/report.xlsx\", \"./downloads/\")\n\n# Browse folder contents (if needed)\nfolder = client.path(\"https://sharepoint.com/sites/Team/Documents/Reports/\")\nfor item in folder.children:\n print(f\"\ud83d\udcc4 {item.name}\")\n```\n\n### Data Models\n\nRich data models provide comprehensive SharePoint object information:\n\n```python\nfrom sharepoint_api import GraphSiteData, DriveFolder, DriveFile, FileSize\n\n# Site information\nsite = client.get_site(site_name=\"TeamSite\")\nprint(f\"Site: {site.name} ({site.web_url})\")\n\n# File information with rich metadata\nfile = client.path(\"https://sharepoint.com/file.xlsx\")\nprint(f\"File: {file.name}\")\nprint(f\"Size: {file.size}\") # Automatically formatted (e.g., \"1.5 MB\") \nprint(f\"Modified: {file.last_modified_date_time}\")\nprint(f\"Download URL: {file.download_url}\")\n\n# Folder with children\nfolder = client.path(\"https://sharepoint.com/folder/\")\nfor item in folder.children:\n item_type = \"\ud83d\udcc1\" if isinstance(item, DriveFolder) else \"\ud83d\udcc4\"\n print(f\"{item_type} {item.name}\")\n```\n\n## Advanced Usage\n\n### Custom Authentication\n\n```python\n# Use your own OAuth2 tokens\nclient = SharePointClient(\n client_id=\"your_app_id\",\n client_secret=\"your_secret\", \n tenant_id=\"your_tenant\",\n resource_url=\"https://graph.microsoft.com/\",\n resource_url_version=\"v1.0\"\n)\n```\n\n### Error Handling\n\n```python\nfrom sharepoint_api.core.errors import SharepointAPIError\n\ntry:\n file = client.download(\"https://sharepoint.com/nonexistent.xlsx\")\nexcept SharepointAPIError as e:\n print(f\"SharePoint API error: {e}\")\nexcept Exception as e:\n print(f\"General error: {e}\")\n```\n\n### Performance Tuning\n\n```python\n# Configure connection pooling and timeouts\nclient = SharePointClient.from_env(\n auto_close_timeout=300, # 5 minute idle timeout\n large_file_threshold=500*1024*1024, # 500MB streaming threshold\n)\n\n# HTTP/2 support (requires h2 package)\n# pip install h2\n# client.http2 = True # Coming soon\n```\n\n## Examples\n\nSee the `examples/` directory for complete examples:\n\n- **Basic operations**: Site access, file upload/download\n- **Async operations**: Using AsyncSharePointClient \n- **Bulk operations**: Processing multiple files\n- **Advanced scenarios**: Custom authentication, error handling\n\n## Contributing\n\nContributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Built with \u2764\ufe0f using:**\n- [httpx](https://www.python-httpx.org/) - Modern HTTP client\n- [authlib](https://authlib.org/) - OAuth2 authentication\n- [pydantic](https://pydantic.dev/) - Data validation and models",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modern Python library for SharePoint API with httpx, async support, and automatic URL parsing",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/earldennison/sharepoint-api-py/issues",
"Changelog": "https://github.com/earldennison/sharepoint-api-py/releases",
"Documentation": "https://github.com/earldennison/sharepoint-api-py#readme",
"Homepage": "https://github.com/earldennison/sharepoint-api-py",
"Repository": "https://github.com/earldennison/sharepoint-api-py"
},
"split_keywords": [
"sharepoint",
" microsoft",
" graph-api",
" httpx",
" async",
" office365"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4fea4af12e7e99710f38075e426e3d6fe23bf6c21aa7324568de1b9ff2b5c1ff",
"md5": "d8ff510b662f29a6955858e42ee5dd24",
"sha256": "5e43921ea6f80a6288e8aa35060606c395a26147a04adfc0c618afc49d44b8c9"
},
"downloads": -1,
"filename": "sharepoint_api_py-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8ff510b662f29a6955858e42ee5dd24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22231,
"upload_time": "2025-08-04T12:53:22",
"upload_time_iso_8601": "2025-08-04T12:53:22.259038Z",
"url": "https://files.pythonhosted.org/packages/4f/ea/4af12e7e99710f38075e426e3d6fe23bf6c21aa7324568de1b9ff2b5c1ff/sharepoint_api_py-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e765c6e038a24e5f73a22f62c26eeb8c2c0466ca2c98870c1dc9ba9fef8646a",
"md5": "17a5fd8b2b2316da26ea7402c386743d",
"sha256": "555f3cb6dbeeaea1a79bf9e8850c6fc127508550b545d6cca580ce9bc1a34c5a"
},
"downloads": -1,
"filename": "sharepoint_api_py-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "17a5fd8b2b2316da26ea7402c386743d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 18039,
"upload_time": "2025-08-04T12:53:24",
"upload_time_iso_8601": "2025-08-04T12:53:24.263795Z",
"url": "https://files.pythonhosted.org/packages/1e/76/5c6e038a24e5f73a22f62c26eeb8c2c0466ca2c98870c1dc9ba9fef8646a/sharepoint_api_py-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 12:53:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "earldennison",
"github_project": "sharepoint-api-py",
"github_not_found": true,
"lcname": "sharepoint-api-py"
}
JSON
