# FetchPoint
A Python library for SharePoint Online integration with federated authentication support.
## Overview
FetchPoint is a clean, enterprise-ready library for SharePoint Online integration with federated authentication support. Provides secure, read-only access to files stored in SharePoint document libraries with comprehensive error handling, metadata extraction, and Excel file focus. Designed for enterprise environments with Azure AD and federated authentication.
## Key Features
- **Federated Authentication**: Azure AD and enterprise identity provider support
- **Read-Only Operations**: Secure file listing and downloading
- **Excel Focus**: Optimized for .xlsx, .xls, .xlsm, .xlsb files
- **Path Validation**: Hierarchical folder navigation with detailed error reporting
- **Context Manager**: Clean resource management
- **Comprehensive Error Handling**: Detailed diagnostics for troubleshooting
- **No Environment Dependencies**: Explicit configuration required (environment variables optional)
## Installation
```bash
uv add fetchpoint
```
## Quick Start
```python
from fetchpoint import SharePointClient, create_sharepoint_config
# Create configuration
config = create_sharepoint_config(
username="user@company.com",
password="your_password",
sharepoint_url="https://company.sharepoint.com/sites/project"
)
# Use context manager (recommended)
with SharePointClient(config) as client:
# List Excel files
files = client.list_excel_files(
library_name="Documents",
folder_path="General/Reports"
)
# Download files
results = client.download_files(
library_name="Documents",
folder_path="General/Reports",
filenames=files,
download_dir="./downloads"
)
```
## Configuration
### Method 1: Explicit Configuration
```python
from fetchpoint import create_sharepoint_config
config = create_sharepoint_config(
username="user@company.com", # Required: SharePoint username (email)
password="your_password", # Required: User password
sharepoint_url="https://company.sharepoint.com/sites/yoursite", # Required: SharePoint site URL
timeout_seconds=30, # Optional: Connection timeout (default: 30)
max_file_size_mb=100 # Optional: File size limit (default: 100)
)
```
### Method 2: Dictionary Configuration
```python
from fetchpoint import SharePointClient
client = SharePointClient.from_dict({
"username": "user@company.com",
"password": "your_password",
"sharepoint_url": "https://company.sharepoint.com/sites/yoursite"
})
```
### Method 3: Environment Variables (Legacy)
```bash
# Required
SHAREPOINT_URL=https://company.sharepoint.com/sites/yoursite
SHAREPOINT_USERNAME=user@company.com
SHAREPOINT_PASSWORD=your_password
# Optional
SHAREPOINT_TIMEOUT_SECONDS=30
SHAREPOINT_MAX_FILE_SIZE_MB=100
SHAREPOINT_AUTH_TYPE=federated
SHAREPOINT_SESSION_TIMEOUT=3600
SHAREPOINT_LOG_LEVEL=INFO
```
**Important**: `SHAREPOINT_URL` is optional when using explicit configuration methods. When using environment variables, it's required and specifies the complete SharePoint site URL.
## API Reference
### SharePointClient
Main client class for SharePoint operations.
#### Methods
**`connect() -> bool`**
- Establish connection to SharePoint
- Returns: `True` if successful
**`test_connection() -> bool`**
- Validate current connection
- Returns: `True` if connection is valid
**`disconnect() -> None`**
- Clean up connection and resources
**`list_excel_files(library_name: str, folder_path: str) -> list[str]`**
- List Excel file names in specified location
- Args: `library_name` (default: "Documents"), `folder_path` (e.g., "General/Reports")
- Returns: List of Excel filenames
**`list_files(library: str, path: list[str]) -> list[FileInfo]`**
- List files with complete metadata
- Args: `library` name, `path` segments
- Returns: List of FileInfo objects with metadata
**`list_folders(library_name: str, folder_path: str) -> list[str]`**
- List folder names in specified location
- Returns: List of folder names
**`download_file(library: str, path: list[str], local_path: str) -> None`**
- Download single file
- Args: `library` name, `path` segments including filename, `local_path`
**`download_files(library_name: str, folder_path: str, filenames: list[str], download_dir: str) -> dict`**
- Download multiple files with per-file error handling
- Returns: Dictionary with success/failure status for each file
**`get_file_details(library_name: str, folder_path: str, filename: str) -> FileInfo`**
- Get comprehensive file metadata
- Returns: FileInfo object with complete metadata
**`validate_paths(library_name: str) -> dict`**
- Validate configured SharePoint paths
- Returns: Validation results with error details and available folders
**`discover_structure(library_name: str, max_depth: int) -> dict`**
- Explore SharePoint library structure
- Returns: Hierarchical representation of folders and files
### Configuration Functions
**`create_sharepoint_config(...) -> SharePointAuthConfig`**
- Create configuration with explicit parameters
**`create_config_from_dict(config_dict: dict) -> SharePointAuthConfig`**
- Create configuration from dictionary
**`create_authenticated_context(config: SharePointAuthConfig) -> ClientContext`**
- Create authenticated SharePoint context
### Models
**`SharePointAuthConfig`**
- Configuration model with validation
- Fields: `username`, `password`, `sharepoint_url`, `timeout_seconds`, `max_file_size_mb`
**`FileInfo`**
- File metadata model
- Fields: `name`, `size_bytes`, `size_mb`, `created_date`, `modified_date`, `file_type`, `library_name`, `folder_path`, `created_by`, `modified_by`
**`FileType`**
- Enum for supported Excel extensions
- Values: `XLSX`, `XLS`, `XLSM`, `XLSB`
### Exceptions
All exceptions inherit from `SharePointError`:
- **`AuthenticationError`**: Authentication failures
- **`FederatedAuthError`**: Federated authentication issues (Azure AD specific)
- **`ConnectionError`**: Connection problems
- **`FileNotFoundError`**: File not found in SharePoint
- **`FileDownloadError`**: Download failures
- **`FileSizeLimitError`**: File exceeds size limit
- **`ConfigurationError`**: Invalid configuration
- **`PermissionError`**: Access denied
- **`LibraryNotFoundError`**: Document library not found
- **`InvalidFileTypeError`**: Unsupported file type
## Security
- Passwords stored as `SecretStr` (Pydantic)
- Usernames masked in logs (first 3 characters only)
- Read-only operations only
- Configurable file size limits (default: 100MB)
- No environment dependencies by default
## Error Handling
FetchPoint provides detailed error messages with context:
```python
try:
with SharePointClient(config) as client:
files = client.list_excel_files("Documents", "NonExistent/Path")
except LibraryNotFoundError as e:
print(f"Library error: {e}")
print(f"Available folders: {e.available_folders}")
```
## Development
For project developers working on the fetchpoint library:
### Setup
```bash
# Install dependencies
uv sync --all-groups
# Build wheel package
uv build --wheel
```
### Development Commands
**Code Quality (run after every change):**
```bash
# Format code
uv run ruff format src
# Lint with auto-fix
uv run ruff check --fix src
# Type checking
uv run pyright src
# Run tests
uv run pytest src -vv
# Run tests with coverage
uv run pytest src --cov=src --cov-report=term-missing
```
**Complete validation workflow:**
```bash
uv run ruff format src && uv run ruff check --fix src && uv run pyright src && uv run pytest src -vv
```
### Testing
- Tests located in `__tests__/` directories co-located with source code
- Use pytest with extensions (pytest-asyncio, pytest-mock, pytest-cov)
- Minimum 90% coverage for critical components
### Version Management
FetchPoint uses a single source of truth for version management:
- **Version Source**: `src/fetchpoint/__init__.py` contains `__version__ = "x.y.z"`
- **Dynamic Configuration**: `pyproject.toml` reads version automatically from `__init__.py`
- **Publishing Workflow**:
1. Update version in `src/fetchpoint/__init__.py`
2. Build: `uv build --wheel`
3. Publish: `uv publish --token $PYPI_TOKEN`
Update `uv.lock` via:
```sh
uv lock --refresh
```
**Version Access:**
```python
import fetchpoint
print(fetchpoint.__version__) # e.g., "0.2.0"
```
### Publishing Quick Reference
```bash
just validate
rm -rf dist/
uv build --wheel && uv build --sdist
uv publish --token $PYPI_TOKEN
```
## Roadmap
- Download a single file by path
- Handle filetypes
## License
Open source library for SharePoint Online integration.
Raw data
{
"_id": null,
"home_page": null,
"name": "fetchpoint",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "azure-ad, document-management, enterprise, excel, federated-authentication, office365, sharepoint",
"author": "Massimo Mauri",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4b/69/5a84b5e03d4f53e53bd4268bce49864503e60010c4b87ad1f3fd52503a44/fetchpoint-0.0.3.tar.gz",
"platform": null,
"description": "# FetchPoint\n\nA Python library for SharePoint Online integration with federated authentication support.\n\n## Overview\n\nFetchPoint is a clean, enterprise-ready library for SharePoint Online integration with federated authentication support. Provides secure, read-only access to files stored in SharePoint document libraries with comprehensive error handling, metadata extraction, and Excel file focus. Designed for enterprise environments with Azure AD and federated authentication.\n\n## Key Features\n\n- **Federated Authentication**: Azure AD and enterprise identity provider support\n- **Read-Only Operations**: Secure file listing and downloading\n- **Excel Focus**: Optimized for .xlsx, .xls, .xlsm, .xlsb files\n- **Path Validation**: Hierarchical folder navigation with detailed error reporting\n- **Context Manager**: Clean resource management\n- **Comprehensive Error Handling**: Detailed diagnostics for troubleshooting\n- **No Environment Dependencies**: Explicit configuration required (environment variables optional)\n\n## Installation\n\n```bash\nuv add fetchpoint\n```\n\n## Quick Start\n\n```python\nfrom fetchpoint import SharePointClient, create_sharepoint_config\n\n# Create configuration\nconfig = create_sharepoint_config(\n username=\"user@company.com\",\n password=\"your_password\",\n sharepoint_url=\"https://company.sharepoint.com/sites/project\"\n)\n\n# Use context manager (recommended)\nwith SharePointClient(config) as client:\n # List Excel files\n files = client.list_excel_files(\n library_name=\"Documents\",\n folder_path=\"General/Reports\"\n )\n\n # Download files\n results = client.download_files(\n library_name=\"Documents\",\n folder_path=\"General/Reports\",\n filenames=files,\n download_dir=\"./downloads\"\n )\n```\n\n## Configuration\n\n### Method 1: Explicit Configuration\n\n```python\nfrom fetchpoint import create_sharepoint_config\n\nconfig = create_sharepoint_config(\n username=\"user@company.com\", # Required: SharePoint username (email)\n password=\"your_password\", # Required: User password\n sharepoint_url=\"https://company.sharepoint.com/sites/yoursite\", # Required: SharePoint site URL\n timeout_seconds=30, # Optional: Connection timeout (default: 30)\n max_file_size_mb=100 # Optional: File size limit (default: 100)\n)\n```\n\n### Method 2: Dictionary Configuration\n\n```python\nfrom fetchpoint import SharePointClient\n\nclient = SharePointClient.from_dict({\n \"username\": \"user@company.com\",\n \"password\": \"your_password\",\n \"sharepoint_url\": \"https://company.sharepoint.com/sites/yoursite\"\n})\n```\n\n### Method 3: Environment Variables (Legacy)\n\n```bash\n# Required\nSHAREPOINT_URL=https://company.sharepoint.com/sites/yoursite\nSHAREPOINT_USERNAME=user@company.com\nSHAREPOINT_PASSWORD=your_password\n\n# Optional\nSHAREPOINT_TIMEOUT_SECONDS=30\nSHAREPOINT_MAX_FILE_SIZE_MB=100\nSHAREPOINT_AUTH_TYPE=federated\nSHAREPOINT_SESSION_TIMEOUT=3600\nSHAREPOINT_LOG_LEVEL=INFO\n```\n\n**Important**: `SHAREPOINT_URL` is optional when using explicit configuration methods. When using environment variables, it's required and specifies the complete SharePoint site URL.\n\n## API Reference\n\n### SharePointClient\n\nMain client class for SharePoint operations.\n\n#### Methods\n\n**`connect() -> bool`**\n\n- Establish connection to SharePoint\n- Returns: `True` if successful\n\n**`test_connection() -> bool`**\n\n- Validate current connection\n- Returns: `True` if connection is valid\n\n**`disconnect() -> None`**\n\n- Clean up connection and resources\n\n**`list_excel_files(library_name: str, folder_path: str) -> list[str]`**\n\n- List Excel file names in specified location\n- Args: `library_name` (default: \"Documents\"), `folder_path` (e.g., \"General/Reports\")\n- Returns: List of Excel filenames\n\n**`list_files(library: str, path: list[str]) -> list[FileInfo]`**\n\n- List files with complete metadata\n- Args: `library` name, `path` segments\n- Returns: List of FileInfo objects with metadata\n\n**`list_folders(library_name: str, folder_path: str) -> list[str]`**\n\n- List folder names in specified location\n- Returns: List of folder names\n\n**`download_file(library: str, path: list[str], local_path: str) -> None`**\n\n- Download single file\n- Args: `library` name, `path` segments including filename, `local_path`\n\n**`download_files(library_name: str, folder_path: str, filenames: list[str], download_dir: str) -> dict`**\n\n- Download multiple files with per-file error handling\n- Returns: Dictionary with success/failure status for each file\n\n**`get_file_details(library_name: str, folder_path: str, filename: str) -> FileInfo`**\n\n- Get comprehensive file metadata\n- Returns: FileInfo object with complete metadata\n\n**`validate_paths(library_name: str) -> dict`**\n\n- Validate configured SharePoint paths\n- Returns: Validation results with error details and available folders\n\n**`discover_structure(library_name: str, max_depth: int) -> dict`**\n\n- Explore SharePoint library structure\n- Returns: Hierarchical representation of folders and files\n\n### Configuration Functions\n\n**`create_sharepoint_config(...) -> SharePointAuthConfig`**\n\n- Create configuration with explicit parameters\n\n**`create_config_from_dict(config_dict: dict) -> SharePointAuthConfig`**\n\n- Create configuration from dictionary\n\n**`create_authenticated_context(config: SharePointAuthConfig) -> ClientContext`**\n\n- Create authenticated SharePoint context\n\n### Models\n\n**`SharePointAuthConfig`**\n\n- Configuration model with validation\n- Fields: `username`, `password`, `sharepoint_url`, `timeout_seconds`, `max_file_size_mb`\n\n**`FileInfo`**\n\n- File metadata model\n- Fields: `name`, `size_bytes`, `size_mb`, `created_date`, `modified_date`, `file_type`, `library_name`, `folder_path`, `created_by`, `modified_by`\n\n**`FileType`**\n\n- Enum for supported Excel extensions\n- Values: `XLSX`, `XLS`, `XLSM`, `XLSB`\n\n### Exceptions\n\nAll exceptions inherit from `SharePointError`:\n\n- **`AuthenticationError`**: Authentication failures\n- **`FederatedAuthError`**: Federated authentication issues (Azure AD specific)\n- **`ConnectionError`**: Connection problems\n- **`FileNotFoundError`**: File not found in SharePoint\n- **`FileDownloadError`**: Download failures\n- **`FileSizeLimitError`**: File exceeds size limit\n- **`ConfigurationError`**: Invalid configuration\n- **`PermissionError`**: Access denied\n- **`LibraryNotFoundError`**: Document library not found\n- **`InvalidFileTypeError`**: Unsupported file type\n\n## Security\n\n- Passwords stored as `SecretStr` (Pydantic)\n- Usernames masked in logs (first 3 characters only)\n- Read-only operations only\n- Configurable file size limits (default: 100MB)\n- No environment dependencies by default\n\n## Error Handling\n\nFetchPoint provides detailed error messages with context:\n\n```python\ntry:\n with SharePointClient(config) as client:\n files = client.list_excel_files(\"Documents\", \"NonExistent/Path\")\nexcept LibraryNotFoundError as e:\n print(f\"Library error: {e}\")\n print(f\"Available folders: {e.available_folders}\")\n```\n\n## Development\n\nFor project developers working on the fetchpoint library:\n\n### Setup\n\n```bash\n# Install dependencies\nuv sync --all-groups\n\n# Build wheel package\nuv build --wheel\n```\n\n### Development Commands\n\n**Code Quality (run after every change):**\n\n```bash\n# Format code\nuv run ruff format src\n\n# Lint with auto-fix\nuv run ruff check --fix src\n\n# Type checking\nuv run pyright src\n\n# Run tests\nuv run pytest src -vv\n\n# Run tests with coverage\nuv run pytest src --cov=src --cov-report=term-missing\n```\n\n**Complete validation workflow:**\n\n```bash\nuv run ruff format src && uv run ruff check --fix src && uv run pyright src && uv run pytest src -vv\n```\n\n### Testing\n\n- Tests located in `__tests__/` directories co-located with source code\n- Use pytest with extensions (pytest-asyncio, pytest-mock, pytest-cov)\n- Minimum 90% coverage for critical components\n\n### Version Management\n\nFetchPoint uses a single source of truth for version management:\n\n- **Version Source**: `src/fetchpoint/__init__.py` contains `__version__ = \"x.y.z\"`\n- **Dynamic Configuration**: `pyproject.toml` reads version automatically from `__init__.py`\n- **Publishing Workflow**:\n 1. Update version in `src/fetchpoint/__init__.py`\n 2. Build: `uv build --wheel`\n 3. Publish: `uv publish --token $PYPI_TOKEN`\n\nUpdate `uv.lock` via:\n\n```sh\nuv lock --refresh\n```\n\n**Version Access:**\n\n```python\nimport fetchpoint\nprint(fetchpoint.__version__) # e.g., \"0.2.0\"\n```\n\n### Publishing Quick Reference\n\n```bash\njust validate\nrm -rf dist/\nuv build --wheel && uv build --sdist\nuv publish --token $PYPI_TOKEN\n```\n\n## Roadmap\n\n- Download a single file by path\n- Handle filetypes\n\n## License\n\nOpen source library for SharePoint Online integration.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern SharePoint client library for Python with federated authentication support",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://github.com/masmau/fetchpoint#readme",
"Homepage": "https://github.com/masmau/fetchpoint",
"Issues": "https://github.com/masmau/fetchpoint/issues",
"Repository": "https://github.com/masmau/fetchpoint"
},
"split_keywords": [
"azure-ad",
" document-management",
" enterprise",
" excel",
" federated-authentication",
" office365",
" sharepoint"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b9f18de957f698bd019f5ff601215c3f8823beb370c836024f599f7faf3aecc",
"md5": "592c26020fd921875f64d6989e718f3e",
"sha256": "7ef44acd2d4d84c6fdb54a0fc0472f4cf819792b22f50563b54ef230536d8068"
},
"downloads": -1,
"filename": "fetchpoint-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "592c26020fd921875f64d6989e718f3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 40523,
"upload_time": "2025-08-15T20:51:21",
"upload_time_iso_8601": "2025-08-15T20:51:21.892636Z",
"url": "https://files.pythonhosted.org/packages/1b/9f/18de957f698bd019f5ff601215c3f8823beb370c836024f599f7faf3aecc/fetchpoint-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4b695a84b5e03d4f53e53bd4268bce49864503e60010c4b87ad1f3fd52503a44",
"md5": "ab94d8739650829750e10e39964c8b1b",
"sha256": "fcb28715529b5b08957c51dd1d33be762b285654fb7abece5f8fecc60f7f23af"
},
"downloads": -1,
"filename": "fetchpoint-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "ab94d8739650829750e10e39964c8b1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 115712,
"upload_time": "2025-08-15T20:51:23",
"upload_time_iso_8601": "2025-08-15T20:51:23.079659Z",
"url": "https://files.pythonhosted.org/packages/4b/69/5a84b5e03d4f53e53bd4268bce49864503e60010c4b87ad1f3fd52503a44/fetchpoint-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 20:51:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "masmau",
"github_project": "fetchpoint#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fetchpoint"
}
JSON
