16 document the library

.github/workflows/integration-tests.yml

@@ -2,10 +2,10 @@ name: Python Integration Tests
 
 on:
   pull_request:
-    branches: [ main ]
+    branches: [main]
     types: [review_requested, ready_for_review]
   push:
-    branches: [ main ]
+    branches: [main]
   repository_dispatch:
     types: [verify-new-go-lib-version]
 
@@ -237,6 +237,8 @@ jobs:
 
           # clean up unneeded files
           rm -rf python_release/tests
+          rm -rf python_release/docs
+          rm python_release/mkdocs.yml
           find python_release -type d -name "__pycache__" -exec rm -rf {} +
           rm -rf python_release/.venv
 

README.md

@@ -1 +1,123 @@
-# lib-python
+# Teams API Python Wrapper
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-online-green)](https://pzsp-teams.github.io/lib-python/)
+
+<br>
+
+A high-performance **Python wrapper** for the Microsoft Teams Graph API. It leverages a compiled **Go (Golang)** backend to handle heavy lifting, concurrency, and caching, while providing a clean, fully typed Pythonic interface.
+
+## 🚀 Key Features
+
+- **Performance of Go**: Uses a compiled Go subprocess for efficient API communication and state management.
+- **Pythonic Interface**: Fully typed using `dataclasses` and `Enums`. Native support for IDE autocompletion and type checkers (`mypy`).
+- **Intelligent Cache**: Background caching of Team/Channel IDs to minimize API throttling and latency (handled transparently by the backend).
+- **Simplified Auth**: Wraps MSAL authentication flows configuration.
+
+## 📦 Installation
+
+```bash
+pip install teams-lib-pzsp2-z1
+```
+
+## 🛠️ Architecture
+
+This library acts as a bridge. When initialized, it spawns a dedicated Go subprocess (`teamsClientLib`) and communicates via JSON-RPC over `stdin`/`stdout`.
+
+The `TeamsClient` aggregates domain-specific services:
+
+- **client.teams**: Manage team lifecycles (create, list, delete).
+
+- **client.channels**: Manage standard and private channels.
+
+- **client.chats**: Handle messages, mentions, and chat participants.
+
+## 💻 Quick Start
+
+### 1. Configuration
+
+Create a `.env` in your project with your Azure AD credentials:
+
+```ini
+CLIENT_ID=your-client-id-uuid
+TENANT_ID=your-tenant-id-uuid
+EMAIL=user@example.com
+SCOPES=User.Read,Team.ReadBasic.All,Channel.ReadBasic.All
+AUTH_METHOD=DEVICE_CODE [or INTERACTIVE]
+```
+
+Scopes needed by all functions could be found in [.env.template](https://github.com/pzsp-teams/lib-python/tree/main/.env.template).
+
+### 2. Basic usage
+
+Here is a minimal example showing how to initialize the client and list joined teams:
+
+```python
+from teams_lib_pzsp2_z1.client import TeamsClient
+from teams_lib_pzsp2_z1.config import CacheMode
+
+def main():
+    # Initialize the client.
+    # This spawns the Go subprocess and performs authentication.
+    client = TeamsClient()
+
+    try:
+        print("Fetching teams...")
+        teams = client.teams.list_my_joined()
+
+        for team in teams:
+            print(f"Team: {team.display_name} | ID: {team.id}")
+
+            # Example: List channels in the first team
+            channels = client.channels.list_channels(team.id)
+            print(f"  -> Found {len(channels)} channels.")
+
+    except RuntimeError as e:
+        print(f"An error occurred: {e}")
+
+    finally:
+        # Crucial: Close the client to ensure background cache writes finish
+        # and the Go subprocess is terminated gracefully.
+        client.close()
+
+if __name__ == "__main__":
+    main()
+```
+
+## 📚 Documentation
+
+Full API reference, architecture details, and configuration guides are available here:
+
+👉 [Read the Documentation](https://pzsp-teams.github.io/lib-python/)
+
+## Authentication
+
+The library loads credentials from environment variables. Ensure your Azure App Registration has the necessary **API Permissions** (e.g., `Team.ReadBasic.All`, `Channel.ReadBasic.All`) granted in the Azure Portal.
+
+Supported Authentication Methods (`AUTH_METHOD`):
+
+- **INTERACTIVE**: Opens a browser window automatically.
+
+- **DEVICE_CODE**: Prints a code to the console to login via microsoft.com/devicelogin.
+
+## Cache & Lifecycle
+
+If caching is enabled (SYNC or ASYNC), the Go backend stores metadata locally (e.g., `teams_cache.json`) to speed up reference resolution.
+
+⚠️ Important: client.close()
+Because the Go backend might be running background goroutines (especially for Async Cache), you **must** call `client.close()` before your script exits. This ensures:
+
+1. Pending cache writes are flushed to disk.
+
+2. The Go subprocess is terminated correctly.
+
+```python
+client.close()
+```
+
+## 📄 License
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/pzsp-teams/lib-python/blob/main/LICENSE) file for details.
+
+## Port
+This lib is also available in [GO](https://github.com/pzsp-teams/lib)

go/bridge/main.go

@@ -5,9 +5,11 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"context"
 
 	jsonClientLib "github.com/pzsp-teams/lib-python/internal/json-client"
 	jsonModel "github.com/pzsp-teams/lib-python/internal/json-model"
+	"github.com/pzsp-teams/lib"
 )
 
 var client *jsonClientLib.TeamsJSONClient
@@ -51,19 +53,24 @@ func main() {
 				continue
 			}
 
-			switch req.Method {
-			case "listChannels":
-				channels, err := client.ListChannels(req.Params)
-				if err != nil {
-					respondError(writer, err)
-				} else {
-					respondResult(writer, channels)
-				}
-			default:
+			handler, exists := jsonClientLib.Handlers[req.Method]
+			if !exists {
 				respondError(writer, fmt.Errorf("unknown method"))
+				continue
+			}
+
+			result, err := handler(client, context.Background(), req.Params)
+			if err != nil {
+				respondError(writer, err)
 			}
+			respondResult(writer, result)
 			continue
 		}
-		respondError(writer, fmt.Errorf("unknown request type"))
+
+        if req.Type == "close" {
+			lib.Close()
+            respondResult(writer, "closed")
+            return
+        }
 	}
 }

go/bridge/responses.go

@@ -6,7 +6,7 @@ import (
 )
 
 type response struct {
-	Result interface{} `json:"result,omitempty"`
+	Result any `json:"result,omitempty"`
 	Error  string      `json:"error,omitempty"`
 }
 
@@ -29,7 +29,7 @@ func respondError(writer *bufio.Writer, err error) {
 	writer.Flush()
 }
 
-func respondResult(writer *bufio.Writer, result interface{}) {
+func respondResult(writer *bufio.Writer, result any) {
 	response := response{
 		Result: result,
 	}

go/go.mod

@@ -4,23 +4,25 @@ go 1.25.5
 
 require (
 	github.com/microsoft/kiota-abstractions-go v1.9.3
-	github.com/microsoftgraph/msgraph-sdk-go v1.90.0
-	github.com/pzsp-teams/lib v0.0.0-20251213104555-e41d3adf599f
+	github.com/microsoftgraph/msgraph-sdk-go v1.93.0
+	github.com/mitchellh/mapstructure v1.5.0
+	github.com/pzsp-teams/lib v0.0.0-20260112132712-1335fb93c11f
 )
 
 require (
-	al.essio.dev/pkg/shellescape v1.5.1 // indirect
-	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1 // indirect
+	al.essio.dev/pkg/shellescape v1.6.0 // indirect
+	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.20.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
 	github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1 // indirect
 	github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 // indirect
-	github.com/danieljoos/wincred v1.2.2 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/danieljoos/wincred v1.2.3 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
-	github.com/godbus/dbus/v5 v5.1.0 // indirect
-	github.com/golang-jwt/jwt/v5 v5.2.2 // indirect
+	github.com/godbus/dbus/v5 v5.2.2 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/keybase/go-keychain v0.0.0-20230523030712-b5615109f100 // indirect
+	github.com/keybase/go-keychain v0.0.1 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/microsoft/kiota-authentication-azure-go v1.3.1 // indirect
 	github.com/microsoft/kiota-http-go v1.5.4 // indirect
@@ -30,13 +32,14 @@ require (
 	github.com/microsoft/kiota-serialization-text-go v1.1.3 // indirect
 	github.com/microsoftgraph/msgraph-sdk-go-core v1.4.0 // indirect
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
-	github.com/std-uritemplate/std-uritemplate/go/v2 v2.0.3 // indirect
+	github.com/std-uritemplate/std-uritemplate/go/v2 v2.0.8 // indirect
 	github.com/zalando/go-keyring v0.2.6 // indirect
-	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
-	go.opentelemetry.io/otel v1.37.0 // indirect
-	go.opentelemetry.io/otel/metric v1.37.0 // indirect
-	go.opentelemetry.io/otel/trace v1.37.0 // indirect
-	golang.org/x/net v0.43.0 // indirect
-	golang.org/x/sys v0.35.0 // indirect
-	golang.org/x/text v0.28.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.39.0 // indirect
+	go.opentelemetry.io/otel/metric v1.39.0 // indirect
+	go.opentelemetry.io/otel/trace v1.39.0 // indirect
+	golang.org/x/net v0.48.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.39.0 // indirect
+	golang.org/x/text v0.32.0 // indirect
 )