JupyterLabApiClient 1.0.1

JupyterLab API Client

A comprehensive, type-safe C# wrapper for the JupyterLab Server API with robust authentication, complete test coverage, and professional packaging.

📦 Installation

From NuGet (Recommended)

# Install via Package Manager
Install-Package JupyterLabApiClient

# Install via .NET CLI
dotnet add package JupyterLabApiClient

# Install via PackageReference
<PackageReference Include="JupyterLabApiClient" Version="1.0.0" />

From Source

git clone https://github.com/saeedmaghdam/jupyterlab-wrapper.git
cd jupyterlab-wrapper
dotnet build JupyterLabApiClient.sln
dotnet pack --configuration Release

🏁 Quick Start

1. Basic Setup with Dependency Injection

using JupyterLabApiClient.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddJupyterLabClient(options =>
        {
            options.BaseUrl = "http://localhost:8888";
            options.Token = "your-jupyter-token-here";
            options.ValidateSslCertificate = false; // For local development
            options.Timeout = TimeSpan.FromSeconds(30);
        });
    })
    .Build();

var client = host.Services.GetRequiredService<IJupyterLabClient>();

2. Test Connection and Get Server Info

// Test connection
bool isConnected = await client.TestConnectionAsync();
if (!isConnected)
{
    Console.WriteLine("Could not connect to JupyterLab server");
    return;
}

// Get server information
var serverInfo = await client.GetServerInfoAsync();
Console.WriteLine($"JupyterLab Version: {serverInfo.Version}");

// Get server status
var status = await client.GetServerStatusAsync();
Console.WriteLine($"Active Connections: {status.Connections}");
Console.WriteLine($"Running Kernels: {status.Kernels}");

3. Get Current User Information

var userInfo = await client.GetCurrentUserAsync();
Console.WriteLine($"saeedmaghdam: {userInfo.Identity.saeedmaghdam}");
Console.WriteLine($"Display Name: {userInfo.Identity.DisplayName}");

// Check permissions
foreach (var permission in userInfo.Permissions)
{
    Console.WriteLine($"{permission.Key}: [{string.Join(", ", permission.Value)}]");
}

⚙️ Configuration

Options Pattern Configuration

public class JupyterLabOptions
{
    public string BaseUrl { get; set; } = string.Empty;
    public string Token { get; set; } = string.Empty;
    public TimeSpan Timeout { get; set; } = TimeSpan.FromMinutes(5);
    public int MaxRetryAttempts { get; set; } = 3;
    public TimeSpan RetryDelay { get; set; } = TimeSpan.FromSeconds(1);
    public bool ValidateSslCertificate { get; set; } = true;
    public Dictionary<string, string> AdditionalHeaders { get; set; } = new();
    public bool EnableDetailedLogging { get; set; } = false;
}

Configuration from appsettings.json

{
  "JupyterLab": {
    "BaseUrl": "https://your-jupyter-server.com",
    "Token": "your-long-secure-token",
    "Timeout": "00:05:00",
    "MaxRetryAttempts": 3,
    "ValidateSslCertificate": true,
    "AdditionalHeaders": {
      "User-Agent": "MyApp/1.0"
    },
    "EnableDetailedLogging": false
  }
}

// In Program.cs
services.AddJupyterLabClient(
    configuration.GetSection(JupyterLabOptions.SectionName)
);

🔐 Authentication

The client supports token-based authentication (Bearer tokens). Get your token from JupyterLab:

# Start JupyterLab and get token from URL
jupyter lab

# Or list running servers to get token
jupyter server list

Custom Token Provider

public class CustomTokenProvider : ITokenProvider
{
    public async Task<string> GetTokenAsync(CancellationToken cancellationToken = default)
    {
        // Custom token retrieval logic
        return await GetTokenFromSomewhereAsync();
    }
    
    public async Task<bool> IsTokenValidAsync(CancellationToken cancellationToken = default)
    {
        // Custom token validation logic
        return await ValidateTokenAsync();
    }
    
    public async Task<string?> RefreshTokenAsync(CancellationToken cancellationToken = default)
    {
        // Custom token refresh logic (if supported)
        return await RefreshTokenAsync();
    }
}

// Register custom token provider
services.AddJupyterLabClient<CustomTokenProvider>(
    options => { /* configure */ },
    serviceProvider => new CustomTokenProvider()
);

🧪 Examples and Samples

The repository includes comprehensive examples demonstrating various usage patterns:

Console Application (samples/ConsoleApp/)

A complete console application showing:

• Configuration loading from appsettings.json
• Dependency injection setup
• Basic API operations (connection, server info, user data)
• Error handling and logging
• Interactive demonstrations

cd samples/ConsoleApp
dotnet run

Web API Application (samples/WebApp/)

An ASP.NET Core web application featuring:

• RESTful API endpoints with Swagger documentation
• Health checks and monitoring endpoints
• Dashboard API combining multiple data sources
• Async operations and parallel processing
• Production-ready error handling

cd samples/WebApp
dotnet run
# Open https://localhost:5001 for Swagger UI

Quick Start Example

# Update token in appsettings.json first, then:
cd src/JupyterLabApiClient.Examples.ConsoleApp
dotnet run

🏗️ Project Structure

src/
├── JupyterLabApiClient/           # Main library
│   ├── Client/                    # Core client implementation
│   ├── Configuration/             # Options and DI setup  
│   ├── Authentication/            # Token providers and handlers
│   ├── Models/                    # Request/response DTOs
│   ├── Exceptions/                # Custom exceptions
│   └── Utils/                     # Utility helpers
├── JupyterLabApiClient.Tests/     # Unit and integration tests
└── JupyterLabApiClient.Examples.ConsoleApp/  # Legacy example

samples/
├── ConsoleApp/                    # Console application example
│   ├── Program.cs                 # Main application with DI
│   ├── appsettings.json          # Configuration example
│   └── README.md                  # Setup instructions
└── WebApp/                        # Web API application example
    ├── Controllers/               # API controllers
    ├── Program.cs                 # Web application setup
    ├── appsettings.json          # Web configuration
    └── README.md                  # API documentation

.github/workflows/                 # CI/CD automation
├── ci.yml                        # Main build and test pipeline
├── dependency-update.yml         # Automated dependency updates
└── release.yml                   # Release automation

packages/                          # Generated NuGet packages
└── JupyterLabApiClient.1.0.0.nupkg

🔧 Development

Prerequisites

• .NET 6.0 or .NET 8.0 SDK
• JupyterLab server for testing
• Git for source control

Build and Test

# Clone repository
git clone https://github.com/saeedmaghdam/jupyterlab-wrapper.git
cd jupyterlab-wrapper

# Restore dependencies
dotnet restore

# Build solution
dotnet build JupyterLabApiClient.sln --configuration Release

# Run all tests
dotnet test JupyterLabApiClient.sln --configuration Release

# Generate test coverage report
dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage

# Pack NuGet packages
dotnet pack --configuration Release --output ./packages

Local Development Setup

1. Start JupyterLab Server:

   pip install jupyterlab
   jupyter lab --allow-root --ip=0.0.0.0 --port=8888 --no-browser
   

2. Get Token: Copy token from JupyterLab startup logs or run:

   jupyter server list
   

3. Update Test Configuration: Edit test-config.json with your server details

4. Run Example Application:

   cd src/JupyterLabApiClient.Examples.ConsoleApp
   dotnet run
   

Test Coverage

The project maintains comprehensive test coverage across all components:

• Configuration Tests: Options validation, dependency injection setup
• Authentication Tests: Token providers, retry mechanisms, security
• Core Client Tests: API communication, error handling, timeouts
• Integration Tests: End-to-end scenarios with live JupyterLab server
• Utility Tests: Path handling, JSON serialization, extensions

Current Coverage: 182/182 tests passing (100% success rate)

CI/CD Pipeline

The project uses GitHub Actions for automated testing and publishing:

• Continuous Integration: Automated testing on multiple .NET versions
• Code Quality: CodeQL security analysis and code coverage reporting
• Dependency Management: Automated dependency updates via Dependabot
• Release Automation: Automated NuGet publishing on version tags
• Documentation: Automated API documentation generation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Links

• JupyterLab Documentation
• JupyterLab API Specification
• Microsoft.Extensions.DependencyInjection