docs: update python integrations documentation

docs/mkdocs.yml

@@ -214,7 +214,44 @@ nav:
       - Apache Airflow: integrations/airflow.md
       - Airbyte: integrations/airbyte.md
     - Dev & Tools:
-      - Python: integrations/python.md
+      - Python:
+        - Overview: integrations/python/index.md
+        - Getting Started: integrations/python/getting-started.md
+        - High-Level SDK:
+          - Overview: integrations/python/high-level-sdk/index.md
+          - Quickstart: integrations/python/high-level-sdk/quickstart.md
+          - Repositories: integrations/python/high-level-sdk/repositories.md
+          - Branches & Commits: integrations/python/high-level-sdk/branches-and-commits.md
+          - Objects & I/O: integrations/python/high-level-sdk/objects-and-io.md
+          - Imports & Exports: integrations/python/high-level-sdk/imports-and-exports.md
+          - Transactions: integrations/python/high-level-sdk/transactions.md
+          - Advanced Features: integrations/python/high-level-sdk/advanced.md
+        - Generated SDK:
+          - Overview: integrations/python/generated-sdk/index.md
+          - API Reference: integrations/python/generated-sdk/api-reference.md
+          - Examples: integrations/python/generated-sdk/examples.md
+          - Direct Access: integrations/python/generated-sdk/direct-access.md
+        - lakefs-spec:
+          - Overview: integrations/python/lakefs-spec/index.md
+          - Filesystem API: integrations/python/lakefs-spec/filesystem-api.md
+          - Integrations: integrations/python/lakefs-spec/integrations.md
+          - Transactions: integrations/python/lakefs-spec/transactions.md
+        - Boto3:
+          - Overview: integrations/python/boto3/index.md
+          - Configuration: integrations/python/boto3/configuration.md
+          - S3 Operations: integrations/python/boto3/s3-operations.md
+          - S3 Router: integrations/python/boto3/s3-router.md
+        - Tutorials:
+          - Overview: integrations/python/tutorials/index.md
+          - Data Science Workflow: integrations/python/tutorials/data-science-workflow.md
+          - ETL Pipeline: integrations/python/tutorials/etl-pipeline.md
+          - ML Experiment Tracking: integrations/python/tutorials/ml-experiment-tracking.md
+        - Reference:
+          - Overview: integrations/python/reference/index.md
+          - API Comparison: integrations/python/reference/api-comparison.md
+          - Best Practices: integrations/python/reference/best-practices.md
+          - Troubleshooting: integrations/python/reference/troubleshooting.md
+          - Changelog: integrations/python/reference/changelog.md
       - AWS CLI: integrations/aws_cli.md
       - Git: integrations/git.md
       - R: integrations/r.md

docs/src/integrations/python/_templates/api-reference-template.md

@@ -0,0 +1,207 @@
+# API Reference Template
+
+Use this template for consistent API documentation throughout the Python documentation.
+
+## Method Documentation Format
+
+```markdown
+#### `method_name(param1, param2=None, **kwargs)`
+
+Brief description of the method and its purpose. Explain what it does and when to use it.
+
+**Parameters:**
+- `param1` (str): Description of the parameter, including valid values or constraints
+- `param2` (Optional[int], default=None): Description of optional parameter with default value
+- `**kwargs`: Additional keyword arguments passed to underlying implementation
+
+**Returns:**
+- `ReturnType`: Description of what the method returns, including type information
+
+**Raises:**
+- `SpecificException`: When this specific exception occurs and why
+- `ValueError`: When invalid parameters are provided
+- `ConnectionError`: When connection to lakeFS fails
+
+**Example:**
+```python
+# Basic usage
+result = obj.method_name("required_value")
+
+# With optional parameters
+result = obj.method_name("required_value", param2=42, extra_option=True)
+
+# Error handling
+try:
+    result = obj.method_name("value")
+except SpecificException as e:
+    print(f"Operation failed: {e}")
+```
+
+**See Also:**
+- [Related Method](../path/to/related-method.md)
+- [Usage Guide](../path/to/usage-guide.md)
+```
+
+## Class Documentation Format
+
+```markdown
+### ClassName
+
+Brief description of the class and its purpose.
+
+**Initialization:**
+```python
+obj = ClassName(param1, param2=default_value)
+```
+
+**Parameters:**
+- `param1` (str): Required parameter description
+- `param2` (Optional[type], default=default_value): Optional parameter description
+
+**Attributes:**
+- `attribute_name` (type): Description of public attribute
+- `another_attr` (type): Description of another attribute
+
+**Methods:**
+- [`method1()`](#method1): Brief description
+- [`method2()`](#method2): Brief description
+
+**Example:**
+```python
+# Create instance
+obj = ClassName("required_param")
+
+# Use methods
+result = obj.method1()
+```
+```
+
+## Exception Documentation Format
+
+```markdown
+### ExceptionName
+
+Description of when this exception is raised and what it indicates.
+
+**Inheritance:** `BaseException` → `CustomException` → `ExceptionName`
+
+**Attributes:**
+- `message` (str): Error message
+- `error_code` (Optional[int]): Specific error code if applicable
+
+**Example:**
+```python
+try:
+    # Operation that might raise this exception
+    result = risky_operation()
+except ExceptionName as e:
+    print(f"Error: {e.message}")
+    if e.error_code:
+        print(f"Code: {e.error_code}")
+```
+```
+
+## Type Hints and Annotations
+
+Use consistent type hints throughout documentation:
+
+```python
+from typing import Optional, List, Dict, Union, Any
+
+def example_function(
+    required_param: str,
+    optional_param: Optional[int] = None,
+    list_param: List[str] = None,
+    dict_param: Dict[str, Any] = None
+) -> Union[str, None]:
+    """
+    Example function with proper type hints.
+
+    Args:
+        required_param: Required string parameter
+        optional_param: Optional integer parameter
+        list_param: List of strings
+        dict_param: Dictionary with string keys
+
+    Returns:
+        String result or None if operation fails
+    """
+    pass
+```
+
+## SDK-Specific API Documentation
+
+### High-Level SDK API Format
+Focus on the simplified, Pythonic interface:
+
+```markdown
+#### `repository(name)`
+
+Get a repository object for the specified repository name.
+
+**Parameters:**
+- `name` (str): Repository name
+
+**Returns:**
+- `Repository`: Repository object for performing operations
+
+**Example:**
+```python
+repo = lakefs.repository("my-repo")
+```
+```
+
+### Generated SDK API Format
+Include full OpenAPI-based documentation:
+
+```markdown
+#### `create_repository(repository_creation)`
+
+Create a new repository using the Generated SDK.
+
+**Parameters:**
+- `repository_creation` (RepositoryCreation): Repository creation object containing:
+  - `name` (str): Repository name
+  - `storage_namespace` (str): Storage namespace URI
+  - `default_branch` (Optional[str]): Default branch name
+
+**Returns:**
+- `Repository`: Created repository object
+
+**Raises:**
+- `ConflictException`: Repository already exists
+- `ValidationException`: Invalid parameters
+
+**Example:**
+```python
+from lakefs_sdk import RepositoryCreation
+
+repo_creation = RepositoryCreation(
+    name="my-repo",
+    storage_namespace="s3://bucket/path"
+)
+repo = repositories_api.create_repository(repository_creation=repo_creation)
+```
+```
+
+## Documentation Standards
+
+### Consistency Guidelines
+1. **Parameter Names**: Use consistent parameter names across similar operations
+2. **Return Types**: Always specify return types clearly
+3. **Error Handling**: Document all possible exceptions
+4. **Examples**: Provide practical, runnable examples
+5. **Cross-References**: Link to related documentation
+
+### Writing Style
+- Use active voice
+- Be concise but complete
+- Explain the "why" not just the "what"
+- Include practical use cases
+- Use consistent terminology
+
+### Code Quality
+- All examples must be syntactically correct
+- Use realistic parameter values
+- Include error handling where appropriate
+- Show both basic and advanced usage patterns

docs/src/integrations/python/_templates/code-example-template.md

@@ -0,0 +1,134 @@
+# Code Example Template
+
+Use this template for consistent code examples throughout the Python documentation.
+
+## Basic Code Example Format
+
+```markdown
+### Operation Name
+
+Brief description of what this operation does and when to use it.
+
+```python
+# Complete, runnable example with clear comments
+import lakefs
+
+# Setup (if needed)
+client = lakefs.Client(host="http://localhost:8000", ...)
+
+# Main operation with descriptive variable names
+result = client.operation_name(parameter="value")
+print(result)
+```
+
+**Expected Output:**
+```
+Expected output here (when applicable)
+```
+
+**Key Points:**
+- Important concept 1
+- Important concept 2
+- When to use this pattern
+
+**See Also:**
+- [Related Topic](../path/to/related.md)
+- [Advanced Usage](../path/to/advanced.md)
+```
+
+## Code Example Guidelines
+
+### Code Style
+- Use clear, descriptive variable names
+- Include necessary imports at the top
+- Add comments explaining non-obvious operations
+- Show complete, runnable examples when possible
+- Use consistent indentation (4 spaces)
+
+### Content Structure
+- Start with a brief description
+- Provide the code example
+- Show expected output when relevant
+- List key points or concepts
+- Include cross-references to related topics
+
+### Error Handling Examples
+```python
+try:
+    # Operation that might fail
+    result = client.risky_operation()
+    print(f"Success: {result}")
+except SpecificException as e:
+    print(f"Specific error: {e}")
+    # Handle specific error case
+except Exception as e:
+    print(f"General error: {e}")
+    # Handle general error case
+```
+
+### Multi-Step Examples
+For complex operations, break into clear steps:
+
+```python
+# Step 1: Setup
+client = lakefs.Client(...)
+
+# Step 2: Prepare data
+data = prepare_data()
+
+# Step 3: Execute operation
+result = client.complex_operation(data)
+
+# Step 4: Process results
+processed_result = process_results(result)
+```
+
+## SDK-Specific Templates
+
+### High-Level SDK Example
+```python
+import lakefs
+
+# Use High-Level SDK patterns
+repo = lakefs.repository("my-repo")
+branch = repo.branch("main")
+obj = branch.object("path/to/file.txt")
+
+# Show the operation
+result = obj.upload(data="content")
+```
+
+### Generated SDK Example
+```python
+import lakefs_sdk
+from lakefs_sdk.client import LakeFSClient
+
+# Initialize Generated SDK client
+client = LakeFSClient(configuration=lakefs_sdk.Configuration(...))
+api = lakefs_sdk.ObjectsApi(client)
+
+# Show the operation
+result = api.upload_object(...)
+```
+
+### lakefs-spec Example
+```python
+from lakefs_spec import LakeFSFileSystem
+
+# Initialize filesystem
+fs = LakeFSFileSystem()
+
+# Show the operation
+fs.write_text("lakefs://repo/branch/file.txt", "content")
+```
+
+### Boto3 Example
+```python
+import boto3
+
+# Initialize Boto3 client
+s3 = boto3.client('s3', endpoint_url='http://localhost:8000', ...)
+
+# Show the operation
+s3.put_object(Bucket='repo', Key='branch/file.txt', Body=b'content')
+```